背景: 2026-06-23 jxcj E2E BS-14 闭环后, 每个 ssw-{app_code} 都要自己写 MapperConfig
仍重复且易遗漏。集中到 ssw-common 后, 业务包零配置。
修改:
- 新增 boot/ssw-common/ssw-common-biz/.../config/SswMapperConfig.java
* @Configuration @MapperScan(basePackages = "ssw.**.mapper")
* 一处配置覆盖所有 ssw-{app_code}/ssw-{app_code}.mapper
- 删除 boot/ssw-jxcj/.../config/JxcjMapperConfig.java
* jxcj 不再自己写 MapperConfig
- 修改 boot/ssw-jxcj/ssw-jxcj-biz/pom.xml
* 加 ssw-common-biz 依赖 (传递包含 SswMapperConfig)
配套已更新:
- .claude/skills/{no-spa-page,backend-dev,ssw-pack-init} 文档统一指向 ssw-common
- .claude/skills/ssw-pack-init/scripts/check_ssw_pack.py BS-14 检测改成共享版
- dacli/src/commands/_blindspot_guards.ts BS-14 guard 同改
验证:
- python3 .claude/skills/ssw-pack-init/scripts/check_ssw_pack.py jxcj
✓ BS-14: 共享 SswMapperConfig @MapperScan('ssw.**.mapper') + 业务包依赖 ssw-common-biz
Co-Authored-By: Claude <[email protected]>
ssw-common 模块开发指南
本文档记录如何在 ssw-common 中添加新功能,包括代码编写、编译、打包、重启和测试验证。
一、模块结构
boot/ssw-common/
├── ssw-common-entity/ # 实体层
│ └── pom.xml
├── ssw-common-biz/ # 业务层
│ ├── pom.xml
│ └── src/main/java/ssw/common/
│ ├── entity/ # 实体类
│ ├── service/ # 服务接口
│ └── service/impl/ # 服务实现
└── ssw-common-controller/ # 控制层
├── pom.xml
└── src/main/java/ssw/common/controller/
二、Maven 安装(如果系统没有 mvn)
# 方案1:下载解压
cd /tmp
curl -L "https://archive.apache.org/dist/maven/maven-3/3.9.6/binaries/apache-maven-3.9.6-bin.tar.gz" -o maven.tar.gz
tar -xzf maven.tar.gz
mv apache-maven-3.9.6 ~/maven
export PATH="$HOME/maven/bin:$PATH"
# 方案2:Homebrew
brew install maven
三、编译
cd /Users/xs/Desktop/6.2/boot
export PATH="$HOME/maven/bin:$PATH"
# 仅编译 ssw-common(快速检查语法)
mvn clean compile -pl ssw-common -am -DskipTests
# 编译整个项目(推荐)
mvn clean compile -DskipTests
四、打包
cd /Users/xs/Desktop/6.2/boot
export PATH="$HOME/maven/bin:$PATH"
# 跳过测试打包
mvn clean package -DskipTests
五、重启服务
cd /Users/xs/Desktop/6.2/boot/jnpf-admin
# 1. 找到进程 PID
ps aux | grep "jnpf-admin.*dev" | grep -v grep
# 2. 停止旧进程(替换 PID)
kill <PID>
# 3. 启动新 jar
java -jar target/jnpf-admin-6.2.0-RELEASE.jar --spring.profiles.active=dev
# 或者后台运行
nohup java -jar target/jnpf-admin-6.2.0-RELEASE.jar --spring.profiles.active=dev > app.log 2>&1 &
六、测试验证
6.1 获取 Token(使用 Python)
import sys
sys.path.insert(0, '/Users/xs/Desktop/6.2')
from aibridge import JNPFClient, JNPFConfig
client = JNPFClient.from_config(JNPFConfig())
client.login()
print(client.token)
6.2 使用 curl 测试
# 获取 token(从上面 Python 输出复制)
TOKEN="bearer <your-token>"
# 测试 API
curl -s "http://127.0.0.1:30000/api/common/tableCount/ais/count" \
-H "Authorization: $TOKEN" | jq .
curl -s "http://127.0.0.1:30000/api/common/tableCount/ais/list" \
-H "Authorization: $TOKEN" | jq '.data | .[0:5]'
七、pom.xml 依赖规范
ssw-common-entity/pom.xml
<dependencies>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common-all</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<scope>provided</scope>
</dependency>
</dependencies>
ssw-common-biz/pom.xml
<dependencies>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>ssw-common-entity</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common-all</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.12.0</version>
</dependency>
</dependencies>
ssw-common-controller/pom.xml
<dependencies>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>ssw-common-biz</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common-all</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
jnpf-admin/pom.xml(添加模块依赖)
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>ssw-common-controller</artifactId>
<version>${project.version}</version>
</dependency>
八、常见问题
8.1 mvn: command not found
Maven 未安装或不在 PATH 中,参考第二节安装。
8.2 编译错误:找不到符号
- 检查
pom.xml依赖是否正确添加 - 检查 import 语句是否正确
- 确保在
boot根目录执行 mvn 命令
8.3 404 错误:接口未找到
服务未重启,需要重新打包并启动 jar。
8.4 401 错误:未授权
Token 过期或未传递,重新获取 Token。
九、一键脚本
#!/bin/bash
cd /Users/xs/Desktop/6.2/boot
export PATH="$HOME/maven/bin:$PATH"
echo "=== 1. 编译打包 ==="
mvn clean package -DskipTests
echo "=== 2. 停止旧进程 ==="
PID=$(ps aux | grep "jnpf-admin.*dev" | grep -v grep | awk '{print $2}')
if [ -n "$PID" ]; then
kill $PID
echo "已停止进程: $PID"
sleep 3
fi
echo "=== 3. 启动新服务 ==="
cd jnpf-admin
nohup java -jar target/jnpf-admin-6.2.0-RELEASE.jar --spring.profiles.active=dev > /tmp/jnpf.log 2>&1 &
echo "启动中,等待 15 秒..."
sleep 15
echo "=== 4. 测试验证 ==="
curl -s "http://127.0.0.1:30000/api/common/tableCount/ais/count" | jq .
十、相关配置
| 配置项 | 值 |
|---|---|
| Maven 路径 | ~/maven/bin/mvn |
| 项目路径 | /Users/xs/Desktop/6.2/boot |
| JAR 路径 | jnpf-admin/target/jnpf-admin-6.2.0-RELEASE.jar |
| 服务端口 | 30000 |
| 日志文件 | /tmp/jnpf.log |
| ais db_link_id | 808687067075709509 |