# 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。其它版本请自行调整 `` 的 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 ``` ## 包命名约定 **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 包名**不强制同**:模板默认 `com.example` + `ssw-boot`(用户改 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` + `` 排除 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")` | ## 跑通流程 ```bash # 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 的 + 。 # 用 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-/ # 包名 = ssw.,目录用小写连字符 ├── pom.xml # parent = ssw-boot ├── ssw--entity/ │ ├── pom.xml │ └── src/main/java/ssw//entity/Entity.java │ └─ extends SuperBaseEntity └── ssw--controller/ ├── pom.xml └── src/main/java/ssw// ├── controller/Controller.java │ └─ @RestController + @RequestMapping("/api/ssw//") └── mapper/Mapper.java └─ extends SuperMapper<Entity> ``` **业务 Controller 三端点**(参考 `ssw-demo/ssw-demo-controller/.../DemoController.java`): ```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` 的 `` 加: ```xml com.myorg ssw--controller ${project.version} ``` 并在 `application-dev.yml` 加新业务库节点: ```yaml spring: datasource: dynamic: datasource: ssw-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 的 `` 用 `${project.version}` 占位,被 ssw-boot 继承后 `${project.version}` 展开成 `1.0.0-SNAPSHOT` | 父 POM 加 `7.0.0-RELEASE` 属性 + `` 显式锁 `jnpf-common-core/-database/-auth/-redis` 四个最常用的版本号 | | 2 | **`SuperBaseEntity` 泛型基类 `getId()` 返 Object** | `DemoEntity extends SuperBaseEntity` 不带 `` → `getId()` 编译期解析为 `Object` → `.isBlank()` 报"找不到符号" | `DemoEntity` 显式 `extends SuperBaseEntity`(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` 加 `repackage` | 最终产物验证(jar 内部字节码层): ```text $ 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,本机需先: ```bash # 假设本机 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 的 `` 一行 + 补 dependencyManagement 里没列到的 jnpf-* artifact(编译报错时会点名)。 > 配套自检脚本:`bash scripts/verify.sh` — 自动跑这 5 项 + jar 字节码级检查(`@DS` 注解值 / Manifest 的 Start-Class / dependencyManagement 锁版本)。改名 / 换包后忘了某项跑这个脚本能立即定位,不会等到运行时才发现。