API契约测试是验证服务端是否严格遵守与客户端约定的请求/响应结构，而非仅检查接口连通性；在Go中主要测字段类型、数量、嵌套结构等是否符合OpenAPI规范，防止前端因结构不一致而崩溃。
什么是API契约测试，它在Go里到底测什么
API契约测试不是测接口能不能通，而是验证服务端是否严格遵守了与客户端约定的请求/响应结构。Go项目里最常见的场景是：前端用OpenAPI（Swagger）定义了接口规范，后端用gin或echo实现，但实际返回字段类型错、少字段、多字段、嵌套结构不一致——这些都不会被http.StatusOK掩盖，却会导致前端运行时崩溃。
关键判断点：如果你的Go服务有对外发布的OpenAPI文档（openapi.yaml），且该文档被其他团队/前端/SDK消费，那契约测试就不是可选项，而是上线前必须卡住的环节。
用go-swagger + ginkgo做契约验证的实操路径
Go生态没有像Pact那样开箱即用的契约测试框架，但组合go-swagger生成的client + ginkgo测试驱动，能直接复用已有OpenAPI定义，避免重复造模。
- 先用
swagger generate client -f ./openapi.yaml生成Go client代码，它会把所有schema转成struct，并带JSON tag - 写测试时，用
http.ServeMux启动一个最小化服务（不用启完整Web框架），注册你待测的handler - 用生成的client调用该服务，捕获返回的
*http.Response和error - 核心断言不是状态码，而是：
json.Unmarshal(resp.Body, &targetStruct)是否panic；以及reflect.DeepEqual比对字段值是否符合spec中example或default
注意：go-swagger对oneOf/anyOf支持弱，遇到这类定义建议降级为字符串字段+手动校验，否则生成的struct会漏字段。
立即学习“go语言免费学习笔记（深入）”；
用testcontainers跑真实集成环境时的坑
本地单元测试能覆盖结构，但无法验证HTTP头、压缩、重定向、CORS等契约外但影响调用的细节。这时需要用testcontainers-go拉起真实容器化的API服务再测。
- 别在
TestMain里全局启动container——Go测试并发执行，多个test会抢同一个container端口 - 每个测试函数内用
testcontainers.RunContainer启动独立实例，加defer container.Terminate(ctx) - 等待服务就绪不能只靠
time.Sleep(2 * time.Second)，要用WaitForHTTP("/health").WithStatusCodeMatcher匹配200 - 容器内服务日志要重定向到
t.Log()，否则失败时看不到panic: interface conversion: interface {} is nil这类空指针错误源头
为什么不要在CI里只跑“成功路径”契约测试
90%的线上契约问题出在错误响应上：比如文档写明400 Bad Request返回{ "code": "INVALID_EMAIL", "message": "xxx" }，但实际返回了{ "error": "xxx" }——前端按约定字段取code就panic。
- 必须为每个接口的每个
4xx/5xx状态码写独立测试用例，用swagger validate命令行工具校验响应body是否符合对应responses.400.schema - Go里推荐用
github.com/getkin/kin-openapi/openapi3加载openapi.yaml，遍历PathItem.Operations，动态构造非法请求（如必填字段置空、类型错填）并断言响应结构 - 特别注意
nullable: true字段：OpenAPI v3里它允许null，但Go struct的*string反序列化null会得nil，而string类型则会panic——这必须在测试里显式覆盖
契约测试最难的从来不是怎么写断言，而是让所有人同意：一旦OpenAPI文档变更，必须同步更新测试用例，且CI失败即阻断发布。这点在跨团队协作时，比任何技术方案都重要。
