API 文档#

Base URL: http://localhost:8080 (开发环境) Production: https://waterball.yorukaru.com (生产环境)

认证#

大部分 API 需要在请求头中携带 JWT Token：

Authorization: Bearer <your-jwt-token>

API 端点列表#

认证相关#

注册#

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123",
  "name": "张三"
}

响应:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "张三",
    "level": 1,
    "exp": 0
  }
}

登录#

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

{
  "email": "user@example.com",
  "password": "password123"
}

Google OAuth 登录#

POST /api/auth/google
Content-Type: application/json

{
  "token": "<google-oauth-token>"
}

用户相关#

获取当前用户信息#

GET /api/users/me
Authorization: Bearer <token>

响应:

{
  "id": 1,
  "email": "user@example.com",
  "name": "张三",
  "level": 5,
  "exp": 1200,
  "title": "初级工程师",
  "avatarUrl": "https://..."
}

获取用户详情#

GET /api/users/{id}
Authorization: Bearer <token>

课程相关#

获取课程列表#

GET /api/courses

响应:

[
  {
    "id": 1,
    "name": "软件设计模式精通之旅",
    "description": "深入学习设计模式",
    "instructor": "水球潘",
    "price": 3000,
    "studentCount": 1234,
    "missionCount": 45,
    "imageUrl": "https://...",
    "isEnrolled": true
  }
]

获取课程详情#

GET /api/courses/{id}

响应:

{
  "id": 1,
  "name": "软件设计模式精通之旅",
  "chapters": [
    {
      "id": 1,
      "title": "第一章：设计模式基础",
      "orderIndex": 0,
      "missions": [
        {
          "id": 1,
          "title": "什么是设计模式",
          "type": "VIDEO",
          "duration": 1200,
          "exp": 100,
          "isFreePreview": true
        }
      ]
    }
  ]
}

课程报名#

报名课程#

POST /api/enrollments/{courseId}
Authorization: Bearer <token>

检查报名状态#

GET /api/enrollments/check/{courseId}
Authorization: Bearer <token>

获取我的课程#

GET /api/enrollments
Authorization: Bearer <token>

任务相关#

获取任务详情#

GET /api/missions/{id}
Authorization: Bearer <token>

响应:

{
  "id": 1,
  "title": "什么是设计模式",
  "type": "VIDEO",
  "content": "https://youtube.com/watch?v=...",
  "duration": 1200,
  "exp": 100,
  "userProgress": {
    "lastWatchedPosition": 300,
    "completionPercentage": 25.0,
    "rewardClaimed": false
  }
}

更新观看进度#

POST /api/missions/{id}/progress
Authorization: Bearer <token>
Content-Type: application/json

{
  "watchedPosition": 600,
  "videoDuration": 1200
}

领取任务奖励#

POST /api/missions/{id}/claim
Authorization: Bearer <token>

响应:

{
  "expGained": 100,
  "newTotalExp": 1300,
  "oldLevel": 5,
  "newLevel": 6,
  "leveledUp": true
}

排行榜#

获取排行榜#

GET /api/leaderboard

响应:

[
  {
    "rank": 1,
    "userId": 1,
    "name": "Elliot",
    "title": "初级工程师",
    "level": 19,
    "exp": 31040,
    "avatarUrl": "https://..."
  }
]

获取我的排名#

GET /api/leaderboard/me
Authorization: Bearer <token>

错误码#

状态码	说明
200	请求成功
201	创建成功
400	请求参数错误
401	未认证
403	无权限
404	资源不存在
500	服务器错误

开发工具#

推荐使用以下工具测试 API：

Postman - 图形化 API 测试
curl - 命令行测试
Swagger UI - 交互式文档（规划中）