152 lines
7.8 KiB
Markdown
152 lines
7.8 KiB
Markdown
# 通用开发协作规范
|
||
|
||
## 1. 文档定位
|
||
|
||
本文记录可跨项目复用的开发习惯、协作方式、工程边界和 agent 工作规则。
|
||
|
||
新项目可以复制本文为根目录 `AGENTS.md`，再补充项目特有的技术栈、目录、启动命令和业务约束。
|
||
|
||
## 2. 工作方式
|
||
|
||
- 先确认目标、边界和验收标准，再写代码。
|
||
- 大改动前先说明目标、范围和预计修改的文件。
|
||
- 每次只做一个明确 checkpoint，不顺手扩展无关功能。
|
||
- 不修改与当前任务无关的用户变更。
|
||
- 不回滚用户自己的改动，除非用户明确要求。
|
||
- 遇到不确定的技术栈、目录、接口契约或数据模型，先确认再继续。
|
||
- 新项目初始化或技术栈升级前，必须检查前端、后端、构建工具、测试工具和运行时版本兼容性。
|
||
- 输出分层结构、目录树、数据模型、字段映射或接口示例时，必须补充中文说明，不能只依赖英文命名表达业务含义。
|
||
|
||
## 3. 分支与提交
|
||
|
||
- 稳定分支保持可交付。
|
||
- 集成分支用于合并多个功能。
|
||
- `feature/*` 用于具体开发。
|
||
- commit message 使用中文，清楚说明本次业务或技术变更。
|
||
- 提交前检查工作区，避免误提交本地文件、Secret、构建产物或真实业务数据。
|
||
|
||
## 4. 项目结构
|
||
|
||
- 前端、后端、文档和接口契约应分目录管理。
|
||
- 前端只负责展示、交互和调用本项目后端。
|
||
- 后端负责数据库、Secret、外部系统适配、业务规则、审计和安全脱敏。
|
||
- 文档目录应保存设计文档、导入规范、接口说明和重要决策记录。
|
||
- 接口契约要有唯一来源，避免前端和后端各写一套互相漂移的定义。
|
||
- 架构图、目录树、模块边界、表结构和接口字段说明应优先使用中文解释职责、依赖方向和业务含义。
|
||
|
||
## 5. 技术栈版本兼容性
|
||
|
||
新项目建立规范或引入依赖前，应先形成最小版本矩阵，确认前端、后端、运行时、构建工具、测试工具和接口契约工具之间没有明显冲突。
|
||
|
||
最低检查范围：
|
||
|
||
- 后端语言版本、语法版本、框架版本、ORM / Mapper、数据库迁移工具、OpenAPI 工具和测试框架。
|
||
- 前端 Node.js 版本、包管理器、框架、语言、构建工具、Lint、类型检查、测试框架和 UI 组件库。
|
||
- 前后端接口契约工具，例如 OpenAPI 生成器、类型生成器、序列化格式和日期时间格式。
|
||
- 本地开发、CI、部署环境的运行时版本是否一致。
|
||
|
||
落地要求：
|
||
|
||
- 项目级文档必须写清楚当前采用的版本和兼容约束。
|
||
- 版本结论应优先来自官方文档、项目依赖文件、锁文件或实际验证命令。
|
||
- 发现版本冲突时，先调整版本方案，再生成代码或项目骨架。
|
||
- 升级核心依赖前，应先检查 breaking changes、运行时要求和配套插件支持范围。
|
||
- 无法确认兼容性时，应在项目文档中标记为待确认，不能假装已经验证。
|
||
|
||
## 6. 低耦合与可维护性
|
||
|
||
项目各功能模块必须保持低耦合、高内聚和高可维护性。新增功能时，应先明确模块边界、输入输出、依赖方向和验收标准，再开始实现。
|
||
|
||
落地要求：
|
||
|
||
- 每个模块只负责一个清晰业务能力。
|
||
- 依赖方向必须单向清晰，通用能力不能反向依赖具体业务。
|
||
- 跨模块调用优先通过 Service、Port、API 契约或事件完成，不直接访问对方 Mapper、Entity 或内部实现。
|
||
- 外部系统能力通过 Adapter 隔离，业务层只依赖稳定端口。
|
||
- DTO、Entity、Domain、Response、外部系统 DTO 不混用。
|
||
- 公共代码只有在出现真实重复和稳定语义后再抽取。
|
||
- 禁止提前设计大而全的通用工具、通用服务或通用模型。
|
||
- 单个文件、类、方法或组件过大时，应按业务职责拆分。
|
||
- 修改一个功能时，不应迫使无关模块跟着改；频繁连锁修改说明边界需要重新设计。
|
||
- 测试应覆盖模块公开行为和关键边界，避免只测试内部实现细节。
|
||
|
||
## 7. 前端规范
|
||
|
||
- 使用 TypeScript 时应开启严格类型检查。
|
||
- 页面组件负责展示和交互，不直接承载复杂业务规则。
|
||
- API 请求统一封装，不在组件里拼接后端 URL。
|
||
- 服务端数据不要长期复制进客户端全局状态。
|
||
- 前端不得保存或传递后端 Secret、Provider API Key、数据库凭证或客户渠道 Token。
|
||
- 不使用中文或英文显示文案做业务判断。
|
||
|
||
## 8. 后端规范
|
||
|
||
- Controller 只处理 HTTP 契约、参数校验、权限入口和响应映射。
|
||
- Service 编排业务流程、事务、领域对象、Repository 和外部端口。
|
||
- 外部系统通过 Port / Adapter 隔离，业务层不直接依赖厂商 SDK 或外部 DTO。
|
||
- 数据库变更必须可追踪；已发布 migration 不直接修改。
|
||
- 新项目建表前必须明确数据库字符集和 collation 策略；MySQL 项目默认建议使用 `utf8mb4_bin`，避免外部 ID、Token、哈希、状态码或业务代码因大小写不敏感而误判。
|
||
- 写接口要考虑幂等、并发版本、审计、失败恢复和脱敏。
|
||
|
||
Java 后端代码默认参考 Alibaba Java Coding Guidelines。可复用摘要见 `docs/import/reusable/alibaba-java-coding-guidelines-summary.md`。
|
||
|
||
后端基础结构、ID、审计字段、分页和 Mapper 规范可复用 `docs/import/reusable/backend-base-structure-pagination-guidelines.md`。
|
||
|
||
核心要求：
|
||
|
||
- 命名清晰，不使用拼音、无意义缩写或随意缩写。
|
||
- DTO、Entity、领域对象、VO / Response 不混用。
|
||
- 不写魔法值，业务代码、状态码和固定字符串应抽为常量或枚举。
|
||
- 集合、空值、字符串、时间、金额和 `BigDecimal` 使用安全写法。
|
||
- 异常不吞掉，日志有上下文但不输出 Secret、Token 或个人敏感信息。
|
||
- 分层结构、包结构、数据模型和字段映射必须配中文注释或中文说明，说明每层职责、依赖方向和关键字段含义。
|
||
- 复杂流程、幂等、事务、外部字段映射和脱敏逻辑要写必要中文注释。
|
||
|
||
## 9. 接口契约
|
||
|
||
- API 返回稳定代码，不返回中文或英文文本作为前端业务判断依据。
|
||
- 动态字段使用稳定 `fieldKey` 和可国际化 `labelKey`。
|
||
- 错误响应不得回显 Secret、Token、原始消息正文、附件 URL 或个人敏感信息。
|
||
- 接口变更前先确认领域模型、字段映射、前端影响和测试范围。
|
||
|
||
## 10. 安全规范
|
||
|
||
- Secret 只放环境变量、本地 `.env` 或部署平台 Secret。
|
||
- 仓库只提交无真实值的 `.env.example`。
|
||
- 禁止提交真实客户数据、Token、Cookie、API Key、数据库密码或支付信息。
|
||
- 日志、错误响应和测试夹具不得暴露敏感信息。
|
||
- `.DS_Store`、构建产物、依赖目录、IDE 临时文件和本地样本目录应忽略。
|
||
|
||
## 11. 测试与验证
|
||
|
||
- 修改后运行对应模块已有检查命令。
|
||
- 如果检查命令尚未配置或因环境问题无法运行，必须明确说明原因。
|
||
- 不假装测试通过。
|
||
- 优先做小的可验证闭环，再逐步扩展业务能力。
|
||
- 高风险改动需要补充更接近真实使用路径的测试。
|
||
|
||
## 12. Agent 协作规则
|
||
|
||
Coding agent 开始任务前应先读取：
|
||
|
||
1. `AGENTS.md`
|
||
2. `README.md`，如果存在
|
||
3. `docs/` 中与当前任务相关的文档
|
||
4. 当前代码结构和最近 Git 状态
|
||
|
||
改文件前要说明计划；完成后要说明改了什么、如何验证、还有哪些风险或未完成项。
|
||
|
||
## 13. 新项目补充模板
|
||
|
||
复制到新项目后，建议补充：
|
||
|
||
- 项目名称和业务定位。
|
||
- 技术栈和版本。
|
||
- 前后端与运行时版本兼容性检查结论。
|
||
- 目录结构。
|
||
- 分层结构、数据模型和字段映射的中文说明。
|
||
- 本地启动、测试、构建命令。
|
||
- 接口契约位置。
|
||
- 不能随便改的目录或文件。
|
||
- 当前第一个 checkpoint 和验收标准。
|