同时修改客户端库的同步和异步版本，不破坏API

## 编辑前先列出必须保持不变的公开行为 编辑前，先确定对外公开的行为、受支持的运行时版本、相关架构，以及负责该改动的最小文件集合。 - 将公开签名、参数名称、默认值、返回类型、异常和边界情况行为视为兼容性契约。 - 找出同一行为的所有并行实现，例如同步客户端和异步客户端。 - 确定可能参与该行为的路由、解析、策略、连接和响应整形层。 - 选择模式前，阅读附近的实现、测试和类型重载。 - 除非请求的改动明确要求采用其他做法，否则保留现有协议和服务器语义。 - 不要将任务扩大到无关的清理工作。 如果请求的行为与已记录的不变量冲突，应停止并明确指出冲突，不要暗中重新定义契约。 ## 对同步和异步客户端做同样的修改 当库提供功能等同的客户端技术栈时，应将两者一致视为必备属性。 1. 将已改动的同步符号对应到异步版本，或反向进行对应。 2. 比较签名、重载、类型提示、默认值、返回结构、错误和副作用。 3. 除非已记录的运行时差异使其无法实现，否则在两个技术栈中应用等同行为。 4. 使共享命令接口、路由表、解析器回调和策略元数据保持一致。 5. 如果两个技术栈都公开该行为，则添加成对测试。 使用代码库既有的类型语法和重载约定。如果只应改动一侧，应记录具体的架构原因，并验证这种不对称是有意设计的。 ## 只改负责的那一层，并复用现有辅助函数 优先采用复用现有辅助工具和约定的精准改动。 - 只修改负责该行为的层。 - 保留公开API和错误语义。 - 除非现有设施无法满足要求，否则避免引入新依赖项。 - 如果现有辅助工具或模式已经足够，则不要引入新的抽象。 - 除非延迟导入在技术上确有必要，否则应尽量减少导入并将其置于模块作用域。 - 行为发生变化时更新文档字符串，并使其与类型保持一致。 正确性优先。只有在行为正确后才进行优化，绝不能以正确性换取更少的内存分配或更快的执行速度。 ## 不拖慢高频路径，也不改变协议行为 检查热路径改动中是否存在可避免的内存分配、重复解析、重复工作和大型临时结构。 - 复用既有辅助工具和已缓存的元数据。 - 使线路协议的选择独立于面向用户的响应整形。 - 使路由和聚合策略与命令语义保持一致。 - 在相关情况下，明确处理重定向、重试、拓扑差异和错误传播。 - 不要暗中将底层服务明确区分的边界情况归一化。 性能改动必须保持相同的可观察行为。如果某项优化使正确性或一致性变得复杂，应选择更简单且正确的实现。 ## 从一个失败用例逐步测试到完整测试矩阵 按范围递增的顺序建立证据： 1. 添加或更新一个在修复前会失败的确定性测试。 2. 运行最小的相关测试或测试套件。 3. 运行镜像式同步与异步覆盖测试。 4. 验证有意义的协议、响应模式、拓扑或可选功能组合。 5. 运行项目要求的代码检查、格式检查和类型检查。 6. 如果改动可能影响共享行为，则运行全部受支持的测试矩阵。 不要仅为使测试套件通过而弱化断言、移除覆盖范围或重新归类失败。需要外部基础设施的测试应与默认本地测试套件保持明确分离。 ## 检查最终差异，找出调试代码和同步/异步的不一致 完成前，检查全部改动并验证： - 只有相关文件和行发生了变化； - 未残留调试代码、意外缺失的逻辑或无关的格式变动； - 除非有明确意图，否则公开API和错误行为均未改变； - 镜像实现和类型提示仍然一致； - 测试覆盖成功路径、边界情况和失败路径； - 代码检查和必要的测试套件均通过； - 文档与已实现的行为一致； - 未引入不必要的依赖项、内存分配或抽象。 修复发现的每个问题，并重新执行受影响的检查。报告改动内容、验证内容以及任何明确未测试的外部场景，但不要声称完成了超出实际范围的验证。