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