Skip to content

Commit 7627008

Browse files
committed
docs: 同步 GitHub Issue 处理流程与 Java 编码规范
- docs/conventions/workflow/github-issue.md:8.x/17.x 双版本线 issue 处理流程 - docs/conventions/java:命名、测试设计、领域建模、静态方法四篇规范 - CLAUDE.md 补充开发规范章节;.gitignore 忽略 .worktrees/
1 parent d6358f5 commit 7627008

8 files changed

Lines changed: 801 additions & 1 deletion

File tree

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,6 @@ build/
4040

4141
.flattened-pom.xml
4242
test.db*
43+
44+
### worktrees ###
45+
.worktrees/

‎CLAUDE.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,92 @@ codingapi.data-authorization.show-sql=false # 打印拦截后的 SQL
119119

120120
见根 `pom.xml` 的 `<properties>` 区块。主要版本:Groovy 4.0.24、JSqlParser 5.0、Fastjson 2.0.53、JJWT 0.12.6、H2 1.4.200。
121121

122+
## 开发规范
123+
124+
本仓库同时维护 **8.x(JDK 8 / Spring Boot 2.7.x / `javax.*`,当前分支)与 17.x(JDK 17 / Spring Boot 3.x / `jakarta.*`)两条版本线**,各自独立交付,没有 `dev` 分支。8.x 分支不包含 `example/` 与 `frontend/`。
125+
126+
### GitHub Issue 标准处理流程
127+
128+
处理任何来自 GitHub 的 issue 时,必须遵循 [docs/conventions/workflow/github-issue.md](./docs/conventions/workflow/github-issue.md):
129+
130+
1. **定位阶段**可只读代码分析,不必创建 worktree;
131+
2. **先确认影响版本线**(8.x / 17.x / 两者),定位完成后先回复 issue,说明根因、影响版本与处理方案;
132+
3. **实际改代码必须使用 git worktree + 特性分支**,基线按版本线选择:8.x 用 `8.2.x`,17.x 用 `17.3.x`;不得在主工作区直接修改;
133+
4. 修复需测试先行,并使用对应版本线的 JDK 完成本地编译/测试验证;双版本 issue 必须两条线分别验证;
134+
5. 完成后**只推送该 issue 的特性分支到 GitHub**:提交内容、推送与 issue 关联均以该特性分支为准,**不合并版本分支**;是否合并由人工决定,任务完成时仅提示分支与 PR 链接(PR 目标为 `8.2.x` 或 `17.3.x`);
135+
6. 提交信息使用 `Closes #<issue编号>` 关联 issue;仅当进入默认分支 `main` 时自动关闭,未自动关闭时需用户确认后手动关闭(8.x 合并到 `8.2.x` 不会自动关闭);
136+
7. **特性分支推送到 GitHub 后再回复 issue**,说明修复内容、验证结果与推送分支/提交;未推送前不得发布完成回复(定位回复不受此限)。
137+
138+
### 基本规范
139+
140+
- **与用户沟通及编写文档时,所有内容必须使用中文表述**
141+
- **在每次修改代码以后,要执行本地化的编译验证确保代码没有错误**
142+
- Java 代码遵循 Spring Boot 规范
143+
- 8.x 使用 `javax.*` 与 JDK 8,17.x 使用 `jakarta.*` 与 JDK 17,两条线的修复不得直接 cherry-pick,必须做命名空间与代际适配
144+
- 编码规范见 `docs/conventions`:方法命名 [java/naming-convention](./docs/conventions/java/naming-convention.md)、测试设计 [java/test-design-convention](./docs/conventions/java/test-design-convention.md)、领域建模 [java/domain-modeling-convention](./docs/conventions/java/domain-modeling-convention.md)、静态方法 [java/static-method-convention](./docs/conventions/java/static-method-convention.md)
145+
146+
### 测试规范
147+
148+
本项目后端采用 JUnit 5 进行单元测试。两条版本线测试命令一致,但需切换到对应 JDK(8.x 用 JDK 8,17.x 用 JDK 17)。
149+
150+
**测试文件位置:**
151+
152+
- 测试文件放在各模块 `src/test/java/` 目录下,包路径与源码保持一致
153+
- 测试文件命名:`*Test.java`
154+
155+
**测试编写流程:**
156+
157+
1. **Red(红灯)**:先编写测试用例,明确预期行为
158+
2. **Green(绿灯)**:编写最小代码使测试通过
159+
3. **Refactor(重构)**:优化代码结构,运行全部测试确认不回归
160+
161+
**测试用例设计要求:**
162+
163+
- 每个测试用例需明确:测试目标、前置条件、执行步骤、期望断言
164+
- 优先测试核心业务逻辑(DTO、事件系统、动态查询、SQL 拦截、脚本引擎等)
165+
- 测试应该有确定性结果,避免依赖外部状态
166+
167+
**测试命令:**
168+
169+
```bash
170+
# 运行所有测试(与 CI 一致)
171+
./mvnw clean test -P travis
172+
173+
# 运行特定模块的测试
174+
./mvnw test -pl springboot-starter
175+
176+
# 运行特定的测试类
177+
./mvnw test -pl springboot-starter -Dtest=ResponseTest
178+
```
179+
180+
**示例(基于 springboot-starter 的响应封装测试,8.x 版本线):**
181+
182+
```java
183+
package com.codingapi.springboot.framework.dto;
184+
185+
import com.codingapi.springboot.framework.dto.response.SingleResponse;
186+
import org.junit.jupiter.api.Test;
187+
188+
import static org.junit.jupiter.api.Assertions.assertEquals;
189+
import static org.junit.jupiter.api.Assertions.assertTrue;
190+
191+
class SingleResponseTest {
192+
193+
@Test
194+
void should_wrap_single_data() {
195+
// given
196+
String data = "hello";
197+
198+
// when
199+
SingleResponse<String> response = SingleResponse.of(data);
200+
201+
// then
202+
assertTrue(response.isSuccess());
203+
assertEquals(data, response.getData());
204+
}
205+
}
206+
```
207+
122208
<!-- PKR-START -->
123209
## PKR 知识查阅(编码前必须)
124210

