3. 服务契约概念：什么是服务契约、契约驱动开发（CDD）与OpenAPI规范

在微服务架构与分布式系统中，服务之间的通信依赖明确的接口约定。这种约定被称为服务契约（Service Contract）。它定义了服务提供者与服务消费者之间的交互规则，包括协议、数据格式、端点路径、请求/响应结构以及错误处理方式。

3.1 服务契约的核心要素

一个完整的服务契约通常包含以下五个维度：

3.2 契约驱动开发（CDD）

契约驱动开发（Contract-Driven Development, CDD）是一种以服务契约为设计中心的开发方法论。其核心流程为：先定义契约，再实现服务。这与传统的先写代码、后补文档的方式完全相反。

CDD 的典型工作流包含以下步骤：

1. 契约设计： 团队（或 API 设计者）使用 OpenAPI、gRPC Proto 等规范编写服务契约文件。
2. 契约评审： 提供方与消费方共同评审契约，确认接口语义、字段约束与错误码。
3. Mock 生成： 从契约自动生成模拟服务（Mock Server），使消费方可以并行开发。
4. 服务实现： 提供方按照契约实现真实端点，消费方按照契约编写调用代码。
5. 契约验证： 在 CI/CD 流水线中自动校验实现是否满足契约，防止契约漂移。

3.3 OpenAPI 规范

OpenAPI 规范（原 Swagger Specification）是目前业界最广泛使用的 RESTful API 契约描述标准。它以 YAML 或 JSON 格式定义服务的完整接口信息，具备机器可读与人类可读的双重特性。

一个典型的 OpenAPI 3.0 契约文件包含以下顶层结构：

openapi: "3.0.3"
info:
  title: 用户服务
  version: "1.0.0"
servers:
  - url: https://api.example.com/v1
paths:
  /users/{id}:
    get:
      summary: 获取用户信息
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  email:
                    type: string
                required:
                  - id
                  - name

3.4 服务契约在压测闭环中的角色

在《Go服务契约压测闭环》课程体系中，服务契约是连接测试环境配置与压测脚本生成的桥梁。其作用体现在以下三个环节：

• 环境配置阶段： 从契约中提取 servers.url 与 paths，自动生成压测目标端点列表。
• 脚本生成阶段： 将契约中的 schema 转换为 Go 结构体与 JSON 断言函数。
• 结果校验阶段： 使用契约中的响应码定义与字段约束，自动判定压测请求是否通过。

3.5 契约与压测断言的关系

在 Go 压测脚本中，契约驱动的断言通常表现为以下模式：

// 从 OpenAPI schema 自动生成的响应校验函数
func validateUserResponse(body []byte, statusCode int) error {
    // 契约要求：状态码必须为 200
    if statusCode != http.StatusOK {
        return fmt.Errorf("期望状态码 200，实际 %d", statusCode)
    }

    var user User
    if err := json.Unmarshal(body, &user); err != nil {
        return fmt.Errorf("响应 JSON 解析失败: %w", err)
    }

    // 契约要求：id 和 name 为必填字段
    if user.ID == 0 {
        return fmt.Errorf("契约约束违反: 字段 id 缺失或为 0")
    }
    if user.Name == "" {
        return fmt.Errorf("契约约束违反: 字段 name 为空")
    }

    return nil
}