4.7 KiB
4.7 KiB
abacus.springboot.example — 开发规范（CONVENTIONS）
命名、目录、提交、风格、测试的权威（本仓库视角）。前后端共享约束见工作区
docs/coding-standards.md（../../../../docs/coding-standards.md），本文只写后端特有内容 + 指针，禁止复制 docs/ 正文。
0. 阅读指引
- 适用范围：
src/main/java/abacus/springboot.<应用名>/**业务开发（模板基础结构 pom/assembly/config 原则上不动）。 - 分工：ARCHITECTURE 管"拆成什么模块"；本文管"怎么命名/写"；共享编码规范、接口契约、SQL 约定、AI 生成工作流在
docs/coding-standards.md§5~§7。
1. 命名
1.1 标识符
- 类：PascalCase；接口带后缀
IF（pi 层XxxAccessIF、wsi 层XxxServiceIF）；编排服务XxxBizService；实现XxxAccess。 - Controller：
XxxController（api 对外 / controller 内部）；基类BaseServlet。 - 实体：表名小写下划线（
jc_bill），类名驼峰（JcBill）；DTO：请求ApiReqXxx、响应ApiRespXxx或ApiXxx（api/view）。 - 配置：
XxxConfiguration、XxxConfigKey（常量类）。
1.2 模块命名（语义禁区）
- 禁止
Manager/Helper/Util/Common/Misc/Tools这类语义为空的名字；用"动词+名词"。 - util/ vo/ 兼容：既有
util/DateUtil、vo/BaiduToken等可引不可增——新代码禁止在util/、vo/包新增文件（共享规范 §8.4）。
1.3 文件 / 1.4 目录 / 1.5 资产命名
- 文件按类名命名（一文件一公共类）；目录即包名（分层见 ARCHITECTURE §6）。
- SQL：
sql/table/{mysql,sqlserver}.sql、sql/upgrade.xml、sql/data/；版本号yyyy-MM-dd[.count]。
1.6 字符串与本地化
- 异常消息中文、可行动（"参数[x]为空！"）；不硬编码无意义字符串；状态常量用
public final static int STATUS_*。
2. 代码风格
2.1 排版
- Java 4 空格缩进、行宽 ≤ 120；分号/括号按 Java 惯例。
- 不使用 Lombok（手写 getter/setter，与示例一致）。
2.2 分层纪律
- Controller 只做参数校验 + 调编排，不写 SQL、不碰 Repository；esb 只编排不做 SQL。
- 原生 SQL 在
impl/，全量?参数化；标准 CRUD/派生查询用repository。 - 业务主键一律
DaoIdGenerator，禁止手拼。
2.3 并发 / 2.4 错误处理
- 事务边界在 esb 编排方法（按需
@Transactional）；JPA 乐观锁用@Version。 - 业务错误抛
BusinessException（中文消息）；Controller 方法级 try/catch(Throwable) 记日志后 rethrow；禁止吞异常。
2.5 注释
- 每个方法必须写注释（一行职责说明，复杂方法补充入参/出参/边界，便于人工复核）；只在 WHY 不明显处补充 WHY 注释；不写会随时间失效的注释。
3. 提交规范
3.1 Commit message 风格
Conventional Commits：type(scope): subject。允许 type：feat / fix / docs / refactor / test / chore。例：feat(jcbill): 新增稽查收货保存接口。
3.2 提交粒度 / 3.3 工作区纪律 / 3.4 分支模型
- 一次提交一个目的；不在脏工作区叠加不相关改动。
- 分支模型：主干 + 短命功能分支（按需，单人开发可直推主干）。
- 本仓库属于工作区单一 git 仓库（
D:\workBuddySpace\member）；纯后端改动 commit 限定本目录，跨项目改动（docs/）单独 commit。
3.5 实施日志
- 规则见
VIBECODING_GUIDE §5：每个可独立验收的部分写.project.agents/log/YYYY-MM-DD-<slug>.md。 - 功能更新同步追加
src/main/resources/doc/升级日志.md（共享规范 §5.11 格式）。
4. 测试策略
4.1 框架 / 4.2 必须有测试的模块
- 无自动化测试框架（PRD 决策）；接口人工冒烟。
4.3 必须真机/真环境验证
- 必须真机验证（mock/模拟器不算数）：多数据源路由、Kafka 消费、XXL-JOB 调度、Nacos 配置拉取、真实数据库迁移。
5. 与上游文档的同步矩阵
| 变更点 | 必须同步更新 |
|---|---|
| 新增/改动业务功能 | PRD.md（功能定义）；共享规范如有涉及先改 docs/coding-standards.md |
| 新增包/模块/依赖方向 | 本仓库 ARCHITECTURE.md §2+§3 |
| 新增 SQL/表结构 | sql/table/ 双份 + sql/upgrade.xml；ARCHITECTURE.md §1 实体清单 |
| 配置项变更 | config/{dev,test,prod}/ 三套同步 |
| 依赖版本变更 | pom.xml + doc/升级日志.md |
6. 不在本文范围（明确划清）
- 模块拆分归
ARCHITECTURE.md；行为/范围归PRD.md；前后端共享约束（响应体/异常码/分页/APP_NAME/打包）归docs/coding-standards.md。