‎docs/conventions/index.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,17 @@
66

77
| 名称 | 模块 | 描述 | 范围 | 来源 |
88
|------|------|------|------|------|
9+
| [java/domain-modeling-convention](./java/domain-modeling-convention.md) | java | 领域建模规范:同一性判断、聚合间深复制、可配置单一出口与只读集合 | 后端 | 项目自有 |
10+
| [java/naming-convention](./java/naming-convention.md) | java | 方法命名规范:按返回数量选择 get/find,必须存在的场景用 require | 后端 | 项目自有 |
11+
| [java/static-method-convention](./java/static-method-convention.md) | java | 静态方法规范:领域判断回归实例方法,明确允许的 static 场景 | 后端 | 项目自有 |
12+
| [java/test-design-convention](./java/test-design-convention.md) | java | 测试设计规范:模型不为测试让路,区分模型能力与测试脚手架 | 后端 | 项目自有 |
913
| [springboot-starter/ddd-layered-architecture](./springboot-starter/ddd-layered-architecture.md) | springboot-starter | DDD 分层架构规范,定义 interface/app/domain/infra 四层的依赖规则和职责划分 | 后端 | 项目自有 |
1014
| [springboot-starter/event-driven-convention](./springboot-starter/event-driven-convention.md) | springboot-starter | 事件驱动开发规范,定义 IEvent/IHandler 的使用约定和事件处理模式 | 后端 | 项目自有 |
1115
| [springboot-starter/exception-handling-convention](./springboot-starter/exception-handling-convention.md) | springboot-starter | 全局异常处理规范,定义异常抛出和捕获的标准模式 | 后端 | 项目自有 |
1216
| [springboot-starter/response-convention](./springboot-starter/response-convention.md) | springboot-starter | 统一响应格式规范,定义 Controller 层返回值的标准格式 | 后端 | 项目自有 |
1317
| [springboot-starter-data-fast/dynamic-query-convention](./springboot-starter-data-fast/dynamic-query-convention.md) | springboot-starter-data-fast | 动态查询规范,定义 PageRequest + RequestFilter + FastRepository 的使用模式 | 后端 | 项目自有 |
18+
| [workflow/github-issue](./workflow/github-issue.md) | workflow | GitHub Issue 标准处理流程 — 定位 → 回复 → worktree 修复 → 推送特性分支 → 推送后回复(8.x/17.x 双线) | 全栈 | 项目自有 |
1419

