500 lines
15 KiB
Markdown
500 lines
15 KiB
Markdown
# 通用代码结构设计规范（强制执行）
|
||
|
||
本文档定义项目在长期演进中应遵守的结构边界、拆分原则与审计标准。
|
||
|
||
目标不是机械追求“小文件”“多目录”或“某种固定架构”，而是让任意语言、任意框架、任意部署形态下的代码都满足以下要求：
|
||
|
||
- 入口清晰
|
||
- 依赖方向稳定
|
||
- 职责边界明确
|
||
- 修改影响面可控
|
||
- 新人可顺序读懂
|
||
|
||
本文档适用于：
|
||
|
||
- 前端应用
|
||
- 后端服务
|
||
- CLI / 脚本 / Worker
|
||
- SDK / Library
|
||
- 单仓或多仓项目
|
||
|
||
本文档自落地起作为后续开发与重构的默认结构基线。
|
||
|
||
---
|
||
|
||
## 1. 核心原则
|
||
|
||
### 1.1 先划清职责，再决定目录
|
||
|
||
- 先区分“入口层 / 业务编排层 / 领域规则层 / 基础设施层 / 共享基础层”，再决定是否拆目录、拆文件、拆包。
|
||
- 目录结构是职责设计的结果，不是先验答案。
|
||
- 同一个团队可以采用不同目录形态，但不能模糊职责边界。
|
||
|
||
### 1.2 领域内聚优先于机械拆分
|
||
|
||
- 第一判断标准是“是否仍然属于同一业务主题”，不是“文件还能不能再拆小”。
|
||
- 同一主题内的读取、写入、校验、少量派生逻辑，可以保留在同一模块中。
|
||
- 如果拆分只会制造更多跳转、隐藏真实依赖、降低顺序可读性，就不应继续拆。
|
||
|
||
### 1.3 装配层必须薄
|
||
|
||
- 启动入口、路由入口、页面入口、命令入口都只负责装配。
|
||
- 装配层可以做依赖注入、参数收集、状态接线、组件拼装、调用编排入口。
|
||
- 装配层不应承载复杂业务规则、数据库细节、文件系统细节、网络细节或长流程状态机。
|
||
|
||
### 1.4 副作用必须收口
|
||
|
||
- 数据库访问、文件读写、网络调用、缓存、定时器、浏览器存储、进程环境依赖等，都属于副作用。
|
||
- 副作用应集中在可识别的边界模块中，不应在页面、视图、路由、DTO、纯工具里四处散落。
|
||
- 任何需要 mock、替换、复用或测试隔离的外部依赖，都应有明确归属。
|
||
|
||
### 1.5 依赖方向必须单向
|
||
|
||
- 默认依赖方向应从外向内：入口层 -> 业务编排层 -> 领域规则层 -> 基础设施实现。
|
||
- 共享基础层可以被多个层使用，但不能反向依赖业务实现。
|
||
- 低层不能反向引用高层具体实现来“图省事”。
|
||
|
||
### 1.6 文件大小不是目标，跨职责才是风险
|
||
|
||
- 行数只作为预警信号，不作为强制拆分指标。
|
||
- 真正需要拆分的信号包括：
|
||
- 一个模块服务多个业务主题
|
||
- 一个模块同时承担输入解析、业务决策、数据访问和展示
|
||
- 一个改动常常需要在同一文件中切换多种关注点
|
||
- 一个模块需要为不同调用方维持多套语义
|
||
|
||
### 1.7 重构优先低风险搬运
|
||
|
||
- 结构重构优先做“职责收口、边界清理、命名校正、依赖下沉/上提”。
|
||
- 默认不要在同一轮改动里同时进行：
|
||
- 大规模结构调整
|
||
- 新功能开发
|
||
- 行为修复
|
||
- 如果确需并行，必须以最小范围控制风险，并显式验证关键路径。
|
||
|
||
### 1.8 命名必须体现主题
|
||
|
||
- 文件、目录、模块、类型、服务名都应直接表达责任。
|
||
- 禁止使用模糊命名掩盖职责，例如：
|
||
- `misc`
|
||
- `helpers2`
|
||
- `commonThing`
|
||
- `temp_service`
|
||
- `manager_new`
|
||
|
||
---
|
||
|
||
## 2. 通用分层模型
|
||
|
||
以下是跨语言可复用的职责模型。项目不要求逐字使用这些目录名，但必须能映射到这些边界。
|
||
|
||
### 2.1 入口层 / 接口层
|
||
|
||
典型形态：
|
||
|
||
- 前端的 `App`、路由入口、页面入口
|
||
- 后端的 router / controller / handler
|
||
- CLI 的 command / main
|
||
- Worker 的 job handler / consumer entry
|
||
|
||
职责：
|
||
|
||
- 接收输入
|
||
- 做基础参数解析与协议适配
|
||
- 调用业务编排层
|
||
- 返回结果或渲染输出
|
||
|
||
禁止：
|
||
|
||
- 写复杂业务规则
|
||
- 直接拼装 SQL / ORM 流程
|
||
- 直接进行大段文件系统读写
|
||
- 直接进行复杂网络编排
|
||
- 在入口层内维护长生命周期状态机
|
||
|
||
### 2.2 业务编排层 / 用例层
|
||
|
||
典型形态：
|
||
|
||
- service
|
||
- use case
|
||
- action
|
||
- controller hook
|
||
- page model
|
||
- workflow
|
||
|
||
职责：
|
||
|
||
- 表达一个明确业务流程
|
||
- 协调多个依赖
|
||
- 承载事务边界、步骤顺序、状态推进
|
||
- 组织权限判断、前置校验、错误分支
|
||
|
||
要求：
|
||
|
||
- 一个模块只负责一个业务域或一个稳定子流程
|
||
- 可以依赖基础设施接口，但不应把具体协议细节暴露给上层
|
||
- 可以包含少量私有 helper，但 helper 仅服务当前主题
|
||
|
||
### 2.3 领域规则层
|
||
|
||
典型形态：
|
||
|
||
- domain service
|
||
- policy
|
||
- rule
|
||
- validator
|
||
- entity behavior
|
||
- pure business helpers
|
||
|
||
职责：
|
||
|
||
- 承载稳定的业务规则和领域语义
|
||
- 保持尽量纯净、可测试、与外部协议解耦
|
||
- 统一业务概念、状态转换、派生计算
|
||
|
||
要求：
|
||
|
||
- 不直接访问数据库、网络、文件、浏览器环境
|
||
- 不依赖 UI、HTTP、CLI、消息队列等入口协议
|
||
|
||
### 2.4 基础设施层 / 数据访问层
|
||
|
||
典型形态：
|
||
|
||
- repository
|
||
- gateway
|
||
- API client
|
||
- storage adapter
|
||
- cache adapter
|
||
- filesystem adapter
|
||
- persistence implementation
|
||
|
||
职责：
|
||
|
||
- 封装外部系统细节
|
||
- 处理数据库、缓存、HTTP、对象存储、消息队列、浏览器存储、操作系统能力
|
||
- 提供可复用的边界接口
|
||
|
||
要求：
|
||
|
||
- 只解决“怎么接外部系统”，不承担业务决策
|
||
- 协议转换、序列化、连接管理、重试策略等应在此层收口
|
||
|
||
### 2.5 共享基础层
|
||
|
||
典型形态：
|
||
|
||
- constants
|
||
- shared types
|
||
- date / string / number helpers
|
||
- 通用 UI 基础组件
|
||
- 通用错误定义
|
||
|
||
要求：
|
||
|
||
- 必须是真正跨域、稳定、低语义耦合的内容
|
||
- 不允许把业务逻辑伪装成“common / shared / utils”
|
||
- 一旦某模块开始依赖特定业务名词，它就不再是共享基础层
|
||
|
||
---
|
||
|
||
## 3. 目录与模块组织规范
|
||
|
||
### 3.1 允许的组织方式
|
||
|
||
项目可以采用以下任一方式：
|
||
|
||
- 按领域优先组织：`<domain>/<entry|application|infra|shared>`
|
||
- 按层优先组织：`entry/ application/ domain/ infra/`
|
||
- 混合组织：顶层按领域，领域内再分层
|
||
- Monorepo 组织：`apps/ packages/ services/ workers/`
|
||
|
||
允许多种组织方式并存，但必须满足：
|
||
|
||
- 同一仓库内的同类代码遵循一致的判断逻辑
|
||
- 每个模块都能被映射到明确职责层
|
||
- 依赖方向清晰、稳定、可审计
|
||
|
||
### 3.2 推荐的判断方式
|
||
|
||
当你不确定某段代码应该放哪里时，按顺序判断：
|
||
|
||
1. 它是在接收输入、渲染输出、还是拼装启动吗
|
||
2. 它是在表达一个完整业务流程吗
|
||
3. 它是在表达不依赖外部协议的业务规则吗
|
||
4. 它是在接数据库、文件、网络、缓存、浏览器或系统能力吗
|
||
5. 它真的是跨域共享能力吗
|
||
|
||
### 3.3 一个模块只能有一个主语义
|
||
|
||
- 一个模块可以有多个函数，但只能服务一个主职责。
|
||
- 如果一个文件既是“页面”又是“API 聚合器”又是“缓存控制器”又是“视图组件”，就已经越界。
|
||
- 如果一个 router 文件开始长时间停留在 SQL、文件读写、事务与状态轮询细节上，也已经越界。
|
||
|
||
### 3.4 兼容层与过渡层
|
||
|
||
- 允许存在短期兼容层、导出层、适配层。
|
||
- 兼容层必须被明确标记为过渡用途。
|
||
- 禁止长期把新逻辑继续堆回兼容层。
|
||
|
||
---
|
||
|
||
## 4. 前端通用规范
|
||
|
||
本节适用于 Web、桌面端、移动端和前端壳应用，不绑定 React / Vue / Svelte 等具体框架。
|
||
|
||
### 4.1 页面/路由入口必须薄
|
||
|
||
- 页面文件默认负责页面装配、布局组织、边界兜底。
|
||
- 页面可持有少量与页面展示强绑定的状态。
|
||
- 当页面开始同时承担以下两项及以上时，应拆出页面级编排模块：
|
||
- 多个接口请求
|
||
- 轮询或定时器
|
||
- 上传/下载流程
|
||
- 多个 Drawer / Modal / Sheet 子流程
|
||
- 复杂权限判断
|
||
- 大量数据清洗与派生
|
||
|
||
### 4.2 视图组件默认无副作用
|
||
|
||
- 纯视图组件只接收整理好的 props。
|
||
- 纯视图组件默认不直接请求接口、不直接碰浏览器存储、不直接起轮询。
|
||
- 如果一个组件必须自带数据流程，它应被明确视为“功能组件”或“场景组件”，而不是伪装成通用组件。
|
||
|
||
### 4.3 页面级业务流程应集中编排
|
||
|
||
- 页面相关的请求、轮询、草稿保存、上传进度、权限行为、状态联动，应尽量集中在页面编排层。
|
||
- 页面编排层可以是 hook、store、controller、presenter 或 view-model，不限定技术名词。
|
||
- 不要求为了形式而一律抽 hook；只有在页面入口已经承担过多流程时才拆。
|
||
|
||
### 4.4 前端基础设施应收口
|
||
|
||
- API client
|
||
- 本地存储
|
||
- Session / token 持久化
|
||
- 浏览器标题、副作用事件、定时器策略
|
||
- 配置读取
|
||
|
||
以上能力应收口在可识别模块中，不应被页面随机复制。
|
||
|
||
### 4.5 复用原则
|
||
|
||
- 提炼稳定复用模式，不提炼偶然重复。
|
||
- 三处以上重复，优先评估抽取。
|
||
- 如果抽取后的接口比原地代码更难理解，不应抽取。
|
||
- 不允许制造“只有一个页面使用、但包装层很多”的伪复用。
|
||
|
||
---
|
||
|
||
## 5. 后端通用规范
|
||
|
||
本节适用于 HTTP 服务、RPC 服务、任务处理器和后台作业，不绑定 FastAPI / Spring / NestJS / Gin 等框架。
|
||
|
||
### 5.1 启动入口必须只做装配
|
||
|
||
- `main`
|
||
- app factory
|
||
- bootstrap
|
||
- container
|
||
|
||
这些入口只负责：
|
||
|
||
- 创建应用实例
|
||
- 注册路由/处理器
|
||
- 初始化中间件
|
||
- 装配依赖
|
||
- 生命周期绑定
|
||
|
||
不应承担：
|
||
|
||
- 业务规则
|
||
- SQL 或 ORM 编排
|
||
- 文件系统细节
|
||
- 长流程任务控制
|
||
|
||
### 5.2 Router / Controller / Handler 只做协议转换
|
||
|
||
允许：
|
||
|
||
- 接收请求参数
|
||
- 基础校验
|
||
- 调用用例层
|
||
- 将领域错误映射为接口错误
|
||
|
||
不允许：
|
||
|
||
- 在 handler 内直接堆大量 SQL
|
||
- 一边处理权限，一边处理事务，一边操作文件，一边组装响应模型
|
||
- 在 handler 内实现长流程状态机
|
||
|
||
### 5.3 Service / Use Case 以业务域组织
|
||
|
||
- 一个 service 文件只负责一个业务域或一个稳定子主题。
|
||
- 同域内的查询、写入、校验、少量派生逻辑可以在一起。
|
||
- 如果一个 service 同时承担多个主题，应优先拆主题而不是拆技术动作。
|
||
|
||
### 5.4 数据访问与外部适配要收口
|
||
|
||
- 数据库查询
|
||
- ORM 组装
|
||
- 缓存细节
|
||
- 第三方 HTTP 调用
|
||
- 文件上传下载
|
||
- 对象存储
|
||
- 队列/任务系统
|
||
|
||
这些细节应尽量沉到 repository / gateway / adapter / infra 中。
|
||
|
||
### 5.5 Schema / DTO / Contract 必须纯净
|
||
|
||
- DTO 只用于定义契约，不应携带数据库、文件系统、网络调用或业务副作用。
|
||
- 契约字段演进必须可追踪。
|
||
- 避免让数据库模型、接口模型、领域模型长期混成一种结构。
|
||
|
||
---
|
||
|
||
## 6. CLI / 脚本 / Worker 规范
|
||
|
||
- 命令入口只负责解析参数、准备依赖、调用用例。
|
||
- 脚本如果会长期保留，必须从“一次性脚本”升级为可读的结构化模块。
|
||
- Worker handler 只负责接收消息、提取 payload、调用业务流程、回写状态。
|
||
- 重试、幂等、死信、超时策略等运行时策略应有单独归属，不应散落在业务逻辑内部。
|
||
|
||
---
|
||
|
||
## 7. 拆分与合并准则
|
||
|
||
### 7.1 何时应拆分
|
||
|
||
满足任一项即可考虑拆分：
|
||
|
||
- 同一模块出现多个业务主题
|
||
- 同一模块同时依赖多种外部系统
|
||
- 同一模块同时承担输入解析、业务编排、持久化和展示
|
||
- 多人修改时经常产生冲突
|
||
- 阅读一个改动需要频繁跨越无关上下文
|
||
- 相同规则被复制到多个入口
|
||
|
||
### 7.2 何时不应拆分
|
||
|
||
- 仍是单一主题
|
||
- 代码虽长但顺序可读
|
||
- 继续拆只会制造纯转发层
|
||
- 继续拆会让调用链更深、定位更慢
|
||
- 抽出后接口语义比原代码更含糊
|
||
|
||
### 7.3 合并也是一种优化
|
||
|
||
- 如果多个模块只是在相互转发、没有独立语义，应考虑合并。
|
||
- 如果拆分之后需要同时打开 4 到 6 个文件才能理解一个简单流程，通常已经过度拆分。
|
||
|
||
---
|
||
|
||
## 8. 命名与依赖规则
|
||
|
||
### 8.1 命名规则
|
||
|
||
- 名称应表达业务主题或技术边界，不表达情绪和历史包袱。
|
||
- 优先使用“对象 + 语义”命名，而不是“抽象 + 序号”命名。
|
||
- 避免模糊后缀：
|
||
- `handler2`
|
||
- `newService`
|
||
- `commonUtils`
|
||
- `tempPage`
|
||
|
||
### 8.2 依赖规则
|
||
|
||
- 上层可以依赖下层抽象，不应依赖下层杂乱细节。
|
||
- 共享层不能反向依赖业务层。
|
||
- 领域模块之间若需协作，应通过明确用例、接口或边界对象完成，而不是互相穿透内部实现。
|
||
|
||
---
|
||
|
||
## 9. 测试与验证要求
|
||
|
||
### 9.1 结构改动后的默认验证
|
||
|
||
- 前端结构改动后，至少执行构建或类型校验。
|
||
- 后端结构改动后，至少执行语法校验、启动校验或最小测试集。
|
||
- 如果改动涉及契约、权限、状态流转、持久化边界，应追加针对性验证。
|
||
|
||
### 9.2 测试优先级
|
||
|
||
- 先保关键业务路径
|
||
- 再保跨层边界
|
||
- 再保复杂状态流转
|
||
- 最后补充纯工具覆盖
|
||
|
||
### 9.3 文档同步要求
|
||
|
||
以下情况必须同步设计文档或架构说明：
|
||
|
||
- 新增一层明确职责边界
|
||
- 新增一个稳定领域模块模板
|
||
- 改变入口层、用例层、基础设施层的责任划分
|
||
- 引入新的运行时或新的跨项目复用规范
|
||
|
||
---
|
||
|
||
## 10. 评审与审计清单
|
||
|
||
做结构评审时，默认检查以下问题：
|
||
|
||
### 10.1 入口层
|
||
|
||
- 入口是否足够薄
|
||
- 是否混入业务规则
|
||
- 是否混入外部系统细节
|
||
|
||
### 10.2 业务编排层
|
||
|
||
- 是否以业务主题组织
|
||
- 是否承担了过多无关流程
|
||
- 是否存在纯转发服务
|
||
|
||
### 10.3 领域规则层
|
||
|
||
- 是否仍保持纯净
|
||
- 是否被框架、HTTP、数据库协议污染
|
||
|
||
### 10.4 基础设施层
|
||
|
||
- 副作用是否收口
|
||
- 是否把业务规则偷偷塞回 adapter / utils / core
|
||
|
||
### 10.5 共享层
|
||
|
||
- 是否真的跨域复用
|
||
- 是否把业务逻辑伪装成 common / shared / utils
|
||
|
||
### 10.6 演进风险
|
||
|
||
- 新增功能是否沿着既有边界落位
|
||
- 兼容层是否在持续变厚
|
||
- 是否出现单文件多职责继续膨胀
|
||
|
||
---
|
||
|
||
## 11. 禁止事项
|
||
|
||
- 禁止为了图省事把新逻辑堆回入口层
|
||
- 禁止为了“文件更短”制造无语义的纯包装层
|
||
- 禁止在 `utils` / `common` / `shared` 中隐藏领域逻辑
|
||
- 禁止让页面、路由、handler 直接承载大量持久化或文件系统细节
|
||
- 禁止把 schema / DTO / config 当成业务逻辑容器
|
||
- 禁止一次改动里同时重写结构、协议、UI 和业务行为，且没有明确验证策略
|
||
|
||
---
|
||
|
||
## 12. 执行基线
|
||
|
||
后续所有新增功能、重构与代码审计，均以本文档为默认判断依据：
|
||
|
||
- 先判断职责边界是否正确
|
||
- 再判断依赖方向是否健康
|
||
- 再判断是否需要拆分或合并
|
||
- 最后才考虑目录美观、文件长短和风格一致性
|
||
|
||
当“看起来更模块化”和“真实可读、可改、可验证”发生冲突时，优先后者。
|