team/docs/09-API契约.md

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 认证方式

接口类别	认证方式	说明

---

2. 通用响应格式

2.1 成功响应

{
    "data": {
        "key": "value"
    },
    "meta": {
        "request_id": "550e8400-e29b-41d4-a716-446655440000"
    }
}

2.2 错误响应

{
    "error": {
        "code": "ERROR_CODE",
        "message": "用户可读的错误描述"
    },
    "meta": {
        "request_id": "550e8400-e29b-41d4-a716-446655440000"
    }
}

2.3 分页响应

{
    "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 --

请求：

{
    "field": "value"
}

响应 ：

{
    "data": {},
    "meta": {
        "request_id": "550e8400-e29b-41d4-a716-446655440000"
    }
}

错误响应：

状态码	错误码	说明

---

6. FR 映射表

FR 编号	功能	对应 API 接口
FR-001
FR-002

---

版本历史:

• v1.0.0 (2026-04-19): 初始化模板