1520
---
1621

17-
**统计**: 共 5 篇 — 已实现 5 / 计划中 0 / 已废弃 0
22+
**统计**: 共 10 篇 — 已实现 10 / 计划中 0 / 已废弃 0
Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
name: java/domain-modeling-convention
3+
module: java
4+
description: 领域建模规范:同一性判断、聚合间深复制、可配置单一出口与只读集合
5+
status: 已实现
6+
scope: 后端
7+
source: 项目自有
8+
---
9+
10+
## 解决什么问题
11+
12+
领域逻辑写成「外部函数 + 到处开的口子」后,模型只剩数据容器:
13+
14+
- 同一性判断写成静态函数,散落在各个 Service 里,口径逐渐分叉;
15+
- 覆盖 `equals` 用 `id` 比较,但实体 `id` 会从 0 变为非 0,放进 `HashSet` / `HashMap` 后取不出来;
16+
- 聚合之间直接共享可变引用,改一个项目的名单,方案模板跟着变,下一次立项少人;
17+
- 「还能不能改」各处各写一遍 `state != END`,理解不一致;
18+
- 集合直接从 getter 外泄,所有「不许改」的校验被一句 `getXxx().add(...)` 绕过去。
19+
20+
## 如何使用
21+
22+
### 同一性判断属于对象
23+
24+
统一使用实例方法 `isSameAs`,规则固定为:**同引用,或同类且 `id` 非 0 并相等**。
25+
26+
- 不覆盖 `equals`:实体 `id` 会从 0 变为非 0,破坏哈希容器不变量;
27+
- 批量版本 `isSameAsAny(Collection)` 也属于对象,读作「我是否在这组里」;
28+
- 禁止写成 `containsXxx(集合, 我)` 这类外部静态函数。
29+
30+
### 重载歧义换名字,不靠强转
31+
32+
当一个类型同时实现两个都声明了 `isSameAs` 的接口时(如部门既是组织、又是参与方),「拿部门比部门」会让编译器无法选择。此时**换名字**而不是强转,例如组织侧叫 `isSameOrganizationAs`。「判断同一性的是这个对象」这条原则不变,只是名字要让编译器分得清。
33+
34+
### 聚合之间复制,不共享可变引用
35+
36+
跨聚合复制时**深复制行与值**,定义类对象(指标定义、类型定义等)仍可共用。
37+
38+
判断口诀:**A 的编辑动作会不会写进 B 的资料?会,就说明该复制。**
39+
40+
### 「能不能改」只判定一次
41+
42+
聚合根暴露唯一的 `isConfigurable()`,所有调整动作先过 `requireConfigurable(action)`,提示语带上动作名。禁止各处自写 `state != END`,各自理解什么叫「还能改」。
43+
44+
### 集合出口返回只读快照
45+
46+
`getXxx()` 返回 `List.copyOf(...)`,要改只能走领域动作。只包一层外层列表不够,**内层对象自己的集合也要收口**。
47+
48+
## 使用实例
49+
50+
### ✅ 正确示例
51+
52+
```java
53+
public class Project {
54+
private long id;
55+
56+
public boolean isSameAs(Project other) {
57+
if (this == other) {
58+
return true;
59+
}
60+
if (other == null || getClass() != other.getClass()) {
61+
return false;
62+
}
63+
return id != 0 && id == other.id;
64+
}
65+
66+
public boolean isSameAsAny(Collection<Project> others) {
67+
return others.stream().anyMatch(this::isSameAs);
68+
}
69+
}
70+
```
71+
72+
```java
73+
// 深复制行与值,定义对象共用
74+
public Project copyFrom(PlanInstance plan) {
75+
Project project = new Project();
76+
project.items = plan.getItems().stream()
77+
.map(PlanItem::copy)
78+
.collect(Collectors.toList());
79+
project.weight = plan.getWeight();
80+
project.indicator = plan.getIndicator(); // 定义对象共用
81+
return project;
82+
}
83+
```
84+
85+
```java
86+
// 唯一出口 + 带动作名的提示
87+
public boolean isConfigurable() {
88+
return state != State.END;
89+
}
90+
91+
private void requireConfigurable(String action) {
92+
if (!isConfigurable()) {
93+
throw new BusinessException("当前状态不允许" + action);
94+
}
95+
}
96+
97+
public void adjustWeight(int weight) {
98+
requireConfigurable("调整权重");
99+
this.weight = weight;
100+
}
101+
```
102+
103+
```java
104+
// 只读快照
105+
public List<PlanItem> getItems() {
106+
return List.copyOf(items);
107+
}
108+
```
109+
110+
### ❌ 错误示例
111+
112+
```java
113+
// ❌ 覆盖 equals 用可变 id,破坏哈希容器
114+
@Override
115+
public boolean equals(Object o) {
116+
return o instanceof Project && ((Project) o).id == this.id;
117+
}
118+
```
119+
120+
```java
121+
// ❌ 外部静态函数判断同一性,口径分散
122+
public static boolean isSamePlan(Project a, Project b) { ... }
123+
public static boolean containsProject(List<Project> list, Project p) { ... }
124+
```
125+
126+
```java
127+
// ❌ 共享可变引用:改项目会写回模板
128+
public Project from(PlanInstance plan) {
129+
Project project = new Project();
130+
project.items = plan.getItems(); // 同一个 List
131+
return project;
132+
}
133+
```
134+
135+
```java
136+
// ❌ 「能不能改」各处自行理解
137+
public void adjustWeight(int weight) {
138+
if (state == State.END) { // 别处可能还允许 PAUSED
139+
throw new BusinessException("已结束");
140+
}
141+
this.weight = weight;
142+
}
143+
```
144+
145+
```java
146+
// ❌ 集合直接外泄
147+
public List<PlanItem> getItems() {
148+
return items; // 调用方可直接 add / remove
149+
}
150+
```
151+
152+
## 自查清单
153+
154+
- [ ] 同一性判断是否为对象上的 `isSameAs` / `isSameAsAny`
155+
- [ ] 是否没有覆盖 `equals`(实体/聚合根)
156+
- [ ] 跨聚合复制是否深复制了行与值
157+
- [ ] 「能不能改」是否只经 `isConfigurable()` + `requireConfigurable(action)`
158+
- [ ] 集合出口是否为只读快照,内层集合是否也收口
Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
name: java/naming-convention
3+
module: java
4+
description: 方法命名规范:按返回数量选择 get/find,必须存在的场景用 require
5+
status: 已实现
6+
scope: 后端
7+
source: 项目自有
8+
---
9+
10+
## 解决什么问题
11+
12+
方法名不表达「返回几条」和「是否保证存在」,调用方只能靠猜:
13+
14+
- 名字叫 `getXxx` 却可能返回 `null`,调用方默认非空、不做判空,最终在业务路径上 NPE,把本该给出的业务提示(如「访问码不存在或已失效」)顶掉;
15+
- 同一个语义在不同类里分别叫 `get` / `find` / `query` / `load`,阅读和检索成本高;
16+
- 「必须存在」的校验散落在调用方,提示语各处一份、口径不一;
17+
- 为了「保证不为空」,在 `get` 里偷偷抛业务异常,名字与行为不符,调用方无从预判。
18+
19+
## 如何使用
20+
21+
### 核心规则
22+
23+
1. **按返回数量选动词,不看是否可能为空**:
24+
- 返回一条数据 → `getXxx`(返回对象或 `Optional` 都叫 `get`);
25+
- 返回多条数据 → `findXxx`(返回 `List`、`Set` 等集合)。
26+
2. **「必须存在,否则报错」→ 用语义动词表达前提**:使用 `requireXxx`(或 `loadXxxOrThrow` 这类明确的词),把前提写进方法名,不要靠 `get` 里偷偷抛异常。
27+
3. **`get` 是纯查询**:不校验、不抛业务异常。「找不到」由返回值表达——对象可为 `null`,或返回 `Optional`。
28+
4. **「必须有」的场合由调用方决定处理方式**:`orElseThrow`,或包一层 `requireXxx` 把提示语集中在一处。
29+
5. **命名描述契约,不描述实现**:`get` / `find` 只用于查询语义;有副作用或写入行为的操作不得使用 `get` / `find` 前缀,改用能表达动作的动词(`create`、`save`、`remove` 等)。
30+
31+
### 命名对照
32+
33+
| 语义 | 命名 | 返回约定 | 不存在时 |
34+
|------|------|----------|----------|
35+
| 取单条(可能不存在) | `getXxx` | 对象或 `Optional` | 返回 `null` / `Optional.empty()` |
36+
| 取多条 | `findXxx` | `List` / `Set` | 返回空集合,不返回 `null` |
37+
| 取单条(必须存在) | `requireXxx` | 对象 | 抛业务异常 |
38+
| 判断存在 | `existsXxx` | `boolean` | — |
39+
40+
## 使用实例
41+
42+
### ✅ 正确示例
43+
44+
```java
45+
public class AccountService {
46+
47+
// 单条:可能为 null
48+
public Account getAccount(long id) {
49+
return accountRepository.findById(id);
50+
}
51+
52+
// 单条:用 Optional 表达可能不存在
53+
public Optional<Account> getAccountByNo(String accountNo) {
54+
return accountRepository.findByNo(accountNo);
55+
}
56+
57+
// 多条:find
58+
public List<Account> findAccountsByOwner(long ownerId) {
59+
return accountRepository.findAllByOwner(ownerId);
60+
}
61+
62+
// 必须存在:前提写在名字里,提示语集中在一处
63+
public Account requireAccount(long id) {
64+
Account account = getAccount(id);
65+
if (account == null) {
66+
throw new BusinessException("账户不存在:" + id);
67+
}
68+
return account;
69+
}
70+
}
71+
```
72+
73+
```java
74+
// 调用方:需要「必须存在」时显式处理
75+
Account account = accountService.requireAccount(accountId);
76+
// 或
77+
Account account = accountService.getAccountByNo(no)
78+
.orElseThrow(() -> new BusinessException("账户不存在:" + no));
79+
```
80+
81+
### ❌ 错误示例
82+
83+
```java
84+
// ❌ get 返回 null,名字却暗示「已拿到有效对象」
85+
private AccessCode getActiveCode(String scene) {
86+
AccessCode code = accessCodeRepository.findByScene(scene);
87+
if (code == null || code.isUsed()) {
88+
return null;
89+
}
90+
return code;
91+
}
92+
93+
public void submitCode(String scene) {
94+
AccessCode code = getActiveCode(scene);
95+
code.markUsed(); // NPE:把「访问码不存在或已失效」的业务提示顶掉了
96+
}
97+
```
98+
99+
```java
100+
// ❌ get 里做校验并抛业务异常:名字与行为不符
101+
public Account getAccount(long id) {
102+
Account account = accountRepository.findById(id);
103+
if (account == null) {
104+
throw new BusinessException("账户不存在"); // 应叫 requireAccount
105+
}
106+
return account;
107+
}
108+
```
109+
110+
```java
111+
// ❌ 返回多条却用 get
112+
public List<Account> getAccounts(long ownerId) { ... } // 应为 findAccounts
113+
```
114+
115+
## 自查清单
116+
117+
- [ ] 返回单条的方法是否都叫 `getXxx`(`Optional` 也算 `get`)
118+
- [ ] 返回多条的方法是否都叫 `findXxx`
119+
- [ ] `get` / `find` 内是否没有任何业务校验与业务异常
120+
- [ ] 「必须存在」的场景是否用 `requireXxx` 或调用方 `orElseThrow` 显式表达

0 commit comments

Comments
 (0)