logo
0
0
WeChat Login

docs(rules): 阶段 1 · PR 2/3 — backend 规则拆层为核心+参考实现#18

Merged
created 2 weeks ago
main
docs/backend-rule-split
Edit
OverviewCommits
1
Files changed
9
Attachments

为什么做这个

PR #17 落地了 R0 元原则,但 backend-development.md(1629 行)仍是Java/Spring/MyBatis 特化,让脚手架对 Go/Node/Python 后端项目毫无用处。违反定位 A(通用 AI Agent 协作框架)。

解法:核心 + 参考实现

不是删 Java 内容(那 1600 行资产太珍贵),而是分层

文件内容
通用骨架rules/backend-core.md(新增,440 行)任何后端栈都适用的硬约束
Java 参考实现rules/.archived/backend-java-spring.md(原文归档)Java + Spring Boot 的完整落地,1600 行资产保留

backend-core.md 的 11 章节

  1. 分层架构:接口/应用/数据三层 + 循环依赖禁止 + 按业务模块化(跨语言工具:ArchUnit / jdeps / madge / pydeps / go mod graph)
  2. 边界对象:DTO ≠ VO ≠ Entity,三者各自的职责与禁止
  3. API 设计:RESTful + 统一响应 + 错误码分段(40001~/50001~)+ 契约化(OpenAPI/proto/SDL/JSON Schema)
  4. 应用层:业务动作命名 + 事务显式化 + 幂等(多语言工具:Java @Transactional / Node TypeORM / Python @transaction.atomic)+ 状态机显式
  5. 统一异常:5 类异常 + 单一全局处理入口(@RestControllerAdvice / Express middleware / Nest ExceptionFilter / FastAPI exception_handler
  6. 配置与密钥:环境分离 + 密钥注入 + 迁移脚本(Flyway/Liquibase/Alembic/Prisma Migrate)
  7. 日志:结构化 + traceId + 敏感脱敏
  8. 并发:共享状态显式策略 + 线程池有界命名 + 异常不吞
  9. 安全基线:OWASP 底线(参数化查询 / 慢哈希 / 鉴权统一拦截 / 依赖扫描)
  10. 测试门禁:派生自 meta-principles §原则 1-3
  11. 代码风格:各栈主流工具对照表(Java/Kotlin/Go/Node/Python)

附录:新增技术栈 5 步落地步骤。

跨栈示例均衡

Java:   8 处
Go:     8 处
Node:   7 处
Python: 7 处
Kotlin: 2 处

Java/Spring 在 backend-core 中的提及仅限于跨栈对比("Java 用 @Transactional、Node 用 TypeORM、Python 用 @transaction.atomic"这种形态),不作为硬要求。

归档处理

backend-java-spring.md 头部加了定位说明:

- 本文件是 backend-core.md 的 Java + Spring Boot 参考实现
- 其他栈项目以 backend-core.md 为主
- 声明派生自 meta-principles 的 5 条元原则

1600 行原内容一行不删,完整保留团队积累的 Java 实战经验。

跨文件引用更新(连锁反应)

文件处理
.codebuddy/README.md 规则索引新增 R4(backend-core)+ R4-java 两行
project-architecture.md循环依赖引用指向 backend-core.md §1.2 + Java 实现 §1.1
code-review/backend-checklist.md定位为 Java 栈特化的 checklist
requirement-workflow/SKILL.md引用路径更新
README.md 目录结构 + 快速上手步骤同步
LESSONS.md 资产清单、已知限制同步

改动统计

8 files changed, 418 insertions(+), 20 deletions(-)
新增: rules/backend-core.md (440 行)
归档: rules/backend-development.md → rules/.archived/backend-java-spring.md

自举验证

  • read_lints 0 错误
  • ✅ backend-core.md 无 Java/Spring/MyBatis 硬绑定
  • ✅ 跨栈示例均衡
  • ✅ 所有旧引用已更新(grep 确认 0 残留)

下一步(阶段 1 收官)

PR 3/3:frontend 同模式处理 + meta-principles 引用在各规则里补齐(给剩余 7 份规则加 派生自原则 X 的标注行)+ 最终抽象度扫描。

通用性声明

本 PR 后backend-core.md 可以直接迁移到任何后端技术栈的项目使用;Java 项目可继续用 .archived/backend-java-spring.md 的完整参考实现;新增 Go/Node/Python 栈时按附录 5 步走。

is using the squash method to merge into20abf5e5
docs(rules): backend 规则拆层为核心+参考实现 (#18)
docs(checkpoint): 回填 PR #29 CNB 首绿实测 + 事实更正 + 隐藏 bug 记录

Successfully merged and closed

branch can be safely deleted
Reviewer
None yet
Assignee
None yet
Label
None yet
Participant