95 lines
4.7 KiB
Markdown
95 lines
4.7 KiB
Markdown
# 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`。
|