---
name: 接口设计模版
when: '接口设计, API设计, 接口文档, 接口定义'
scope:
  - backend
  - frontend
products:
  - '*'
id: ka-artifact_template-接口设计模版
asset_kind: artifact_template
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 接口设计
  - API设计
  - 接口文档
  - 接口定义
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits:
  - acceptance_report
secondary_triggers: []
negative_triggers: []
type: acceptance_template
status: active
---

# 接口设计文档

## 1. 接口总览
| 序号 | 路径 | 方法 | 认证 | 描述 |
|------|------|------|------|------|
|      |      |      |      |      |

## 2. 接口详情

### 2.1 [接口名称]
- **路径**: `POST /api/v1/xxx`
- **认证**: Bearer Token / API Key
- **幂等性**: 是/否（幂等键：xxx）

**请求参数**:
| 字段 | 类型 | 必填 | 校验规则 | 说明 |
|------|------|------|---------|------|
|      |      |      |         |      |

**响应结构**:
```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

**错误码**:
| 错误码 | HTTP 状态码 | 触发条件 | 用户提示 |
|--------|-----------|---------|---------|
|        |           |         |         |

## 3. 枚举值定义
| 枚举名 | 值 | 含义 |
|--------|------|------|
|        |      |      |

## 4. 页面交互映射
| 页面操作 | 触发接口 | 加载状态 | 成功行为 | 失败行为 |
|---------|---------|---------|---------|---------|
|         |         |         |         |         |

## 5. 接口规范检查
- [ ] 是否定义了接口版本号和演进策略（如 /api/v1/）
- [ ] 是否有幂等设计（写接口需标注幂等键或唯一约束）
- [ ] 错误码体系是否完整（业务码 + HTTP 状态码双映射）
- [ ] 是否有分页参数上限限制（防止恶意大翻页）
- [ ] 是否有接口限流策略（QPS/并发上限）
- [ ] 批量操作是否有数量上限（≤ 500 条）
