一、接口设计原则
1. RESTful风格：遵循REST架构原则，使用标准HTTP方法（GET/POST/PUT/DELETE）
2. 一致性：保持接口命名、参数格式、返回结构统一
3. 安全性：实现身份验证、权限控制和数据加密
4. 可扩展性：版本控制机制，便于后续功能迭代
5. 明确性：每个接口有清晰的功能定义和边界
二、接口规范
1. 基础规范
- 协议：HTTPS
- 域名：`api.kuailv.com`（示例）
- 版本控制：路径中包含版本号，如`/v1/`
- 超时设置：建议3-5秒
2. 请求规范
请求方法
- `GET`：获取资源
- `POST`：创建资源
- `PUT`：更新资源（全量）
- `PATCH`：更新资源（部分）
- `DELETE`：删除资源
请求头
```
Content-Type: application/json
Authorization: Bearer
Accept: application/json
X-Request-ID: <唯一请求ID>
```
请求参数
- 路径参数：`/users/{userId}`
- 查询参数：`/orders?status=paid&page=1`
- 请求体：JSON格式
3. 响应规范
成功响应
```json
{
"code": 200,
"message": "success",
"data": {
// 业务数据
},
"timestamp": 1625097600
}
```
错误响应
```json
{
"code": 400,
"message": "Invalid parameter",
"errors": [
{
"field": "username",
"message": "用户名不能为空"
}
],
"timestamp": 1625097600
}
```
状态码规范
- 200：成功
- 201：创建成功
- 400：参数错误
- 401：未授权
- 403：禁止访问
- 404：资源不存在
- 500：服务器错误
三、生鲜业务接口规范
1. 商品管理接口
商品列表查询
`GET /v1/products`
请求参数：
```
page: 页码
size: 每页数量
categoryId: 分类ID
keyword: 搜索关键词
```
响应示例：
```json
{
"code": 200,
"data": {
"list": [
{
"id": "123",
"name": "新鲜苹果",
"category": "水果",
"price": 9.9,
"stock": 100,
"unit": "500g",
"image": "https://...",
"spec": "进口红富士"
}
],
"total": 100
}
}
```
2. 订单管理接口
创建订单
`POST /v1/orders`
请求体：
```json
{
"userId": "u123",
"items": [
{
"productId": "p123",
"quantity": 2,
"price": 9.9
}
],
"addressId": "a123",
"deliveryTime": "2023-08-20 10:00-12:00"
}
```
响应：
```json
{
"code": 200,
"data": {
"orderId": "o123",
"totalAmount": 19.8,
"estimatedTime": "2023-08-20 11:30"
}
}
```
3. 库存管理接口
库存查询
`GET /v1/inventory/{productId}`
响应：
```json
{
"code": 200,
"data": {
"productId": "p123",
"stock": 50,
"locked": 5,
"available": 45,
"lastUpdate": "2023-08-15T10:30:00Z"
}
}
```
四、安全规范
1. 认证授权：
- 使用JWT进行身份验证
- 接口权限通过Scope控制
2. 数据加密：
- 敏感数据在传输和存储时加密
- 使用HTTPS协议
3. 防重放攻击：
- 请求中包含时间戳和签名
- 服务器验证请求时效性
4. 频率限制：
- 对API调用进行限流
- 不同接口可设置不同阈值
五、文档规范
1. 接口文档：
- 使用Swagger或OpenAPI规范
- 包含请求示例、响应示例、错误码说明
2. 变更记录：
- 维护接口变更历史
- 明确版本兼容性说明
3. 测试用例：
- 提供Postman集合或curl示例
- 包含正常和异常场景测试
六、错误码规范
| 错误码 | 含义 | 场景 |
|--------|------|------|
| 10001 | 参数错误 | 必填参数缺失或格式错误 |
| 10002 | 权限不足 | 调用方无权访问该资源 |
| 10003 | 资源不存在 | 查询的资源不存在 |
| 10004 | 业务冲突 | 如库存不足、订单已取消等 |
| 10005 | 系统繁忙 | 服务器暂时无法处理请求 |
七、最佳实践
1. 幂等性设计：
- 重要操作接口需支持幂等
- 使用唯一请求ID防止重复提交
2. 分页查询：
- 默认返回20条数据
- 支持page/size参数
3. 时间格式：
- 使用ISO8601标准：`YYYY-MM-DDTHH:mm:ssZ`
4. 字段命名：
- 使用小写+下划线风格
- 避免使用保留字
5. 日志记录：
- 记录完整请求响应
- 包含请求ID便于追踪
本规范应作为快驴生鲜系统API开发的基础标准，所有新接口开发需遵循此规范，已有接口应逐步迁移至新标准。
广告
