Common Contract Generation

契约生成技能

功能描述

提供 API 契约文档的生成和管理能力，帮助团队定义和维护服务间的接口契约，确保前后端协作的一致性。

何时使用

在以下情况调用此技能：

• 需要设计新的 API 接口时
• 需要生成 OpenAPI/Swagger 文档时
• 需要验证契约一致性时
• 需要生成客户端 SDK 时

核心功能

• 契约设计：设计 RESTful API 接口契约
• 文档生成：生成 OpenAPI/Swagger 文档
• 契约验证：验证接口实现与契约的一致性
• SDK生成：生成客户端 SDK 和类型定义
• Mock生成：生成 Mock 数据和服务器

输入参数

输出格式

{
  "status": "SUCCESS",
  "apiName": "用户服务 API",
  "version": "1.0.0",
  "openapiSpec": "OpenAPI YAML/JSON 规范",
  "endpoints": [
    {
      "path": "/api/users",
      "method": "GET",
      "summary": "获取用户列表",
      "request": {},
      "response": {}
    }
  ],
  "validationResult": {
    "valid": true,
    "errors": []
  },
  "generatedFiles": ["openapi.yaml", "client-sdk.ts"]
}

契约设计流程

需求分析 → 接口设计 → 契约编写 → 契约验证 → 文档生成 → SDK生成 → Mock生成

详细步骤

1. 需求分析：理解业务需求，确定接口功能
2. 接口设计：设计 API 端点、参数和响应结构
3. 契约编写：编写 OpenAPI 规范文档
4. 契约验证：验证契约的语法和语义正确性
5. 文档生成：生成可视化的 API 文档
6. SDK生成：生成客户端 SDK 和类型定义
7. Mock生成：生成 Mock 数据和服务器

契约质量检查清单

最佳实践指南

OpenAPI 规范示例

openapi: 3.0.3
info:
  title: 用户服务 API
  description: 用户管理相关接口
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: 获取用户列表
      description: 获取所有用户的列表
      parameters:
        - name: page
          in: query
          description: 页码
          required: false
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: 成功获取用户列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
      required:
        - id
        - email

REST API 设计规范

1. 路径命名：使用小写字母和连字符，如 /api/user-profiles
2. HTTP 方法：
   • GET：获取资源
   • POST：创建资源
   • PUT：更新完整资源
   • PATCH：更新部分资源
   • DELETE：删除资源
3. 状态码：
   • 200：成功获取/更新
   • 201：成功创建
   • 204：成功删除（无内容）
   • 400：请求参数错误
   • 401：未认证
   • 403：无权限
   • 404：资源不存在
   • 500：服务器错误

错误响应格式

components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: 错误代码
        message:
          type: string
          description: 错误消息
        details:
          type: array
          items:
            type: string
          description: 详细错误信息
      required:
        - code
        - message

契约管理策略

版本控制

契约演进

1. 向后兼容变更：添加新字段、新端点
2. 非向后兼容变更：修改现有字段、删除字段、删除端点
3. 版本升级策略：使用新版本号，保持旧版本可用

核心组件

配置要求

环境变量

配置文件

contract:
  format: openapi3
  version: 1.0.0
  output:
    spec: openapi.yaml
    docs: docs/api
    sdk:
      - language: typescript
        output: src/client
      - language: java
        output: client/java

扩展指南

添加新语言 SDK 支持

1. 创建对应语言的 SDK 生成器
2. 定义代码模板和映射规则
3. 添加 SDK 生成配置

添加自定义验证规则

1. 在验证器中添加新规则
2. 定义规则的检查逻辑和错误消息
3. 更新契约质量检查清单

触发条件