- 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/:前端接口清单、页面依赖反查、运行时探针
245 lines
14 KiB
Markdown
245 lines
14 KiB
Markdown
# 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 锁版本)。改名 / 换包后忘了某项跑这个脚本能立即定位,不会等到运行时才发现。 |