# 通用代码结构设计规范（强制执行） 本文档定义项目在长期演进中应遵守的结构边界、拆分原则与审计标准。 目标不是机械追求“小文件”“多目录”或“某种固定架构”，而是让任意语言、任意框架、任意部署形态下的代码都满足以下要求： - 入口清晰 - 依赖方向稳定 - 职责边界明确 - 修改影响面可控 - 新人可顺序读懂 本文档适用于： - 前端应用 - 后端服务 - 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 允许的组织方式 项目可以采用以下任一方式： - 按领域优先组织：`/` - 按层优先组织：`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. 执行基线 后续所有新增功能、重构与代码审计，均以本文档为默认判断依据： - 先判断职责边界是否正确 - 再判断依赖方向是否健康 - 再判断是否需要拆分或合并 - 最后才考虑目录美观、文件长短和风格一致性 当“看起来更模块化”和“真实可读、可改、可验证”发生冲突时，优先后者。