学习追踪系统

Appearance

认证接口 ​

认证接口提供用户登录、注册、密码管理等身份验证相关功能。

接口概览 ​

基础信息 ​

  • 基础路径: /api/auth
  • 认证方式: JWT Token
  • 数据格式: JSON
  • 字符编码: UTF-8

接口列表 ​

获取密码配置 ​

接口信息 ​

  • 路径: GET /api/auth/password-config
  • 描述: 获取系统密码策略配置
  • 权限: 无需认证

请求参数 ​

无需请求参数

响应结果 ​

成功响应 (200) ​

json
{
  "success": true,
  "minPasswordLength": 8
}

错误响应 (500) ​

json
{
  "success": false,
  "error": "获取密码配置失败",
  "minPasswordLength": 8
}

错误码说明 ​

状态码说明
200获取成功
500服务器内部错误

用户注册 ​

接口信息 ​

  • 路径: POST /api/auth/register
  • 描述: 创建新用户账户
  • 权限: 无需认证

请求参数 ​

请求体 ​

json
{
  "username": "string",
  "email": "string",
  "password": "string",
  "confirmPassword": "string",
  "avatar": "string (可选)"
}

参数说明 ​

参数类型必填说明
usernamestring是用户名，3-20个字符
emailstring是邮箱地址
passwordstring是密码，8-50个字符
confirmPasswordstring是确认密码
avatarstring否头像URL

响应结果 ​

成功响应 (200) ​

