42 lines
1.2 KiB
Markdown
42 lines
1.2 KiB
Markdown
|
# 接口约定与返回规范
|
|||
|
|
|
|||
|
|
## 1. 目标
|
|||
|
|
统一前后端接口风格，降低多端协作成本，并为后续生成 OpenAPI 文档提供基础约束。
|
|||
|
|
|
|||
|
|
## 2. 通用约定
|
|||
|
|
- 协议：HTTPS
|
|||
|
|
- 数据格式：`application/json`
|
|||
|
|
- 时间字段：统一使用 ISO 8601 或毫秒时间戳（待最终确定）
|
|||
|
|
- 分页参数建议：`page`、`pageSize`
|
|||
|
|
|
|||
|
|
## 3. 推荐返回结构
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 0,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {},
|
|||
|
|
"requestId": "string"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 4. 错误码建议
|
|||
|
|
| code | 含义 |
|
|||
|
|
| --- | --- |
|
|||
|
|
| 0 | 成功 |
|
|||
|
|
| 40001 | 参数错误 |
|
|||
|
|
| 40101 | 未登录或登录失效 |
|
|||
|
|
| 40301 | 无权限访问 |
|
|||
|
|
| 40401 | 资源不存在 |
|
|||
|
|
| 40901 | 状态冲突 |
|
|||
|
|
| 50001 | 系统异常 |
|
|||
|
|
|
|||
|
|
## 5. 接口分类建议
|
|||
|
|
- 用户端接口：登录、赛事列表、赛事详情、报名、支付、我的报名、成绩查询
|
|||
|
|
- 商户端接口：商户资料、赛事管理、报名管理、成绩录入、数据导出
|
|||
|
|
- 管理端接口：商户审核、赛事审核、用户管理、报表统计
|
|||
|
|
|
|||
|
|
## 6. 设计要求
|
|||
|
|
- 所有写接口必须记录操作人。
|
|||
|
|
- 支付回调、退款回调类接口必须保证幂等。
|
|||
|
|
- 涉及列表查询的接口需明确筛选条件和排序规则。
|