Files
ssw-platform/template-boot-jnpf/README.md
T
sukyboor 9771fa844d init: 尚数网平台 JNPF 7.0 兼容后端(多应用 + 面 A/面 B 双契约)
- axum 0.8 + pglite:12 张表,多应用按 App-Code 头解析 f_system_id 隔离
- 面 A(ssw/react 形状)+ 面 B(官方 JNPF 形状,Vue-Version: 3)双契约并存
- 业务模块 asset/DataResource;面 B 用户 CRUD 9 条已落地
- 六道闸门 + 两把运行时尺子(perm-smoke 43 / perm-smoke-jnpf 23)
- scripts/:前端接口清单、页面依赖反查、运行时探针
2026-10-30 22:08:31 +08:00

14 KiB
Raw Blame History

template-boot-jnpf — JNPF 标准栈最小骨架

ssw-jnpf-lite-react(NestJS MVP)稳定后迁到 JNPF 标准 Java 栈时的最小可运行模板—— 自包含、5 个踩坑点已写在防御注释中,开发者 cp -R 到新目录、把 Maven groupId 由 com.example 替换为自己组织、appCode=demo 替换为业务名,第一次 mvn package 就过。

⚠️ 这不是开箱即用的成品:模板只搭出"启动即可见到 Spring Boot 默认页 + 一个 CRUD 端点"的 骨架,不包含: • DDL 数据初始化(jnpf 7.0 自动建表,但 seed 数据要按官方 installer 走) • 完整 4 库菜单 / 权限 / 角色初始化(按需自家业务自己写) • 鉴权拦截器完整版(BaseCrudController 的权限 / 数据范围钩子默认 noop, 由业务子类按需 override — 不绑死任何权限框架)

模板对应 JNPF 7.0.0-RELEASE + JDK 17。其它版本请自行调整 <parent> 的 jnpf-common version。

目录结构

template-boot-jnpf/
├── pom.xml                                  # 父 POM(继承 jnpf-common 7.0.0-RELEASE,artifactId=ssw-boot)
├── .env.example                              # DB_HOST / REDIS_HOST 等环境变量样板
├── README.md                                 # 本文件
├── ssw-admin/                                # 唯一可执行的 Spring Boot 入口
│   ├── pom.xml
│   └── src/main/
│       ├── java/ssw/
│       │   ├── SswAdminApplication.java      # @SpringBootApplication(scanBasePackages = {"jnpf","ssw"})
│       │   └── common/config/
│       │       └── SswMapperConfig.java      # 统一扫 ssw.**.mapper
│       └── resources/
│           ├── application.yml               # profile 切换 + 鉴权
│           └── application-dev.yml           # dev 单业务库 + Redis IP
└── ssw-demo/                                 # 一个最小业务模块(appCode=demo)
    ├── pom.xml                              # ssw-demo 的父(聚合 -entity / -controller)
    ├── ssw-demo-entity/
    │   ├── pom.xml
    │   └── src/main/java/ssw/demo/entity/DemoEntity.java
    └── ssw-demo-controller/
        ├── pom.xml
        └── src/main/java/ssw/demo/
            ├── controller/DemoController.java   # @RestController 三端点
            └── mapper/DemoMapper.java           # extends SuperMapper<DemoEntity>

包命名约定

Java 包命名 = ssw.{appCode}.xx.xx:

类 包
SswAdminApplication ssw(顶层,无子包)
SswMapperConfig ssw.common.config(共享层)
DemoController ssw.demo.controller(业务模块)
DemoMapper ssw.demo.mapper(业务模块)
DemoEntity ssw.demo.entity(业务模块)

Maven groupId / artifactId 与 Java 包名不强制同:模板默认 <groupId>com.example</groupId> + <artifactId>ssw-boot</artifactId>(用户改 groupId 时同步改所有子模块 parent 段)。Java 包名按上表硬约定。

数据源约定(多库架构)

两个数据源分离:MVP 时代 base_* 权限表与业务表同库;迁 JNPF 后必须分离:

数据源 key 物理 DB 装什么表 切换方式
master(默认) jnpf 主库(DB_NAME) base_user / base_role / base_module / base_* 等权限与系统表 JNPF MybatisPlusConfig 自动建
ssw-demoDs 业务库(DEMO_DB_NAME) demo_demo 等业务表 Mapper 上 @DS("ssw-demoDs")

