Archived

This repository has been archived on 2026-04-05. You can view files and clone it. You cannot open issues or pull requests or push a commit.

Files

bisnsh 3d1d4cf506 init

2026-03-20 21:41:00 +08:00

9.2 KiB

Raw Permalink Blame History

API 接口测试文档

基础信息

Base URL: http://localhost:8080/api
认证方式: JWT Bearer Token
请求格式: JSON (Content-Type: application/json)

认证接口

1. 用户登录

接口: POST /login

请求参数:

{
  "username": "admin",
  "password": "admin123"
}

响应示例:

{
  "code": 200,
  "msg": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

说明:

登录成功后返回 JWT Token
Token 有效期 24 小时（可在配置文件中修改）
后续请求需在 Header 中携带：Authorization: Bearer {token}

2. 用户注册

接口: POST /register

请求参数:

{
  "username": "testuser",
  "password": "123456",
  "real_name": "张三",
  "id_card": "110101199001011234",
  "email": "test@example.com",
  "phone": "13800138000"
}

响应示例:

{
  "code": 200,
  "msg": "success",
  "data": null
}

考试管理接口

3. 获取考试列表

接口: GET /exams

请求参数:

page=1&pageSize=10

响应示例:

{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "title": "2024 年春季英语等级考试",
        "code": "ENG-2024-001",
        "subject": "英语",
        "exam_location": "北京市朝阳区考试中心",
        "exam_fee": 150.00,
        "max_candidates": 500,
        "status": 1,
        "start_time": "2024-04-15T09:00:00Z",
        "end_time": "2024-04-15T11:00:00Z"
      }
    ],
    "total": 10,
    "page": 1,
    "pageSize": 10
  }
}

4. 获取考试详情

接口: GET /exams/:id

响应示例:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "title": "2024 年春季英语等级考试",
    "description": "本次考试为英语等级考试...",
    "start_time": "2024-04-15T09:00:00Z",
    "end_time": "2024-04-15T11:00:00Z",
    "registration_start": "2024-03-01T00:00:00Z",
    "registration_end": "2024-04-01T23:59:59Z",
    "max_candidates": 500,
    "exam_fee": 150.00,
    "exam_location": "北京市朝阳区考试中心",
    "subject": "英语",
    "status": 1
  }
}

5. 创建考试（需管理员权限）

接口: POST /exams

Header: Authorization: Bearer {token}

请求参数:

{
  "title": "2024 年夏季数学竞赛",
  "code": "MATH-2024-001",
  "description": "全市高中数学竞赛",
  "start_time": "2024-07-15 09:00:00",
  "end_time": "2024-07-15 12:00:00",
  "registration_start": "2024-06-01 00:00:00",
  "registration_end": "2024-07-01 23:59:59",
  "max_candidates": 300,
  "exam_fee": 100.00,
  "exam_location": "北京市第一中學",
  "subject": "数学"
}

6. 更新考试

接口: PUT /exams/:id

请求参数:

{
  "title": "更新的考试名称",
  "max_candidates": 400
}

7. 删除考试

接口: DELETE /exams/:id

响应: 删除成功返回空数据

报名管理接口

8. 创建报名

接口: POST /registrations

Header: Authorization: Bearer {token}

请求参数:

{
  "exam_id": 1,
  "remark": "首次参加，请多关照"
}

响应示例:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "user_id": 2,
    "exam_id": 1,
    "status": 0,
    "payment_status": 0,
    "remark": "首次参加，请多关照"
  }
}

状态码说明:

0: 待审核
1: 已通过
2: 已拒绝
3: 已取消

9. 获取报名列表

接口: GET /registrations

请求参数:

user_id=2&exam_id=1&page=1&pageSize=10&status=0

响应示例:

{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "user_id": 2,
        "exam_id": 1,
        "status": 1,
        "payment_status": 1,
        "ticket_number": "TKT11712345678",
        "exam_seat": "A-001",
        "audit_comment": "审核通过",
        "user": {
          "username": "testuser",
          "real_name": "张三"
        },
        "exam": {
          "title": "2024 年春季英语等级考试",
          "code": "ENG-2024-001"
        }
      }
    ],
    "total": 1
  }
}

10. 审核报名（管理员）

接口: PUT /registrations/:id/audit

请求参数:

{
  "status": 1,
  "comment": "审核通过，请按时参加考试"
}

说明:

status: 1-通过，2-拒绝
comment: 审核意见

11. 更新报名信息

接口: PUT /registrations/:id

请求参数:

{
  "remark": "更新备注信息"
}

12. 取消报名

接口: DELETE /registrations/:id

考试通知接口

13. 获取通知列表

接口: GET /notices

请求参数:

exam_id=1&page=1&pageSize=10

响应示例:

