Files
ssw-mvp/docs/JNPF_BACKEND_GUIDE.md
admin 3247e9fd15 init: ssw-mvp initial commit
- 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
2026-08-05 18:29:12 +08:00

87 KiB
Raw Permalink Blame History

按 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。

〇、核心结论(先看这段)

  1. 不要从零写框架——直接复用 JNPF 的 boot 启动模块 + jnpf-common-all 依赖栈。你只需要写业务包。
  2. 业务包三层结构:ssw-{app_code}-entity / -biz / -controller,全部挂在 ssw-{app_code} 父 pom 下。
  3. API 前缀:/api/ssw/{app_code}/...,与 JNPF 的 /api/... 并存不冲突。
  4. 双库架构(必做):JNPF 系统表走 master(库 j7),你的业务表放独立业务库(库 sswflow),用 @DS("sswflow") 切换。JNPF 内置 dynamic-datasource,这是平台标准机制。
  5. 鉴权完全复用 JNPF:Sa-Token + /api/oauth/Login,前端只负责"加密密码 + 原样带 token"。
  6. 两个必踩的碰撞坑(不处理就启动即崩):Spring bean 名冲突、MyBatis type-alias 冲突。
  7. ⚠️ 最易翻车的两类"静默/硬失败"已在本版订正:
    • scanBasePackages 必须写 Java 顶级包 jnpf(不是 Maven groupId com.jnpf),写错无报错但鉴权/数据源全失效(见 〇-A·A)。
    • 打包后启动会 NoClassDefFoundError: ThreadPoolExecutorUtil——META-INF/spring/...ApplicationContextInitializer 被 repackage 提到 fat-jar 根目录后读不到,必须代码注册 initializer(见 〇-A·F、§12.1)。
  8. 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 文件,保留)

必须调整的部分(否则编不过或跑不起来):

  1. 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 的关键。
  2. 包名 jnpf → ssw

    • src/main/java/jnpf/ 整个包重命名为 ssw/,启动类 JnpfAdminApplication → SswAdminApplication。
    • ⚠️ 【修正 A】scanBasePackages 必须写 Java 顶级包 jnpf,不能写 groupId com.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"})。
  3. 白名单 / AuthFilter

    • 用独立 Vite 前端时,gateway.exclude-url 保留 JNPF 默认即可(无需 /ssw/**)。
    • 若仍塞 no-spa 静态页,需加 - /ssw/**(见第 8.4 节)。
  4. Boot 3 两个补丁(否则登录时 NoClassDefFoundError: ThreadPoolExecutorUtil)

    • 提供 applicationTaskExecutor bean(JNPF 的 ThreadPoolExecutorUtil 静态块依赖它)。示例见 ssw/config/TaskExecutorConfig.java。
    • 【修正 F,关键】注册 SpringContext initializer 有两条路径,缺一条都会炸:
      • (a) 文件 src/main/resources/META-INF/spring/org.springframework.context.ApplicationContextInitializer,内容一行:
        jnpf.util.context.SpringContext
        
        (原文档写的 jnpf.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 直跑时的双保险保留。
  5. application-dev.yml 数据源与 Redis

    • spring.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 节声明。
  6. 可选清理

    • 用 Vite 独立前端可删除 src/main/resources/static/ssw/**(不影响启动)。
    • 不用的 JNPF 模块依赖可在 pom 里裁剪,但建议先全留、跑通后再减。

【修正 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 字符串
tenantId f_tenant_id
creatorTime f_creator_time 默认 now()
creatorUserId f_creator_user_id
lastModifyTime f_last_modify_time
lastModifyUserId f_last_modify_user_id
deleteMark f_delete_mark JNPF 约定 null=未删
deleteTime f_delete_time
deleteUserId f_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 位 hex 96 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());   // 账号权限不足
    }
}

踩坑要点:

  1. 旁路条件是账号名硬编码字面量 "admin"。你把自建账号的 f_is_administrator 设成 1 没用,只要账号不叫 admin 就照样走权限检查。
  2. 检查的是:base_role_relation(用户/岗位 → 角色)关联出的对象,在 base_authorize 里至少有一条授权记录。
  3. 光有角色还不够,那个角色必须真的有 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) applicationTaskExecutor bean(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) SpringContext initializer 必须代码注册(FQN jnpf.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⑤)

十四、最小落地清单(照抄顺序)

  1. 环境准备:获取官方源码(首次 git clone、之后 git pull 或复用 ~/.m2 已有 jar,见〇-B.1)+ 配 settings.xml 私服(〇-B.2)+ 镜像拉起 j7/Redis 并只取 SQL 初始化库(〇-B.4)
  2. 复制 jnpf-java-boot/jnpf-admin → boot/ssw-admin,按 〇-B.3 调整(parent/pom、包名 jnpf→ssw、scanBasePackages={"jnpf","ssw"}、Boot3 补丁含代码注册 SpringContext、数据源)
  3. 编译 JNPF 源码装本地仓库(第二节,前置见〇-B.1/〇-B.2)
  4. 建 boot/ssw-{app_code}/{entity,biz,controller} 三层 + ssw-admin 聚合
  5. 业务模块 pom 加 source/target=17(父 ssw-boot 已设)、依赖 jnpf-common-all + lombok(provided);不要裸写 mybatis-plus/dynamic-datasource(3.2)
  6. 配 application.yml:allow-bean-definition-overriding: true + mvc.pathmatch.ant_path_matcher + 白名单;application-dev.yml 双数据源 master(j7) 自动补全 + dynamic.datasource.sswflow 业务库(9.2)+ redisson(§11)
  7. 写实体(带 @Alias、继承 SuperEntity<String>、不重复声明公共字段、@DS("sswflow"))
  8. 写 Service(继承 SswflowServiceImpl,@Service("sswflowXxxService") + @DS("sswflow"))
  9. 写 Controller(@RestController("sswflowXxxController")、/api/ssw/{app_code})
  10. 配 application.yml 白名单 + application-dev.yml 数据库
  11. 加 Boot 3 两个补丁(executor bean + SswAdminApplication 代码注册 jnpf.util.context.SpringContext)
  12. 独立 Vite 前端:cipher / request / auth / 业务接口 + proxy 30000
  13. 构建:mvn -o package -DskipTests -pl ssw-admin -am(注意 -am)
  14. 启动(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 个对接点(已写在第十节,务必对齐,其余随意):

  1. utils/cipher.ts —— 密码 AES-256-ECB 加密,key=MD5(CIPHER_KEY),与后端 security.security-key 一致(§8.2,含自检基准值)
  2. api/request.ts —— axios 拦截器注入 Authorization(原样 bearer eyJ...) / App-Code / Jnpf-Origin / Vue-Version;code!==200 报错、600/401 跳登录(§8.3)
  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;dacli src/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 条。