一、概述
本规范旨在为快驴生鲜系统API接口开发提供统一标准，确保接口的规范性、安全性、可维护性和可扩展性，提升系统间交互效率。
二、接口设计原则
1. RESTful风格：优先采用RESTful架构设计API
2. 一致性：保持接口命名、参数、响应格式统一
3. 明确性：接口功能单一明确，避免过度复杂
4. 安全性：确保数据传输和访问安全
5. 可扩展性：预留扩展空间，便于后续功能迭代
三、接口规范
1. 接口命名规范
- 版本控制：接口路径需包含版本号，如`/api/v1/`
- 命名风格：采用小写字母+下划线风格，如`/api/v1/order_list`
- 资源命名：使用名词复数形式表示资源集合，如`/products`
- 动作命名：对非标准CRUD操作使用动词前缀，如`/export_orders`
2. 请求规范
请求方法
- `GET`：获取资源
- `POST`：创建资源
- `PUT`：更新完整资源
- `PATCH`：更新部分资源
- `DELETE`：删除资源
请求头
- 必须包含：
```
Content-Type: application/json
Accept: application/json
Authorization: Bearer (JWT令牌)
X-Request-ID: <唯一请求ID> (用于追踪)
```
请求参数
- 路径参数：用于标识资源，如`/products/{product_id}`
- 查询参数：用于过滤、排序、分页，如`?page=1&size=10&sort=price,desc`
- 请求体：JSON格式，用于创建/更新资源
3. 响应规范
响应结构
```json
{
"code": 200,
"message": "成功",
"data": {
// 业务数据
},
"timestamp": "2023-01-01T12:00:00Z"
}
```
状态码规范
| 状态码 | 含义 |
|--------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 204 | 删除成功 |
| 400 | 参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 429 | 请求过于频繁 |
| 500 | 服务器错误 |
分页响应
```json
{
"code": 200,
"message": "成功",
"data": {
"items": [...],
"total": 100,
"page": 1,
"size": 10,
"pages": 10
},
"timestamp": "2023-01-01T12:00:00Z"
}
```
4. 错误处理
- 错误响应需包含明确的错误码和描述
- 示例：
```json
{
"code": 400,
"message": "参数错误: product_name不能为空",
"data": null,
"timestamp": "2023-01-01T12:00:00Z"
}
```
四、安全规范
1. 认证授权：
- 使用JWT进行身份认证
- 实现基于角色的访问控制(RBAC)
2. 数据加密：
- 敏感数据传输使用HTTPS
- 敏感信息在存储时加密
3. 限流机制：
- 实现接口调用频率限制
- 防止暴力破解和DDoS攻击
4. 输入验证：
- 所有输入参数必须验证
- 防止SQL注入和XSS攻击
五、文档规范
1. 接口文档：
- 使用Swagger/OpenAPI规范
- 包含接口说明、请求示例、响应示例、错误码
2. 更新记录：
- 维护接口变更历史
- 标注版本兼容性
六、测试规范
1. 单元测试：
- 接口单元测试覆盖率≥90%
- 包含正常和异常场景
2. 集成测试：
- 模拟真实业务场景测试
- 验证接口间交互
3. 性能测试：
- 压测接口响应时间和吞吐量
- 确保满足业务需求
七、示例接口
1. 获取商品列表
```
GET /api/v1/products?category=fruit&page=1&size=10
Headers:
Authorization: Bearer
Response:
{
"code": 200,
"message": "成功",
"data": {
"items": [
{
"id": "p001",
"name": "苹果",
"price": 5.99,
"stock": 100
},
...
],
"total": 50,
"page": 1,
"size": 10,
"pages": 5
},
"timestamp": "2023-01-01T12:00:00Z"
}
```
2. 创建订单
```
POST /api/v1/orders
Headers:
Authorization: Bearer
Content-Type: application/json
Body:
{
"user_id": "u1001",
"items": [
{"product_id": "p001", "quantity": 2},
{"product_id": "p002", "quantity": 1}
],
"delivery_address": "北京市朝阳区..."
}
Response:
{
"code": 201,
"message": "订单创建成功",
"data": {
"order_id": "o20230101001",
"total_amount": 17.97
},
"timestamp": "2023-01-01T12:00:00Z"
}
```
八、附则
1. 本规范由快驴生鲜技术部制定并负责解释
2. 规范会根据业务发展和技术演进适时修订
3. 所有API开发必须严格遵守本规范
> 注：实际开发中应根据具体业务需求和技术栈进行适当调整，本规范提供基础框架和最佳实践参考。
广告
