📚 课程目录第4章接口契约基础

4. 接口契约基础：OpenAPI/Swagger 规范、gRPC Proto 定义、契约驱动开发（CDD）理念

在可观测性 Mock 隔离体系中，接口契约是连接真实服务与 Mock 桩的“法律文件”。没有明确的契约，Mock 数据将失去对齐基准，导致测试失真、故障演练失效。本章聚焦三种核心契约形态：OpenAPI/Swagger（RESTful）、gRPC Proto（RPC）以及契约驱动开发（CDD）理念，并阐述它们在 OTel Mock 隔离中的落地方式。

核心观点：契约即规范，规范即 Mock 生成源。在 OTel 场景下，契约不仅定义请求/响应结构，还需携带可观测性元数据（如 trace_id、span_id、baggage 字段），确保 Mock 数据与链路上下文一致。

4.1 OpenAPI / Swagger 规范

OpenAPI（原 Swagger）是 RESTful API 的事实标准契约语言。它使用 JSON/YAML 描述端点、方法、参数、请求体、响应体及错误码。在 OTel Mock 隔离中，OpenAPI 契约承担以下职责：

生成 Mock 桩骨架：工具（如 Prism、WireMock）读取 OpenAPI 文件后自动生成响应模板。
定义可观测性字段：在 headers 或 parameters 中声明 traceparent、tracestate 等 W3C 上下文传播字段。
约束 Mock 数据范围：通过 schema 中的 enum、pattern、example 控制 Mock 输出边界。

OpenAPI 元素	Mock 隔离用途	OTel 扩展示例
`paths`	定义 Mock 端点路由	`/api/v1/traces`
`parameters`	声明请求头/查询参数	`traceparent` (header)
`requestBody`	约束 Mock 请求载荷结构	`span_id` 字段必填
`responses`	定义 Mock 响应模板	返回 `status.code` + `attributes`
`components/schemas`	复用数据类型，保证一致性	`SpanSchema` 包含 `trace_id`

  实践建议：在 OpenAPI 契约中为每个端点显式标注 x-otel-mock: true 扩展属性，便于 Mock 引擎识别哪些端点需要自动生成可观测性上下文。

4.2 gRPC Proto 定义

gRPC 使用 Protocol Buffers（Proto）作为接口定义语言（IDL）。Proto 文件比 OpenAPI 更紧凑，天然支持强类型、流式传输和多语言代码生成。在 OTel Mock 隔离中，Proto 定义的价值体现在：

双向流 Mock：Proto 的 stream 关键字允许 Mock 模拟服务端推送或客户端流式数据。
字段级 Mock 规则：通过 google.protobuf.FieldMask 或自定义 option 控制 Mock 字段可见性。
gRPC 拦截器集成：Mock 服务可复用 OTel gRPC 拦截器，自动注入 grpc-trace-bin 元数据。

syntax = "proto3";

package otel.mock.v1;

import "opentelemetry/proto/trace/v1/trace.proto";

service MockSpanService {
  // 单向 RPC：模拟写入 Span
  rpc ExportSpan(ExportSpanRequest) returns (ExportSpanResponse);

  // 服务端流：模拟批量推送 Span
  rpc StreamSpans(StreamSpansRequest) returns (stream opentelemetry.proto.trace.v1.Span);
}

message ExportSpanRequest {
  string trace_id = 1;
  string span_id = 2;
  map<string, string> attributes = 3;
}

message ExportSpanResponse {
  bool accepted = 1;
  string mock_span_id = 2;
}

注意：gRPC Mock 隔离时，必须确保 Proto 文件中定义的 service 与真实服务完全一致，否则 gRPC 客户端会因方法签名不匹配而拒绝连接。建议使用 protoc 生成桩代码后，再通过 Mock 框架（如 gRPC Mock、Gomock）覆写实现。

4.3 契约驱动开发（CDD）理念

契约驱动开发（Contract-Driven Development, CDD）强调先定义契约，再实现服务。在 OTel Mock 隔离场景中，CDD 的流程如下：

设计契约：团队协作编写 OpenAPI 或 Proto 文件，包含可观测性字段。
生成 Mock：从契约自动生成 Mock 服务，供前端或依赖方并行开发。
验证一致性：使用契约测试工具（如 Pact、Spring Cloud Contract）校验 Mock 响应是否符合契约。
集成 OTel：在 Mock 服务中嵌入 OTel SDK，使 Mock 产生的数据携带正确的 Trace 上下文。
持续同步：契约变更时，Mock 服务自动重建，避免漂移。

CDD + OTel 最佳实践：将 OTel 的 Resource 和 InstrumentationScope 信息写入契约的扩展字段（如 x-otel-resource），确保 Mock 数据与生产环境拥有相同的服务标识。

4.4 三种契约形态对比

维度	OpenAPI / Swagger	gRPC Proto	CDD 理念
协议	HTTP/1.1, HTTP/2	HTTP/2 (gRPC)	不限定协议
序列化	JSON / YAML	Protocol Buffers (二进制)	依赖具体契约
流式支持	有限（SSE, WebSocket）	原生双向流	通过契约扩展
Mock 生成工具	Prism, WireMock, Stoplight	gRPC Mock, GripMock	Pact, Spring Cloud Contract
OTel 集成方式	Header 注入 + 扩展字段	gRPC 拦截器 + Metadata	契约内嵌 OTel 元数据
适用场景	RESTful 微服务、API 网关	高性能 RPC、流式数据处理	多团队协作、持续交付

  选型建议：如果团队已有 RESTful 生态，优先使用 OpenAPI + CDD 组合；如果追求极致性能或需要流式 Mock，选择 gRPC Proto + CDD。无论哪种，都应将 OTel 上下文传播字段作为契约的一等公民。

4.5 契约在 OTel Mock 隔离中的落地检查清单

必含字段：trace_id、span_id、parent_span_id、trace_flags。
可选扩展：baggage、attributes、resource。
Mock 响应约束：通过 enum 限制 status.code 取值范围（如 OK, ERROR, UNSET）。
版本管理：契约文件纳入 Git 仓库，与 Mock 服务版本一一对应。
自动化验证：CI 流水线中执行契约测试，确保 Mock 响应不偏离契约定义。

掌握 OpenAPI、gRPC Proto 和 CDD 理念，是构建可靠 OTel Mock 隔离体系的第一步。下一层我们将深入契约的版本管理与兼容性策略，确保 Mock 服务在契约演进中始终保持稳定。