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

245 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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")` |
## 跑通流程
```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 的 <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`):
```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>` 加:
```xml
<dependency>
<groupId>com.myorg</groupId>
<artifactId>ssw-<your-appcode>-controller</artifactId>
<version>${project.version}</version>
</dependency>
```
并在 `application-dev.yml` 加新业务库节点:
```yaml
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 内部字节码层):
```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 的 `<jnpf.version>` 一行 + 补 dependencyManagement 里没列到的 jnpf-* artifact(编译报错时会点名)。
> 配套自检脚本:`bash scripts/verify.sh` — 自动跑这 5 项 + jar 字节码级检查(`@DS` 注解值 / Manifest 的 Start-Class / dependencyManagement 锁版本)。改名 / 换包后忘了某项跑这个脚本能立即定位,不会等到运行时才发现。