{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "exam_id": 1,
        "title": "关于考试时间的通知",
        "content": "原定于...",
        "type": 2,
        "publish_time": "2024-03-15T10:00:00Z"
      }
    ],
    "total": 5
  }
}

通知类型:

1: 普通通知
2: 重要通知
3: 紧急通知

14. 创建通知（管理员）

接口: POST /notices

请求参数:

{
  "exam_id": 1,
  "title": "考场规则说明",
  "content": "考生须知...",
  "type": 1
}

成绩管理接口

15. 录入成绩（管理员）

接口: POST /scores

请求参数:

{
  "user_id": 2,
  "exam_id": 1,
  "score": 85.5,
  "total_score": 100,
  "remark": "成绩优秀"
}

响应示例:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "user_id": 2,
    "exam_id": 1,
    "score": 85.5,
    "total_score": 100,
    "pass": true,
    "rank": 0,
    "published": false
  }
}

16. 批量录入成绩（管理员）

接口: POST /scores/batch

请求参数:

[
  {
    "user_id": 2,
    "score": 85.5,
    "total_score": 100
  },
  {
    "user_id": 3,
    "score": 92.0,
    "total_score": 100
  }
]

说明:

exam_id 从查询参数或当前上下文中获取
自动计算是否及格（>=60 分）

17. 查询个人成绩

接口: GET /scores/exam/:exam_id

响应示例:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "user_id": 2,
    "exam_id": 1,
    "score": 85.5,
    "total_score": 100,
    "pass": true,
    "rank": 5,
    "published": true
  }
}

18. 获取成绩列表（管理员）

接口: GET /scores

请求参数:

exam_id=1&page=1&pageSize=10

响应示例:

{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "user_id": 2,
        "exam_id": 1,
        "score": 85.5,
        "total_score": 100,
        "pass": true,
        "rank": 1,
        "published": true,
        "user": {
          "username": "testuser",
          "real_name": "张三"
        }
      }
    ],
    "total": 50
  }
}

19. 发布成绩（管理员）

接口: PUT /scores/:id/publish

说明: 发布后学生才能查看成绩

20. 删除成绩

接口: DELETE /scores/:id

用户信息接口

21. 获取当前用户信息

接口: GET /user/info

Header: Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 2,
    "username": "testuser",
    "real_name": "张三",
    "email": "test@example.com",
    "phone": "13800138000",
    "role": "user",
    "status": 1
  }
}

22. 更新用户信息

接口: PUT /user/info

请求参数:

{
  "real_name": "李四",
  "email": "lisi@example.com",
  "phone": "13900139000"
}

错误码说明

错误码	说明
200	成功
400	请求参数错误
401	未授权（Token 无效或过期）
403	无权限
404	资源不存在
500	服务器内部错误

Postman 使用示例

1. 设置环境变量

在 Postman 中设置环境变量：

base_url: http://localhost:8080
token: {{login 后自动填充}}

2. Pre-request Script

在 Collection 的 Pre-request Script 中添加：

// 自动添加 Token
pm.request.headers.add({
  key: 'Authorization',
  value: 'Bearer ' + pm.environment.get('token')
});

3. Test Scripts

在登录接口的 Tests 中添加：

// 自动保存 Token
var jsonData = pm.response.json();
if (jsonData.code === 200) {
  pm.environment.set('token', jsonData.data.token);
}

cURL 测试示例

获取考试列表

curl -X GET "http://localhost:8080/api/exams?page=1&pageSize=10"

创建考试（需要 Token）

curl -X POST http://localhost:8080/api/exams \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "title": "测试考试",
    "code": "TEST-001",
    "start_time": "2024-05-01 09:00:00",
    "end_time": "2024-05-01 11:00:00"
  }'

文档版本: v1.0
最后更新: 2024-03-20

9.2 KiB Raw Permalink Blame History Unescape Escape

API 接口测试文档

基础信息

认证接口

1. 用户登录

2. 用户注册

考试管理接口

3. 获取考试列表

4. 获取考试详情

5. 创建考试（需管理员权限）

6. 更新考试

7. 删除考试

报名管理接口

8. 创建报名

9. 获取报名列表

10. 审核报名（管理员）

11. 更新报名信息

12. 取消报名

考试通知接口

13. 获取通知列表

14. 创建通知（管理员）

成绩管理接口

15. 录入成绩（管理员）

16. 批量录入成绩（管理员）

17. 查询个人成绩

18. 获取成绩列表（管理员）

19. 发布成绩（管理员）

20. 删除成绩

用户信息接口

21. 获取当前用户信息

22. 更新用户信息

错误码说明

Postman 使用示例

1. 设置环境变量

2. Pre-request Script

3. Test Scripts

cURL 测试示例

登录

获取考试列表

创建考试（需要 Token）

9.2 KiB

Raw Permalink Blame History