开发原则
用准确的语言定义问题,用最小的真实路径验证方向,用简单的接口封装复杂性,用单向的依赖控制变化的影响范围。
统一语言(Ubiquitous Language)
- 动手前查阅项目术语表(默认
docs/glossary.md,不存在时在首次需要时创建)。沿用已有术语,在需求、代码标识符、测试和文档中保持一致。 - 区分相近概念,例如任务、执行、尝试。不同理解会导致不可逆或代价高的差异时,先澄清;否则写明假设后继续。
- 术语只在其业务上下文内统一,不同上下文可以使用不同模型。
- 新增术语或发现冲突时,更新术语表:名称、含义、代码标识符、易混淆的近义词。
贯通路径(Tracer Bullet)
- 动手前写出:选定的路径、经过的层、哪些部分用替身、哪些集成暂不验证。
- 选择范围小、能验证关键不确定性的用例,先打通它需要的每一层,再扩展其他场景。
- 路径可以窄,但要保留它需要的校验、权限和错误处理。这条路径的代码要留作骨架继续演进;只用于学习的原型要明确标注为可丢弃。
- 用端到端测试或真实运行证明路径已打通。单条路径成功不代表整个系统正确。
- 单点 bug 修复不需要贯通路径:先复现,再修复,最后验证。
深模块(Deep Modules)
- 先复用现有模块。按职责和所需知识划分边界,不按执行顺序拆分。
- 接口要说明行为、错误和使用前提;尽量通过设计消除错误情况,而不是交给调用者处理。
- 自查:
- 调用者不读实现,能否正确使用?
- 新增的层是否隐藏了复杂度?只做转发的层不要加。
- 同一规则或格式是否散落在多个模块?
- 调用者是否必须按固定顺序组合多个调用?
- 贯通路径跑通后,扩展前检查一遍边界,清理为了打通而临时加的浅层。
单向依赖(Unidirectional Dependencies)
- 依赖只朝一个方向:入口、界面和基础设施依赖业务核心;业务核心不依赖框架、数据库、界面或外部服务的具体实现。
- 模块之间不形成环。新增 import 或调用前,确认不会让两个模块互相依赖。
- 下层需要通知上层或调用外部能力时,由下层定义接口、回调或事件,上层实现或订阅;不反向 import 上层。
- 依赖朝更稳定的方向:容易变化的模块依赖不容易变化的模块,而不是相反。
- 项目已有分层或依赖检查规则时,遵守并运行检查(例如 dependency-cruiser、import-linter、ArchUnit);没有时,在评审中检查新增依赖的方向。
- 贯通路径为了先跑通而临时引入的反向依赖或循环依赖,在扩展前清理。
交付
说明已完成的行为、验证方式和结果、未覆盖的限制,以及本次新增或修改的术语。只实现当前需求,不提前增加没有依据的通用能力。