跳到主要内容

认证 API

用户认证相关接口，包括注册、登录和登出。

基础信息​

基础路径: /api/v1/auth
认证要求: 仅 /logout 需要 Token
响应格式: Result<T>

POST /api/v1/auth/register​

用户注册接口

请求​

URL: POST /api/v1/auth/register
认证: ❌ 公开接口
Content-Type: application/json

请求体 (RegisterDTO):

字段类型必填说明验证规则
usernameString✅用户名3-20个字符，字母数字下划线
passwordString✅密码8-20个字符，包含大小写字母和数字
emailString✅邮箱有效的邮箱格式
nicknameString❌昵称最多30个字符

响应​

成功 (HTTP 200):

{
  "code": 0,
  "message": "Success",
  "data": {
    "id": 1,
    "username": "newuser",
    "email": "new@example.com",
    "nickname": "New User",
    "status": 1,
    "createdAt": "2025-12-10T14:30:00"
  }
}

失败场景:

Code消息原因
400用户名已存在username 重复
400邮箱已被注册email 重复
400参数验证失败DTO 验证不通过

示例​

curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "Password123!",
    "email": "test@example.com",
    "nickname": "Test User"
  }'

POST /api/v1/auth/login​

用户登录接口

请求​

URL: POST /api/v1/auth/login
认证: ❌ 公开接口
Content-Type: application/json

请求体 (LoginDTO):

字段类型必填说明
usernameString✅用户名或邮箱
passwordString✅密码

响应​

成功 (HTTP 200):

{
  "code": 0,
  "message": "Success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMTIzIiwiaWF0IjoxNzAyMTk...",
    "tokenType": "Bearer",
    "expiresIn": 7200,
    "user": {
      "id": 1,
      "username": "testuser",
      "email": "test@example.com",
      "nickname": "Test User",
      "roles": ["USER"]
    }
  }
}

响应字段说明:

字段说明
tokenJWT Token，用于后续API认证
tokenTypeToken类型，固定为 "Bearer"
expiresInToken有效期（秒），默认7200（2小时）
user用户基本信息

失败场景:

Code消息原因
401用户名或密码错误凭证不匹配
401账号已被禁用user.status = 0

示例​

# 使用用户名登录
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "Password123!"
  }'

# 使用邮箱登录
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "test@example.com",
    "password": "Password123!"
  }'

POST /api/v1/auth/logout​

用户登出接口

请求​

URL: POST /api/v1/auth/logout
认证: ✅ 需要 JWT Token
Content-Type: application/json

请求头:

Authorization: Bearer {token}

响应​

成功 (HTTP 200):

{
  "code": 0,
  "message": "Success",
  "data": null
}

说明​

⚠️ 重要提示: 由于 JWT 是无状态的，登出主要由客户端删除 Token 实现。

此接口仅用于：

  • 记录登出日志
  • 未来可扩展为 Token 黑名单机制

示例​

curl -X POST http://localhost:8080/api/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

使用流程​

graph TD
    A[客户端] -->|1. 注册| B[POST /auth/register]
    B -->|返回 UserVO| C[注册成功]
    
    C -->|2. 登录| D[POST /auth/login]
    D -->|返回 Token| E[保存 Token 到本地]
    
    E -->|3. 访问受保护API| F[添加 Authorization Header]
    F -->|携带 Token| G[访问 /api/**]
    
    G -->|Token过期| H[POST /auth/login]
    H -->|刷新 Token| E
    
    G -->|4. 登出| I[POST /auth/logout]
    I -->|删除本地 Token| J[登出成功]

安全建议​

  1. HTTPS: 生产环境必须使用 HTTPS 传输
  2. Token 存储:
    • Web: 存储在 httpOnly Cookie 或 sessionStorage
    • 移动端: 存储在安全的 Keychain/Keystore
  3. Token 过期: 默认 2 小时，可配置
  4. 密码强度: 前端应验证密码强度
  5. 防暴力破解: 建议实现登录失败限流

相关文档​