一、接口设计原则
1. RESTful风格：遵循REST架构原则，使用标准HTTP方法（GET/POST/PUT/DELETE）
2. 一致性：接口命名、参数格式、响应结构保持统一
3. 幂等性：确保重复请求不会产生副作用
4. 安全性：支持HTTPS，敏感数据加密传输
5. 可扩展性：版本控制机制，便于后续迭代
二、接口规范
1. 基础规范
- 协议：强制使用HTTPS（TLS 1.2及以上）
- 域名：统一使用`api.kuailefresh.com`（示例）
- 版本控制：路径中包含版本号，如`/v1/`
- 超时设置：建议客户端设置3-5秒超时
2. 接口路径规范
- 使用名词复数形式：`/orders`而非`/order`
- 分层级设计：`/v1/warehouses/{warehouseId}/products`
- 避免深层次嵌套（建议不超过3级）
3. 请求规范
请求方法
- GET：获取资源
- POST：创建资源
- PUT：更新完整资源
- PATCH：更新部分资源
- DELETE：删除资源
请求头
```
Content-Type: application/json
Accept: application/json
Authorization: Bearer // JWT令牌
X-Request-ID: <唯一请求ID> // 用于追踪请求
```
查询参数
- 使用小写字母和下划线：`start_time`而非`startTime`
- 分页参数：`page=1&page_size=20`
- 排序参数：`sort=create_time_desc`
4. 响应规范
成功响应
```json
{
"code": 200,
"message": "success",
"data": {
// 业务数据
},
"timestamp": 1625097600
}
```
错误响应
```json
{
"code": 400,
"message": "Invalid parameter",
"errors": [
{
"field": "quantity",
"message": "Quantity must be positive"
}
],
"timestamp": 1625097600
}
```
状态码规范
- 200：成功
- 201：创建成功
- 400：客户端错误（参数错误）
- 401：未授权
- 403：禁止访问
- 404：资源不存在
- 500：服务器错误
5. 数据格式规范
日期时间
- 使用ISO 8601格式：`YYYY-MM-DDTHH:mm:ssZ`
- 示例：`2023-06-30T14:30:00+08:00`
金额
- 使用最小单位（分）：`1000`表示10.00元
- 字段命名：`total_amount`
枚举值
- 使用全大写加下划线：`ORDER_STATUS_PENDING`
- 提供完整的枚举值列表
三、安全规范
1. 认证授权：
- 使用JWT进行身份验证
- 接口权限细分（按功能模块）
2. 数据加密：
- 敏感信息（如身份证号）传输时加密
- 存储时使用AES-256加密
3. 限流策略：
- IP限流：1000次/分钟
- 用户限流：500次/分钟
- 关键接口单独限流
4. 日志记录：
- 记录完整请求/响应
- 敏感信息脱敏处理
四、文档规范
1. 接口文档：
- 使用Swagger/OpenAPI规范
- 包含示例请求/响应
- 明确参数约束条件
2. 变更记录：
- 维护CHANGELOG.md
- 记录接口变更历史
3. 测试用例：
- 提供Postman集合
- 包含正常/异常场景
五、示例接口
1. 获取商品列表
请求：
```
GET /v1/products?category_id=1&page=1&page_size=10
Headers:
Authorization: Bearer
```
响应：
```json
{
"code": 200,
"message": "success",
"data": {
"total": 100,
"list": [
{
"product_id": 123,
"name": "新鲜苹果",
"price": 599,
"stock": 100,
"category": "FRUIT"
}
]
},
"timestamp": 1625097600
}
```
2. 创建订单
请求：
```
POST /v1/orders
Headers:
Authorization: Bearer
Content-Type: application/json
Body:
{
"warehouse_id": 1,
"items": [
{
"product_id": 123,
"quantity": 5
}
],
"delivery_time": "2023-07-01T10:00:00+08:00"
}
```
响应：
```json
{
"code": 201,
"message": "Order created",
"data": {
"order_id": "ORD202306300001",
"total_amount": 2995
},
"timestamp": 1625097600
}
```
六、实施建议
1. 使用API网关进行统一管理
2. 实现自动化测试覆盖率≥90%
3. 关键接口实现熔断降级机制
4. 定期进行安全审计和渗透测试
5. 建立接口监控告警体系
本规范应作为快驴生鲜系统API开发的基本准则，所有接口实现需经过代码审查确保符合规范要求。
广告