业务库命名约定 ssw-{appCode}Ds:

  • ssw- 前缀避免与 jnpf 内部 key(如 master / work) 混淆
  • Ds 后缀与 dynamic-datasource-spring-boot-starter 习惯一致
  • 每加一个业务模块 = 一个新 ssw-{appCode}Ds 数据源 + 一个 @DS 注解

⚠️ 业务表必须在业务库,不要让 demo_demo 这种表进 master 库(迁后再拆数据迁移非常痛)。 ⚠️ base_* 表不要自己建——让 jnpf installer 在 master 库装,自己手工建表会和官方 schema 漂移。

5 个已写在防御注释里的踩坑(迁业务模块时也避这 5 个)

这些是从"严格按 JNPF 资深工程复制 → 删除不需要的子系统 → 加自己的业务模块"路线里首次启动 就可能踩到的 5 个连环坑。模板 pom / 配置里都已用 ⚠️ 注释防御。

# 坑 模板里的位置
1 jnpf-common-all 伞包传递依赖失败——每个 jnpf-* 子包自身 pom 用 ${revision} 占位 1.0.0-RELEASE,在 BOM 继承路径下解析失败 ssw-admin/pom.xml 改直引 jnpf-common-core + jnpf-common-database + <exclusion> 排除 SaaS 集成包
2 IdGeneratorConfig 需要 RedisTemplate——jnpf-common-database 的 @Configuration 自动启动,缺 Redis bean 会因 NoSuchBean 启动失败 ssw-admin/pom.xml 含 spring-boot-starter-data-redis;application-dev.yml 含 spring.data.redis.*
3 容器主机名解析失败——主机 DNS 解析不到 docker 容器名(如 jnpf-redis) application-dev.yml 显式用 ${DB_HOST:127.0.0.1} / ${REDIS_HOST:127.0.0.1} 占位符,从 .env 读 IP
4 profile 切换错连多库——多 profile(如 full)会挂载 4 个数据源,缺连接直接启动失败 application.yml 用 ${SPRING_PROFILES_ACTIVE:dev} 占位;不要在 SswAdminApplication 里硬写 default Profile
5 业务库与 base_ 表未分离*——MVP 时代 base_* 与业务表同库;迁 JNPF 后 base_* 应在 jnpf 主库 master,业务表应在 ssw-{appCode}Ds 业务库,Mapper 上打 @DS("ssw-{appCode}Ds") 切库 application-dev.yml 用 JNPF 扁平主配置 (host/port/db-name) + spring.datasource.dynamic.datasource.ssw-demoDs 子节点;DemoMapper.java 加 @DS("ssw-demoDs")

跑通流程

# 1. 复制模板
cp -R /path/to/template-boot-jnpf ./my-boot
cd my-boot

