# Common Contract Generation

> 契约生成技能，提供API契约文档的生成和管理能力

- Skill: `bage2014/common-contract-generation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bage2014/common-contract-generation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bage2014/common-contract-generation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: bage2014 (https://skillmd.com/u/bage2014)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bage2014/common-contract-generation

---


# 契约生成技能

## 功能描述

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

## 何时使用

在以下情况调用此技能：
- 需要设计新的 API 接口时
- 需要生成 OpenAPI/Swagger 文档时
- 需要验证契约一致性时
- 需要生成客户端 SDK 时

## 核心功能

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

## 输入参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| apiName | String | 是 | API 名称 |
| endpoints | List\<Endpoint\> | 是 | 接口端点列表 |
| format | String | 否 | 输出格式（openapi3/swagger2） |
| version | String | 否 | API 版本 |

## 输出格式

```json
{
  "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 数据和服务器

## 契约质量检查清单

| 检查项 | 说明 | 状态 |
|--------|------|------|
| 路径规范 | API 路径是否符合 REST 规范 | ✅/❌ |
| HTTP方法 | 是否使用正确的 HTTP 方法 | ✅/❌ |
| 参数完整 | 请求参数是否完整定义 | ✅/❌ |
| 响应定义 | 响应结构是否完整定义 | ✅/❌ |
| 错误处理 | 是否定义错误响应 | ✅/❌ |
| 状态码 | HTTP 状态码是否正确使用 | ✅/❌ |
| 版本管理 | 是否有版本控制策略 | ✅/❌ |
| 文档完整 | 是否有必要的描述和示例 | ✅/❌ |

## 最佳实践指南

### OpenAPI 规范示例

```yaml
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：服务器错误

### 错误响应格式

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

## 契约管理策略

### 版本控制

| 策略 | 说明 | 适用场景 |
|------|------|----------|
| URL 版本 | `/v1/users` | 简单直接，便于调试 |
| Header 版本 | `Accept-Version: 1.0` | 保持 URL 简洁 |
| Media Type 版本 | `Accept: application/vnd.example.v1+json` | 符合 REST 最佳实践 |

### 契约演进

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

## 核心组件

| 组件 | 职责 | 描述 |
|------|------|------|
| ContractDesigner | 契约设计器 | 设计 API 接口契约 |
| SpecGenerator | 规范生成器 | 生成 OpenAPI 规范 |
| ContractValidator | 契约验证器 | 验证契约一致性 |
| SdkGenerator | SDK 生成器 | 生成客户端 SDK |
| MockGenerator | Mock 生成器 | 生成 Mock 数据 |

## 配置要求

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| CONTRACT_FORMAT | 默认输出格式 | openapi3 |
| API_VERSION | 默认 API 版本 | 1.0.0 |

### 配置文件

```yaml
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. 更新契约质量检查清单
## 触发条件