st/docs/用户认证API文档.md

用户认证 API 文档

📋 概述

本文档描述云酒馆项目前台用户认证系统的所有 API 接口。

🔗 基础信息

• Base URL: http://localhost:8888/app（开发环境）
• 认证方式: JWT Bearer Token
• Content-Type: application/json

📌 API 接口列表

1. 用户注册

接口: POST /app/auth/register

描述: 新用户注册

请求头: 无需认证

请求体:

{
  "username": "testuser",
  "password": "123456",
  "nickName": "测试用户",
  "email": "test@example.com",
  "phone": "13800138000"
}

字段说明:

字段	类型	必填	说明
username	string	是	用户名，3-32字符
password	string	是	密码，6-32字符
nickName	string	否	昵称，最多50字符
email	string	否	邮箱地址
phone	string	否	手机号

成功响应:

{
  "code": 0,
  "msg": "注册成功"
}

错误响应:

{
  "code": 7,
  "msg": "用户名已存在"
}

---

2. 用户登录

接口: POST /app/auth/login

描述: 用户登录获取 Token

请求头: 无需认证

请求体:

{
  "username": "testuser",
  "password": "123456"
}

成功响应:

{
  "code": 0,
  "data": {
    "user": {
      "id": 1,
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "username": "testuser",
      "nickName": "测试用户",
      "email": "test@example.com",
      "phone": "13800138000",
      "avatar": "",
      "status": "active",
      "enable": true,
      "lastLoginAt": "2026-02-10T09:00:00Z",
      "chatCount": 0,
      "messageCount": 0,
      "aiSettings": null,
      "preferences": null,
      "createdAt": "2026-02-10T08:00:00Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresAt": 1707552000
  },
  "msg": "登录成功"
}

错误响应:

{
  "code": 7,
  "msg": "用户名或密码错误"
}

---

3. 刷新 Token

接口: POST /app/auth/refresh

描述: 使用 RefreshToken 获取新的 Token

请求头: 无需认证

请求体:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

成功响应: 同登录接口

---

4. 用户登出

接口: POST /app/auth/logout

描述: 用户登出（清除会话）

请求头:

x-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

或

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

请求体: 无

成功响应:

{
  "code": 0,
  "msg": "登出成功"
}

---

5. 获取用户信息

接口: GET /app/auth/userinfo

描述: 获取当前登录用户信息

请求头: 需要认证（JWT Token）

成功响应:

{
  "code": 0,
  "data": {
    "id": 1,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "username": "testuser",
    "nickName": "测试用户",
    "email": "test@example.com",
    "phone": "13800138000",
    "avatar": "",
    "status": "active",
    "enable": true,
    "lastLoginAt": "2026-02-10T09:00:00Z",
    "chatCount": 5,
    "messageCount": 120,
    "aiSettings": {},
    "preferences": {},
    "createdAt": "2026-02-10T08:00:00Z"
  }
}

---

6. 更新用户信息

接口: PUT /app/user/profile

描述: 更新当前用户的个人信息

请求头: 需要认证（JWT Token）

请求体:

{
  "nickName": "新昵称",
  "email": "newemail@example.com",
  "phone": "13900139000",
  "avatar": "https://example.com/avatar.jpg",
  "preferences": "{\"theme\":\"dark\"}",
  "aiSettings": "{\"defaultModel\":\"gpt-4\"}"
}

字段说明: 所有字段均为可选

成功响应:

{
  "code": 0,
  "msg": "更新成功"
}

---

7. 修改密码

接口: POST /app/user/change-password

描述: 修改当前用户密码

请求头: 需要认证（JWT Token）

请求体:

{
  "oldPassword": "123456",
  "newPassword": "new123456"
}

成功响应:

{
  "code": 0,
  "msg": "修改成功"
}

错误响应:

{
  "code": 7,
  "msg": "原密码错误"
}

---

🔐 认证说明

Token 使用方式

认证接口需要在请求头中携带 Token，支持两种方式：

方式 1: x-token 头

x-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

方式 2: Authorization 头（Bearer Token）

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

方式 3: Query 参数（不推荐，仅用于特殊场景）

GET /app/auth/userinfo?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token 有效期

• Access Token: 配置文件中的 jwt.expiresTime 设置（默认 7200 秒 = 2 小时）
• Refresh Token: 固定 7 天

Token 刷新流程

1. Access Token 过期后，使用 Refresh Token 调用 /app/auth/refresh 接口
2. 获取新的 Access Token 和 Refresh Token
3. 使用新的 Token 继续访问 API

---

🧪 测试用例

使用 curl 测试

1. 注册新用户:

curl -X POST http://localhost:8888/app/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "123456",
    "nickName": "测试用户"
  }'

2. 登录:

curl -X POST http://localhost:8888/app/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "123456"
  }'

3. 获取用户信息（需替换 TOKEN）:

TOKEN="your_token_here"
curl -X GET http://localhost:8888/app/auth/userinfo \
  -H "x-token: $TOKEN"

4. 更新用户信息:

curl -X PUT http://localhost:8888/app/user/profile \
  -H "x-token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nickName": "新昵称",
    "avatar": "https://example.com/avatar.jpg"
  }'

5. 修改密码:

curl -X POST http://localhost:8888/app/user/change-password \
  -H "x-token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "oldPassword": "123456",
    "newPassword": "new123456"
  }'

---

❗ 常见错误码

错误码	说明
0	成功
7	业务错误（如用户名已存在、密码错误等）
401	未认证或 Token 无效
403	账户被禁用或状态异常
500	服务器内部错误

---

📝 注意事项

1. 密码安全: 所有密码均使用 bcrypt 加密存储，不可逆
2. 用户状态: 只有 status=active 且 enable=true 的用户才能登录
3. 用户名唯一性: 用户名和邮箱必须唯一
4. 会话管理: 登出后会删除对应的会话记录，但 Token 在过期前仍然有效
5. 跨域配置: 如需前端调用，请在 initialize/router.go 中启用 CORS 中间件

---

🔄 下一步开发

• 邮箱验证
• 手机号验证
• 找回密码
• 第三方登录（OAuth）
• 多设备登录管理
• 用户在线状态