4. RESTGo 契约定义：契约文件结构、YAML/JSON 契约格式、请求/响应定义、匹配规则

RESTGo 契约是压测与校验的核心载体，它同时描述了“如何构造请求”与“如何校验响应”。本章将深入契约文件的物理结构、两种序列化格式（YAML / JSON）、请求与响应的完整定义，以及决定校验成败的匹配规则体系。

4.1 契约文件结构

一个标准的 RESTGo 契约文件遵循分层结构，顶层包含契约元信息、请求模板和响应校验规则三大部分。文件扩展名通常为 .restgo.yaml 或 .restgo.json。

4.2 YAML 与 JSON 契约格式

RESTGo 同时支持 YAML 和 JSON 两种序列化格式。YAML 因其可读性高、支持注释，被推荐用于开发阶段的契约编写；JSON 则更适合自动化生成或与 CI/CD 工具链集成。

4.2.1 YAML 格式示例

name: "创建用户接口"
version: "1.0.0"
description: "POST /api/v1/users 创建新用户"

variables:
  baseUrl: "https://api.example.com"
  timestamp: "{{now}}"

request:
  method: POST
  path: /api/v1/users
  headers:
    Content-Type: application/json
    Authorization: Bearer {{token}}
  body:
    name: "张三"
    email: "zhangsan@example.com"
    role: "admin"

response:
  status: 201
  headers:
    Content-Type: application/json
  body:
    - match: exact
      path: $.code
      value: 0
    - match: type
      path: $.data.id
      value: integer
    - match: regex
      path: $.data.email
      value: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"

4.2.2 JSON 格式示例

{
  "name": "创建用户接口",
  "version": "1.0.0",
  "description": "POST /api/v1/users 创建新用户",
  "variables": {
    "baseUrl": "https://api.example.com",
    "timestamp": "{{now}}"
  },
  "request": {
    "method": "POST",
    "path": "/api/v1/users",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer {{token}}"
    },
    "body": {
      "name": "张三",
      "email": "zhangsan@example.com",
      "role": "admin"
    }
  },
  "response": {
    "status": 201,
    "headers": {
      "Content-Type": "application/json"
    },
    "body": [
      { "match": "exact", "path": "$.code", "value": 0 },
      { "match": "type", "path": "$.data.id", "value": "integer" },
      { "match": "regex", "path": "$.data.email", "value": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" }
    ]
  }
}

4.3 请求定义详解

请求定义（request）是压测引擎构造 HTTP 请求的依据，包含以下核心字段：

4.4 响应校验定义

响应校验（response）定义了压测通过后对返回结果的断言规则。RESTGo 支持对状态码、响应头和响应体三个维度的校验。

4.4.1 状态码校验

status 字段支持精确值或范围匹配：

# 精确匹配
status: 200

# 范围匹配（2xx 系列）
status: 2xx

# 多值匹配
status: [200, 201, 202]

4.4.2 响应头校验

headers 字段支持键值对精确匹配或正则匹配：

response:
  headers:
    Content-Type: application/json
    X-Request-Id: "{{regex:[a-f0-9-]{36}}}"

4.4.3 响应体校验规则

body 字段是一个规则数组，每条规则包含匹配类型、JSON Path 和期望值。

4.5 匹配规则体系

匹配规则是 RESTGo 校验引擎的核心能力，决定了如何将实际响应值与契约中的期望值进行比较。RESTGo 支持以下 6 种匹配规则：

4.5.1 规则组合示例

response:
  status: 200
  body:
    # 精确匹配业务码
    - match: exact
      path: $.code
      value: 0

    # 类型匹配 data.id 必须为整数
    - match: type
      path: $.data.id
      value: integer

    # 正则匹配邮箱格式
    - match: regex
      path: $.data.email
      value: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"

    # 范围匹配年龄
    - match: range
      path: $.data.age
      value: [18, 60]

    # 长度匹配 tags 数组
    - match: length
      path: $.data.tags
      value: [1, 10]

    # 存在性匹配 profile 字段
    - match: exists
      path: $.data.profile
      value: true

4.6 JSON Path 表达式

RESTGo 使用 JSON Path 语法定位响应体中的字段。支持的语法子集如下：

4.7 变量与动态参数

契约中的变量系统支持在请求和响应中注入动态值，增强契约的灵活性和复用性。

# 使用上下文变量实现接口链式调用
variables:
  baseUrl: "https://api.example.com"

request:
  method: POST
  path: /api/v1/orders
  body:
    userId: "{{$prevResponse.$.data.userId}}"
    productId: "{{$prevResponse.$.data.productId}}"
    quantity: "{{randomInt(1,10)}}"

response:
  status: 201
  body:
    - match: exact
      path: $.code
      value: 0
    - match: type
      path: $.data.orderId
      value: integer

通过本章的学习，你已经掌握了 RESTGo 契约的完整定义方法。从文件结构到 YAML/JSON 格式，从请求构造到响应校验，再到灵活的匹配规则和变量系统，这些知识将为你后续进行契约压测与自动化校验打下坚实基础。