Files

3.0 KiB

代码结构与重构标准

这份标准用于控制现有模块继续膨胀,并约束后续大文件重构。它不是替代 docs/engineering-delivery-checklist.md,而是补充结构边界。

通用规则

  • 页面、Controller、Service 只保留一个明确入口;独立业务规则、数据映射、授权判断和视图状态必须拆出命名模块。
  • 单文件超过 500 行必须提供拆分计划;超过 800 行应拆分。拆分要按职责,不按行数机械切分。
  • 禁止在页面组件内内联完整 API 调用、复杂 JSON 转换和多层级业务规则。
  • 禁止新增全局工具函数堆积文件;按领域模块导出,不建 utils.ts 黑洞。
  • 迁移、DTO、API Client 类型、页面、测试和文档随行为一起变更。

Admin React 标准

  • 页面组件负责组合布局和路由;不直接实现超过一个相关领域的业务逻辑。
  • 一个页面由以下边界组成:
    • 页面组件:布局、路由、页面状态组合。
    • hooks:数据查询、mutation、表单初始化、草稿与预览状态。
    • 领域工具:纯函数,可单测,不调用 fetch。
    • feature 组件:局部 UI 区块。
    • shared components:跨 feature 使用的表单字段、状态和基础控件。
  • React Query 的 query key、失效和成功提示统一放在 hooks 中;页面不要散落 invalidateQueries。
  • 表单初始化、同步字段、脏检查和失败恢复不能重复实现;优先复用同一模块。
  • 类型边界使用 API Client 导出类型,不在页面重建后端响应形状。

API NestJS 标准

  • Controller 只处理认证入口、DTO、状态码、响应形状和路由。
  • 授权、Prisma、模板安装、快照组装、工作流推进必须进入 Service 或 Guard。
  • 同一个领域不要分散在根目录和 modules 中;新代码必须归入领域模块,旧 Controller 重构时逐步迁移。
  • DTO 是唯一输入边界;禁止 Partial<T>、any、未验证 JSON 和 Controller 内私有 schema。
  • 授权测试、成功行为、失败路径和品牌隔离测试是结构重构不可删除的回归线。

API Client 标准

  • 按资源拆分方法模块和类型模块;index.ts 只做聚合导出和 Client 组装。
  • 一个资源定义一组类型、一组方法、一致的错误语义,不在 Client 内做页面专用逻辑。

Config 与模板包标准

  • manifest、runtime、admin 契约、示例内容分别放独立模块;避免一个大索引文件同时承载所有契约。
  • 模板字段必须声明 binding、输入类型和预览目标;模板键使用 allow-list,不接受任意字符串。

重构流程

  1. 先建立或修改标准,再动代码。
  2. 每轮只处理一个高影响热点,保持外部行为不变。
  3. 重构后运行 pnpm format:check、pnpm lint、pnpm typecheck、相关测试和生产构建。
  4. 行为变化必须有测试;纯结构重构也必须保留所有授权、品牌隔离和关键 UI 状态测试。
  5. 在分支完成并全量验证后合并回 main。