NovaStack

简体中文

English

简体中文

English

Appearance

API 端点 ​

以下是 NovaStack 项目中可用的 API 端点列表及其详细说明。

认证相关 ​

用户登录 ​

  • URL: /api/auth/login
  • 方法: POST
  • 描述: 使用用户名和密码进行登录
  • 请求体:
    json
    {
  "username": "user@example.com",
  "password": "your_password",
  "deviceId": "unique-device-id"
}
  • 响应示例:
    json
    {
  "code": 0,
  "message": "登录成功",
  "user": {
    "id": 1,
    "username": "user",
    "email": "user@example.com"
  },
  "accessToken": "access-token-value",
  "refreshToken": "refresh-token-value",
  "expiresIn": 604800
}

用户注册 ​

  • URL: /api/auth/register
  • 方法: POST
  • 描述: 创建新用户账户
  • 请求体:
    json
    {
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "securepassword"
}

刷新令牌 ​

  • URL: /api/auth/refresh
  • 方法: POST
  • 描述: 使用刷新令牌获取新的访问令牌
  • 响应示例:
    json
    {
  "code": 0,
  "message": "Refresh successful"
}

用户登出 ​

  • URL: /api/auth/logout
  • 方法: POST
  • 描述: 注销用户会话并清除认证 Cookie
  • 请求体:
    json
    {
  "deviceId": "unique-device-id"
}

获取验证码 ​

  • URL: /api/auth/captcha
  • 方法: POST
  • 描述: 获取登录验证码

用户管理 ​

获取当前用户信息 ​

  • URL: /api/user/index
  • 方法: GET
  • 描述: 获取当前登录用户的信息
  • 请求头:
    • Cookie: auth-token=<token>
  • 响应示例:
    json
    {
  "code": 0,
  "message": "用户信息获取成功",
  "data": {
    "id": 1,
    "username": "user",
    "email": "user@example.com",
    "role": "admin"
  }
}

获取用户列表 ​

  • URL: /api/user/list
  • 方法: GET
  • 描述: 获取用户列表（支持分页和搜索）
  • 请求头:
    • Cookie: auth-token=<token>
  • 查询参数:
    • page: 页码（默认: 1）
    • limit: 每页数量（默认: 10）
    • search: 搜索关键词
  • 响应示例:
    json
    {
  "code": 0,
  "message": "User list retrieved successfully",
  "data": {
    "users": [...],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 10,
      "totalPages": 10
    }
  }
}

获取用户菜单 ​

  • URL: /api/user/menus
  • 方法: GET
  • 描述: 获取当前用户的菜单权限
  • 请求头:
    • Cookie: auth-token=<token>

删除用户 ​

  • URL: /api/user/delete
  • 方法: POST
  • 描述: 删除指定用户
  • 请求头:
    • Cookie: auth-token=<token>
  • 请求体:
    json
    {
  "userId": 123
}

更新用户角色 ​

  • URL: /api/user/update-role
  • 方法: POST
  • 描述: 更新用户的角色
  • 请求头:
    • Cookie: auth-token=<token>
  • 请求体:
    json
    {
  "userId": 123,
  "roleId": 2
}

管理员功能 ​

获取所有用户 ​

  • URL: /api/admin/users
  • 方法: GET
  • 描述: 管理员获取所有用户列表
  • 请求头:
    • Cookie: auth-token=<token>

创建用户 ​

  • URL: /api/admin/users
  • 方法: POST
  • 描述: 管理员创建新用户
  • 请求头:
    • Cookie: auth-token=<token>
  • 请求体:
    json
    {
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "securepassword",
  "role": "user"
}

获取角色列表 ​

  • URL: /api/admin/roles
  • 方法: GET
  • 描述: 获取所有角色列表
  • 请求头:
    • Cookie: auth-token=<token>

创建角色 ​

  • URL: /api/admin/roles.create
  • 方法: POST
  • 描述: 创建新的角色
  • 请求头:
    • Cookie: auth-token=<token>
  • 请求体:
    json
    {
  "name": "editor",
  "description": "Editor role"
}

分配角色 ​

  • URL: /api/admin/assign-role
  • 方法: POST
  • 描述: 为用户分配角色
  • 请求头:
    • Cookie: auth-token=<token>
  • 请求体:
    json
    {
  "userId": 123,
  "roleId": 2
}

获取菜单列表 ​

  • URL: /api/admin/menus
  • 方法: GET
  • 描述: 获取系统菜单列表
  • 请求头:
    • Cookie: auth-token=<token>

统一响应格式 ​

所有 API 响应遵循以下格式：

json
{
  "code": 0,
  "message": "success",
  "data": {}
}
  • code: 0 - 表示成功
  • code !== 0 - 表示业务错误

错误处理 ​

状态码描述
200请求成功完成
400请求有误，服务器无法处理
401身份验证失败
403禁止访问
404请求的资源不存在
500内部服务器错误

认证说明 ​

NovaStack 使用 Cookie 和令牌结合的认证机制：

  1. 登录成功后，系统会设置以下 Cookie：

    • auth-token: 访问令牌（30分钟有效期）
    • refresh-token: 刷新令牌（7天有效期）
    • isAuth: 认证状态标识

  2. 大多数 API 请求会自动从 Cookie 中读取认证信息

  3. 如果访问令牌过期，系统会自动使用刷新令牌获取新的访问令牌

  4. 如果刷新令牌也失效，用户需要重新登录

注意事项 ​

  1. 所有受保护的 API 端点都需要有效的认证令牌
  2. 用户密码等敏感信息应通过 HTTPS 传输
  3. 令牌过期后，系统会自动尝试刷新
  4. 管理员功能需要相应的权限才能访问
  5. 分页参数从 1 开始计数