认证 API

基础路径: /api/v1/auth

---

POST /register

用户注册

请求

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"
  }'

请求参数

字段	类型	必填	说明
username	String	✅	3-20字符，字母数字下划线
password	String	✅	8-20字符，含大小写和数字
email	String	✅	有效邮箱格式
nickname	String	❌	最多30字符

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "nickname": "Test User",
    "roles": ["ROLE_USER"]
  }
}

错误

Code	说明
400	用户名已存在 / 邮箱已被注册

---

POST /login

用户登录

请求

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

请求参数

字段	类型	必填	说明
username	String	✅	用户名或邮箱
password	String	✅	密码

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "tokenType": "Bearer",
    "expiresIn": 7200,
    "user": {
      "id": 1,
      "username": "testuser",
      "roles": ["ROLE_USER"]
    }
  }
}

响应字段

字段	说明
token	JWT Token
tokenType	固定 "Bearer"
expiresIn	有效期（秒），默认 7200（2小时）

错误

Code	说明
401	用户名或密码错误 / 账号已被禁用

---

POST /logout

用户登出（需认证）

请求

curl -X POST http://localhost:8080/api/v1/auth/logout \
  -H "Authorization: Bearer {token}"

响应

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

JWT 无状态

登出主要由客户端删除 Token 实现。此接口用于记录登出日志。

---

使用流程

sequenceDiagram
    participant C as 客户端
    participant S as 服务端
    
    C->>S: POST /auth/register
    S-->>C: UserVO
    
    C->>S: POST /auth/login
    S-->>C: JWT Token
    
    Note over C: 保存 Token
    
    C->>S: GET /api/v1/users/me<br/>Header: Authorization: Bearer {token}
    S-->>C: UserVO
    
    C->>S: POST /auth/logout
    Note over C: 删除本地 Token

---

安全建议

1. HTTPS — 生产环境必须使用
2. Token 存储 — Web 用 httpOnly Cookie，移动端用 Keychain/Keystore
3. 密码强度 — 前端应验证密码规则
4. 防暴力破解 — 建议实现登录限流