# 2. 重命名:groupId com.example → com.myorg;包名 ssw.{appCode} 默认即可(appCode=demo 是模板演示,可全替换)
#    涉及文件:所有 pom.xml 的 <parent><groupId> + <dependency><groupId>。
#    用 sed 批量替换 com.example → com.myorg,但要保留 jnpf.* / org.springframework.* 等前缀不动。
#    Java 包名已是 ssw.* 形态,不需要改目录结构。
sed -i '' 's/com.example/com.myorg/g' \
  pom.xml ssw-admin/pom.xml ssw-demo/pom.xml ssw-demo/*/pom.xml

# 3. 配 .env
cp .env.example .env
$EDITOR .env   # 必改:DB_HOST / DB_NAME (j7) / DEMO_DB_NAME (demo_db) / DB_USER / DB_PASSWORD / REDIS_HOST
#   跑通前置条件:本机装好 PostgreSQL + 建好两个库 (j7, demo_db) + Redis 在跑
#   j7 库由 jnpf installer 装 base_* 表;demo_db 自己 psql -c 'CREATE DATABASE demo_db;' 即可

# 4. mvn install(先装父 POM,再装各子模块)
mvn -N install -DskipTests
mvn install -DskipTests

# 5. 启 ssw-admin
cd ssw-admin
nohup java -jar target/ssw-admin-1.0.0-SNAPSHOT.jar > ../boot.log 2>&1 &
tail -f ../boot.log
# → Tomcat on port 30000 + jnpf 启动成功后访问 http://127.0.0.1:30000/api/oauth/Login 应返 {"code":600,...}

# 6. 端到端验证
curl -s -X POST http://127.0.0.1:30000/api/oauth/Login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "account=admin" --data-urlencode "password=$PWD_ENC" --data-urlencode "grant_type=password"
#   password 必须按官方公式:md5( md5(明文) + secretkey.toLowerCase() ),AES cipher 是密文传输
#   端点返 {"code":200,"data":{token:...}} 即视为端到端通

加一个新业务模块(按本模板结构复制)

参照 ssw-demo/ 形态(包命名 ssw.{appCode}.xx.xx):

my-boot/
└── ssw-<your-appcode>/                        # 包名 = ssw.<your-appcode>,目录用小写连字符
    ├── pom.xml                                # parent = ssw-boot
    ├── ssw-<your-appcode>-entity/
    │   ├── pom.xml
    │   └── src/main/java/ssw/<your-appcode>/entity/<Entity>Entity.java
    │                                          └─ extends SuperBaseEntity
    └── ssw-<your-appcode>-controller/
        ├── pom.xml
        └── src/main/java/ssw/<your-appcode>/
            ├── controller/<Entity>Controller.java
            │   └─ @RestController + @RequestMapping("/api/ssw/<your-appcode>/<Entity>")
            └── mapper/<Entity>Mapper.java
                └─ extends SuperMapper<<Entity>Entity>

业务 Controller 三端点(参考 ssw-demo/ssw-demo-controller/.../DemoController.java):

@GetMapping("/List")    // GET    /api/ssw/{appCode}/{Entity}/List
@PostMapping("/Save")   // POST   /api/ssw/{appCode}/{Entity}/Save    body = JSON
@DeleteMapping("/Delete") // DELETE /api/ssw/{appCode}/{Entity}/Delete?id=

并在 ssw-admin/pom.xml 的 <dependencies> 加:

<dependency>
    <groupId>com.myorg</groupId>
    <artifactId>ssw-<your-appcode>-controller</artifactId>
    <version>${project.version}</version>
</dependency>

并在 application-dev.yml 加新业务库节点:

spring:
  datasource:
    dynamic:
      datasource:
        ssw-<your-appcode>Ds:                       # ⚠️ key 必须与 Mapper 上 @DS("...") 一致
          url: jdbc:postgresql://${DEMO_DB_HOST:127.0.0.1}:${DEMO_DB_PORT:5432}/${DEMO_DB_NAME:other_db}?currentSchema=public&stringtype=unspecified
          username: ${DEMO_DB_USER:postgres}
          password: ${DEMO_DB_PASSWORD:postgres}
          driver-class-name: org.postgresql.Driver
          lazy: false

最后 mvn install + 重启 ssw-admin。

⚠️ Mapper 必须打 @DS("ssw-{yourAppcode}Ds")——不加则默认走 master 库,业务表会建到 jnpf 主库里去, 后续想拆业务库时数据迁移非常痛。详见 ssw-demo/ssw-demo-controller/.../DemoMapper.java。

⚠️ 想要"继承基类省 5 个样板"?模板不预设这种抽象 — 各 JNPF 工程命名风格不一, 本仓库 ../references/BaseCrudController.java 是中性版本(包 ssw.common.controller), 拷到目标 ssw.common.controller 包即用。审计钩子默认 noop,按需 override audit() 连到自家审计服务 (详见 ../references/README.md)。

与 ssw-jnpf-lite-react 的契约对接

迁业务模块时 f_ 列 / varchar(50) UUID / ActionResult{code,msg,data} / code:200 / code:600/601/602 会话过期 / BizException → code:400 / 端点 /api/ssw/{appCode}/{Entity}/{List|Save|Delete} 全部一对一保留——前端契约不变,零改接入。

详细对照表见 ../MIGRATION.md。

验证记录与已知踩坑(2026-09-18 实测)

2026-09-18 把模板复制到 /Users/xs/Desktop/jxcj/boot/ 跑 mvn package 验证,记录 5 个修复:

# 坑 现象 修复(已写进模板)
1 jnpf-common- 找不到(${project.version} 占位被继承后污染)* Maven 报 com.jnpf:jnpf-common-database:jar:1.0.0-SNAPSHOT (absent) — jnpf-common 父 POM 的 <dependencyManagement> 用 ${project.version} 占位,被 ssw-boot 继承后 ${project.version} 展开成 1.0.0-SNAPSHOT 父 POM 加 <jnpf.version>7.0.0-RELEASE</jnpf.version> 属性 + <dependencyManagement> 显式锁 jnpf-common-core/-database/-auth/-redis 四个最常用的版本号
2 SuperBaseEntity<T> 泛型基类 getId() 返 Object DemoEntity extends SuperBaseEntity 不带 <String> → getId() 编译期解析为 Object → .isBlank() 报"找不到符号" DemoEntity 显式 extends SuperBaseEntity<String>(SuperBaseEntity 的 T 就是 id 的类型)
3 JNPF API 名是 RandomUtil.uuId() 不是 uuid() dto.setId(RandomUtil.uuid()) 报"找不到方法 uuid()" 改为 RandomUtil.uuId()(jnpf.util.RandomUtil 的实际方法签名是 uuId(),驼峰式)
4 @EnableFileStorage(dromara x-file-storage)+ SpringContext(jnpf 内)不在依赖里 SswAdminApplication import 这俩就编译失败 SswAdminApplication 删掉这俩 import + 注解;用到时再加对应 starter
5 spring-boot-maven-plugin 没绑 repackage → 瘦 jar 第一次打出来是 6.9K 瘦 jar,启动 java -jar 找不到依赖。Spring Boot 默认只在 pluginManagement 里 register,要显式 executions 绑到 package 阶段 ssw-admin/pom.xml 加 <executions><execution><goals><goal>repackage</goal></goals></execution></executions>

最终产物验证(jar 内部字节码层):

$ mvn -pl ssw-admin -am package -DskipTests
[INFO] BUILD SUCCESS  # 5 模块全绿
$ unzip -l ssw-admin/target/ssw-admin-1.0.0-SNAPSHOT.jar
169M / 332 files / 196 jars in BOOT-INF/lib/
  ✓ Main-Class: org.springframework.boot.loader.launch.JarLauncher
  ✓ Start-Class: ssw.SswAdminApplication
  ✓ BOOT-INF/classes/ssw/SswAdminApplication.class
  ✓ BOOT-INF/classes/ssw/common/config/SswMapperConfig.class
  ✓ BOOT-INF/lib/ssw-demo-controller-1.0.0-SNAPSHOT.jar (嵌套 jar)
  ✓ BOOT-INF/lib/jnpf-common-database-7.0.0-RELEASE.jar
  ✓ BOOT-INF/lib/dynamic-datasource-spring-boot3-starter-4.5.0.jar
  ✓ BOOT-INF/classes/application-dev.yml

$ javap -v BOOT-INF/lib/ssw-demo-controller-*.jar (内 DemoMapper.class)
  RuntimeVisibleAnnotations:
    com.baomidou.dynamic.datasource.annotation.DS(value="ssw-demoDs")

模板已用 @DS 把业务表切到 ssw-demoDs 数据源;与 application-dev.yml 里 dynamic.datasource.datasource.ssw-demoDs key 一一对应。

运行时启动未实测:模板运行需连 jnpf 主库(master)+ 业务库(ssw-{appCode}Ds)+ Redis,本机需先:

# 假设本机 jnpf 已用官方 installer 装过 master 库;新业务库直接 psql 建空 DB 即可
psql -h ${DB_HOST} -U ${DB_USER} -c "CREATE DATABASE demo_db;"
nohup java -jar ssw-admin/target/ssw-admin-1.0.0-SNAPSHOT.jar > boot.log 2>&1 &
tail -f boot.log

升级 jnpf 7.x → 8.x 时只需改父 POM 的 <jnpf.version> 一行 + 补 dependencyManagement 里没列到的 jnpf-* artifact(编译报错时会点名)。

配套自检脚本:bash scripts/verify.sh — 自动跑这 5 项 + jar 字节码级检查(@DS 注解值 / Manifest 的 Start-Class / dependencyManagement 锁版本)。改名 / 换包后忘了某项跑这个脚本能立即定位,不会等到运行时才发现。