Skip to content

Commit 4ae4f54

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 b2b6e9f commit 4ae4f54

8 files changed

Lines changed: 804 additions & 1 deletion

File tree

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,3 +53,6 @@ build/
5353
### flatten-maven-plugin ###
5454
.flattened-pom.xml
5555
test.db*
56+
57+
### worktrees ###
58+
.worktrees/

‎CLAUDE.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,95 @@ codingapi.framework.handler-thread-pool-size=20 # 事件异步线程池大小
153153

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

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

157246
<!-- PKR-START -->
158247
## PKR 知识查阅(编码前必须)

‎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+
- [ ] 集合出口是否为只读快照,内层集合是否也收口

0 commit comments

Comments
 (0)