3. 接口契约定义：OpenAPI/Swagger 规范与 go-swagger 实践

在 Go Web 契约压测中，接口契约是测试的“法律依据”。契约定义了请求与响应的结构、字段约束、状态码和媒体类型，是集成测试与压测脚本生成的唯一数据源。本章围绕 OpenAPI/Swagger 规范，讲解如何使用 go-swagger 生成接口文档，并深入剖析契约文件的结构与字段约束。

3.1 OpenAPI / Swagger 规范概述

OpenAPI 规范（原 Swagger 规范）是一种与语言无关的接口描述标准。它使用 JSON 或 YAML 格式定义 RESTful API 的端点、参数、请求体、响应和认证方式。Swagger 是 OpenAPI 规范的早期实现名称，目前两者常混用，但 OpenAPI 3.x 是当前主流版本。

3.2 使用 go-swagger 生成接口文档

go-swagger 是一个 Go 语言的工具链，支持从代码注释生成 OpenAPI 规范文件，也支持从规范文件生成 Go 服务端和客户端代码。在契约压测中，我们主要使用其 文档生成 功能。

3.2.1 安装与初始化

# 安装 go-swagger
go install github.com/go-swagger/go-swagger/cmd/swagger@latest

# 验证安装
swagger version

3.2.2 在 Go 代码中编写注释

go-swagger 通过解析 Go 结构体上的注释来生成规范。以下是一个典型的用户注册接口注释示例：

// Package api 用户管理接口
//
// 用户管理 API 提供注册、登录、信息查询功能。
//
// 方案: Bearer 认证
//
// swagger:meta
package api

import "time"

// swagger:model
type User struct {
    // 用户唯一标识
    // required: true
    // format: uuid
    ID string `json:"id"`

    // 用户名，3-20 个字符
    // required: true
    // pattern: ^[a-zA-Z0-9_]{3,20}$
    // min length: 3
    // max length: 20
    Username string `json:"username"`

    // 邮箱地址
    // required: true
    // format: email
    Email string `json:"email"`

    // 注册时间
    // read only: true
    CreatedAt time.Time `json:"created_at"`
}

// swagger:route POST /api/v1/users users createUser
//
// 创建新用户
//
// 注册一个新用户账号，需要提供用户名、邮箱和密码。
//
// 参数:
//   + name: body
//     in: body
//     required: true
//     schema:
//       "$ref": "#/definitions/CreateUserRequest"
//
// 响应:
//   201: CreateUserResponse
//   400: ErrorResponse
//   409: ErrorResponse
func CreateUserHandler(w http.ResponseWriter, r *http.Request) {
    // 处理逻辑
}

3.2.3 生成 OpenAPI 规范文件

# 生成 swagger.json
swagger generate spec -o ./swagger.json --scan-models

# 生成 swagger.yaml
swagger generate spec -o ./swagger.yaml --scan-models

3.3 契约文件的结构与字段约束

一个完整的 OpenAPI 契约文件包含以下核心部分。理解这些结构是编写精确压测脚本的前提。

3.3.1 字段约束详解

契约中的字段约束直接决定了压测脚本的生成规则。以下是常用约束及其在压测中的用途：

3.3.2 契约文件示例（YAML）

openapi: "3.0.0"
info:
  title: 用户管理 API
  version: "1.0.0"
  description: 提供用户注册、登录、信息查询功能
servers:
  - url: https://api.example.com/v1
    description: 生产环境
paths:
  /users:
    post:
      summary: 创建新用户
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CreateUserRequest:
      type: object
      required:
        - username
        - email
        - password
      properties:
        username:
          type: string
          minLength: 3
          maxLength: 20
          pattern: '^[a-zA-Z0-9_]+$'
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
          maxLength: 128
    UserResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        username:
          type: string
        email:
          type: string
        created_at:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string

3.4 契约在压测中的核心作用

契约文件不仅是文档，更是压测脚本的“数据源”。通过解析契约，压测工具可以：

• 自动生成请求模板：根据 requestBody 和 parameters 生成合法的 JSON 请求体。
• 验证响应结构：压测后对比响应字段是否与 responses 中的 schema 一致。
• 边界测试：利用 minLength、maximum 等约束生成边界值，测试后端健壮性。
• 契约变更检测：当契约文件更新时，自动标记需要重新录制的压测用例。