更新记录

1.0.0（2026-10-23） 下载此版本

初版

平台兼容性

其他

在线试卷 — 后端数据接口说明

本文档定义了前端页面期望的 返回数据格式，后端同学按照以下结构返回即可直接渲染。 核心原则：一个接口返回全部试卷信息，前端不做二次组装。

一、接口概览

标准响应包装

{
  "code": 200,
  "message": "success",
  "data": { /* 试卷完整数据，见下方结构 */ }
}

若你们项目使用其他包装（如 ret / success），保持你们既有的外层即可，data 内部结构必须严格对齐下文。

二、data 顶层结构

{
  "examInfo":       { /* 考试基础信息 */ },
  "questionGroups": [ /* 大题数组 */ ]
}

三、examInfo 字段详解

"examInfo": {
  "title":            "2026 年度前端工程师专业能力认证考试",  // 考试标题（页面大字标题）
  "duration":         "考试时间 120 分钟",                    // 文案描述（纯展示用）
  "durationMinutes":  120,                                   // ⏱ 考试时长（单位：分钟，**用于倒计时计算**）
  "totalScore":       100,                                   // 试卷总分
  "studentName":      "张三",                                // 学生姓名（可为空字符串）
  "rules": [                                                 // 考试守则数组，每条独立一行
    "考生须在规定时间内完成所有题目，超时将自动提交。",
    "请确保网络连接稳定，答题过程中请勿刷新页面。"
  ]
}

⚠️ 重要：倒计时从 durationMinutes × 60 秒开始倒数，不要把秒数直接塞进来。

四、questionGroups 大题数组

"questionGroups": [
  {
    "id":       "g1",                          // 大题唯一标识（字符串）
    "title":    "一、单项选择题",               // 大题标题
    "score":    30,                            // 本大题总分
    "questions": [ /* 本大题下的小题数组 */ ]
  }
]

五、小题通用字段（questions 内每一项）

{
  "id":          "q1",          // 小题唯一标识（整个试卷内不重复）
  "type":        "single",      // 题型枚举，见下表
  "score":       5,             // 本题分值
  "description": "题干内容..."   // 题目描述（支持纯文本）
}

type 枚举表

六、各题型完整示例

1）单选题 type: "single"

{
  "id":          "q1",
  "type":        "single",
  "score":       5,
  "description": "以下哪个是 JavaScript 中的基本数据类型？",
  "options": [
    { "key": "A", "value": "Array"    },
    { "key": "B", "value": "Object"   },
    { "key": "C", "value": "Symbol"   },
    { "key": "D", "value": "Function" }
  ]
}

2）多选题 type: "multiple"

{
  "id":          "q7",
  "type":        "multiple",
  "score":       10,
  "description": "以下哪些是 JavaScript 中声明变量的关键字？（多选）",
  "options": [
    { "key": "A", "value": "var"    },
    { "key": "B", "value": "let"    },
    { "key": "C", "value": "const"  },
    { "key": "D", "value": "define" }
  ]
}

options 结构与单选题完全相同，前端自动根据 type 切换为 checkbox 交互。

3）判断题 type: "judge"

{
  "id":          "q9",
  "type":        "judge",
  "score":       5,
  "description": "JavaScript 中，typeof null 的返回值是 \"object\"。"
}

⚠️ 不需要 options 字段。前端固定渲染「✓ 正确 / ✕ 错误」两个按钮，用户答案为 "T" 或 "F"。

4）简答题 type: "shortAnswer"

{
  "id":          "q11",
  "type":        "shortAnswer",
  "score":       10,
  "description": "请简述浏览器从输入 URL 到页面渲染完成的主要过程。"
}

⚠️ 不需要 options 字段。前端渲染一个 textarea（500 字上限）。

5）写作题 type: "writing"

{
  "id":          "q13",
  "type":        "writing",
  "score":       20,
  "description": "结合你的实际开发经验，以\"如何构建一个高性能的 Web 应用\"为主题，写一篇不少于 300 字的短文。"
}

⚠️ 不需要 options 字段。前端渲染大尺寸 textarea（2000 字上限）。

