Skip to main content

API 接口规范

本页仅描述 公共约定（统一响应、错误码、认证方式、分页规则等）。全部接口清单 请直接查看线上 Swagger 文档。

1️⃣ 基础信息​

端点类别前缀说明
公共问卷/survey/*匿名、授权登陆答题等前台接口
管理后台/admin-api/*RBAC 保护，后台管理功能
其他功能/admin-api/*工具类或其它后台接口

无版本号路径，以 Swagger/OpenAPI 控制兼容。

2️⃣ 统一响应结构​

所有接口统一返回 CommonResult<T>：

{
  "code": 0,
  "data": {},
  "msg": "" // 业务提示，成功时通常为空
}
  • code = 0 表示成功，非 0 表示失败。
  • data 为业务数据，类型由接口决定。
  • msg 为给前端展示的文本。

分页接口额外使用

{
  "code": 0,
  "data": {
    "list": [],
    "total": 123
  },
  "msg": ""
}

3️⃣ 错误码​

核心错误码来自 GlobalErrorCodeConstants：

code含义
0成功
400请求参数错误
401未认证 / Token 失效
403无权限
404资源不存在
405方法不被允许
423请求被锁定（并发、乐观锁等）
429过于频繁的请求
500系统异常
900重复请求
901Demo 环境禁止写
999未知错误

业务模块可追加自定义错误码，保持 唯一、不可重复。

4️⃣ 认证与授权​

4.1 OAuth2​

后台接口采用 OAuth2 (password / refresh_token / client_credentials 等) 颁发访问令牌。

POST /admin-api/oauth2/token
Authorization: Basic <clientId:clientSecret base64>
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=admin&password=123456

成功返回

{
  "code": 0,
  "data": {
    "access_token": "eyJraWQiOi...",
    "expires_in": 86400,
    "refresh_token": "...",
    "token_type": "bearer"
  },
  "msg": ""
}

调用后台其它接口时携带

Authorization: Bearer <access_token>

前台 /survey/* 接口无需登录，但部分接口支持 OAuth2 Social Login（详见 Swagger > SurveyController）。

4.2 RBAC​

后台服务使用 Spring Security + @PreAuthorize 注解实现 基于资源的权限检查，权限点格式 模块:资源:动作，例如 system:user:create。

5️⃣ 常用约定​

  1. 幂等性：除 GET/HEAD 外，一律通过 雪花 ID + 乐观锁 保证。
  2. 时间格式：请求与响应均使用 ISO-8601，示例 2025-07-04T12:00:00Z。
  3. 文件上传：使用 multipart/form-data，字段名 file。示例接口：/survey/upload。
  4. 长任务：异步导出/统计任务返回 任务编号，轮询 /admin-api/task/get 获取进度，完成后返回下载地址。

6️⃣ 分页、排序、筛选​

后台列表接口统一使用（以用户分页为例）：

GET /admin-api/user/page?pageNo=1&pageSize=20&sort=createdTime_desc&username=tom
参数必填说明
pageNo否页码，默认 1
pageSize否每页大小，默认 20，最大 200
sort否字段名_asc 或 字段名_desc，可多个逗号分隔
其它业务字段否直接作为筛选条件

返回结构见 2️⃣ 分页示例。

7️⃣ 开发规范​

  • Bean Validation：DTO 加 @Valid，配合全局异常处理自动转换为 code=400。
  • 日志：所有写操作默认记录 @OperateLog，包含耗时、入参、结果。
  • 监控：接口指标通过 Micrometer + Prometheus 导出，主要监控 RT、QPS、错误率。
  • 限流：热点接口可加 @RateLimiter，超限返回 code=429。

📚 详细接口请阅读 线上 Swagger 文档，或在本地 server 模块运行后访问 本地 Swagger 页面。

Last updated on