- 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/:前端接口清单、页面依赖反查、运行时探针
14 KiB
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,按需 overrideaudit()连到自家审计服务 (详见../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 锁版本)。改名 / 换包后忘了某项跑这个脚本能立即定位,不会等到运行时才发现。