3. HTTP 协议与 RESTful API：HTTP 请求/响应模型、RESTful 设计原则、常见状态码

在契约压测与校验体系中，HTTP 协议是服务间通信的基石。理解 HTTP 请求/响应模型、RESTful 设计原则以及常见状态码，是编写精准契约、设计高效压测场景的前提。本章将系统梳理这些核心概念，并展示它们如何在 Go 契约测试中落地。

3.1 HTTP 请求/响应模型

HTTP 协议采用经典的客户端-服务器（Client-Server）模型。客户端发起请求（Request），服务器处理并返回响应（Response）。每一次完整的交互构成一个事务。

3.1.1 请求结构

一个标准的 HTTP 请求由以下部分组成：

• 请求行（Request Line）： 包含方法（GET/POST/PUT/DELETE 等）、URI 路径、HTTP 版本。
• 请求头（Headers）： 键值对集合，传递元数据（如 Content-Type、Authorization、Accept）。
• 请求体（Body）： 可选，通常用于 POST/PUT 请求，承载 JSON、XML 或表单数据。

3.1.2 响应结构

服务器返回的响应包含：

• 状态行（Status Line）： HTTP 版本、状态码、状态文本（如 200 OK）。
• 响应头（Headers）： 如 Content-Type、Content-Length、Cache-Control。
• 响应体（Body）： 返回的数据内容，通常为 JSON 格式。

3.1.3 请求-响应生命周期

下图展示了从客户端发起请求到接收响应的完整流程，以及契约测试的介入点：

3.2 RESTful 设计原则

REST（Representational State Transfer）是一种架构风格，而非协议。遵循 RESTful 原则的 API 更易于理解、扩展和契约化。以下是核心原则：

3.2.1 RESTful 资源命名规范

良好的资源命名是契约清晰度的基础：

• 使用名词复数形式：/users、/orders、/products。
• 使用子资源表达层级关系：/users/{userId}/orders。
• 使用查询参数过滤、排序、分页：/users?status=active&page=1&size=20。
• 避免在 URL 中使用动词：/getUser 应改为 /users/{id}。

3.3 常见 HTTP 状态码

状态码是服务器对请求处理结果的数字表示。在契约测试中，状态码是断言的核心要素之一。以下是契约压测中最常遇到的分类：

3.4 RESTful API 契约结构示例

以下是一个典型的 RESTful 用户管理 API 的契约定义片段，展示了请求/响应模型、状态码与资源命名的结合：

// 契约：创建用户
// POST /api/v1/users
// 请求体
{
  "username": "string (required, 3-50 chars)",
  "email": "string (required, valid email format)",
  "role": "string (optional, default: 'user')"
}
// 成功响应 (201 Created)
{
  "id": "string (uuid)",
  "username": "string",
  "email": "string",
  "role": "string",
  "created_at": "string (ISO 8601)"
}
// 错误响应 (400 Bad Request)
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Username is required",
    "field": "username"
  }
}
// 错误响应 (409 Conflict)
{
  "error": {
    "code": "DUPLICATE_EMAIL",
    "message": "Email already exists"
  }
}

3.5 状态码在契约压测中的策略

在压测场景中，不同状态码的分布直接反映系统健康度。以下是一个典型的压测断言策略表：

3.6 本章小结