七、完整返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "examInfo": {
      "title":           "2026 年度前端工程师专业能力认证考试",
      "duration":        "考试时间 120 分钟",
      "durationMinutes": 120,
      "totalScore":      100,
      "studentName":     "张三",
      "rules": [
        "考生须在规定时间内完成所有题目，超时将自动提交。",
        "请确保网络连接稳定，答题过程中请勿刷新页面。"
      ]
    },
    "questionGroups": [
      {
        "id":    "g1",
        "title": "一、单项选择题",
        "score": 30,
        "questions": [
          {
            "id":          "q1",
            "type":        "single",
            "score":       5,
            "description": "以下哪个是 JavaScript 中的基本数据类型？",
            "options": [
              { "key": "A", "value": "Array"    },
              { "key": "B", "value": "Object"   },
              { "key": "C", "value": "Symbol"   },
              { "key": "D", "value": "Function" }
            ]
          }
        ]
      },
      {
        "id":    "g2",
        "title": "二、判断题",
        "score": 10,
        "questions": [
          {
            "id":          "q9",
            "type":        "judge",
            "score":       5,
            "description": "JavaScript 中，typeof null 的返回值是 \"object\"。"
          }
        ]
      },
      {
        "id":    "g3",
        "title": "三、简答题",
        "score": 20,
        "questions": [
          {
            "id":          "q11",
            "type":        "shortAnswer",
            "score":       10,
            "description": "请简述浏览器从输入 URL 到页面渲染完成的主要过程。"
          }
        ]
      }
    ]
  }
}

八、前端提交答案格式（后端接收参考）

前端提交 POST /api/exam/submit 时，data 结构如下：

{
  "examInfo": {
    "title":           "2026 年度前端工程师专业能力认证考试",
    "durationMinutes": 120,
    "totalScore":      100
  },
  "answers": {
    "q1":  "C",              // 单选：单个 key
    "q7":  ["A", "B", "C"],  // 多选：key 数组
    "q9":  "T",              // 判断：T / F
    "q11": "浏览器渲染过程..." // 简答 / 写作：文本
  }
}

九、Review 答卷详情模式（后端额外字段）

前端通过 URL 参数切换模式：

9.1 每个小题需额外返回（仅 review 模式下必须）

{
  "id":          "q1",
  "type":        "single",
  "score":       5,
  "description": "...",
  // === 以下字段 review 模式必带 ===
  "correctAnswer": "C",        // 正确答案
  "analysis":      "解析文本..."  // 答案解析
}

correctAnswer 按题型取值

9.2 data 顶层额外返回学生答卷（仅 review 模式）

{
  "examInfo":       { ... },
  "questionGroups":  [ ... ],
  // ========== review 模式额外字段 ==========
  "userAnswers": {
    "q1":  "C",             // 单选：单个 key
    "q2":  null,            // 未答：null 或 ''
    "q7":  ["A", "B"],      // 多选：key 数组
    "q9":  "T",             // 判断：T / F
    "q11": "用户写的内容...", // 简答/写作：文本
    "q13": ""               // 未答：''
  }
}

userAnswers 以小题 id 为 key，前端直接合并进 userAnswers 状态对象。 如果 exam 模式接口不想改，也可以用两个接口：/exam/detail（exam 用）和 /exam/review（review 用，多返回 userAnswers + 每题的 correctAnswer/analysis）。

9.3 前端判分规则（供后端参考，也可后端判分后直接返回 score）

9.4 examInfo 在 review 模式下可额外带

"examInfo": {
  // ...原有字段...
  "score": 85  // 学生得分，review 模式显示在头部
}

十、后端实现注意事项

1. id 全局唯一：大题 id（g1）和小题 id（q1）建议使用数据库主键或雪花 id，不要用前端临时编号，方便与后端题目表关联。
2. durationMinutes 为倒计时唯一来源：请勿只返回 "02:00:00" 这样的格式化字符串，前端拿不到分钟数。
3. 可选类型严格区分：
   • single / multiple 必须带 options
   • judge / shortAnswer / writing 不要带 options（带了也会被前端忽略）
4. 分数校验（可选）：建议后端校验 sum(questionGroups.score) === examInfo.totalScore，不一致时打 warning。
5. 题目顺序：前端按 questionGroups 数组顺序 + 每个大题内 questions 数组顺序渲染，后端请按照试卷编排顺序返回。