Skip to content

API 概览 ​

砚考的全部接口经网关统一暴露。这份文档描述实际存在的接口,供第三方系统集成使用。

想看 Swagger

服务起来后可以直接用 SpringDoc 界面:

text
http://<网关>:8080/<服务前缀>/v3/api-docs

网关白名单里已经放行了 /*/v3/api-docs。详见 接口文档配置。

基础约定 ​

项值
协议HTTP/HTTPS
网关地址http://<host>:8080
生产反代前缀/prod-api(Nginx 剥掉前缀后转发)
数据格式application/json
字符集UTF-8

服务前缀一览 ​

前缀服务端口
/auth认证中心9210
/system、/monitor系统管理9201
/tool代码生成9202
/resource文件/OSS/短信/邮件9204
/workflow工作流9205
/question、/bank、/bankCategory、/option、/tag题库9211
/paper试卷9212
/exam、/invite考试管理9213
/answer答题(内部 /record)9214
/mark阅卷9215
/stat统计9216
/practice错题本(内部 /wrong)9217
/cert证书9218
/proctor防作弊9219
/aiAI9220

三个服务会剥掉前缀

answer、practice、proctor 三条网关路由配了 StripPrefix=1:

text
对外 /answer/record/center        → 内部 /record/center
对外 /practice/wrong/overview     → 内部 /wrong/overview
对外 /proctor/exam/list           → 内部 /exam/list

调用时用对外形式。其它服务前缀与内部路径一致。

鉴权 ​

砚考用 Sa-Token + JWT。

1. 获取验证码 ​

bash
GET /auth/code

响应:

json
{
  "captchaEnabled": true,
  "code": 200,
  "img": "data:image/png;base64,...",
  "uuid": "8f3c1a2b-..."
}

调试期可以在 Nacos 的 ruoyi-auth.yml 里把 captcha.enabled 设为 false 关掉验证码。

2. 登录 ​

bash
POST /auth/login
Content-Type: application/json

{
  "tenantId": "000000",
  "username": "admin",
  "password": "admin123",
  "rememberMe": false,
  "uuid": "<上一步的 uuid>",
  "code": "12",
  "clientId": "e5cd7e4891bf95d1d19206ce24a7b32e",
  "grantType": "password"
}

响应里拿到 access_token(在 Authorization 字段)。

3. 携带 Token ​

bash
GET /exam/list
Authorization: Bearer <access_token>

clientId 需与后端一致

clientId / grantType 必须与 sys_client 表里的一条记录匹配。 前端 .env 里的 VITE_APP_CLIENT_ID 是同一个值。

免登录白名单 ​

网关默认放行这些路径:

text
/auth/code   /auth/logout   /auth/login
/auth/binding/*   /auth/register   /auth/tenant/list
/resource/sms/code   /resource/sse/close
/*/v3/api-docs   /*/error   /csrf   /warm-flow-ui/**

配置在 ruoyi-gateway.yml 的 security.ignore.whites。 详见 网关路由与放行。

接口加密 ​

application-common.yml 默认开启 api-decrypt.enabled: true,用 RSA 对请求/响应体加解密。

场景处理
浏览器前端自动处理(.env 里的公私钥)
第三方集成建议关闭或单独协商密钥

开源仓库里的密钥是公开的

仓库内置的 RSA 密钥对等于没加密。生产必须重新生成。 详见 请求响应加解密。

调试时可以临时关掉(后端 api-decrypt.enabled: false,前端 VITE_APP_ENCRYPT=false),详见 登录调试步骤。

统一响应结构 ​

json
{
  "code": 200,
  "msg": "操作成功",
  "data": { }
}
code含义
200成功
401未认证 / Token 失效
403无权限
500服务端异常

失败时 data 通常为 null,msg 带具体原因。

分页约定 ​

列表接口统一用 query 参数:

参数说明
pageNum页码,从 1 开始
pageSize每页条数
orderByColumn排序列
isAscasc / desc
bash
GET /exam/list?pageNum=1&pageSize=20

详见 分页功能。

雪花 ID ​

所有 ID 都是 19 位雪花 ID

超过 JavaScript Number.MAX_SAFE_INTEGER(9007199254740991)。 JSON 解析时必须用字符串 / int64,否则精度丢失,查不到数据。

json
{ "examId": 1834523456789012345 }
  • Java:用 Long
  • TypeScript:用 string
  • Python:int(安全)

幂等性 ​

砚考对写操作有 防重幂等 支持。 特别是 交卷接口是幂等的——重复提交不会生成多份成绩。

接口清单 ​

分组说明
考生端接口考试中心、答题、交卷、成绩、错题本、证书
管理端接口题库、试卷、考试、阅卷、统计、证书管理
AI 接口AI 出题、预评、质检、学情归因、对话助手

常见问题 ​

相关 ​

砚考 · 让每一次考试都经得起检验