修改公共Go库，而不破坏使用者的代码

## 改代码前，先确认支持的Go版本和分支 将正确性、向后兼容性和适用的外部规范作为首要验收标准。修改代码前，应明确： - 当前开发分支和最新的稳定维护分支； - 使用者所支持的最低Go版本； - 仓库开发所需的较新Go版本和工具链； - 哪些包构成公开且受兼容性保证的API； - 哪些可导入的内部包或实验性包不受语义化版本保证，但在实践中仍有人使用。 不得把“不受语义化版本保证”等同于“可以安全破坏”。应标明可能影响真实使用者的行为变更或API变更。按照仓库策略，将新功能提交到开发分支，将修复提交到适当的稳定分支。 对于公共包，应避免使用晚于所声明最低Go版本的标准库API和语言特性。兼容性门禁必须能够在构建过程中执行，使不受支持的特性尽早失败，而不是流入使用者环境。 ## 用项目自己的工具运行检查和测试 使用项目指定的任务运行器和格式化工具，不要用熟悉的命令自行替代。默认验证目标应同时包含编译、许可证检查、格式检查、模块检查、lint和快速测试。 维护两个测试层级： - 启用race检测、用于快速反馈的短测试套件； - 包含仓库所需服务依赖并使用更长超时时间的完整集成测试套件。 如果集成测试共享服务器状态，完整套件必须串行运行，绝不能仅为缩短运行时间而提高并行度。服务端点应支持配置，同时保留已文档化的本地默认值。 当底层行为依赖处理器架构时，应执行跨架构lint或编译检查。使用原子访问时尤其要验证32-bit目标：通过原子操作访问的64-bit字段必须具备安全对齐，例如放在结构体起始位置，或使用带类型的原子包装器。 ## 错误处理和公共API沿用库现有的写法 遵循仓库中已经确立的模式： - 使用`%w`在包装错误时附加上下文，并通过`errors.Is`或`errors.As`进行比较，不要匹配错误消息文本； - 所有会阻塞的公共方法都应将`context.Context`作为第一个参数，并从调用方的context派生截止时间，不要创建与其竞争的独立实时时钟计时器； - 对键顺序有意义的命令或数据使用有序文档类型，仅在顺序确实无关时使用map类型；只有在有充分依据的热点路径中，才使用底层、由字节切片支撑的表示形式； - 导出标识符使用完整单词而非缩写，为所有导出标识符添加以名称为主语的文档注释，并为新选项遵循项目的builder或setter模式。 保持当前的包布局和迁移决策。不得恢复已停用的导入路径或过时的公共抽象。 如果命令监控或诊断能够观察到认证交互，应先将处理凭据的命令加入脱敏策略，再暴露相关事件。特定功能所需的原生依赖和构建标签，必须始终在安装说明和测试说明中明确列出。 ## 分开放置单元测试和集成测试，并运行改动需要的测试 将单元测试放在实现旁边，将集成测试放在仓库指定的集成测试区域。使用项目的断言辅助工具，优先采用`ErrorIs`等语义检查，而不是子字符串断言。 对于集成行为，使用标准的拓扑感知测试框架完成部署设置、故障点注入和事件捕获。将规范fixture保存在指定的测试数据位置；克隆仓库后，初始化所需的submodule或fixture来源。需要可追溯性时，文字测试用例的编号应与所依据规范的编号对应。 评审前运行默认验证目标。变更涉及集成行为或共享服务器状态时，应串行运行完整套件。仅有范围狭窄的单元测试通过，不足以证明跨架构、兼容性或规范敏感型变更正确。 ## 在pull request中写明测试结果和兼容性影响 在提交消息和pull request标题中使用规定的工作项前缀。pull request应说明使用者可见的行为、兼容性影响、测试证据以及分支选择。 根据变更类型补充证据： - 变更公共API时，生成仓库的API报告并将其加入pull request； - 存在使用者可见的破坏性变更时，更新相关迁移指南； - 涉及规范符合性时，引用实现所满足的准确规范要求； - 变更可导入的实验性包时，即使语义化版本不要求，也要明确说明破坏性影响。 不得仅因变更能在本地构建，就将其标记为准备完成。准备完成要求通过仓库默认检查，以及所有直接适用的兼容性、集成、API和规范门禁。