一、总则
1. 目的：规范快驴生鲜系统API接口设计、开发与维护，确保接口的稳定性、安全性和可维护性。
2. 适用范围：快驴生鲜系统内部各模块间接口、与第三方系统对接接口。
3. 基本原则：
- 统一性：接口设计遵循统一规范
- 安全性：确保数据传输和访问安全
- 可扩展性：便于后续功能扩展
- 易用性：提供清晰的接口文档和使用示例
二、接口设计规范
2.1 接口命名规范
1. 命名规则：
- 使用小写字母和下划线组合（snake_case）
- 动词+名词结构，如：`get_product_list`
- 避免使用保留字和特殊字符
2. 版本控制：
- 接口版本号放在URL路径中，如：`/api/v1/products`
- 版本号格式：`v`+数字（如v1, v2）
2.2 请求规范
1. 请求方法：
- GET：获取资源
- POST：创建资源
- PUT：更新完整资源
- PATCH：更新部分资源
- DELETE：删除资源
2. 请求头：
```http
Content-Type: application/json
Accept: application/json
Authorization: Bearer 认证token
X-Request-ID: <唯一请求ID> 用于追踪请求
```
3. 请求参数：
- GET请求参数通过URL查询字符串传递
- POST/PUT/PATCH请求参数通过请求体传递
- 参数命名遵循snake_case规范
2.3 响应规范
1. 成功响应：
```json
{
"code": 200,
"message": "success",
"data": {
// 业务数据
}
}
```
2. 错误响应：
```json
{
"code": 400,
"message": "Invalid parameter",
"errors": [
{
"field": "product_id",
"message": "Product ID is required"
}
]
}
```
3. 状态码规范：
- 200：成功
- 400：客户端错误（参数错误）
- 401：未授权
- 403：禁止访问
- 404：资源不存在
- 500：服务器内部错误
三、数据格式规范
3.1 日期时间格式
- 使用ISO 8601标准格式：`YYYY-MM-DD HH:MM:SS`
- 示例：`2023-05-15 14:30:00`
3.2 金额格式
- 使用整数表示，单位为分
- 示例：100元表示为10000
3.3 分页数据格式
```json
{
"pagination": {
"current_page": 1,
"per_page": 20,
"total_pages": 10,
"total_items": 200
},
"data": [...]
}
```
四、安全规范
1. 认证授权：
- 使用JWT或OAuth2.0进行认证
- 所有敏感接口需验证token有效性
2. 数据加密：
- 敏感数据（如用户密码）传输需加密
- 考虑使用HTTPS协议
3. 访问控制：
- 基于角色的访问控制（RBAC）
- 接口级权限控制
4. 输入验证：
- 所有输入参数需进行验证
- 防止SQL注入、XSS攻击等
五、文档规范
1. 接口文档内容：
- 接口名称和描述
- 请求URL和方法
- 请求参数说明（名称、类型、是否必填、描述）
- 响应示例和说明
- 错误码说明
- 调用示例（代码片段）
2. 文档格式：
- 使用Swagger或OpenAPI规范
- 提供在线文档和离线文档两种形式
3. 更新机制：
- 接口变更需同步更新文档
- 文档版本与接口版本保持一致
六、测试规范
1. 单元测试：
- 每个接口需编写单元测试
- 测试覆盖率不低于80%
2. 集成测试：
- 模拟真实场景进行接口联调
- 测试边界条件和异常情况
3. 性能测试：
- 关键接口需进行压力测试
- 确定接口QPS上限
七、版本管理规范
1. 版本控制策略：
- 遵循语义化版本控制（SemVer）
- 重大变更需升级主版本号
2. 兼容性要求：
- 向下兼容：新版本接口需兼容旧版本调用
- 废弃接口需提供至少3个月的过渡期
3. 变更通知：
- 接口变更需提前通知相关方
- 提供变更日志和迁移指南
八、监控与告警规范
1. 监控指标：
- 接口调用成功率
- 平均响应时间
- 错误率
- QPS
2. 告警规则：
- 成功率低于95%触发告警
- 平均响应时间超过500ms触发告警
- 错误率超过1%触发告警
3. 日志记录：
- 记录完整请求和响应
- 记录请求来源和用户信息
- 保留至少30天的日志
九、附录
1. 常用错误码定义：
- 1000-1999：系统错误
- 2000-2999：参数错误
- 3000-3999：权限错误
- 4000-4999：业务错误
2. 示例接口：
```http
// 获取商品列表
GET /api/v1/products?category_id=1&page=1&per_page=20
Headers:
Authorization: Bearer xxx
// 响应示例
{
"code": 200,
"message": "success",
"pagination": {
"current_page": 1,
"per_page": 20,
"total_pages": 5,
"total_items": 100
},
"data": [
{
"product_id": 1001,
"name": "新鲜苹果",
"price": 599, // 5.99元
"stock": 100,
"created_at": "2023-05-10 09:00:00"
}
]
}
```
本规范作为快驴生鲜系统API接口开发的标准指南，所有开发人员需严格遵守。如有特殊情况需要偏离规范，需经过技术委员会评审通过。
广告
