首页 › API 参考 › 接口概览
API 参考

API 接口概览

EduBuddy 后端提供标准的 RESTful API，所有接口返回 JSON 格式数据。Base URL 为 http://localhost:3001/api（开发环境）。

认证方式

除登录和注册接口外，所有 API 均需要在请求头中携带 JWT Token：

Authorization: Bearer <your-jwt-token>

Token 在登录/注册时由服务端签发，有效期 7 天。Token 过期或无效时，接口返回 401 Unauthorized。

统一响应格式

成功响应

{
  "success": true,
  "message": "操作成功",    // 可选
  "data": { ... }           // 具体数据
}

错误响应

{
  "success": false,
  "message": "错误描述信息"
}

HTTP 状态码规范

状态码含义常见场景
200成功查询、更新操作成功
201创建成功注册用户、创建题目/路线等
400请求参数错误必填项缺失、格式不正确
401未认证Token 缺失、无效或过期
403无权限修改/删除他人资源
404资源不存在指定 ID 的题目/路线不存在
409冲突用户名/邮箱已存在
413文件过大上传文件超过 10MB
429速率限制请求过于频繁
500服务器错误数据库错误、AI 调用失败

速率限制

接口范围限制
所有 /api/* 接口200 次 / 15 分钟（每 IP）
POST /api/questions/generate20 次 / 分钟（每 IP）
POST /api/questions/:id/solve20 次 / 分钟
POST /api/progress/analyze20 次 / 分钟
POST /api/learning-paths/generate20 次 / 分钟

接口总览

认证模块 /api/auth

方法路径说明需认证
POST/auth/register用户注册否
POST/auth/login用户登录否
GET/auth/me获取当前用户信息是
PUT/auth/profile更新用户资料是
PUT/auth/password修改密码是
GET/auth/users获取用户列表是

题目模块 /api/questions

方法路径说明AI
GET/questions获取题目列表（支持筛选分页）否
GET/questions/:id获取单道题目详情否
POST/questions手动创建题目否
POST/questions/generateAI 生成题目✅
POST/questions/extract从文本提取题目✅
POST/questions/:id/solveAI 解题✅
POST/questions/:id/submit提交答案（AI 批改）✅
PUT/questions/:id更新题目否
DELETE/questions/:id删除题目否

进度模块 /api/progress

方法路径说明AI
GET/progress/summary获取学习统计摘要否
GET/progress/mastery获取知识点掌握度（雷达图数据）否
GET/progress/daily-stats获取每日学习统计（折线图数据）否
GET/progress/practice-records获取练习记录列表否
GET/progress/weaknesses获取薄弱知识点列表否
GET/progress/subject-distribution获取学科分布（饼图数据）否
POST/progress/analyzeAI 分析薄弱环节并生成建议✅
POST/progress/assessment-reportAI 生成评估报告✅
GET/progress/suggestions获取学习建议列表否
PUT/progress/suggestions/:id/read标记建议已读否
GET/progress/goals获取学习目标列表否
POST/progress/goals创建学习目标否
PUT/progress/goals/:id更新学习目标进度否

学习路线模块 /api/learning-paths

方法路径说明AI
GET/learning-paths获取学习路线列表否
GET/learning-paths/:id获取路线详情（含节点）否
POST/learning-paths手动创建路线否
POST/learning-paths/generateAI 生成学习路线✅
POST/learning-paths/:id/enroll报名加入路线否
PUT/learning-paths/:id/progress更新学习进度否
GET/learning-paths/my/enrolled获取我已报名的路线否
POST/learning-paths/:id/nodes添加路线节点否

文件上传模块 /api/upload

方法路径说明
POST/upload/pdf上传 PDF 并提取题目
POST/upload/image上传图片（OCR 识别题目）
POST/upload/audio上传音频（语音转文字）
POST/upload/text直接提交文本提取题目
GET/upload/history获取上传记录

分享模块 /api/sharing

方法路径说明
POST/sharing发送分享
GET/sharing/received获取收到的分享
GET/sharing/sent获取我发出的分享
PUT/sharing/:id/read标记分享已读
GET/sharing/unread-count获取未读分享数量

健康检查

GET /health — 无需认证，检查服务是否正常运行 
// 响应示例
{
  "status": "ok",
  "timestamp": "2024-01-15T08:30:00.000Z",
  "version": "1.0.0",
  "service": "AI学生帮手后端"
}