Skip to content

Commit 0dcd170

Browse files
committed
docs: 新增 AGENTS.md 统一维护开发指南,CLAUDE.md/CODEBUDDY.md 简化为引用入口
1 parent 4ae4f54 commit 0dcd170

3 files changed

Lines changed: 296 additions & 238 deletions

File tree

‎AGENTS.md‎

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to AI coding agents when working with code in this repository.
4+
5+
## 项目概述
6+
7+
springboot-framework 是一个基于 Spring Boot 3.3.5(Java 17)的多模块企业级开发框架,由 CodingApi 团队维护。核心定位是为领域驱动设计(DDD)与事件风暴提供开箱即用的基础设施。当前开发版本为 `17.3.0-SNAPSHOT`,采用 Maven `${revision}` CI-Friendly 版本机制,正式发布时通过 `-Drevision=x.y.z` 指定正式版本号。版本号含义:17 = JDK 版本,3 = Spring Boot 大版本,第三位为补丁版本。
8+
9+
**回复语言**:请使用中文进行回答。
10+
11+
## 常用命令
12+
13+
```bash
14+
# 全量构建
15+
./mvnw clean install
16+
17+
# 仅运行测试(CI 使用)
18+
./mvnw clean test -P travis
19+
20+
# 运行单个模块的测试
21+
./mvnw test -pl springboot-starter
22+
./mvnw test -pl springboot-starter-security
23+
24+
# 运行单个测试类
25+
./mvnw test -pl springboot-starter -Dtest=SomeTestClass
26+
27+
# 运行 example 示例应用(端口 8090,H2 文件数据库)
28+
./mvnw spring-boot:run -pl example/example-server
29+
30+
# 正式发布(通过 -Drevision 指定正式版本号,无需修改 pom)
31+
./mvnw clean deploy -P ossrh -Drevision=17.3.0
32+
```
33+
34+
### 前端(frontend monorepo)
35+
36+
```bash
37+
cd frontend
38+
pnpm install
39+
pnpm dev:pc # PC 端开发模式(代理后端)
40+
pnpm dev:mobile # 移动端开发模式(代理后端)
41+
pnpm mock:pc # PC 端 Mock 模式(前端 mock 数据)
42+
pnpm mock:mobile # 移动端 Mock 模式(前端 mock 数据)
43+
pnpm build:pc # PC 端生产构建
44+
pnpm build:mobile # 移动端生产构建
45+
pnpm test:pc # PC 端 Jest 测试
46+
pnpm test:mobile # 移动端 Jest 测试
47+
```
48+
49+
- apps/pc(原 admin-ui)基于 React 18 + Ant Design 5 + Ant Design Pro Components + Rsbuild
50+
- apps/mobile(原 mobile-ui)基于 React 18 + Ant Design Mobile 5 + Rsbuild
51+
- 两者由 pnpm workspace 统一管理,公共代码位于 packages/shared(@springboot-framework/shared);均使用 Module Federation 做微前端集成
52+
53+
## 模块架构
54+
55+
### Starter 模块(框架核心)
56+
57+
| 模块 | 职责 |
58+
|------|------|
59+
| `springboot-starter` | 核心基础:统一 Response DTO、分页 PageRequest/Filter、事件系统、国际化异常、事务管理 |
60+
| `springboot-starter-security` | Spring Security + JWT 无状态认证 / Redis 有状态认证,加解密支持 |
61+
| `springboot-starter-data-fast` | JPA 增强:FastRepository 支持动态过滤查询、HQL 构建、SearchRequest |
62+
| `springboot-starter-data-authorization` | 数据权限:通过 JDBC Connection/Statement 代理拦截 SQL,透明注入权限条件 |
63+
| `springboot-starter-script` | Groovy 脚本引擎:运行时编译、LRU 缓存、热更新,提供 REST API |
64+
65+
### 自动配置注册
66+
67+
各 starter 模块同时维护 `META-INF/spring.factories`(兼容旧版)和 `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`(Spring Boot 3.x 标准)。新增 starter 时需同时注册这两种文件。
68+
69+
### 模块间依赖关系
70+
71+
```
72+
springboot-starter (核心,无外部依赖)
73+
├── springboot-starter-security (依赖 starter)
74+
├── springboot-starter-data-fast (依赖 starter)
75+
├── springboot-starter-data-authorization (依赖 starter + JSqlParser)
76+
└── springboot-starter-script (依赖 starter + Groovy)
77+
```
78+
79+
## 核心架构模式
80+
81+
### 事件系统(Event System)
82+
83+
框架自建的发布-订阅事件机制,是 DDD 领域事件的核心基础设施:
84+
85+
- **`IEvent`** — 事件标记接口,分为 `ISyncEvent`(同步)和 `IAsyncEvent`(异步)
86+
- **`IHandler<T extends IEvent>`** — 事件处理器,支持 `order()` 排序和 `error()` 异常回调
87+
- **`EventPusher.push(event, sync)`** — 事件推送入口
88+
- **`DomainEvent`** — 领域实体事件基类,派生 `DomainCreateEvent`、`DomainChangeEvent`、`DomainDeleteEvent`
89+
- **`DomainChangeInterceptor`** — 通过代理拦截实体字段变更,自动推送 `DomainChangeEvent`
90+
91+
Handler 通过 Spring Bean 自动注册,由 `HandlerBeanDefinitionRegistrar` 扫描所有 `IHandler` 实现并注册到 `ApplicationHandlerUtils`。
92+
93+
### 统一响应封装
94+
95+
```java
96+
Response // 基础响应(success / errCode / errMessage)
97+
SingleResponse<T> // 单对象响应
98+
MultiResponse<T> // 列表响应
99+
MapResponse // Map 响应
100+
```
101+
102+
### 数据查询(PageRequest + FastRepository)
103+
104+
`PageRequest` 扩展了 Spring Data 的 `PageRequest`,增加了 `RequestFilter` 动态过滤条件:
105+
106+
```java
107+
PageRequest request = PageRequest.of(0, 20);
108+
request.addFilter("name", "张三");
109+
request.addFilter("age", Relation.GREATER_THAN, 18);
110+
Page<User> page = userRepository.findAll(request);
111+
```
112+
113+
`FastRepository.findAll(PageRequest)` 自动根据 Filter 构建 Example 或 HQL 查询。
114+
115+
### 数据权限(SQL 拦截)
116+
117+
`ConnectionProxy` → `PreparedStatementProxy` / `StatementProxy` 代理链,在 SQL 执行前通过 `SQLRunningContext.intercept(sql)` 注入权限条件,实现透明的行级数据过滤。使用 JSqlParser 解析和改写 SQL。
118+
119+
## DDD 示例项目结构(example 模块)
120+
121+
```
122+
example/
123+
example-server — Spring Boot 启动入口
124+
example-interface — 接口层:Controller(API)、Handler(事件处理)、Runner
125+
example-app — 应用层
126+
example-app-query — 查询服务(CQRS Query 侧)
127+
example-app-cmd-domain — 命令服务(CQRS Command 侧,领域编排)
128+
example-app-cmd-meta — 元数据命令服务
129+
example-domain — 领域层
130+
example-domain-user — 用户领域(Entity、Repository、Service、Event、Gateway)
131+
example-infra — 基础设施层
132+
example-infra-jpa — JPA 持久化实现
133+
example-infra-security — 安全配置
134+
```
135+
136+
遵循 DDD 分层依赖规则:`interface → app → domain ← infra`。domain 层定义 Repository 接口,infra 层提供实现。
137+
138+
## 框架配置项
139+
140+
在 `application.properties` 中可用的配置前缀:
141+
142+
```properties
143+
# 安全模块
144+
codingapi.security.jwt.enable=true # 启用 JWT 认证
145+
codingapi.security.redis.enable=true # 启用 Redis 有状态认证
146+
codingapi.security.ignore-urls=/open/**,/#/** # 免认证 URL 列表
147+
148+
# 框架核心
149+
codingapi.framework.handler-thread-pool-size=20 # 事件异步线程池大小
150+
```
151+
152+
## 关键依赖版本
153+
154+
见根 `pom.xml` 的 `<properties>` 区块。主要版本:Groovy 4.0.24、JSqlParser 5.0、Fastjson 2.0.53、JJWT 0.12.6、H2 2.3.232。
155+
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+
```
245+
246+
<!-- PKR-START -->
247+
## PKR 知识查阅(编码前必须)
248+
249+
进入计划模式或实现功能前,**必须按以下优先级查阅**:
250+
251+
### ⚠️ 开发规范(最高优先级,必须严格遵守)
252+
253+
1. [docs/conventions/index.md](./docs/conventions/index.md) — 项目开发规范
254+
255+
**规范具有最高优先级。** 所有代码必须遵循已注册的 Convention,违反规范的代码视为缺陷。
256+
编码前必须逐条检查相关规范,确保命名、结构、模式完全符合要求。
257+
258+
### 已有能力(必须复用,禁止重复实现)
259+
260+
2. [docs/capabilities/index.md](./docs/capabilities/index.md) — 已有可复用能力
261+
262+
已有能力必须复用,禁止重新实现。优先组合已有能力解决问题。
263+
264+
### 计划模式约束
265+
266+
计划方案中必须包含:
267+
1. **遵循了哪些规范** — 列出遵守的 Convention(必须首先说明)
268+
2. **复用了哪些已有能力** — 列出从 PKR 中找到并复用的 Capability
269+
3. **是否有新增能力** — 如果本次开发产生了可复用的新能力,完成后通过 `/pkr-add` 注册
270+
271+
### 知识管理命令
272+
273+
| 命令 | 用途 |
274+
|------|------|
275+
| `/pkr-init` | 扫描项目,发现候选能力和规范(自动跳过已有文档) |
276+
| `/pkr-sync` | 全量同步,对比代码变更 |
277+
| `/pkr-update <module>/<name> [desc]` | 单项更新,可带描述指导更新 |
278+
| `/pkr-add <module>/<name> <desc>` | 从代码/框架扫描注册 |
279+
| `/pkr-add plan <module>/<name> <desc>` | 注册计划中的能力 |
280+
| `/pkr-export <module> ...` | 导出模块文档供其他项目使用 |
281+
<!-- PKR-END -->

0 commit comments

Comments
 (0)