一、总则
1. 目的：规范快驴生鲜系统API接口设计、开发、测试及维护流程，确保接口的稳定性、安全性和可维护性。
2. 适用范围：快驴生鲜系统所有对外提供及内部调用的API接口。
3. 基本原则：RESTful风格、一致性、安全性、可扩展性、易用性。
二、API设计规范
1. 接口命名规范
- 资源命名：使用名词复数形式表示资源集合（如`/orders`），单数形式表示特定资源（如`/orders/{id}`）。
- 版本控制：在URL中包含版本号（如`/v1/orders`），便于后续迭代。
- 命名风格：小写字母+下划线或短横线（推荐短横线，如`/order-items`）。
2. 请求方法规范
- GET：获取资源，不修改服务器状态。
- POST：创建资源或触发非幂等操作。
- PUT：更新整个资源（幂等）。
- PATCH：部分更新资源（幂等）。
- DELETE：删除资源。
3. 请求/响应格式
- 内容类型：统一使用`application/json`。
- 字符编码：UTF-8。
- 时间格式：ISO 8601标准（如`2023-01-01T12:00:00Z`）。
4. 请求参数规范
- 路径参数：用于标识资源（如`/orders/{orderId}`）。
- 查询参数：用于过滤、排序、分页（如`?status=pending&page=1`）。
- 请求体：POST/PUT/PATCH请求中，使用JSON格式传递数据。
- 必填/选填：明确标注参数是否为必填（`required: true/false`）。
5. 响应格式规范
- 成功响应：
```json
{
"code": 200,
"message": "success",
"data": {
"id": 123,
"name": "example"
}
}
```
- 错误响应：
```json
{
"code": 400,
"message": "Invalid parameter",
"errors": [
{
"field": "name",
"message": "Name is required"
}
]
}
```
- 状态码：
- 200 OK：成功请求。
- 201 Created：资源创建成功。
- 400 Bad Request：客户端错误。
- 401 Unauthorized：未授权。
- 403 Forbidden：禁止访问。
- 404 Not Found：资源不存在。
- 500 Internal Server Error：服务器错误。
三、API安全规范
1. 认证与授权
- OAuth 2.0：使用OAuth 2.0进行授权，支持客户端凭证、密码模式等。
- JWT：使用JWT（JSON Web Token）进行身份验证，包含用户信息及过期时间。
- API Key：可选的API Key验证，用于内部服务调用。
2. 数据加密
- HTTPS：所有API必须通过HTTPS协议传输，禁用HTTP。
- 敏感数据：敏感数据（如密码、支付信息）需加密存储及传输。
3. 访问控制
- IP白名单：可选的IP白名单机制，限制特定IP访问。
- 速率限制：对API调用进行速率限制，防止滥用。
四、API开发规范
1. 代码规范
- 命名规范：变量、方法、类名等遵循驼峰命名法。
- 注释规范：关键逻辑需添加注释，接口需添加Swagger注解。
- 异常处理：统一异常处理机制，避免暴露敏感信息。
2. 文档规范
- Swagger：使用Swagger生成API文档，包含接口说明、参数、示例等。
- 版本说明：文档中明确标注API版本及变更历史。
3. 测试规范
- 单元测试：关键逻辑需编写单元测试。
- 接口测试：使用Postman或JMeter进行接口测试。
- Mock服务：开发阶段可使用Mock服务模拟依赖。
五、API维护规范
1. 版本管理
- 向后兼容：新版本API需保持对旧版本客户端的兼容性。
- 废弃策略：明确标注废弃API及替代方案，设置合理的过渡期。
2. 监控与告警
- 日志记录：记录API调用日志，包括请求参数、响应时间等。
- 监控指标：监控API调用量、成功率、响应时间等。
- 告警机制：设置阈值，异常时触发告警。
3. 变更管理
- 变更流程：API变更需经过评审、测试、发布流程。
- 回滚机制：发布失败时需支持快速回滚。
六、附录
1. 示例接口
```
GET /v1/products?category=fruit&page=1
```
响应：
```json
{
"code": 200,
"message": "success",
"data": {
"items": [
{
"id": 1,
"name": "Apple",
"price": 5.00,
"category": "fruit"
}
],
"pagination": {
"page": 1,
"size": 10,
"total": 50
}
}
}
```
2. 常见错误码
| 错误码 | 含义 |
|--------|------|
| 400 | 参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器错误 |
3. 术语表
- RESTful：一种网络应用程序的设计风格和开发方式。
- JWT：JSON Web Token，一种开放标准（RFC 7519）。
- 幂等性：多次执行同一操作产生相同结果。
本规范为快驴生鲜系统API接口开发的基础标准，所有开发人员需严格遵守，并根据实际需求进行补充和完善。
广告
