1. 课程导论：为什么需要错误码断言接口契约

1.1 从一次线上事故说起

假设你负责的微服务 A 调用下游服务 B 的 /user/info 接口。服务 B 文档承诺：当用户不存在时，返回 HTTP 400 + JSON {"code":1001,"msg":"user not found"}。你的代码这样写：

resp, err := http.Get("http://svc-b/user/info?id=999")
if err != nil {
    // 网络错误处理
}
if resp.StatusCode == 400 {
    // 期望的错误码 1001
}

某天，服务 B 升级后，将错误码改为 2001，但 HTTP 状态码仍是 400。你的断言 resp.StatusCode == 400 通过了，但业务逻辑却因为错误码不匹配而走错了分支——用户被误判为“参数错误”，而不是“用户不存在”。

1.2 为什么需要错误码断言接口契约

在 Go 微服务架构中，接口契约不仅包含路径、方法、请求/响应结构，更包含错误码的语义约定。错误码断言接口契约的核心价值在于：

• 精确性：将错误码从“文档备注”提升为“可测试的契约字段”，每次接口调用都自动校验错误码是否符合预期。
• 可测试性：在单元测试、集成测试中，通过断言错误码而非 HTTP 状态码，提前捕获错误语义变更。
• 可维护性：当上游服务修改错误码时，契约测试立即失败，迫使双方同步更新，避免“静默兼容”带来的隐患。
• 跨团队协作：错误码契约成为服务间通信的“共同语言”，减少因文档滞后导致的联调成本。

1.3 课程目标与适用人群

课程目标：

• 掌握 Go 语言中错误码断言接口契约的设计模式与实现方法。
• 学会使用 go-cmp、testify、httptest 等工具构建可复用的错误码断言库。
• 能够在实际项目中落地错误码契约测试，提升微服务接口的健壮性。
• 理解契约测试在 TDD（测试驱动开发）流程中的位置与价值。

适用人群：

• Go 后端开发工程师，尤其是微服务架构下的服务开发者。
• API 设计者，希望建立更严谨的接口契约规范。
• 测试工程师，需要提升接口测试的精确度和覆盖率。
• 技术管理者，希望推动团队采用契约测试实践。

1.4 整体知识图谱概览

本课程共 30 章，分为 5 个模块，从基础概念到高级实战，逐步构建完整的错误码断言接口契约体系。

1.5 课程核心概念速览

在进入后续章节之前，先明确几个贯穿全课程的核心术语：