- boot/ (Java/Maven, JNPF 7.0) — 移除旧的 boot/.git,源码直接纳入仓库
- web/ (Vue 3 + Vite + Ant Design Vue, pnpm)
- docs/, scard/, nax/
- refs/INDEX.md + refs/国标/(其余 refs/* 开源子仓库不纳入)
- 已忽略: connector_data/, jweb/, log/, web/{dist,node_modules,.pnpm}, boot/*/target/, .DS_Store, .idea, .vscode
87 KiB
按 JNPF 规范快速搭建后端框架(SSW 公司内部规范)· 增强版
适用版本:JNPF 7.0.0-RELEASE(Spring Boot 3.5.x,jakarta.*,Java 21 运行时 / 编译目标 17) 适用场景:在 JNPF 低代码平台之上,挂载自有业务模块,复用其登录/鉴权/ORM/响应体系,同时不污染 JNPF 自身包。 编写依据:本版基于原
JNPF_BACKEND_GUIDE.md,通过一个仅依据原文档、从零搭建可编译可运行脚手架(位于本仓库boot/+tss-web/,app_code=tss)的实践,逐项核对并修正了原文档中所有会导致「编译失败 / 打包失败 / 启动即崩 / 静默失效」的问题。 状态:已验证可落地(增强版修正项均已用真实构建复核) 原文档JNPF_BACKEND_GUIDE.md保持不动,本文件为修正后的新版本。
示例占位约定:本文沿用原文档的
sswflow作为app_code示例(保持可复用),实际落地时按规则替换:sswflow → <你的 app_code>、Sswflow → <AppCode>、SswflowXxxService → <AppCode>XxxService、库 sswflow → <你的 app_code>、API /api/ssw/sswflow → /api/ssw/<你的 app_code>。 关键:业务库名 == app_code(双库架构下每个 app_code 独立库,dynamic.datasource.<app_code>与@DS("<app_code>")同名)。已落地验证:
tss(首版):脚手架见boot/与tss-web/,可直接对照。tss2(二次验证,本仓库tss2/):仅依据本指南、不参考任何其它脚手架、不启用容器,从零落地第二个应用。后端mvn -o package -pl ssw-admin -am构建通过、前端npm run build通过、密码算法自检 PASS。证明本指南可复用;落地中暴露的缺口已在 第十六节 补齐。tss2 命名映射见 16.1。
〇、核心结论(先看这段)
- 不要从零写框架——直接复用 JNPF 的
boot启动模块 +jnpf-common-all依赖栈。你只需要写业务包。 - 业务包三层结构:
ssw-{app_code}-entity/-biz/-controller,全部挂在ssw-{app_code}父 pom 下。 - API 前缀:
/api/ssw/{app_code}/...,与 JNPF 的/api/...并存不冲突。 - 双库架构(必做):JNPF 系统表走
master(库j7),你的业务表放独立业务库(库sswflow),用@DS("sswflow")切换。JNPF 内置dynamic-datasource,这是平台标准机制。 - 鉴权完全复用 JNPF:Sa-Token +
/api/oauth/Login,前端只负责"加密密码 + 原样带 token"。 - 两个必踩的碰撞坑(不处理就启动即崩):Spring bean 名冲突、MyBatis type-alias 冲突。
- ⚠️ 最易翻车的两类"静默/硬失败"已在本版订正:
scanBasePackages必须写 Java 顶级包jnpf(不是 Maven groupIdcom.jnpf),写错无报错但鉴权/数据源全失效(见 〇-A·A)。- 打包后启动会
NoClassDefFoundError: ThreadPoolExecutorUtil——META-INF/spring/...ApplicationContextInitializer被 repackage 提到 fat-jar 根目录后读不到,必须代码注册 initializer(见 〇-A·F、§12.1)。
- JNPF 源码只需本地
~/.m2有 jar 即可:私有仓库要鉴权,离线mvn拉不到jnpf-common-*的 jar。首次按「〇-B.1」clone 并mvn install进本地仓库;之后只要~/.m2里com/jnpf/**的 jar 还在(本机留存或拷自他人),直接编译业务模块即可。
〇-A、相对原版的修正清单(速览)
| 编号 | 原文档位置 | 原文档问题 | 本版修正 | 严重程度 |
|---|---|---|---|---|
| A | §〇-B.3(2)、§3.2、§14-2 | scanBasePackages={"com.jnpf","ssw"} |
改为 {"jnpf","ssw"};明确 com.jnpf 只是 Maven groupId,Java 顶级包是 jnpf |
🔴 静默失效(无报错,鉴权/DS 全挂) |
| B | §4.1、§4.2、§9.3 | extends EntityBase |
改为 extends SuperEntity<String>(EntityBase 在 7.0.0 不存在) |
🔴 编译失败 |
| C | §3.2 | entity pom 裸写 mybatis-plus-boot-starter / dynamic-datasource-spring-boot-starter 且无 <version> |
删除这两个依赖(随 jnpf-common-all 传递引入);确需锁版本必须显式写 <version> |
🔴 mvn validate 失败(缺 version) |
| D | §3.2 | 未说明 lombok 需自行声明 | entity(及用 @Data 的模块)pom 显式加 org.projectlombok:lombok(scope=provided);父 pom 全局加一份 |
🔴 编译失败(找不到 getXxx()) |
| E | §〇-B.3 末、§12、§14 | mvn package -DskipTests -pl ssw-admin -o |
改为 mvn -o package -DskipTests -pl ssw-admin -am(-am 把业务模块纳入 reactor) |
🔴 打包失败(解析不到 ssw-tss-controller) |
| F | §〇-B.3(4)、§12.1 | jnpf.SpringContext(FQN 错);仅靠 META-INF 文件注册 |
FQN 改为 jnpf.util.context.SpringContext;且必须在 SswAdminApplication.main() 代码注册 initializer |
🔴 打包后启动 NoClassDefFoundError |
| G | §9.4 | getDataSource() 签名/返回值说明含糊 |
接口实为 <T extends DataSourceUtil> T getDataSource(),init(String) 返回 DbLinkEntity(其父类即 DataSourceUtil),原写法可编译,补澄清 |
🟡 澄清(原代码能编) |
| H | §8.2 | 旧版把内层写成 MD5(密码) 误判为 bug;后又把「原始明文」错当成唯一标准 |
最终定稿为双约定模型:传输层内层 S 有两种——官方默认 S = md5(明文)(96-hex,d4958348…),旧变体 S = 明文(32-hex,ea80d323…);存储层随之 md5(S + f_secretkey.toLowerCase())。两条约定都合法但互不相通,关键看账号 f_password 用哪种。关键陷阱:SecurityProperties setter 内部自动 MD5 → 16 字符 key 实际变 32 字节 = AES-256。dacli src/core/crypto.ts 与 tss2 实测均为官方约定 |
🔴 算法级错误(选错约定即登录失败) |
| I | §12.2 | 只有片段 | 提供零依赖 scripts/smoke.mjs(自检+登录+业务接口,支持 --base/--account/--password/--key/--appcode) |
🟢 可验证性 |
| J | §〇-B.3、application.yml | 未要求 allow-bean-definition-overriding |
application.yml 必须 spring.main.allow-bean-definition-overriding: true(JNPF 内部同名 bean) |
🔴 启动失败 |
| K | §12.1、application.yml | 未要求 mvc.pathmatch 策略 |
spring.mvc.pathmatch.matching-strategy: ant_path_matcher(JNPF 用 ant 路径匹配) |
🔴 启动/路由异常 |
| L | §8.2-B | 未解释自建账号登录报 400 账号权限不足 |
给出根因(超管旁路硬编码只认账号名 admin,非 admin 必须挂角色且角色有 base_authorize)+ 挂「管理员」角色 SQL + 登录错误码速查(LOG101/LOG004/LOG005/OA013) |
🔴 自建账号无法登录 |
| M | §16.6 | 未记录运行期实测坑 | 新增「运行期实测暴露的 5 个坑」:SERVER__PORT 端口漂移、容器名≠发布端口+Redis 未映射、dynamic.datasource 少一层、base-path 不可写、后台进程被 shell 回收 |
🟡 排障加速 |
| N | §16.8 | 未给造验证账号脚本 | 新增「造验证账号完整脚本」:md5(明文+secretkey.toLowerCase()) 算 f_password + 复制 admin 行插 base_user + 插 base_role_relation(含 ON CONFLICT 处理) |
🟢 可复现 |
严重程度图例:🔴 阻断(编不过/起不来) 🟡 澄清 🟢 增强可验证性
〇-B、环境准备:获取官方源码 / 私服 / 数据库中间件 / admin 骨架
这一节是「前置的前置」——在写任何业务代码之前,先把官方源码拿到、私服配通、数据库与 Redis 跑起来、boot 启动骨架复制好。 参考:
~/Desktop/workspace/jnpf/init/start.md、JNPF 官方jnpf-java-boot/README.md。
〇-B.1 从官方仓库 git clone JNPF 7 后端源码
官方仓库托管在 coding.jnpfsoft.com,后端按模块拆分,每个模块是独立 git 仓库,统一挂在 /v7.0/<module> 路径下。
官方根域:https://coding.jnpfsoft.com/v7.0/<module>
登录账号:[email protected]
登录密码:jnpf@ssw
后端核心模块清单(按 start.md):
| 模块 | 说明 |
|---|---|
jnpf-java-boot |
聚合工程(含 jnpf-admin 子模块),编译入口 |
jnpf-common |
Java 基础依赖项目源码(被所有模块依赖) |
jnpf-java-ai-core |
AI 核心依赖源码 |
jnpf-file-core-starter |
文件基础依赖 |
jnpf-workflow / jnpf-workflow-core |
Flowable 流程引擎 |
jnpf-bpmn |
BPMN 相关 |
jnpf-datareport / jnpf-java-datareport-univer(-core) |
报表 |
jnpf-scheduletask |
任务调度 |
jnpf-java-tenant |
多租户(按合同交付) |
jnpf-database |
数据库脚本仓库(j7 / j7flow / j7xxl 初始化 SQL) |
jnpf-resources |
静态资源(ip2region、模板等) |
你只需要 clone
jnpf-java-boot一个仓库——它是聚合工程,pull 下来后内部jnpf-admin子模块、以及它依赖的jnpf-common等兄弟模块,都要各自 clone 到同级目录才能mvn install(聚合 pom 用相对路径引用兄弟模块)。
增量复用(核心:别每次全量 clone)
场景 做法 首次拿到源码 按下面 git clone把需要的模块拉到~/workspace/jnpf(平级目录)已 clone 过,要更新 进各模块目录 git pull(不要重新 clone)~/.m2里com/jnpf/**的 jar 还在(同机留存或拷自他人)根本不需要源码:直接 mvn package你的业务模块即可;源码仅在你改了 JNPF 自身代码时才需重新mvn install只缺某几个模块 jar cd ~/workspace/jnpf/<module> && mvn install -DskipTests(无需重装全部)一句话:
git clone是一次性动作;mvn install把 jar 沉淀到~/.m2之后,日常只跟自己的业务模块打交道。 同机协作时,把~/.m2/repository/com/jnpf整体拷给对方,对方连 clone 都省了。
# 1) 建一个总目录,所有 JNPF 模块平铺其中(路径禁止含中文/空格/特殊字符,README 特别说明)
mkdir -p ~/workspace/jnpf && cd ~/workspace/jnpf
# 2) clone 聚合工程(仅【首次】需要;之后用 git pull 更新,见上表)
git clone https://coding.jnpfsoft.com/v7.0/jnpf-java-boot.git
# 3) clone 它依赖的兄弟模块(与 jnpf-java-boot 同级)
git clone https://coding.jnpfsoft.com/v7.0/jnpf-common.git
git clone https://coding.jnpfsoft.com/v7.0/jnpf-java-ai-core.git
git clone https://coding.jnpfsoft.com/v7.0/jnpf-file-core-starter.git
git clone https://coding.jnpfsoft.com/v7.0/jnpf-workflow.git
git clone https://coding.jnpfsoft.com/v7.0/jnpf-workflow-core.git
# ... 其余模块按需 clone(见上表)
# 4)(可选)数据库脚本与静态资源
git clone https://coding.jnpfsoft.com/v7.0/jnpf-database.git
git clone https://coding.jnpfsoft.com/v7.0/jnpf-resources.git
# 免去每次输密码:把凭据缓存到 ~/.git-credentials
git config --global credential.helper store
踩坑提示(来自 start.md):若某模块目录缺失文件,直接用上面的官方账号从对应仓库
git clone补齐即可;官方包地址/账号密码齐全,缺的都能下到。
〇-B.2 配置 Maven settings.xml 引用官方私服
JNPF 的依赖(jnpf-common-*、dynamic-datasource 等定制版)不在 Maven Central,只在官方私服 maven-releases。不配私服会 Could not resolve ... 401/404,离线环境更是直接编不过。
7.0 的
jnpf-dependencies内部仓库声明用的是http://nexus.jnpfsoft.com/repository/maven-public/,而官方 README 文档写的是https://repository.jnpfsoft.com/repository/maven-public/。两者 server id 都是maven-releases,所以只要下面 settings.xml 里<server>的 id 配成maven-releases,就能同时覆盖这两种地址。
放在哪:用户级 ~/.m2/settings.xml(推荐),或 Maven 安装目录 conf/settings.xml。在对应节点里加入:
<!-- 1) <servers> 里加:私服账号密码(id 必须叫 maven-releases) -->
<server>
<id>maven-releases</id>
<username>[email protected]</username>
<password>ssw222666</password>
</server>
<!-- 2) <mirrors> 里加:把所有下载请求镜像到官方私服(README 官方写法) -->
<mirror>
<id>maven-releases</id>
<mirrorOf>*</mirrorOf>
<name>maven-releases</name>
<url>https://repository.jnpfsoft.com/repository/maven-public/</url>
</mirror>
配好后
mvn就能从官方私服拉依赖。IDEA 若出现部分依赖报红,重启 IDEA 清缓存即可(README 原话)。 注意~/.m2/settings.xml默认是 Maven 的示例模板,本身没有任何<server>,初次使用时务必补上上面的内容。
〇-B.3 复制 jnpf-java-boot/jnpf-admin → boot/ssw-admin(有部分需要调整)
jnpf-admin 是聚合工程 jnpf-java-boot 下的可运行 jar 模块——它自己不编 JNPF 各 controller 源码,只 pom 依赖 jnpf-*-controller 等 jar(这些 jar 来自 〇-B.1 的 mvn install)。我们要做的,就是把它整体复制成自己的 ssw-admin 启动骨架,再改少量配置。
源 → 目标:
jnpf-java-boot/jnpf-admin/ ──复制──▶ boot/ssw-admin/
├── pom.xml
├── src/main/java/jnpf/ ──包名 jnpf → ssw──▶ src/main/java/ssw/
└── src/main/resources/ ──整目录拷──▶ src/main/resources/
├── application.yml / application-dev.yml
├── application-{dev,test,prod,preview}.yml
├── mapper/ i18n/ logback-spring.xml ip2region/ sharding-sphere.yml
├── static/ (no-spa 静态页,用 Vite 独立前端可删)
└── META-INF/spring/... (若已有 initializer 文件,保留)
必须调整的部分(否则编不过或跑不起来):
-
pom.xml父子关系<parent>从jnpf-java-boot改成你自己的聚合父ssw-boot(或直连jnpf-common)。<artifactId>改成ssw-admin。<dependencies>保留 JNPF 各*-controller(完整清单见 §3.2 末的ssw-admin/pom.xml示例);新增你自己的业务 controller,例如:<dependency> <groupId>com.jnpf</groupId> <artifactId>ssw-sswflow-controller</artifactId> <version>${project.version}</version> </dependency>注意
<groupId>com.jnpf</groupId>这里是对的——它是 Maven 坐标的 groupId;只有 Java 源码包名才是jnpf(见第 2 点)。<profiles>里的boot3(jdk[17,)激活jnpf-ai-v3-controller)原样保留——它正是 Boot 3 下启用 AI controller 的关键。
-
包名
jnpf→sswsrc/main/java/jnpf/整个包重命名为ssw/,启动类JnpfAdminApplication→SswAdminApplication。- ⚠️ 【修正 A】
scanBasePackages必须写 Java 顶级包jnpf,不能写 groupIdcom.jnpf:写成@SpringBootApplication(scanBasePackages = {"jnpf", "ssw"}){"com.jnpf","ssw"}会导致 JNPF 的自动配置(Sa-Token、dynamic-datasource、MyBatis 等)全部不生效,且启动时不报任何错,表现为登录 404 / 注入失败,极难排查。com.jnpf只是pom.xml的<groupId>与依赖坐标前缀,与 Java 包名无关。 - 同时
@MapperScan要覆盖两侧:@MapperScan({"jnpf.**.mapper", "ssw.**.mapper"})。
-
白名单 / AuthFilter
- 用独立 Vite 前端时,
gateway.exclude-url保留 JNPF 默认即可(无需/ssw/**)。 - 若仍塞 no-spa 静态页,需加
- /ssw/**(见第 8.4 节)。
- 用独立 Vite 前端时,
-
Boot 3 两个补丁(否则登录时
NoClassDefFoundError: ThreadPoolExecutorUtil)- 提供
applicationTaskExecutorbean(JNPF 的ThreadPoolExecutorUtil静态块依赖它)。示例见ssw/config/TaskExecutorConfig.java。 - 【修正 F,关键】注册
SpringContextinitializer 有两条路径,缺一条都会炸:- (a) 文件
src/main/resources/META-INF/spring/org.springframework.context.ApplicationContextInitializer,内容一行:(原文档写的jnpf.util.context.SpringContextjnpf.SpringContext是错的,全限定名是jnpf.util.context.SpringContext。) - (b) 并且在
SswAdminApplication.main()里代码注册(这才是打包后可靠的方式):SpringApplication application = new SpringApplication(SswAdminApplication.class); application.addInitializers(new jnpf.util.context.SpringContext()); application.run(args); - 为什么必须代码注册:
spring-boot-maven-plugin在repackage时会把target/classes/META-INF/提升到 fat-jar 根目录,而 Boot 3 的LaunchedClassLoader只加载BOOT-INF/classes与BOOT-INF/lib/*.jar——根目录的META-INF/spring不在 classpath 上。于是打成 jar 后该文件读不到,启动表现为NoClassDefFoundError: Could not initialize class jnpf.util.ThreadPoolExecutorUtil。代码注册不受打包结构影响,是最可靠的路径;文件 (a) 作为 IDE 直跑时的双保险保留。
- (a) 文件
- 提供
-
application-dev.yml数据源与 Redisspring.datasource.db-name: j7(master 系统库),host/port/username/password指向你的 PG。spring.redis.redisson.config的address指向你的 Redis 实例,password与 Redis 实际密码对齐(JNPF 默认123456,纯镜像无密码时要二选一对齐,见 §11)。dynamic.datasource.sswflow业务库节点按第 9.2 节声明。
-
可选清理
- 用 Vite 独立前端可删除
src/main/resources/static/ssw/**(不影响启动)。 - 不用的 JNPF 模块依赖可在
pom里裁剪,但建议先全留、跑通后再减。
- 用 Vite 独立前端可删除
【修正 E】复制完成后构建命令:
cd boot && mvn -o package -DskipTests -pl ssw-admin -am必须带
-am(also-make)——否则 reactor 里没有ssw-tss-*业务模块,会报Could not resolve com.jnpf:ssw-tss-controller:... has not been downloaded。 成功产物:ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar。
〇-B.4 安装 j7 数据库与 Redis(镜像方式,最快)
为了快速起环境,直接用阿里云个人版容器镜像仓库的现成镜像(PostgreSQL 16 + Redis),免去了手动装数据库。
镜像地址:
PostgreSQL:crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/postgres:16-alpine
Redis: crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/redis:latest
# 1) 拉取镜像
docker pull crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/postgres:16-alpine
docker pull crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/redis:latest
# 2) 起 PostgreSQL(用户名/密码/默认库 与 JNPF 约定一致:dacli / dacli123 / j7)
docker run -d --name jnpf-postgres -p 15432:5432 \
-e POSTGRES_USER=dacli -e POSTGRES_PASSWORD=dacli123 -e POSTGRES_DB=j7 \
crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/postgres:16-alpine
# 3) 起 Redis(JNPF 默认 redisson 密码 123456;纯镜像无密码,这里用无密码启动,
# 然后把 application-dev.yml 的 redisson password 清空对齐;或加 --requirepass 123456)
docker run -d --name jnpf-redis -p 6379:6379 \
crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/redis:latest
# 4) 验证
docker ps | grep -E "jnpf-postgres|jnpf-redis"
初始化 j7 主库(来自官方 jnpf-database 仓库):
不必 clone 整个
jnpf-database仓库(体积大,平时只盯 SQL)。只需拿到下面 3 个.sql即可——用git sparse-checkout只拉 SQL 所在的目录,或直接从仓库下载对应文件:# 只取 SQL,不拉全量仓库(--sparse 后按需 set 目录) git clone --filter=blob:none --sparse https://coding.jnpfsoft.com/v7.0/jnpf-database.git cd jnpf-database && git sparse-checkout set <jnpf_db_init / jnpf_flow_init / jnpf_xxljob_init 所在目录>若同机
~/.m2已沉淀 JNPF 源码,jnpf-database/通常已在~/workspace/jnpf/下,直接复用即可。
start.md 明确:只需装 以下三个;
JNPF-PostgreSQL.sql是租户初始库,不要装。
| 脚本 | 导入目标库 |
|---|---|
jnpf_db_init |
j7(JNPF 主库,承载 base_user/组织/权限/字典) |
jnpf_flow_init |
j7flow(Flowable 流程引擎库) |
jnpf_xxljob_init |
j7xxl(XXL-JOB 调度库) |
# 进入 PG 容器用 psql 导入(脚本从 jnpf-database 仓库取得)
docker exec -i jnpf-postgres psql -U dacli -d j7 < /path/to/jnpf-database/jnpf_db_init.sql
docker exec -i jnpf-postgres psql -U dacli -d j7flow < /path/to/jnpf-database/jnpf_flow_init.sql
docker exec -i jnpf-postgres psql -U dacli -d j7xxl < /path/to/jnpf-database/jnpf_xxljob_init.sql
# 另建业务库 sswflow 并执行你的建表脚本(见第 9 / 11 节)
docker exec -i jnpf-postgres psql -U dacli -d postgres -c "CREATE DATABASE sswflow;"
docker exec -i jnpf-postgres psql -U dacli -d sswflow < /path/to/sswflow/boot/db/V1.0.0__schema.sql
网络与访问(重要):
- 容器内互相用容器名
jnpf-postgres/jnpf-redis解析;宿主机若用.orb.local或容器 IP,启动 jar 时用-DDB_HOST=... -DREDIS_HOST=...覆盖(详见第 11 节 Netty DNS 注意)。 - 若宿主机直接用容器 IP(如 OrbStack 下
192.168.97.3:5432/192.168.97.2:6379),把application-dev.yml的 host 改成 IP 最稳。
一、整体工程结构
boot/ # 启动模块(拷贝 JNPF 的 boot 骨架)
├── pom.xml # 父:ssw-boot → jnpf-common → jnpf-dependencies
├── ssw-{app_code}/ # 你的业务父模块
│ ├── pom.xml # 聚合 entity/biz/controller
│ ├── ssw-{app_code}-entity/ # 实体 + MyBatis XML
│ ├── ssw-{app_code}-biz/ # Service 接口 + Impl + Mapper(含 @DS)
│ └── ssw-{app_code}-controller/ # Controller(REST 入口)
└── ssw-admin/ # 可运行 jar 聚合模块(打最终 boot jar)
└── src/main/resources/ # application.yml / application-dev.yml / static
命名约定:
{app_code}用小写驼峰,例如sswflow。所有包名、bean 名、alias 都要带Sswflow/sswflow前缀,这是避免与 JNPF 内部类冲突的唯一手段(详见第八节)。
二、前置:编译 JNPF 源码(一次性,约 7 分钟)
JNPF 的 jnpf-common-all 等构件不在公网 Maven 仓库,私有仓库需鉴权,离线构建会失败。
# 1. 取得官方源码(git clone 步骤见「〇-B.1」;私服配置见「〇-B.2」)
# 至少 clone 聚合工程 jnpf-java-boot 及其依赖的兄弟模块(jnpf-common 等)到同级目录
cd /path/to/jnpf-java-boot
# 2. 一次性编译安装到本地仓库(跳过测试/文档/gpg,否则很慢)
mvn clean install -DskipTests -Dmaven.javadoc.skip=true -Dgpg.skip=true
完成后 ~/.m2/repository/com/jnpf/** 会出现 jnpf-common-all、jnpf-common-core、jnpf-oauth-* 等全部 jar,你的业务模块才能编译。
验证:
ls ~/.m2/repository/com/jnpf/jnpf-common-all/7.0.0-RELEASE/应有 jar。
三、Maven 关键配置
3.1 boot3 profile 会锁死 Java 版本
jnpf-dependencies 的 boot3 profile 把 maven.compiler.source 锁成 8(为了 JNPF 自有模块向后兼容)。你的新代码要用 Java 17 语法(switch 表达式、instanceof 模式匹配等),必须在你的业务模块 pom 里覆盖——最省事是在聚合父 ssw-boot/pom.xml 的 <properties> 统一设:
<!-- ssw-boot/pom.xml 的 properties(父链:ssw-boot → jnpf-common → jnpf-dependencies) -->
<properties>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
<java.version>17</java.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<!-- JNPF 平台构件统一版本 -->
<jnpf.version>7.0.0-RELEASE</jnpf.version>
<!-- 本工程 app_code,贯穿包名/bean名/API前缀/业务库名 -->
<ssw.app-code>sswflow</ssw.app-code>
</properties>
不覆盖会报:-source 8 中不支持 switch 表达式 / instanceof 模式匹配。
3.2 业务包父链与依赖
你的 ssw-admin(打 jar)
└─ 依赖 ssw-{app_code}-controller
└─ 依赖 ssw-{app_code}-biz
└─ 依赖 ssw-{app_code}-entity
└─ 依赖 jnpf-common-all(提供 SuperEntity / ActionResult / @DS / Sa-Token 等)
【修正 C/D】
ssw-{app_code}-entity/pom.xml关键依赖(正确写法):<dependencies> <!-- jnpf-common-all 提供: jnpf.base.entity.SuperEntity / SuperBaseEntity(公共字段,已映射 f_xxx 列) jnpf.base.ActionResult / jnpf.base.vo.PageListVO jnpf.base.service.SuperServiceImpl / jnpf.base.mapper.SuperMapper Sa-Token、dynamic-datasource(@DS)等整套依赖 --> <dependency> <groupId>com.jnpf</groupId> <artifactId>jnpf-common-all</artifactId> <version>${jnpf.version}</version> </dependency> <!-- lombok:JNPF 侧是 provided scope,不会传递到你的模块。 业务实体若使用 @Data/@Getter 必须自行声明,否则编译报 "找不到符号 getXxx()"。 放在 entity 模块;若 biz/controller 也用 lombok,同样加。 --> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <scope>provided</scope> </dependency> <!-- ⚠️ 不要照搬"只写 groupId/artifactId 不写 version"的写法: jnpf-common 的 dependencyManagement 并未托管 mybatis-plus-boot-starter / dynamic-datasource-spring-boot-starter,缺 version 会直接构建失败: 'dependencies.dependency.version' for com.baomidou:... is missing 这两者已由 jnpf-common-all 传递引入(MyBatis-Plus 3.5.x + dynamic-datasource 4.x), 正常情况【无需声明】。若确需锁版本,必须显式写 <version>。 --> </dependencies>
父
ssw-boot/pom.xml也可以全局给一份 lombok(继承给所有子模块),与本模块声明二选一即可:<dependencies> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <scope>provided</scope> </dependency> </dependencies>
ssw-admin/pom.xml 依赖 JNPF 各 controller(完整清单,缺一不可,否则登录//api 能力缺失):
<dependencies>
<!-- 自有业务模块 -->
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>ssw-sswflow-controller</artifactId>
<version>${project.version}</version>
</dependency>
<!-- JNPF 平台 controller:登录 /api/oauth/Login 由 jnpf-oauth-controller 提供,必需 -->
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-oauth-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-permission-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-system-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-file-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-message-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-extend-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-flowable-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-scheduletask-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdev-base-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdev-generater-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdev-onlinedev-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdev-portal-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdata-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-app-controller</artifactId><version>${jnpf.version}</version></dependency>
</dependencies>
<profiles>
<!-- boot3:JDK 17+ 启用 AI v3 controller,原样保留 -->
<profile>
<id>boot3</id>
<activation><jdk>[17,)</jdk></activation>
<dependencies>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-ai-v3-controller</artifactId>
<version>${jnpf.version}</version>
</dependency>
</dependencies>
</profile>
</profiles>
<build>
<finalName>ssw-admin-${project.version}</finalName>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<mainClass>ssw.SswAdminApplication</mainClass>
<excludes>
<exclude>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</exclude>
</excludes>
</configuration>
<executions><execution><goals><goal>repackage</goal></goals></execution></executions>
</plugin>
</plugins>
</build>
四、实体层规范(entity)
4.1 字段命名:JNPF 风格 f_xxx
【修正 B】基类是
jnpf.base.entity.SuperEntity<T>(7.0.0 中EntityBase不存在)。 继承后,以下 9 个公共字段与列映射自动获得,不要在本类重复声明,否则 MyBatis-Plus 会因重复列名报错:
Java 字段(父类) 列名 说明 id(SuperBaseEntity)f_id@TableId,UUID 字符串tenantIdf_tenant_idcreatorTimef_creator_time默认 now()creatorUserIdf_creator_user_idlastModifyTimef_last_modify_timelastModifyUserIdf_last_modify_user_iddeleteMarkf_delete_markJNPF 约定 null=未删deleteTimef_delete_timedeleteUserIdf_delete_user_id
@Data
@EqualsAndHashCode(callSuper = true)
@Alias("SswflowProjectEntity") // ⚠️ 必须,防 MyBatis alias 碰撞(见第八节)
@DS("sswflow") // ⚠️ 必须,切到业务库(见第九节)
@TableName("project")
public class ProjectEntity extends SuperEntity<String> {
// 业务字段(公共字段已在父类,无需也不应重复声明)
@TableField("name")
private String name;
@TableField("project_code")
private String projectCode;
@TableField("compute_mode") // MPC / TEE / FL
private String computeMode;
@TableField("status") // DRAFT / ONLINE ...
private String status;
}
4.2 公共字段基线(建议)
| 字段 | 列名 | 说明 |
|---|---|---|
| 主键 | f_id |
@TableId,UUID 字符串(来自 SuperBaseEntity) |
| 创建时间 | f_creator_time |
默认 now() |
| 创建人 | f_creator_user_id |
|
| 修改时间 | f_last_modify_time |
|
| 修改人 | f_last_modify_user_id |
|
| 删除标记 | f_delete_mark |
JNPF 约定 null 表示未删除;查询条件 f_delete_mark is null |
| 租户 | f_tenant_id |
|
| 删除时间 | f_delete_time |
|
| 删除人 | f_delete_user_id |
查询存活数据统一用常量,例如
ALIVE = "f_delete_mark is null",默认排序f_creator_time desc。
五、Service 层规范(biz)
// 接口
public interface ProjectService extends IService<ProjectEntity> {
ActionResult<PageListVO> pageList(ProjectPageForm form);
void create(ProjectEntity e);
}
// 实现——⚠️ bean 名 + @DS 都必须显式指定
@Service("sswflowProjectService")
@DS("sswflow") // ⚠️ 切到业务库;注解不继承,子类必须各自打
public class ProjectServiceImpl extends SswflowServiceImpl<ProjectMapper, ProjectEntity>
implements ProjectService {
@Override
public ActionResult<PageListVO> pageList(ProjectPageForm form) {
// 用 MyBatis-Plus 分页;JNPF 分页包装见第六节
}
}
所有
@Service实现类都加@Service("sswflow<Short>Service")+@DS("sswflow"):
- bean 名防与 JNPF 内部 Service 碰撞(默认名会
ConflictingBeanDefinitionException);@DS把读写路由到业务库,否则会落到master(j7) 系统库。 推荐所有业务 Service 继承SswflowServiceImpl(见 9.4),统一获得@DS兜底与动态自愈能力。
六、Controller 层规范(controller)
// ⚠️ 必须显式 bean 名,JNPF 自带 jnpf.flowable.controller.OperatorController 会撞名
@RestController("sswflowProjectController")
@RequestMapping("/api/ssw/sswflow/Project")
public class ProjectController {
@Autowired
private ProjectService projectService; // 按 bean 名注入上面那个
@GetMapping("/All")
public ActionResult<List<ProjectEntity>> all() {
return ActionResult.success(projectService.list());
}
@GetMapping
public ActionResult<PageListVO> list(@RequestBody ProjectPageForm form) {
return projectService.pageList(form);
}
@PostMapping
public ActionResult<String> create(@RequestBody ProjectEntity e) {
projectService.create(e);
return ActionResult.success("ok");
}
}
6.1 响应封装(JNPF 约定)
| 场景 | 写法 | 返回形状 |
|---|---|---|
| 单对象/成功 | ActionResult.success(data) |
{code:200, data, msg:"Success"} |
| 分页 | ActionResult.page(list, pagination) |
{code:200, data:{list, pagination:{currentPage,pageSize,total}}} |
| 失败 | ActionResult.fail("msg") |
{code:非200, msg} |
| 登录过期 | 由 AuthFilter 统一返回 code:600 |
前端据此清 token 跳登录 |
分页
PageListVO结构:{ list: [...], pagination: { currentPage, pageSize, total } }。 前端约定:code !== 200即视为错误;code === 600(或 HTTP 401)视为未登录。
七、必踩的两个碰撞坑(不处理启动即崩)
7.1 Spring bean 名冲突
JNPF 自带 jnpf.flowable.controller.OperatorController、jnpf.*.service.OperatorService 等。你的同名 Controller/Service 会触发:
ConflictingBeanDefinitionException: bean name 'operatorController' ...
conflicts with jnpf.flowable.controller.OperatorController
解决:所有 Controller 加 @RestController("sswflowXxxController"),所有 Service Impl 加 @Service("sswflowXxxService")。
7.2 MyBatis type-alias 冲突
JNPF 已有 DataSetEntity(注意大小写),你的 DatasetEntity 在大小写不敏感匹配下会撞:
The alias 'DataSetEntity' is already mapped to 'ssw.sswflow.entity.DatasetEntity'
解决:每个实体加 @Alias("Sswflow<Entity>Entity")(如 SswflowDatasetEntity),并 import org.apache.ibatis.type.Alias;。
八、鉴权接入(复用 JNPF 体系,前端照做即可)
8.1 登录接口
POST /api/oauth/Login
Content-Type: application/x-www-form-urlencoded
Headers: App-Code: {app_code} # 例如 sswflow
Jnpf-Origin: pc
Vue-Version: 3
Body: account=admin&password=<密文>&grant_type=password
8.2 密码加密算法(前端/客户端实现)
【修正 H · 2026-08-01 最终定稿】 本节经「反编译官方字节码 + dacli 实测 + 本仓库
tss2运行期验证」三证对齐,结论:传输层内层字符串分两种约定,官方默认是md5(明文)。
约定 传输层内层 S 密文长度 存储 f_password谁在用 官方(默认) md5(明文)的 32 位 hex96 hex(48 字节) md5( md5(明文) + secretkey )JNPF 官方前端、 admin、dacli、本仓库tss2旧变体(legacy) 明文原文32 hex(16 字节) md5( 明文 + secretkey )部分老集成项目 两条约定都合法,但互不相通——关键看账号创建时存的是哪种
f_password。登录时后端先用DesUtil把密文解回内层字符串 S,再比md5(S + f_secretkey.toLowerCase())。所以:用官方前端 / dacli 建的账号(含admin)必须按官方约定登录;你自己造账号时可任选一种,只要f_password与约定配套(见 §16.8)。
务必先分清两条独立的链路,混淆是登录调不通的头号原因:
| 传输层(前端 → 后端) | 存储层(DB 里存什么) | |
|---|---|---|
| 用途 | 把密码从浏览器安全送到后端 | 校验密码是否正确 |
| 密钥 | 全局 security.security-key |
每个用户自己的 base_user.f_secretkey |
| 算法 | AES-256-ECB / PKCS7,输出 hex | MD5 摘要,不可逆 |
| 谁做 | 前端 crypto.js ↔ 后端 DesUtil.aesOrDecode |
后端 PasswordTokenGranter |
后端权威实现(jnpf-oauth-biz → jnpf.granter.PasswordTokenGranter#authenticatePassword):
String pwd = form.getPassword();
try {
pwd = DesUtil.aesOrDecode(pwd, false, true); // ① 传输层解密 → 拿回内层字符串 S
} catch (Exception e) {
log.error("{}:{}", MsgCode.OA013.get(), pwd, e);
pwd = "";
}
// ② 存储层比对:注意只对 secretkey 做 toLowerCase,S 原样拼接
if (!user.getPassword().equals(Md5Util.getStringMd5(pwd + user.getSecretkey().toLowerCase()))) {
throw new LoginException(MsgCode.LOG101.get()); // 密码错误
}
① 传输层:AES-256-ECB
DesUtil.aesOrDecode(data, isEncrypt=false, isAes=true) 展开后等价于:
输入 = hex 字符串 → HexUtil.decodeHex 还原字节
key = SecurityProperties.getInstance().getSecurityKey() 的 UTF-8 字节
算法 = SymmetricCrypto(AES, key) → JDK 默认 AES/ECB/PKCS5Padding
输出 = new String(内层字节, UTF-8)
关键陷阱:SecurityProperties.setSecurityKey() 的 setter 内部自动做了一次 MD5:
public void setSecurityKey(String v) {
this.securityKey = Md5Util.getStringMd5(v); // ← 配置值先被 MD5
}
所以配置里写 EY8WePvjM5GGwQzn(16 字符),实际参与运算的 key 是
md5("EY8WePvjM5GGwQzn") = 05b0175907a859751f57a04d5a5ee9ac(32 字符 hex 文本),
按 UTF-8 取字节 = 32 字节 → AES-256(不是 AES-128)。
这正好与前端 crypto.js 的 encryptAES(data, encryptByMd5(aesKey)) 对齐。
官方约定(默认,JNPF 前端 / admin / dacli / 本仓库 tss2 都用这个):内层 S = md5(明文),把它的 hex 字符串当明文做 AES:
CIPHER_KEY = EY8WePvjM5GGwQzn # 与后端 security.security-key 一致
key = md5(CIPHER_KEY) 的 32 位 hex 文本,UTF-8 取字节(32B,AES-256)
S = md5(明文密码) 的 32 位 hex 字符串
密文 = Hex( AES256_ECB_PKCS7( UTF8(S), key ) ) # 96 hex
旧变体(legacy,仅部分老集成项目):内层 S = 明文原文:
密文 = Hex( AES256_ECB_PKCS7( UTF8(原始明文密码), key ) ) # 32 hex
自检基准值(已用 Node
crypto与crypto-js双实现交叉验证,并跑通tss2真实登录):md5("EY8WePvjM5GGwQzn") = 05b0175907a859751f57a04d5a5ee9ac # 官方约定(默认) encryptPassword_official("123456") = d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b # 96 hex # 旧变体(legacy) encryptPassword_legacy("123456") = ea80d323686b9dfe734f2b42159db1a6 # 32 hex对不上就别往下试登录,一定是 key 或约定(官方 / 旧变体)选错了。
② 存储层:f_password 怎么算
# 官方约定(默认):S = md5(明文)
base_user.f_password = md5( md5(明文密码) + base_user.f_secretkey.toLowerCase() )
# 旧变体(legacy):S = 明文
base_user.f_password = md5( 明文密码 + base_user.f_secretkey.toLowerCase() )
f_secretkey是每个用户一条、互不相同的随机串,不是全局密钥。security-key只管传输,跟入库摘要毫无关系——这两个千万别搞混。- 造验证账号时,按你选的约定算好
f_password与f_secretkey一起 INSERT 即可(见 §16.8,本仓库tss2用官方约定)。
# 例:tss2dev 用【官方约定】生成 123456 的入库摘要(secretkey = tss2dev-secret-key-001)
node -e "const c=require('crypto');const m=s=>c.createHash('md5').update(s,'utf8').digest('hex');
console.log(m(m('123456')+'tss2dev-secret-key-001'))"
# => 2898aa333ba4efb48658db85e10d9fd9
反过来也说明:你无法从 DB 里反推别人的密码,也无法拿
admin的f_password去猜明文。 实测 j7 库admin的f_password与md5("123456"+其 secretkey)并不相等, 说明这套环境的 admin 密码不是 123456 —— 别浪费时间试,自己造账号(见 §16.4)。
8.2-B 【新增】自建账号登录报「账号权限不足」(LOG004)
现象:密码算得完全正确,登录却返回 {"code":400,"msg":"账号权限不足"}。
根因(jnpf-oauth-biz → jnpf.service.impl.LoginServiceImpl):
// 超管旁路:账号名必须字面量等于 "admin",且 is_administrator == 1
if (!("admin".equals(user.getAccount()) && user.getIsAdministrator() == 1)) {
List<String> objectIds = 用户的岗位ID列表(position);
objectIds.add(user.getId());
List<?> roles = roleRelationApi.getListByObjectId(objectIds, null); // base_role_relation
List<String> all = objectIds + roles.map(角色ID);
if (CollUtil.isEmpty(all) || CollUtil.isEmpty(authorizeApi.getListByObjectId(all))) {
throw new LoginException(MsgCode.LOG004.get()); // 账号权限不足
}
}
踩坑要点:
- 旁路条件是账号名硬编码字面量
"admin"。你把自建账号的f_is_administrator设成 1 没用,只要账号不叫admin就照样走权限检查。 - 检查的是:
base_role_relation(用户/岗位 → 角色)关联出的对象,在base_authorize里至少有一条授权记录。 - 光有角色还不够,那个角色必须真的有
base_authorize数据。
解法:给自建账号挂一个已有授权数据的角色。先查有哪些角色可用:
-- 看哪些角色真的有授权记录
SELECT r.f_id, r.f_full_name, count(a.f_object_id) AS 授权数
FROM base_role r JOIN base_authorize a ON a.f_object_id = r.f_id
GROUP BY r.f_id, r.f_full_name ORDER BY 授权数 DESC;
-- 666911261245571844 | 管理员 | 101
-- 666911261245571845 | 开发者 | 84
-- 666911261245571846 | 使用者 | 18
-- 挂上「管理员」角色(f_object_type 固定 'user',f_tenant_id 非空约束,填 '' 即可)
INSERT INTO base_role_relation
(f_id, f_role_id, f_object_type, f_object_id, f_creator_time, f_creator_user_id, f_delete_mark, f_tenant_id)
VALUES ('tss2dev-rel-001', '666911261245571844', 'user', 'tss2dev-001', now(), 'tss2dev-001', 0, '');
另外
base_user.f_enabled_mark必须为1。从 admin 行 copy 建账号时这列容易带成 NULL, 非超管路径会因此抛LOG005。建完记得UPDATE base_user SET f_enabled_mark=1 WHERE f_account='xxx';
登录错误码速查:
| code | 含义 | 检查方向 |
|---|---|---|
LOG101 密码错误 |
传输层解密后与 f_password 对不上 |
§8.2 两条链路是否搞混 |
LOG004 账号权限不足 |
无角色 / 角色无 base_authorize |
本节,挂角色 |
LOG005 账号已禁用 |
f_enabled_mark 不是 1 |
UPDATE 该列 |
OA013(日志里) |
传输层 AES 解密抛异常 | 密文不是 hex / key 不对 |
8.3 Token 传递(最容易被坑的一点)
- 登录返回的
data.token形如bearer eyJhbGciOi...(已带bearer前缀)。 - Sa-Token 配置:
getTokenName()="Authorization"、getTokenPrefix()="bearer"、isReadHeader=true。 - 前端必须原样把登录返回的整串作为
Authorization头值发送,Sa-Token 会按前缀bearer(小写)剥离。
Authorization: bearer eyJhbGciOi... # ✅ 原样
Authorization: Bearer eyJ... # ❌ 大写 B 不会被剥离 → 600 登录过期
Authorization: bearer bearer eyJ... # ❌ 叠两层 → 600
8.4 白名单配置
AuthFilter 拦截 /**(含静态资源)。登录页、静态资源、登录接口必须放行:
# application.yml(JNPF 网关配置区)
gateway:
exclude-url: # 免 Token 且不记录日志
- /api/oauth/Login
- /static/**
# 用独立 Vite 前端时无需 /ssw/**;若塞 no-spa 静态页再加 - /ssw/**
九、多数据源 @DS 规范(JNPF 标准机制,必做)
JNPF 内置 dynamic-datasource-spring-boot-starter,通过 @DS 注解在运行时切换数据源。接入业务模块应当采用「系统库 + 业务库」双库架构,业务表独立成库,用 @DS 切换——这既是 JNPF 自身的标准做法(其 permission / visualdev / generater 模块同样用 @DS 分库),也符合公司「每 app_code 独立库」的规范。
9.1 双库架构
| 源 | 角色 | 库名 | 承载内容 |
|---|---|---|---|
master(默认 primary) |
JNPF 平台主库 | j7 |
base_user、组织、权限、字典等系统表 |
sswflow(业务源) |
SSWFlow 业务库 | sswflow(可用 ${SSWFLOW_DB} 覆盖) |
你的业务表 |
master无需显式声明:由MybatisPlusConfig#initPrimaryDataSource从spring.datasource.*主配置自动补全。- 业务代码一律
@DS("sswflow"),登录/鉴权/系统查询走master。
9.2 配置(application-dev.yml)
spring:
datasource:
db-name: j7 # 主库(JNPF 系统库)
host: ${DB_HOST:jnpf-postgres}
port: ${DB_PORT:5432}
username: ${DB_USER:dacli}
password: ${DB_PWD:dacli123}
dynamic:
primary: master # 默认数据源
strict: true # 严格匹配:true-未匹配到源直接抛异常;false-降级用默认源
druid: # 连接池参数(略)
initial-size: 4
max-active: 20
datasource:
# 业务库只需声明这一个节点;master 由框架自动补全
sswflow:
url: jdbc:postgresql://${spring.datasource.host}:${spring.datasource.port}/${SSWFLOW_DB:sswflow}?currentSchema=public&stringtype=unspecified
username: ${spring.datasource.username}
password: ${spring.datasource.password}
driver-class-name: org.postgresql.Driver
lazy: false
strict: true下,若@DS("sswflow")指定的源不存在会直接抛异常(而不是静默落到 master),能尽早暴露配置错误。
9.3 用法(实体 + Service 都要打)
@Alias("SswflowProjectEntity")
@DS("sswflow") // ⚠️ 切到业务库
@TableName("project")
public class ProjectEntity extends SuperEntity<String> { ... }
@Service("sswflowProjectService")
@DS("sswflow") // ⚠️ 注解【不继承】!子类必须各自打,写在基类上无效
public class ProjectServiceImpl extends SswflowServiceImpl<ProjectMapper, ProjectEntity>
implements ProjectService { ... }
⚠️ @DS 不会从父类继承:基类 SswflowServiceImpl 即使打了 @DS,子类也读不到——JNPF 切面取的是 methodInvocation.getThis().getClass().getAnnotation(DS.class)。每个业务 Service Impl 必须自己打 @DS("sswflow"),实体同理。
9.4 基类承载「动态自愈」(SSWFlow 自定义增强)
SswflowServiceImpl 实现 JNPF 的 DynamicSourceGeneratorInterface,命中 MybatisPlusConfig#myDynamicDatasourceGeneratorAdvisor 切面(切点 within(DynamicSourceGeneratorInterface+) && @target(@DS)):
- 静态兜底:
application-dev.yml已声明sswflow连接池,正常路径不依赖运行时生成。 - 动态自愈:一旦
sswflow源缺失(连接池被销毁、多租户重建等),会用主库连接参数复制一份并把库名换成sswflow重新注册,避免strict=true下抛dynamic-datasource can not find primary datasource。
【修正 G】接口真实签名(已反编译
jnpf-common-database-7.0.0-RELEASE.jar复核):public interface DynamicSourceGeneratorInterface { public abstract <T extends jnpf.database.util.DataSourceUtil> T getDataSource(); public default boolean cachedConnection(); }
jnpf.database.util.DataSourceUtil标注@Component(可直接@Autowired),其init(String)返回jnpf.database.model.entity.DbLinkEntity——而DbLinkEntity extends DataSourceUtil,所以return masterDataSourceUtil.init(DS_KEY);赋值给DataSourceUtil完全合法。原文档写法能编译,这里仅补充精确签名与类型关系,避免读者误以为init返回DataSourceUtil本身。
public abstract class SswflowServiceImpl<M extends SuperMapper<T>, T>
extends SuperServiceImpl<M, T> implements DynamicSourceGeneratorInterface {
public static final String DS_KEY = "sswflow";
@Autowired
private DataSourceUtil masterDataSourceUtil; // 主库连接参数(只读,@Component)
@Override
public DataSourceUtil getDataSource() {
return masterDataSourceUtil.init(DS_KEY); // 复制主库参数,库名换成 sswflow
}
}
所有业务 Service 继承
SswflowServiceImpl即可自动获得该能力(仍需各自打@DS("sswflow"))。
十、前端对接:用独立 Vite,别塞 jar
把静态页塞进 Spring Boot jar 会踩一堆坑(静态资源映射是 /static/** 而非根、每次改前端要重打包、AuthFilter 白名单)。独立 Vite dev server 干净得多:
sswflow-web/ # Vite + Vue3 + TS + ant-design-vue
├── vite.config.ts # proxy: { '/api': { target: 'http://localhost:30000' } }
├── scripts/smoke.mjs # 零依赖烟测(见 §12.2)
└── src/
├── utils/cipher.ts # 密码 AES 加密(对齐 8.2)
├── api/request.ts # axios:注入 Authorization/App-Code/Jnpf-Origin/Vue-Version;600/401 跳登录
├── api/auth.ts # login/logout/getToken
└── api/sswflow.ts # 业务接口(路径 /api/ssw/sswflow/...)
vite.config.ts:
export default defineConfig({
server: { port: 5173, proxy: { '/api': { target: 'http://localhost:30000', changeOrigin: true } } },
plugins: [vue()]
})
浏览器只跟 5173 通信,由 Vite 代理到 30000,同源无 CORS 问题。
src/utils/cipher.ts(官方约定,与 §8.2 一致,含自检 —— 内层 = md5(明文)):
import CryptoJS from 'crypto-js'
const CIPHER_KEY: string = import.meta.env.VITE_CIPHER_KEY || 'EY8WePvjM5GGwQzn'
export function encryptPassword(plain: string): string {
const key = CryptoJS.enc.Utf8.parse(CryptoJS.MD5(CIPHER_KEY).toString()) // md5(securityKey) 32B = AES-256
const inner = CryptoJS.MD5(plain).toString() // 官方约定:内层 = md5(明文) 的 32 hex
const encrypted = CryptoJS.AES.encrypt(CryptoJS.enc.Utf8.parse(inner), key, {
mode: CryptoJS.mode.ECB, padding: CryptoJS.pad.Pkcs7
})
return CryptoJS.enc.Base64.parse(encrypted.toString()).toString(CryptoJS.enc.Hex)
}
export const SELF_CHECK_123456 =
'd4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b'
export function selfCheck(): boolean {
return encryptPassword('123456') === SELF_CHECK_123456
}
src/api/request.ts 关键拦截器(要点):
// 请求拦截:注入 4 个头,token 原样带(含 "bearer " 前缀)
config.headers.Authorization = getToken() // 形如 "bearer eyJ..."
config.headers['App-Code'] = appCode
config.headers['Jnpf-Origin'] = 'pc'
config.headers['Vue-Version'] = '3'
// 响应拦截:code !== 200 视为错误;code === 600 || http 401 → 清 token 跳登录
if (res.data.code !== 200) {
if (res.data.code === 600) { clearToken(); router.replace('/login') }
return Promise.reject(res.data.msg)
}
十一、数据库与中间件(PostgreSQL + Redis)
快速起环境:不想手动装库,直接用阿里云镜像(PostgreSQL 16 + Redis)一条命令拉起,并初始化
j7主库——完整步骤见「〇-B.4」。下面只讲配置与接入约定。
# application-dev.yml(节选,完整见 §9.2)
spring:
datasource:
url: jdbc:postgresql://${DB_HOST:localhost}:${DB_PORT:5432}/${SSWFLOW_DB:sswflow}
username: dacli
password: dacli123
data:
redis:
host: ${REDIS_HOST:localhost}
port: ${REDIS_PORT:6379}
redis:
redisson:
config: |
singleServerConfig:
address: "redis://${REDIS_HOST:localhost}:${REDIS_PORT:6379}"
database: 0
password: ${REDIS_PWD:} # 纯镜像无密码时留空;JNPF 默认 123456 → 二选一对齐
connectionPoolSize: 32
connectionMinimumIdleSize: 8
codec: !<org.redisson.codec.JsonJacksonCodec> {}
Netty DNS 注意:Spring/Redis 用的 Netty 解析器不走系统 hosts,
.orb.local后缀在宿主机可能解析不到。宿主机直连用容器 IP(如 OrbStack 下192.168.97.3:5432、192.168.97.2:6379),或启动时用-DDB_HOST=... -DREDIS_HOST=...覆盖(见第 12.1 节启动命令)。
建表:schema 用 Flyway/手工 SQL,列名遵循 f_xxx 约定(公共字段列名不可改动,由 SuperEntity/SuperBaseEntity 硬编码映射);业务库 sswflow 执行 V1.0.0__schema.sql(系统库 j7 由 JNPF 自行初始化,脚本来源见「〇-B.4」的 jnpf-database 仓库)。
业务库建表脚本示例(PostgreSQL,公共字段与 SuperEntity 严格对齐):
-- 项目表
CREATE TABLE project (
f_id varchar(50) NOT NULL,
f_tenant_id varchar(50),
f_creator_time timestamp DEFAULT now(),
f_creator_user_id varchar(50),
f_last_modify_time timestamp,
f_last_modify_user_id varchar(50),
f_delete_mark int4,
f_delete_time timestamp,
f_delete_user_id varchar(50),
name varchar(200) NOT NULL,
project_code varchar(100),
compute_mode varchar(20),
status varchar(20) DEFAULT 'DRAFT',
remark varchar(500),
CONSTRAINT pk_project PRIMARY KEY (f_id)
);
COMMENT ON TABLE project IS '项目';
COMMENT ON COLUMN project.f_delete_mark IS '删除标记,NULL=未删除';
十二、启动与验证
12.1 启动命令(已验证)
cd boot
# jar 跑在宿主机:application-dev.yml 已默认 localhost:15432(PG 发布端口)+ 127.0.0.1:6379(Redis)
# 如需自定义可加: -DDB_HOST=... -DDB_PORT=... -DDB_USER=... -DDB_PWD=... -DTSS2_DB=...
java -Dspring.profiles.active=dev \
--server.port=30000 \
-jar ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar
【
SERVER__PORT环境变量陷阱 · §16.6①】 若宿主机残留SERVER__PORT/SERVER_PORT环境变量,Spring Boot relaxed binding 会把它映射成server.port,且环境变量优先级高于-D系统属性、高于 yml,端口会变成随机高位(如 53160)。最稳的做法是显式传 CLI 参数--server.port=30000(命令行参数优先级最高,可压过环境变量),或启动前env -u SERVER__PORT。 另:-D参数必须放在-jar前面才是 JVM 参数;--server.port是 Spring Boot CLI 参数,位置不限。
【修正 F/J/K】Boot 3 兼容补丁(缺一不可,否则登录时
NoClassDefFoundError: ThreadPoolExecutorUtil或启动失败):(1)
applicationTaskExecutorbean(ssw/config/TaskExecutorConfig.java):@Configuration public class TaskExecutorConfig { @Bean("applicationTaskExecutor") @ConditionalOnMissingBean(name = "applicationTaskExecutor") public ThreadPoolTaskExecutor applicationTaskExecutor() { ThreadPoolTaskExecutor ex = new ThreadPoolTaskExecutor(); ex.setCorePoolSize(8); ex.setMaxPoolSize(32); ex.setQueueCapacity(500); ex.setThreadNamePrefix("ssw-task-"); ex.initialize(); return ex; } }(2)
SpringContextinitializer 必须代码注册(FQNjnpf.util.context.SpringContext):public static void main(String[] args) { SpringApplication application = new SpringApplication(SswAdminApplication.class); application.addInitializers(new jnpf.util.context.SpringContext()); application.run(args); }同时保留
src/main/resources/META-INF/spring/org.springframework.context.ApplicationContextInitializer(内容jnpf.util.context.SpringContext)作 IDE 双保险。(3)
application.yml必加两项(否则 Boot 3 下启动失败/路由异常):spring: main: allow-bean-definition-overriding: true # JNPF 内部存在同名 bean 定义 mvc: pathmatch: matching-strategy: ant_path_matcher # JNPF 用 ant 路径匹配
12.2 烟测脚本(Node,零依赖,已验证)
【修正 I】 提供
scripts/smoke.mjs(不依赖任何 npm 包,纯 Node 内置http/crypto),含密码自检 + 登录 + 业务接口调用,支持参数:--base(默认http://localhost:30000)、--account(默认tss2dev)、--password(默认123456)、--key(默认EY8WePvjM5GGwQzn)、--appcode(默认tss2)。
// scripts/smoke.mjs(核心逻辑 · 与 §8.2 两条链路一致)
import { createHash, createCipheriv, createDecipheriv } from 'node:crypto';
import http from 'node:http';
const md5Hex = (s) => createHash('md5').update(s, 'utf8').digest('hex');
// 传输层(官方约定):hex( AES-256-ECB/PKCS5( md5(明文)的32hex字符串, utf8(md5(securityKey)) ) )
// 内层 S = md5(明文);旧变体(legacy)才是明文原文(见 §8.2)。
function encryptPassword(plain, cipherKey) {
const key = Buffer.from(md5Hex(cipherKey), 'utf8'); // md5(securityKey) 的 32 位 hex 按 UTF-8 取字节 = 32B = AES-256
const inner = md5Hex(plain); // 官方约定:内层 = md5(明文)
const c = createCipheriv('aes-256-ecb', key, null);
c.setAutoPadding(true);
return Buffer.concat([c.update(Buffer.from(inner, 'utf8')), c.final()]).toString('hex');
}
const decryptPassword = (hex, key) => {
const d = createDecipheriv('aes-256-ecb', Buffer.from(md5Hex(key), 'utf8'), null);
d.setAutoPadding(true);
return Buffer.concat([d.update(Buffer.from(hex, 'hex')), d.final()]).toString('utf8');
};
function req(method, path, body, headers) { /* 见仓库脚本:node:http 封装,返回 { status, data } */ }
const post = (p, b, h) => req('POST', p, b, h);
const get = (p, h) => req('GET', p, null, h);
// 1) 自检:与基准值一致 + 解密可逆
const EXPECT_123456 = 'd4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b'; // 官方约定(md5内层),96-hex
const cipher = encryptPassword(password, key);
console.log('cipher self-check:', (cipher === EXPECT_123456 && decryptPassword(cipher, key) === password) ? 'PASS' : 'FAIL');
// 2) 登录(x-www-form-urlencoded)
const body = `account=${encodeURIComponent(account)}&password=${cipher}&grant_type=password`;
const login = await post(`${base}/api/oauth/Login`, body, {
'Content-Type': 'application/x-www-form-urlencoded',
'App-Code': appcode, 'Jnpf-Origin': 'pc', 'Vue-Version': '3'
});
const token = login.data?.data?.token || login.data?.token; // "bearer eyJ..."
// 3) 带 token 调业务接口(走 @DS("tss2") 落到 tss2 库)
await post(`${base}/api/ssw/${appcode}/Project`,
JSON.stringify({ name: 'smoke', projectCode: 'smoke', computeMode: 'MPC', status: 1, remark: 'e2e' }),
{ Authorization: token, 'App-Code': appcode, 'Content-Type': 'application/json' });
const r = await get(`${base}/api/ssw/${appcode}/Project/All`, { Authorization: token, 'App-Code': appcode });
console.log('Project/All code =', r.data.code, '| rows =', (r.data.data || []).length);
验证双库生效:
Project/All返回刚写入的记录(连到tss2业务库),同时登录成功(走master/j7 查base_user)——两者并存即说明@DS路由正确;且j7库无project表证明数据只落在tss2库(§16.5)。
十三、常见坑速查表
| 现象 | 原因 | 解决 |
|---|---|---|
Could not resolve com.jnpf:... 401/404 / 依赖拉不到 |
没配官方私服 settings.xml |
配 ~/.m2/settings.xml 的 maven-releases server+mirror(〇-B.2) |
| 某模块目录文件缺失、编译报找不到类 | 官方仓库模块未 clone 全 | 用账号从 coding.jnpfsoft.com/v7.0/<module> 补齐(〇-B.1) |
jnpf-common-all:jar:7.0.0-RELEASE not found |
私有仓库需鉴权,离线拉不到 | 本地编译 JNPF 源码 mvn install(第二节,前置见〇-B.1/〇-B.2) |
-source 8 不支持 switch 表达式 |
boot3 profile 锁 source=8 | 业务模块 pom 覆盖 source/target=17(3.1,父 ssw-boot 已设) |
dependencies.dependency.version' for com.baomidou:... is missing |
entity pom 裸写 mybatis-plus/dynamic-datasource 无 version | 删除(随 jnpf-common-all 传递引入),或显式加 <version>(3.2) |
编译报 找不到符号 getXxx() / @Data 不生效 |
缺 lombok(JNPF 侧 provided 不传递) | entity pom 加 org.projectlombok:lombok(provided)(3.2) |
Could not resolve com.jnpf:ssw-tss-controller ... has not been downloaded |
打包只 -pl ssw-admin,业务模块不在 reactor |
加 -am:mvn -o package -DskipTests -pl ssw-admin -am(〇-B.3/12) |
ConflictingBeanDefinitionException: operatorController |
与 JNPF 同名 bean 撞 | Controller/Service 显式 bean 名(7.1) |
alias 'DataSetEntity' already mapped |
MyBatis alias 大小写不敏感撞 | 实体加 @Alias("SswflowXxxEntity")(7.2) |
业务接口报 dynamic-datasource can not find primary datasource / 数据跑到 j7 库 |
@DS 没打或打错;strict=true 下缺失源抛异常 |
实体+Service 都打 @DS("sswflow")(9.3) |
登录返回 600 登录过期 |
token 前缀被叠/被改大写 | 原样用 bearer eyJ...(8.3) |
登录报 BadPaddingException |
密码加密算法/key 不对 | 对齐 8.2(AES-256-ECB,key=MD5(CIPHER_KEY) 的 32 字节) |
| 启动无报错但登录 404 / 注入失败 | scanBasePackages 写成 com.jnpf |
改成 {"jnpf","ssw"}(修正 A / 〇-B.3-2) |
NoClassDefFoundError: ThreadPoolExecutorUtil |
applicationTaskExecutor 缺失 + SpringContext 未注册/注册失效 |
12.1 的两个 Boot 3 补丁;务必代码注册 jnpf.util.context.SpringContext(修正 F) |
启动即失败:bean definition ... is expected to be defined in ... overriding is disabled |
JNPF 内部同名 bean 不被允许覆盖 | spring.main.allow-bean-definition-overriding: true(修正 J) |
| 路由 404 / ant 匹配异常 | Boot 3 默认 PathPattern 与 JNPF ant 不匹配 | spring.mvc.pathmatch.matching-strategy: ant_path_matcher(修正 K) |
| 启动后端口是随机高位(如 53160/64052) | 环境变量 SERVER__PORT/SERVER_PORT 覆盖了配置文件(relaxed binding,优先级高于 yml) |
env | grep -i "SERVER.*PORT" 排查;启动加 --server.port=30000(§16.6①) |
| 静态页 404 / 返回 JSON 错误 | 资源映射是 /static/** 非根 |
用独立 Vite(第十节)或加 addResourceHandlers |
UnknownHostException: jnpf-postgres/jnpf-redis |
jar 跑在宿主机却用了容器网络的主机名 | 改 localhost + 容器发布端口(PG 常是 15432 不是 5432)(§16.6②) |
| Redis 连不上但容器是 Up | 容器没做端口映射(PORTS 无 0.0.0.0:6379->) |
另起带 -p 6379:6379 的实例(§16.6②) |
ERR Client sent AUTH, but no password is set |
redisson password 与 Redis 实际不符 | 无密码镜像把 password 留空对齐(§11) |
@DS("xxx") 报数据源不存在 |
YAML 少写一层,写成了 dynamic.<name> |
必须是 dynamic.**datasource**.<name>(§16.6③) |
登录 {"code":400,"msg":"账号权限不足"} |
自建账号没挂角色 / 角色无 base_authorize;超管旁路硬编码只认账号名 admin |
挂「管理员」角色(§8.2-B) |
| 登录密码怎么算都不对 | 把「传输层 AES」和「存储层 MD5」搞混了 | 传输 AES-256-ECB(明文)、存储 md5(明文+secretkey)(§8.2) |
| 文件存储启动报路径不可写 | base-path 默认 /workspace/... 是容器内路径 |
改成工程内可写目录(§16.6④) |
| 后台起的服务莫名消失、日志停半路 | nohup ... & 被父 shell 回收 |
jps -lm 确认;改用前台 exec java -jar 或 tmux/systemd(§16.6⑤) |
十四、最小落地清单(照抄顺序)
- 环境准备:获取官方源码(首次
git clone、之后git pull或复用~/.m2已有 jar,见〇-B.1)+ 配settings.xml私服(〇-B.2)+ 镜像拉起 j7/Redis 并只取 SQL 初始化库(〇-B.4) - 复制
jnpf-java-boot/jnpf-admin→boot/ssw-admin,按 〇-B.3 调整(parent/pom、包名jnpf→ssw、scanBasePackages={"jnpf","ssw"}、Boot3 补丁含代码注册 SpringContext、数据源) - 编译 JNPF 源码装本地仓库(第二节,前置见〇-B.1/〇-B.2)
- 建
boot/ssw-{app_code}/{entity,biz,controller}三层 +ssw-admin聚合 - 业务模块 pom 加
source/target=17(父ssw-boot已设)、依赖jnpf-common-all+lombok(provided);不要裸写 mybatis-plus/dynamic-datasource(3.2) - 配
application.yml:allow-bean-definition-overriding: true+mvc.pathmatch.ant_path_matcher+ 白名单;application-dev.yml双数据源master(j7) 自动补全 +dynamic.datasource.sswflow业务库(9.2)+ redisson(§11) - 写实体(带
@Alias、继承SuperEntity<String>、不重复声明公共字段、@DS("sswflow")) - 写 Service(继承
SswflowServiceImpl,@Service("sswflowXxxService")+@DS("sswflow")) - 写 Controller(
@RestController("sswflowXxxController")、/api/ssw/{app_code}) - 配
application.yml白名单 +application-dev.yml数据库 - 加 Boot 3 两个补丁(executor bean +
SswAdminApplication代码注册jnpf.util.context.SpringContext) - 独立 Vite 前端:cipher / request / auth / 业务接口 + proxy 30000
- 构建:
mvn -o package -DskipTests -pl ssw-admin -am(注意-am) - 启动(12.1 命令)→ 烟测(
node scripts/smoke.mjs,确认登录成功、密码自检 PASS、业务接口走 sswflow 库)→ 浏览器 5173 登录
十五、前端策略:以 AI 编写为主,不套 JNPF views 结构
结论:
sswflow-web保持一个普通的 Vite + Vue3 + TS 工程,由 AI 直接编写,不强行套 JNPF web 的views/**目录范式。 过早对齐 JNPF 页面结构反而增加约束、拖慢 AI 开发效率;只有当"迁回 JNPF web"成为明确任务时,再按需对齐。
只保留与后端 / JNPF 强相关的 3 个对接点(已写在第十节,务必对齐,其余随意):
utils/cipher.ts—— 密码 AES-256-ECB 加密,key=MD5(CIPHER_KEY),与后端security.security-key一致(§8.2,含自检基准值)api/request.ts—— axios 拦截器注入Authorization(原样bearer eyJ...) /App-Code/Jnpf-Origin/Vue-Version;code!==200报错、600/401跳登录(§8.3)- 业务接口路径前缀
/api/ssw/{app_code}/...,响应沿用ActionResult(code/data/msg)+ 分页{list,pagination}(§6.1)
AI 编写时的自由区(不约束):
- 目录怎么分、组件怎么拆、状态管理用 Pinia 还是 composables、UI 库选型 —— 交给 AI 按工程习惯决定。
- 不要求复用 JNPF 的
<BasicTable>/<JnpfForm>等私有组件(它们强耦合 JNPF 运行时,迁移成本高于收益)。 - 页面不强求
views/<module>/<page>的命名 —— 可读性优先,AI 生成的命名保持自洽即可。
迁移提示:真要迁回 JNPF web 时,难点只在上述 3 个对接点 + 页面注册到 JNPF 路由;业务组件本身可整体搬。所以"现在让 AI 自由写"不会欠下迁移债。
十六、tss2 二次落地:验证记录与文档缺口补充
以「完善文档」为目标,在不参考任何其它项目/脚手架、不启用容器的情况下,仅依据本指南从零落地第二个应用
tss2(位于本仓库tss2/),用于校验本指南的可复用性与缺口。结论:后端构建、前端构建、密码算法自检全部通过,证明指南可复用;同时暴露若干「仅看指南无法一次性拼出」的缺口,已在下面补齐。
16.1 tss2 命名映射表
按「示例占位约定」把 sswflow 整体替换为 tss2(app_code = 库名 = 数据源名):
| 占位(原文档通用写法) | tss 首版 | tss2 二次落地 |
|---|---|---|
| app_code | tss |
tss2 |
类前缀 Sswflow |
Tss |
Tss2 |
bean 名前缀 sswflow |
tss |
tss2 |
实体 @Alias SswflowXxxEntity |
TssXxxEntity |
Tss2XxxEntity |
| 业务库/数据源名 | tss |
tss2 |
| API 前缀 | /api/ssw/tss |
/api/ssw/tss2 |
| Java 包 | ssw.tss.* |
ssw.tss2.* |
| Maven artifactId | ssw-tss-* |
ssw-tss2-* |
业务基类 SswflowServiceImpl |
TssServiceImpl |
Tss2ServiceImpl |
关键点:业务库名 == app_code(双库架构下每个 app_code 独立库)。
dynamic.datasource.<app_code>与@DS("<app_code>")用同一个名字;application-dev.yml里${SSWFLOW_DB:<app_code>}的默认值也填 app_code(tss2 即tss2)。
16.2 完整父 pom / 聚合 pom(指南此前只给了 <properties>,缺可拼装的整文件)
boot/pom.xml(ssw-boot,父链 ssw-boot → jnpf-common → jnpf-dependencies):
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common</artifactId>
<version>7.0.0-RELEASE</version>
</parent>
<groupId>com.jnpf</groupId>
<artifactId>ssw-boot</artifactId>
<version>7.0.0-RELEASE</version>
<packaging>pom</packaging>
<properties>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
<java.version>17</java.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<jnpf.version>7.0.0-RELEASE</jnpf.version>
<ssw.app-code>tss2</ssw.app-code>
</properties>
<modules>
<module>ssw-tss2</module>
<module>ssw-admin</module>
</modules>
<dependencies>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<scope>provided</scope>
</dependency>
</dependencies>
</project>
boot/ssw-tss2/pom.xml(业务聚合,下面挂 entity/biz/controller 三个子模块):
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.jnpf</groupId>
<artifactId>ssw-boot</artifactId>
<version>7.0.0-RELEASE</version>
</parent>
<artifactId>ssw-tss2</artifactId>
<packaging>pom</packaging>
<modules>
<module>ssw-tss2-entity</module>
<module>ssw-tss2-biz</module>
<module>ssw-tss2-controller</module>
</modules>
</project>
三个子模块 pom 见 §3.2(entity 依赖
jnpf-common-all+lombok;biz 依赖 entity;controller 依赖 biz +spring-boot-starter-web,见 16.4)。构建命令必须带-am:mvn -o package -DskipTests -pl ssw-admin -am,否则 reactor 找不到ssw-tss2-*而报has not been downloaded(修正 E)。
16.3 业务基类 Tss2ServiceImpl 的文件位置(指南 §9.4 只给了类体,没说放哪)
- 所属模块:biz(
ssw-tss2-biz)。 - 包:
ssw.tss2.biz.service(与ProjectService接口同包;其实现类放在ssw.tss2.biz.service.impl)。 - 所有业务 Service Impl 继承它:
public class ProjectServiceImpl extends Tss2ServiceImpl<ProjectMapper, ProjectEntity> implements ProjectService。 - 它已实现
DynamicSourceGeneratorInterface(jnpf.database.plugins包,泛型<T extends DataSourceUtil> T getDataSource()),并把库名固定为DS_KEY="tss2"。子类仍需各自打@DS("tss2")(注解不继承,见 §9.3)。
16.4 controller 模块需要 Spring MVC 注解
controller 用 @RestController/@RequestMapping/@GetMapping/@PostMapping/@RequestBody,这些来自 spring-web / spring-webmvc。它们经 jnpf-common-all 传递引入(JNPF 的 jnpf-common-swagger 等依赖 spring-webmvc),通常已在 classpath;若编译报 找不到 org.springframework.web...,在 controller 的 pom 显式加(版本由 jnpf-dependencies BOM 托管,无需写 <version>):
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
16.5 验证结果(tss2,仅依据本指南)
第一轮:构建期验证
| 验证项 | 命令 | 结果 |
|---|---|---|
| 后端离线编译+打包 | cd boot && mvn -o package -DskipTests -pl ssw-admin -am |
✅ BUILD SUCCESS,产物 ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar(370 MB,已 repackage) |
| 前端构建 | cd tss2-web && npm install && npm run build |
✅ 产出 dist/ |
| jar 内含 initializer | unzip -l ...jar | grep ApplicationContextInitializer |
✅ META-INF/spring/... 存在,且 SswAdminApplication 代码注册兜底(修正 F) |
第二轮:运行期端到端验证(本轮补做,也正是本轮修正 §8.2 的来源)
| 验证项 | 结果 |
|---|---|
| Redis 连接 | ✅ 24 connections initialized for 127.0.0.1:6379 |
| 双数据源装载 | ✅ add a datasource named [tss2] success + [master] success,primary=master |
| 服务启动 | ✅ Tomcat 30000,/api/oauth/Login 返回 200(启动约 90s) |
| 密码算法自检 | ✅ encryptPassword("123456") = d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b(官方 md5 约定,96-hex) |
| 登录取 token | ✅ code=200,返回 bearer eyJhbGciOiJIUzI1NiIs... |
| 鉴权 + 业务写入 | ✅ POST /api/ssw/tss2/Project → code=200 |
| 业务读取 | ✅ GET /api/ssw/tss2/Project/All → 读回刚写入的记录 |
@DS("tss2") 真实路由 |
✅ 数据只出现在 tss2 库;j7 库根本不存在 project 表(information_schema 计数 = 0) |
| 前端 Vite 代理链路 | ✅ 经 http://127.0.0.1:5173 代理跑同一套烟测,同样全绿 |
$ node scripts/smoke.mjs --base=http://127.0.0.1:30000
[1] cipher self-check: PASS
md5(key) = 05b0175907a859751f57a04d5a5ee9ac
cipher = d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b
[2] login tss2dev @ http://127.0.0.1:30000
http = 200 | code = 200 | token? yes
[3] business POST /api/ssw/tss2/Project name=smoke-1785560577257
http = 200 | code = 200 | msg = ok
[4] business GET /api/ssw/tss2/Project/All
http = 200 | code = 200 | rows = 1
DONE 端到端链路通过:登录 -> 鉴权 -> @DS("tss2") 写入 -> 读出
16.6 运行期实测暴露的 5 个坑(构建期发现不了)
按踩到的先后顺序记录,每个都会直接卡死流程:
① server.port 被环境变量悄悄改掉
现象:application-dev.yml 明明写了 server.port: 30000,实际却绑到随机高位端口。
根因:宿主机存在 SERVER__PORT / SERVER_PORT 环境变量,Spring Boot 的 relaxed binding 把它映射成 server.port,
环境变量优先级高于配置文件。实测 env -u SERVER__PORT 后即恢复 30000。
env | grep -i "SERVER.*PORT" # 先排查
java -jar ssw-admin.jar --spring.profiles.active=dev --server.port=30000 # 命令行显式指定最稳
② jar 跑在宿主机时,数据源地址不能用容器名
jnpf-admin 原配置是 host: jnpf-postgres / port: 5432(docker 网络内地址)。
jar 直接在宿主机跑时必须换成发布端口,否则 UnknownHostException:
spring:
datasource:
host: ${DB_HOST:localhost} # 宿主机跑 → localhost
port: ${DB_PORT:15432} # PG 容器的发布端口,不是 5432
Redis 同理:若容器没做端口映射(docker ps 的 PORTS 列只有 6379/tcp 而没有 0.0.0.0:6379->),
宿主机根本连不上,必须另起一个带 -p 的实例:
docker run -d --name tss2-redis -p 6379:6379 redis:7 --requirepass 123456
docker exec tss2-redis redis-cli -a 123456 ping # 期望 PONG
③ 业务数据源的 YAML 层级容易写错一层
必须是 spring.datasource.dynamic.**datasource**.<app_code>,少写中间那层 datasource 就不会注册,
而 strict: true 下 @DS("tss2") 会直接抛「数据源不存在」:
spring:
datasource:
dynamic:
primary: master
strict: true
datasource: # ← 这一层别漏
tss2:
url: jdbc:postgresql://${spring.datasource.host}:${spring.datasource.port}/${TSS2_DB:tss2}?currentSchema=public&stringtype=unspecified
username: ${spring.datasource.username}
password: ${spring.datasource.password}
driver-class-name: org.postgresql.Driver
lazy: false
启动日志出现下面三行才算真的装上了:
add a datasource named [tss2] success add a datasource named [master] success initial loaded [2] datasource,primary datasource named [master]
④ 文件存储根路径必须可写
config.file-storage.local-plus[0].base-path 默认 /workspace/jnpf-resources/(容器内路径)。
宿主机没有 /workspace 且创建需要 root,改成工程内目录:
base-path: ${TSS2_RESOURCE_PATH:/abs/path/to/tss2/.runtime/resources/}
⑤ 后台启动的进程会被 shell 回收
nohup java -jar ... & 在某些受控 shell 里,父 shell 退出时子进程一起没了(日志停在半路、无端口监听、
jps 查不到)。排查时先 jps -lm 确认进程还在,再看日志。稳妥做法是让 java 占据前台(exec java -jar ...)
由外层作业管理托管,或用 screen/tmux/systemd。
16.7 application.yml 仅为「差异补丁」
ssw-admin/src/main/resources/application.yml在指南里只提供「必须新增/修正」的键(allow-bean-definition-overriding、mvc.pathmatch.ant_path_matcher、gateway.exclude-url)。完整的 JNPF 平台配置(mybatis-plus、sa-token、security.security-key、spring.redis 等)请沿用jnpf-admin的application.yml并把上述键合并进去——这正是 〇-B.3「复制 jnpf-admin 资源」的本意。单独用本指南给出的application.yml片段无法启动(缺 JNPF 必需配置),这是预期,不是指南缺陷。application-dev.yml已给出可直接用的双数据源(master/j7 +dynamic.datasource.tss2)与 redisson 配置,变量默认localhost/15432,可用-DDB_HOST=... -DREDIS_HOST=...或同名环境变量覆盖(详见 §11 / §12.1)。
16.8 造验证账号的完整可复制脚本
不要试图猜 admin 的密码(实测该环境 admin 密码非 123456)。直接造一个自己的账号,
三步缺一不可(少任何一步都登录失败,对应错误码见 §8.2-B):
# ── 步骤 0:算出入库摘要(官方约定:S = md5(明文))───────
# f_password = md5( md5(明文) + f_secretkey.toLowerCase() )
node -e "const c=require('crypto');const m=s=>c.createHash('md5').update(s,'utf8').digest('hex');
console.log(m(m('123456')+'tss2dev-secret-key-001'))"
# => 2898aa333ba4efb48658db85e10d9fd9
-- ── 步骤 1:复制 admin 行建账号(最省事,公共列自动带全)──
INSERT INTO base_user
SELECT * FROM base_user WHERE f_account = 'admin';
UPDATE base_user SET
f_id = 'tss2dev-001',
f_account = 'tss2dev',
f_password = '2898aa333ba4efb48658db85e10d9fd9',
f_secretkey = 'tss2dev-secret-key-001',
f_is_administrator = 1,
f_enabled_mark = 1 -- ← 步骤 2:必须为 1,否则 LOG005
WHERE f_id = (SELECT f_id FROM base_user WHERE f_account='admin') -- 注意先改 id 再改其它
AND f_account = 'admin';
-- ── 步骤 3:挂角色,否则 LOG004「账号权限不足」──────────
INSERT INTO base_role_relation
(f_id, f_role_id, f_object_type, f_object_id, f_creator_time, f_creator_user_id, f_delete_mark, f_tenant_id)
VALUES ('tss2dev-rel-001', '666911261245571844', 'user', 'tss2dev-001', now(), 'tss2dev-001', 0, '');
base_role_relation没有唯一约束,ON CONFLICT (f_id)会直接报there is no unique or exclusion constraint matching the ON CONFLICT specification。 需要幂等就先DELETE FROM base_role_relation WHERE f_id='...';再 INSERT。
验证账号可用性:
node tss2-web/scripts/smoke.mjs --base=http://127.0.0.1:30000 --account=tss2dev --password=123456
附:本增强版相对原版的全部修订(CHANGELOG)
- A ·
scanBasePackages:{"com.jnpf","ssw"}→{"jnpf","ssw"},并加醒目说明:com.jnpf仅 Maven groupId,Java 顶级包是jnpf。 - B · 实体基类:
EntityBase→SuperEntity<String>(含SuperBaseEntity的id),公共字段表补全为 9 列,明确"勿重复声明"。 - C · entity 依赖:删除无 version 的
mybatis-plus-boot-starter/dynamic-datasource-spring-boot-starter(随jnpf-common-all传递引入),补"如需锁版本必须显式<version>"。 - D · lombok:明确 entity(及使用
@Data的模块)需自行声明org.projectlombok:lombok(provided);父ssw-boot也已全局加。 - E · 构建命令:
mvn package -DskipTests -pl ssw-admin -o→mvn -o package -DskipTests -pl ssw-admin -am(补-am)。 - F · initializer:FQN
jnpf.SpringContext→jnpf.util.context.SpringContext;并强制SswAdminApplication.main()代码注册(repackage 会把 META-INF 提到 fat-jar 根导致读不到)。 - G ·
getDataSource:补充接口真实泛型签名<T extends DataSourceUtil> T getDataSource()与init(String)返回DbLinkEntity(其父类为DataSourceUtil),澄清原写法可编译。 - H · 密码算法(2026-08-01 最终定稿):经反编译官方字节码 + dacli 实测 +
tss2运行期验证三证对齐,定为双约定模型。传输层内层 S 分两种:官方默认S = md5(明文)(密文 96-hex,基准d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b),旧变体(legacy)S = 明文(密文 32-hex,基准ea80d323686b9dfe734f2b42159db1a6);存储层f_password = md5( S + f_secretkey.toLowerCase() )。两条约定都合法但互不相通,登录失败通常是选错约定。SecurityProperties.setSecurityKey的 setter 内部自动做 MD5,配置的 16 字符 key 实际变 32 字节 → AES-256;daclisrc/core/crypto.ts与本仓库tss2均用官方约定。 - I · 烟测脚本:新增零依赖
scripts/smoke.mjs(自检+登录+业务接口,可传参)。 - J ·
allow-bean-definition-overriding:application.yml必须true(JNPF 内部同名 bean)。 - K ·
mvc.pathmatch:application.yml必须ant_path_matcher。 - 附 ·
ssw-admin/pom.xml:补全 JNPF 全部 controller 依赖清单(oauth/permission/system/file/message/extend/flowable/scheduletask/visualdev-*/visualdata/app)+ boot3 激活jnpf-ai-v3-controller。 - 附 ·
application.yml/application-dev.yml:给出与 JNPF 7.0 对齐的完整可运行样例(含 dynamic.datasource、redisson 无密码对齐、mvc.pathmatch、allow-bean-definition-overriding)。 - 附 · 脚手架落地:本仓库已按
app_code=tss落地完整可编译脚手架(boot/+tss-web/),上述每一处修正均经真实mvn -o package -pl ssw-admin -am与npm run build复核通过。 - 附 · tss2 二次落地(十六节):在不参考其它脚手架、不启用容器的前提下,仅依据本指南从零落地第二个应用
tss2(本仓库tss2/),后端mvn -o package -pl ssw-admin -am与前端npm run build均通过、密码自检 PASS,证明指南可复用。新增内容:ssw-boot/ssw-{app_code}完整父 pom 与聚合 pom(16.2)、Tss2ServiceImpl文件位置(16.3)、controller 模块 spring-web 依赖说明(16.4)、tss2 命名映射表(16.1)、无容器验证方案与application.yml仅为差异补丁说明(16.6)。 - 附 · 示例占位通用化:「示例占位约定」由固定的
sswflow → tss改为sswflow → <你的 app_code>,并明确业务库名 == app_code,避免第二次落地时误以为库名仍为sswflow。 - 附 · tss2 运行期端到端验证(本轮补做):在真实 PostgreSQL + 新建
tss2-redis上跑通「启动 → 登录 → 鉴权 →@DS("tss2")写入 → 读出」,并核实数据只落在tss2库、j7库无project表。由此新增:§8.2 密码算法全面重写(修正 H)、§8.2-B 自建账号 LOG004 授权坑与登录错误码速查表、§16.5 运行期验证结果表、§16.6 运行期五坑(SERVER__PORT覆盖端口 / 容器名 vs 发布端口 /dynamic.datasource少一层 / 文件存储路径不可写 / 后台进程被 shell 回收)、§16.8 造验证账号完整脚本;§13 速查表同步扩充 6 条。