143 lines
2.5 KiB
Markdown
143 lines
2.5 KiB
Markdown
# API 契约
|
||
|
||
**文档版本**: 1.0.0
|
||
**最后更新**: 2026-04-19
|
||
|
||
---
|
||
|
||
## 1. 通用规范
|
||
|
||
| 规范项 | 规则 |
|
||
|--------|------|
|
||
| **基础路径** | `/api/v1` |
|
||
| **协议** | HTTPS（所有接口强制 HTTPS） |
|
||
| **时间格式** | ISO 8601（示例：`2026-04-15T14:30:00Z`） |
|
||
| **字符编码** | UTF-8 |
|
||
| **分页参数** | `?page=1&per_page=50`（默认 50，最大 200） |
|
||
|
||
### 1.1 认证方式
|
||
|
||
| 接口类别 | 认证方式 | 说明 |
|
||
|----------|----------|------|
|
||
| <!-- 类别1 --> | <!-- 方式 --> | <!-- 说明 --> |
|
||
| <!-- 类别2 --> | <!-- 方式 --> | <!-- 说明 --> |
|
||
|
||
---
|
||
|
||
## 2. 通用响应格式
|
||
|
||
### 2.1 成功响应
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"key": "value"
|
||
},
|
||
"meta": {
|
||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 错误响应
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": "ERROR_CODE",
|
||
"message": "用户可读的错误描述"
|
||
},
|
||
"meta": {
|
||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.3 分页响应
|
||
|
||
```json
|
||
{
|
||
"data": [],
|
||
"meta": {
|
||
"total": 100,
|
||
"page": 1,
|
||
"per_page": 50,
|
||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. HTTP 状态码
|
||
|
||
| 状态码 | 场景 |
|
||
|--------|------|
|
||
| 200 | 成功 |
|
||
| 201 | 创建成功 |
|
||
| 204 | 删除成功（无响应体） |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未认证 |
|
||
| 403 | 未授权 |
|
||
| 404 | 资源不存在 |
|
||
| 409 | 冲突 |
|
||
| 429 | 请求过于频繁 |
|
||
| 500 | 服务端内部错误 |
|
||
|
||
---
|
||
|
||
## 4. 错误码规范
|
||
|
||
| 范围 | 错误码 | 说明 |
|
||
|------|--------|------|
|
||
| `AUTH_*` | <!-- 错误码 --> | 认证相关 |
|
||
| `VALIDATION_*` | <!-- 错误码 --> | 验证相关 |
|
||
| <!-- 范围 --> | <!-- 错误码 --> | <!-- 说明 --> |
|
||
|
||
---
|
||
|
||
## 5. 接口定义
|
||
|
||
<!-- 按以下模板为每个接口编写定义 -->
|
||
|
||
### 5.1 <!-- HTTP方法 --> <!-- 路径 --> -- <!-- 接口说明 -->
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{
|
||
"field": "value"
|
||
}
|
||
```
|
||
|
||
**响应 <!-- 状态码 -->：**
|
||
|
||
```json
|
||
{
|
||
"data": {},
|
||
"meta": {
|
||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
|
||
| 状态码 | 错误码 | 说明 |
|
||
|--------|--------|------|
|
||
| <!-- 状态码 --> | <!-- 错误码 --> | <!-- 说明 --> |
|
||
|
||
---
|
||
|
||
## 6. FR 映射表
|
||
|
||
| FR 编号 | 功能 | 对应 API 接口 |
|
||
|---------|------|---------------|
|
||
| FR-001 | <!-- 功能 --> | <!-- 接口 --> |
|
||
| FR-002 | <!-- 功能 --> | <!-- 接口 --> |
|
||
|
||
---
|
||
|
||
**版本历史**:
|
||
- v1.0.0 (2026-04-19): 初始化模板
|