类与方法的实现规范
把明确的行为落实为容易理解、容易修改、能够验证的代码。降低状态、依赖、控制流和维护成本;代码行数或类数只是结果,不是优化目标。
1. 接住整体契约,限定本次实现范围
与 workflow-first-design 共用行为契约:整体层决定流程、责任边界与跨组件协议,本层落实到类、字段、方法和测试。契约已有于对话、代码或文档时直接复用,不另做整套设计材料。
局部任务先核对输入、预期行为、相关约束和责任类,即可实施。涉及状态或副作用时,再核对失败动作、生效点和清理责任。简单修改按需缩减,不机械生成表格或测试。
以下发现需要回到整体层调整受影响的契约:必须改变策略语义、转移跨组件状态所有权、改变公共协议,或突破系统性能约束。保持契约的字段组织、私有方法拆分、局部算法和封装选择由本层自行决定。不得为了实现方便改变等待、重试、降级、公平性或性能要求。
反例持续导致新增标志、回调和特例时,先检查被推翻的假设及责任边界;不能用补丁掩盖设计缺口,也不因局部缺陷重写系统。只有未决业务含义会改变方案且无法从上下文确认时才询问用户;这不是新增审批流程。
2. 用真实路径确定修改位置
阅读实际入口、关键调用方、目标类、相关依赖和测试,确认当前代码与运行环境版本。只追踪与当前假设相关的路径,不无目标遍历系统。
区分观察到的事实、解释和待验证假设。代码中存在某个机制不等于运行时执行了它,错误表象不等于根因。优先选择能区分不同解释的测试、日志或实验;回归问题必要时对照隔离基线。部署、版本或工作区变化后重新确认相关证据。
确定每项修改如何对应需求或必要依赖,再写代码。沿用项目已有的错误、配置、资源管理和扩展约定,不顺手引入框架或额外能力。
3. 为类确定职责和不变量
对本次新增或实质调整的类,能回答:它代表什么、负责什么、对外保证什么、依赖谁、何时创建和结束。优先复用已有责任组件,不机械地为每个阶段创建一个类。
- 数据对象承载明确粒度的事实或结果;维护自身数据约束,不暗中登记资源、调度任务或发起网络请求。
- 行为对象执行语义完整的操作;方法名和返回值必须体现实际副作用与保证,不能让“选择”暗含调用方不知道的生命周期责任。
- 协调对象处理必要的多步交接和部分成功;只有独立的跨组件责任确实存在时才引入,不能只是转调或搬运字段。
以上是职责检查,不要求固定分成三类。对象持有资源时明确关闭或释放契约;不能通过换一个 Result、Context、Manager、Execution 名称掩盖混合职责。
继承仅用于稳定的可替换关系:子类必须遵守父类的输入、输出、失败和生命周期约束。仅为复用字段、资源记账或分支代码时,先考虑组合或已有公共能力。基类不应判断子类类型、承载大量可选字段,或要求子类以空实现绕过契约。不为一次调用创建无实际替换需求的接口体系。
4. 把字段归属和生命周期落实到代码
涉及重复数据或状态调整时,用紧凑的字段归属表核对;简单字段修改无需填表:
| 字段/事实 | 粒度与含义 | 唯一权威持有者与修改入口 | 读取者/派生副本 | 生效、失效与清理 |
|---|
- 区分请求、一次尝试、节点和一次操作的身份,不能让旧尝试的字段参与新尝试判断。
- 能从可靠现有事实得到的值,通常不另维护一份可变状态。快照、缓存和估算可以存在,但要明确采样时点、更新或失效规则,以及是否计入同一份资源影响。
- 不因字段相似就合并不同粒度的事实,也不在多个结果对象中复制相同生命周期的字段。判断依据是职责和约束。
- 构造完成时尽量形成合法对象。确需分阶段构建时,限制未完成对象的可见范围,避免调用方依赖 setter 顺序、非空字段或多个布尔值猜测阶段。
- 选择明确的修改入口,避免公开可变集合或通过 getter 绕过不变量。不可变快照与活状态引用须有清楚区别。
- 名称沿用领域术语,同一概念同名。handle、lease 等名称只有在语义确实匹配时使用,并解释它代表的具体权利和责任。
5. 让方法和接口表达完整语义
方法应完成一个调用方能够解释的操作。必要的连续操作可以放在同一方法中,不为了行数拆成大量依赖隐含顺序的小函数。
- 明确前置条件、输入身份、返回事实、状态变化和异常后的保证;返回“成功”到底意味着计算完成、登记成功、发布还是执行完成。
- 纯计算只接收必要信息,避免为了方便传入整个可变 Context;执行副作用的入口要清楚,但不强制计算与登记分开到破坏原子性。
- 只向上暴露会改变调用方决策的结果。局部版本冲突、内部代际等可在责任组件内消化,诊断信息按需保留;不要把所有底层细节变成上层状态。
- 区分确定未发生、已发生、结果未知。异常或通知失败不能自动解释为安全重放;遵守整体契约中的等待、清理和重试决定权。
- 避免含义不明的布尔参数、重复重载、转调包装和不一致的错误通道。增加结果类型或参数对象应解决实际歧义,而非仅为形式统一。
- 依赖沿责任边界传递。底层不应通过回调、全局对象或反向引用偷偷决定整个流程的策略。
6. 在操作边界完成状态与资源责任
把整体设计规定的取得、交接、释放落实到确定的代码位置。检查正常路径和最关键的异常路径:每一步修改谁的状态,下一步失败由谁清理,何时可以安全开始替代操作。
- 取得资源后、尚未放入主记录前发生异常,也必须有释放负责人。责任交接以约定的生效点为准,不能根据字段非空猜测。
- 多资源部分成功时遵守契约规定的保留或撤销范围;需要整体撤销时清理全部实际取得的资源,不硬编码最先失败的组件。
- 区分允许重试与已经能够重试。撤销、临时任务退出和资源清理达到约定条件后才能重放;保留规定的请求身份、优先级、截止时间及完成对象。
- 释放须针对精确操作身份;重复释放或晚到回调不能影响其他请求和新尝试。幂等保护不替代明确的清理责任。
- 一个资源释放失败不应阻断其他独立资源的清理。保留未完成责任和错误,不能把返回失败当成资源已回收,也不能假装成功回队。
优先使用语言和项目现有的作用域清理机制。只有跨调用、异步或生命周期需要时才引入持久管理对象,不以形式统一增加线程、回调和状态机。
7. 把并发与性能约束落实到操作范围
指出需要原子的判断与变化,以及其他调用何时能够看到结果,再选最简单的正确同步方式。不预设必须加锁或无锁。
- 检查锁覆盖的数据、锁顺序和持锁调用链。网络、外部回调、阻塞等待和昂贵计算原则上在锁外;必要例外给出依据。
- 用具体交错核对检查与更新、失效与提交、取消与清理、旧回调与新尝试、释放与等待登记。不能仅以有锁、有版本或有原子变量声称整体线程安全。
- 局部变化优先局部更新;重算前核对依赖,区分复用结果重新比较与重新执行昂贵计算。不要为局部冲突默认全表扫描或全局串行化。
- 核对热路径新增的分配、扫描、锁竞争、排队、通知和重试。无锁方案也要解释可见性、重试成本和进展保证;预算和阈值应有依据。
实现无法满足整体约束时,带着具体证据返回整体层调整受影响的方案,不静默削弱保证或新增常量掩盖矛盾。
8. 用测试证明行为,按环境验证性能
从行为契约推导测试,优先覆盖最可能推翻实现的边界,观察可见结果与实际副作用,避免逐行复刻实现或只断言 mock 被调用。
纯逻辑适合单测;所有权交接和通知链需要组件或集成验证;运行环境决定行为时沿真实入口验证。Mock 不能替代正在验证的关键机制。局部单测通过不能代替多组件流程验收。
涉及资源、异步或重试时,按改动风险覆盖部分成功、重复调用、取消或超时、晚到回调及关键竞态。尽量用可控同步构造交错,避免靠随机等待证明并发正确。简单、可逆且低影响的修改不为了形式新增测试。
失败测试先判断契约是否改变、实现是否回归或环境是否异常,必要时对照基线。保留仍有效的行为断言,不改期望迁就实现。
用户指定 UT、perf test 或执行环境时按要求完成,不能以本地替代环境通过宣称完成。性能对比核对代码版本、配置、负载、预热和统计窗口,报告相关的吞吐、尾延迟与错误。不得放宽门槛、换负载或隐去异常;单次达标不能证明没有回退。
区分读过源码、实际运行通过和真实环境验证;记录被替代的依赖及证据限制。检查通过后,仅因新变化、失败或未解决风险扩大验证,避免无理由重复运行。
9. 随调用迁移清理旧实现,检查最终 diff
方案替换时给出具体的保留、合并、删除项及理由。迁移调用后清理失去用途的入口、字段、重载、包装、重复登记或回滚、配置、mock、测试夹具和旧术语;仍有效的行为测试保留。确需过渡路径时遵循整体方案的退出条件。
交付前通读最终 diff,确认主流程能直接看出触发、决策、执行和结束;新增抽象确有职责,旧机制已删除,没有覆盖用户的其他工作。注释解释必要约束和非显然取舍,不替难以阅读的控制流辩护。
报告实际改变的行为、关键类的责任变化、执行过的验证及未完成项。复杂任务将证据回传整体层完成集成验收;只完成类实现或单测时,不把整体任务标为完成。