json
{
  "success": true,
  "message": "注册成功",
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "email": "test@example.com",
      "avatar": "https://example.com/avatar.jpg",
      "created_at": "2024-01-01T00:00:00Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

错误响应 (400) ​

json
{
  "success": false,
  "message": "用户名已存在",
  "errors": {
    "username": ["用户名已被使用"]
  }
}

错误码说明 ​

状态码说明
400请求参数错误
409用户名或邮箱已存在
500服务器内部错误

用户登录 ​

接口信息 ​

  • 路径: POST /api/auth/login
  • 描述: 用户登录获取访问令牌
  • 权限: 无需认证

请求参数 ​

请求体 ​

json
{
  "username": "string",
  "password": "string",
  "remember": "boolean (可选)"
}

参数说明 ​

参数类型必填说明
usernamestring是用户名或邮箱
passwordstring是密码
rememberboolean否记住登录状态

响应结果 ​

成功响应 (200) ​

json
{
  "success": true,
  "message": "登录成功",
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "email": "test@example.com",
      "avatar": "https://example.com/avatar.jpg",
      "role": "user",
      "last_login_at": "2024-01-01T00:00:00Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

错误响应 (401) ​

json
{
  "success": false,
  "message": "用户名或密码错误"
}

错误码说明 ​

状态码说明
400请求参数错误
401用户名或密码错误
403账户被禁用
500服务器内部错误

用户登出 ​

接口信息 ​

  • 路径: POST /api/auth/logout
  • 描述: 用户登出，清除令牌
  • 权限: 需要认证

请求参数 ​

无需请求参数

响应结果 ​

成功响应 (200) ​

json
{
  "success": true,
  "message": "登出成功"
}

刷新令牌 ​

接口信息 ​

  • 路径: POST /api/auth/refresh
  • 描述: 使用刷新令牌获取新的访问令牌
  • 权限: 无需认证

请求参数 ​

请求体 ​

json
{
  "refreshToken": "string"
}

参数说明 ​

参数类型必填说明
refreshTokenstring是刷新令牌

响应结果 ​

成功响应 (200) ​

json
{
  "success": true,
  "message": "令牌刷新成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

错误响应 (401) ​

json
{
  "success": false,
  "message": "刷新令牌无效或已过期"
}

修改密码 ​

接口信息 ​

  • 路径: PUT /api/auth/password
  • 描述: 修改用户密码
  • 权限: 需要认证

请求参数 ​

请求体 ​

json
{
  "currentPassword": "string",
  "newPassword": "string",
  "confirmPassword": "string"
}

参数说明 ​

参数类型必填说明
currentPasswordstring是当前密码
newPasswordstring是新密码
confirmPasswordstring是确认新密码

响应结果 ​

成功响应 (200) ​

json
{
  "success": true,
  "message": "密码修改成功"
}

错误响应 (400) ​

json
{
  "success": false,
  "message": "当前密码错误"
}

重置密码 ​

接口信息 ​

  • 路径: POST /api/auth/reset-password
  • 描述: 发送密码重置邮件
  • 权限: 无需认证

请求参数 ​

请求体 ​

json
{
  "email": "string"
}

参数说明 ​

参数类型必填说明
emailstring是注册邮箱地址

响应结果 ​

成功响应 (200) ​

json
{
  "success": true,
  "message": "密码重置邮件已发送"
}

重置密码确认 ​

接口信息 ​

  • 路径: POST /api/auth/reset-password/confirm
  • 描述: 确认密码重置
  • 权限: 无需认证

请求参数 ​

json
{
  "token": "string",
  "newPassword": "string",
  "confirmPassword": "string"
}

获取用户信息 ​

接口信息 ​

  • 路径: GET /api/auth/profile
  • 描述: 获取当前用户信息
  • 权限: 需要认证

请求参数 ​

无需请求参数

响应结果 ​

成功响应 (200) ​

json
{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "email": "test@example.com",
      "avatar": "https://example.com/avatar.jpg",
      "role": "user",
      "points": 1000,
      "level": 5,
      "created_at": "2024-01-01T00:00:00Z",
      "last_login_at": "2024-01-01T00:00:00Z"
    }
  }
}

更新用户信息 ​

接口信息 ​

  • 路径: PUT /api/auth/profile
  • 描述: 更新用户个人信息
  • 权限: 需要认证

请求参数 ​

请求体 ​

json
{
  "username": "string (可选)",
  "email": "string (可选)",
  "avatar": "string (可选)"
}

响应结果 ​

成功响应 (200) ​

json
{
  "success": true,
  "message": "用户信息更新成功",
  "data": {
    "user": {
      "id": 1,
      "username": "newusername",
      "email": "newemail@example.com",
      "avatar": "https://example.com/new-avatar.jpg",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  }
}

错误处理 ​

通用错误格式 ​

json
{
  "success": false,
  "message": "错误描述",
  "errors": {
    "field": ["具体错误信息"]
  }
}

常见错误码 ​

状态码说明
400请求参数错误
401未认证或认证失败
403权限不足
404资源不存在
409资源冲突
422数据验证失败
500服务器内部错误

安全说明 ​

密码安全 ​

  • 密码使用 bcrypt 加密存储
  • 密码强度要求：至少8个字符，包含字母和数字
  • 密码错误次数限制，防止暴力破解

令牌安全 ​

  • JWT 令牌有效期：7天
  • 刷新令牌有效期：30天
  • 支持令牌撤销机制

请求限制 ​

  • 登录接口：每分钟最多5次
  • 注册接口：每小时最多10次
  • 密码重置：每小时最多3次

示例代码 ​

JavaScript 示例 ​

javascript
// 用户登录
const login = async (username, password) => {
  const response = await fetch('/api/auth/login', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ username, password })
  });
  
  const data = await response.json();
  if (data.success) {
    localStorage.setItem('token', data.data.token);
    return data.data.user;
  } else {
    throw new Error(data.message);
  }
};

// 获取用户信息
const getProfile = async () => {
  const token = localStorage.getItem('token');
  const response = await fetch('/api/auth/profile', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  
  const data = await response.json();
  return data.data.user;
};

Python 示例 ​

python
import requests

# 用户登录
def login(username, password):
    response = requests.post('/api/auth/login', json={
        'username': username,
        'password': password
    })
    
    data = response.json()
    if data['success']:
        return data['data']['user'], data['data']['token']
    else:
        raise Exception(data['message'])

# 获取用户信息
def get_profile(token):
    headers = {'Authorization': f'Bearer {token}'}
    response = requests.get('/api/auth/profile', headers=headers)
    
    data = response.json()
    return data['data']['user']

Released under the MIT License.

Copyright © 2024-present Study Tracker Team