架构评审技能用于在实施非平凡的结构性变更之前对设计进行评估。它不适用于边界和契约保持不变的本地缺陷修复或小型重构。
使用时机
当 dd-trace-js 的变更引入或大幅改变类层次、模块边界、共享辅助层、公共 API 或重复行为时,适合使用本技能。评分是决策辅助,不能替代推理;需解释每个分数背后的证据,并拒绝那些增加复杂性却未改善基线的抽象。
工作流程
- 描述当前设计作为基线,包括其重复、耦合、契约、测试和热路径。
- 描述最小可行方案,并至多给出一个有意义的替代方案。
- 识别受影响的公共 API、包边界、消费者以及每次调用的生产路径。
- 从基线到方案,按以下每个维度以 1–10 分打分。
- 要求方案在五个维度上至少达到 8/10。公共接口纪律或热路径适应性出现回退视为阻塞,即使总分通过。
- 当两个可行设计存在明显权衡时,在实施前询问用户。
- 记录所选设计的契约,并用可观察的测试覆盖边界。
六个维度
- 防漂移:多个类型共享的行为应集中在一处;新增前置条件或分支应只触及一处,而非需要各实现同步修改。
- 模块耦合:跨模块访问必须走有意的边界,绝不能访问另一个类的内部。为 npm 导出的类(如 Span、Tracer 或 OpenTelemetry 桥接 span)添加方法属于持久的兼容性承诺;优先使用回调、诊断通道、组合或重新设计的模块边界,而非暴露内部状态。
- 显式契约:通过构造函数签名、具体 JSDoc 类型、窄接口、适当的抽象方法以及 #private 状态来表达不变量,不依赖模块间未成文的约定。
- 边界可测试性:对具有多个消费者或协议/规范契约的边界直接测试;使用真实入口和可观察输出,不为测试而导出内部实现或构造不可能的对象状态。
- 可扩展性:评估可能的下一个消费者、类型或方法。第三个实现应只需局部新增,而非改动所有现有实现;没有可信的下一用例时不要添加推测性通用化。
- 热路径适应性:在实际调用路径上测量架构边界的开销,避免每次调用产生额外分配、闭包、分派、解析和监听器;以性能为动机增加复杂性需要聚焦且可复现的基准证据。
决策规则
优先使用组合;仅当至多两个同级类型共享完整的接口契约且层次结构使该契约更清晰时才使用继承。诚实评估基线,7 分到 7 分的重写不算架构进步。在评估耦合时,将仅用于测试的导出和访问器视为公共接口扩展。当评分和实测性能实质相同时,优先选择更简单的实现。除非用例需要持久的兼容契约,否则避免新增公共 API。如果上游拥有损坏的抽象,优先修复上游而非长期本地规避。
评审输出
以紧凑表格总结评审,列包括维度、基线、方案、证据,覆盖防漂移、模块耦合、显式契约、边界可测试性、可扩展性、热路径适应性六项。然后说明决策、被拒替代方案、剩余风险以及合并前所需的验证。