一、总体原则
1. RESTful风格：遵循RESTful设计原则，使用标准HTTP方法（GET/POST/PUT/DELETE）
2. 版本控制：API应包含版本号（如`/api/v1/`）
3. 安全性：所有接口需通过HTTPS协议访问
4. 一致性：保持接口命名、参数、响应格式的一致性
5. 可扩展性：设计时应考虑未来业务扩展需求
二、接口设计规范
1. 命名规范
- 使用小写字母和连字符（kebab-case），例如：`/api/v1/order-items`
- 名词复数形式表示资源集合，单数形式表示特定资源
- 避免使用动词，操作通过HTTP方法表达
2. HTTP方法使用
- GET：获取资源
- POST：创建资源
- PUT：更新整个资源
- PATCH：部分更新资源
- DELETE：删除资源
3. 请求头规范
```
Content-Type: application/json
Accept: application/json
Authorization: Bearer // JWT令牌
X-Request-ID: <唯一请求ID> // 用于追踪请求
```
4. 请求参数
- 路径参数：用于标识特定资源，如`/orders/{orderId}`
- 查询参数：用于过滤、排序和分页，如`?status=pending&page=1&size=20`
- 请求体：JSON格式，用于创建/更新资源
三、响应规范
1. 成功响应
```json
{
"code": 200,
"message": "成功",
"data": {
// 业务数据
},
"timestamp": "2023-07-20T12:00:00Z"
}
```
2. 错误响应
```json
{
"code": 400,
"message": "参数错误",
"errors": [
{
"field": "quantity",
"message": "数量必须大于0"
}
],
"timestamp": "2023-07-20T12:00:00Z"
}
```
3. 状态码规范
- 200 OK：成功请求
- 201 Created：资源创建成功
- 204 No Content：成功但无返回数据
- 400 Bad Request：客户端错误
- 401 Unauthorized：未认证
- 403 Forbidden：无权限
- 404 Not Found：资源不存在
- 429 Too Many Requests：请求过于频繁
- 500 Internal Server Error：服务器错误
四、分页规范
```
GET /api/v1/products?page=1&size=20
```
响应示例：
```json
{
"code": 200,
"message": "成功",
"data": {
"items": [...], // 当前页数据
"pagination": {
"total": 100,
"page": 1,
"size": 20,
"pages": 5
}
},
"timestamp": "2023-07-20T12:00:00Z"
}
```
五、安全规范
1. 认证：使用JWT进行身份验证
2. 授权：基于角色的访问控制（RBAC）
3. 输入验证：所有输入参数必须验证
4. 速率限制：防止API滥用
5. 敏感数据：不返回密码、支付信息等敏感字段
六、文档规范
1. 使用OpenAPI/Swagger生成API文档
2. 每个接口需包含：
- 描述
- 请求方法
- 路径
- 请求参数说明
- 响应示例
- 状态码说明
3. 文档需与代码同步更新
七、生鲜业务特定规范
1. 商品接口：
- 必须包含保质期、产地、库存状态等生鲜特有字段
- 支持按保质期倒序排序
2. 订单接口：
- 需支持冷链配送特殊状态
- 包含预计送达时间窗口
3. 库存接口：
- 实时库存查询需考虑批次管理
- 支持库存预警阈值设置
八、测试规范
1. 单元测试覆盖率≥80%
2. 接口测试需包含：
- 正常流程
- 边界条件
- 异常情况
3. 性能测试：关键接口需满足QPS要求
九、版本控制策略
1. 主版本号（v1, v2...）：不兼容的API修改
2. 次版本号（v1.1, v1.2...）：向后兼容的功能新增
3. 修订号（v1.1.1...）：向后兼容的问题修正
十、示例接口
1. 获取商品列表
```
GET /api/v1/products?category=meat&page=1&size=10
```
2. 创建订单
```
POST /api/v1/orders
Content-Type: application/json
{
"items": [
{
"productId": "123",
"quantity": 2,
"specialInstructions": "切块"
}
],
"deliveryAddress": "北京市朝阳区...",
"deliveryTime": "2023-07-21 10:00-12:00"
}
```
3. 更新库存
```
PATCH /api/v1/inventory/{productId}
Content-Type: application/json
{
"adjustment": -5,
"batchNumber": "BATCH20230720"
}
```
本规范应作为快驴生鲜系统API开发的基础标准，所有开发需严格遵守。如有特殊需求，需经过技术委员会评审通过后方可调整。
广告
