1. 概述
本规范旨在为快驴生鲜系统API接口开发提供统一标准，确保接口设计的一致性、可维护性和安全性，提升前后端协作效率。
2. 接口设计原则
2.1 RESTful风格
- 采用RESTful架构设计API
- 使用HTTP方法明确操作类型：
- GET：获取资源
- POST：创建资源
- PUT：更新资源（完整更新）
- PATCH：部分更新资源
- DELETE：删除资源
2.2 版本控制
- 接口必须包含版本号，格式为`/api/v1/`
- 版本升级时保持向下兼容，重大变更时递增版本号
2.3 命名规范
- 使用小写字母和连字符（kebab-case）命名路径
- 资源名使用复数形式（如`/orders`而非`/order`）
- 操作类接口使用动词前缀（如`/search-products`）
3. 接口规范
3.1 请求规范
3.1.1 请求头
```http
Content-Type: application/json
Accept: application/json
Authorization: Bearer JWT授权
X-Request-ID: <唯一请求ID> 用于追踪请求
```
3.1.2 请求参数
- 路径参数：用于标识资源，如`/orders/{orderId}`
- 查询参数：用于过滤、排序和分页，如：
```
/products?category=fruit&sort=price_asc&page=1&size=20
```
- 请求体：JSON格式，用于创建/更新数据
3.2 响应规范
3.2.1 成功响应
```json
{
"code": 200,
"message": "success",
"data": {
// 业务数据
},
"timestamp": "2023-01-01T12:00:00Z"
}
```
3.2.2 错误响应
```json
{
"code": 400,
"message": "Invalid request parameters",
"errors": [
{
"field": "quantity",
"message": "Quantity must be positive integer"
}
],
"timestamp": "2023-01-01T12:00:00Z"
}
```
3.2.3 状态码规范
| 状态码 | 含义 |
|--------|------|
| 200 | 成功 |
| 201 | 资源创建成功 |
| 204 | 成功但无返回数据 |
| 400 | 客户端错误（参数错误） |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 429 | 请求过于频繁 |
| 500 | 服务器内部错误 |
3.3 分页规范
```json
{
"data": [...],
"pagination": {
"page": 1,
"size": 20,
"total": 100,
"pages": 5
}
}
```
4. 安全规范
4.1 认证授权
- 使用JWT进行身份验证
- 敏感接口需验证权限（如管理员接口）
4.2 数据验证
- 所有输入参数必须验证
- 敏感数据需加密传输（HTTPS）
4.3 速率限制
- 公共API实施速率限制（如100次/分钟）
- 返回429状态码当超过限制时
5. 文档规范
5.1 接口文档要求
- 使用OpenAPI/Swagger规范
- 包含：
- 接口描述
- 请求方法
- 路径参数
- 请求体示例
- 响应示例
- 错误码说明
- 速率限制说明
5.2 示例
```yaml
paths:
/api/v1/products/{productId}:
get:
summary: 获取商品详情
parameters:
- name: productId
in: path
required: true
schema:
type: string
responses:
200:
description: 成功响应
content:
application/json:
schema:
$ref: /components/schemas/Product
```
6. 测试规范
6.1 单元测试
- 每个接口需有对应的单元测试
- 测试覆盖率不低于80%
6.2 集成测试
- 测试完整业务流程
- 包括正常流程和异常流程
6.3 性能测试
- 关键接口需进行压力测试
- 确保QPS满足业务需求
7. 部署规范
7.1 环境划分
- 开发环境：dev.kuailv.com
- 测试环境：test.kuailv.com
- 预发布环境：pre.kuailv.com
- 生产环境：api.kuailv.com
7.2 灰度发布
- 新版本接口先在预发布环境验证
- 采用流量百分比灰度策略
8. 维护规范
8.1 接口变更
- 接口变更需通过评审
- 废弃接口需保留至少3个月并返回410状态码
8.2 监控报警
- 关键接口设置监控指标
- 错误率>1%时触发报警
9. 附录
9.1 常用错误码
| 错误码 | 含义 |
|--------|------|
| 1001 | 参数缺失 |
| 1002 | 参数类型错误 |
| 1003 | 参数值越界 |
| 2001 | 资源不存在 |
| 2002 | 资源已存在 |
| 3001 | 权限不足 |
| 4001 | 业务逻辑错误 |
9.2 日期时间格式
- 使用ISO 8601格式：`YYYY-MM-DDTHH:mm:ssZ`
- 示例：`2023-01-01T12:00:00Z`
本规范作为快驴生鲜系统API开发的基础标准，所有开发人员必须严格遵守，确保系统接口的一致性和可靠性。
广告
