API设计

输入要求

业务需求（必填）：需要设计的业务场景和功能
数据模型（必填）：核心实体和字段
接口类型（可选）：RESTful或GraphQL，默认RESTful
已有接口（可选）：如果已有部分接口需要兼容
特殊要求（可选）：如"需要支持批量操作"、"需要Webhook回调"

执行流程

第一步：Spec场景检查

设计前检查是否有明确的spec：

如有spec：提取spec中的Requirement和Scenario作为接口设计依据，确保每个Requirement对应至少一个端点，每个Scenario映射为接口的成功/错误响应

如无spec：提示用户先使用 spec-driven-development 对齐需求，或基于业务需求生成轻量级spec

✓ Spec场景检查: [检测到/未检测到] 需求规格
[如检测到，列出 Requirement → 端点 映射]

第二步：需求分析

识别API的使用场景和用户
确定API的功能边界
明确输入输出数据模型

第三步：设计原则应用

应用RESTful或GraphQL设计原则
设计URL结构和HTTP方法
定义请求/响应格式

第四步：详细设计

设计每个端点的详细规范
定义错误处理策略
设计认证和授权机制
如接口涉及长任务/批处理/导入导出/生成任务，必须采用 Init → Step → Poll AJAX 渐进式防卡死架构

第五步：API规范定义

## API Spec: [API名称]

### ADDED Requirements

#### Requirement: [端点名称]

The system SHALL provide an endpoint to [功能描述].

##### Scenario: 成功请求

- GIVEN [前置条件]
- WHEN 发送 `[METHOD] [路径]` 请求
- THEN 返回 [状态码] 和 [响应体]

##### Scenario: 错误处理

- GIVEN [错误前置条件]
- WHEN 发送 `[METHOD] [路径]` 请求
- THEN 返回 [错误状态码] 和 [错误响应体]

### Design

- **URL结构**: [结构说明]
- **认证方式**: [认证机制]
- **版本策略**: [版本管理]

### File Changes

- `[API定义文件]` (new/modified)

规范验证（必填）

API规范定义完成后，必须完成以下验证才能进入文档生成：

契约一致性：每个 Requirement 至少有一个 Scenario 覆盖，Scenario 的 Given/When/Then 完整
错误码完备：每个端点定义了成功和至少一类错误场景的错误码
认证/授权：需要鉴权的端点标注了认证方式和所需权限
分页/限流：列表端点定义了分页参数和限流策略
幂等性：写操作标注了是否幂等，非幂等操作定义了重试策略
命名规范：路径、字段、错误码遵循统一命名规范（如 snake_case / camelCase）
长任务契约：耗时操作采用 Init-Step-Poll 模式，定义了任务ID、进度查询端点、取消端点和超时策略

如某项无法验证，必须在文档生成时标注"未验证项"，不得跳过。

第六步：文档生成

生成OpenAPI/Swagger规范
编写使用示例
提供SDK代码示例

第七步：记录到项目记忆

API 设计完成后，将关键决策和规范记录到项目记忆（参见 project-memory-management.md）：

记录 API 设计决策（如 RESTful vs GraphQL 选择理由）
记录接口命名约定和版本策略
记录认证/授权方案的选型依据

实战请求示例

示例一：分页查询接口

帮我设计一个订单列表 API。
资源：orders。
查询条件：page、page_size、status、keyword、created_start、created_end。
权限：只有后台运营可访问；普通用户不能访问。
要求：分页最大 100；错误响应要有 code/message；keyword 支持订单号和手机号。
验证：给出正常请求、非法 page_size、无权限访问的响应示例。

优先加载：api-design.md、mysql-database.md、test-generation.md。

示例二：长任务导出接口

帮我设计一个订单导出 API，数据量可能超过 10 万。
要求：不能单请求同步导出，必须 Init-Step-Poll；支持进度、失败原因、取消和重试。
权限：只有管理员可导出；导出文件 24 小时后过期。
前端：需要轮询字段和错误提示文案。
验证：给出 Init、Step、Poll、Cancel 的请求/响应示例。

优先加载：api-design.md、frontend-design.md、test-generation.md。

输出格式


## API设计文档

### 资源定义

| 资源 | 说明 | 核心字段 |
| -------- | ------ | ---------- |
| [资源名] | [说明] | [字段列表] |

### 接口列表

#### [接口名称]

**URL**：`[METHOD] /path`
**说明**：[功能说明]

**请求参数**：
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| [字段] | [类型] | [是/否] | [说明] |

**响应格式**：

```json
{
  "code": 0,
  "data": { ... },
  "message": "success"
}
```

**错误码**：
| 错误码 | 说明 |
|--------|------|
| [CODE] | [说明] |

### 通用规范

- **认证方式**：[Bearer Token / API Key / OAuth2]
- **版本控制**：[URL路径 / Header / 参数]
- **分页方式**：[页码分页 / 游标分页]
- **数据格式**：[snake_case / camelCase]

### 长任务接口规范（如适用）

| 端点 | 方法 | 说明 |
|------|------|------|
| `/tasks/{type}/init` | POST | 创建任务，返回 `task_id`、`total`、初始状态 `queued` |
| `/tasks/{task_id}/step` | POST | 执行一批处理，返回进度和 `has_more` |
| `/tasks/{task_id}/poll` | GET | 查询任务状态、进度、错误和结果 |
| `/tasks/{task_id}/cancel` | POST | 标记任务取消，返回 `status=cancelled`；正在执行的 Step 在下一批次检测取消标记后优雅退出 |

**Step 响应必须包含**：`task_id`, `status`, `processed`, `total`, `percent`, `has_more`, `message`, `errors`

质量标准

URL必须使用名词复数形式，不能用动词（如/users而非/getUsers）
HTTP方法必须符合语义（GET无副作用、POST创建、PUT幂等更新、DELETE删除）
错误响应必须包含机器可读的错误码和人工可读的消息
分页接口必须说明最大页大小和默认页大小
敏感操作（删除、批量修改）必须要求二次确认或特殊权限
不得设计返回超大列表的接口（必须分页或流式）
长任务/批处理接口必须采用 Init → Step → Poll，不得设计为单请求同步阻塞执行
Step 接口必须幂等、可重试，并限制单批处理数量

失败回退机制

关联 reference

tech-selection（技术选型）— 设计前可用 tech-selection 确定API技术方案（REST/GraphQL/gRPC）
code-generation（代码生成）— 设计后可用 code-generation 生成API接口代码
test-generation（测试用例生成）— 设计后可用 test-generation 生成API测试
doc-generation（文档生成）— 设计后可用 doc-generation 生成API文档
project-memory-management（项目记忆管理）— 记录 API 设计决策、接口命名约定和版本策略

api-design.md 8.3 KB Historia Czysty