认证与用户

通用说明

Base URL: https://your-domain.com/api

所有需要认证的接口通过请求头传递 JWT Token：

Authorization: Bearer <your_jwt_token>

统一响应格式：

{
  "code": 200,
  "data": {},
  "msg": "操作成功"
}

错误响应：

code	含义
200	成功
400	请求参数错误
401	未认证或 Token 过期
403	无权限
404	资源不存在
429	请求过于频繁
500	服务器内部错误

频率限制：

接口类型	限制
通用接口 (/api/*)	60 次/分钟
认证接口 (/api/register, /api/login)	20 次/15 分钟

---

注册

POST 公开

/api/register

注册新用户。用户名长度 2-32 位，密码长度 6-128 位。注册成功后自动返回 JWT Token。

请求参数：

字段	类型	必填	说明
username	string	是	用户名，2-32 字符
password	string	是	密码，最少 6 位
nickname	string	否	昵称，默认与用户名相同
email	string	否	邮箱地址
avatar	string	否	头像 URL

请求示例：

curl -X POST http://localhost:3000/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "zhangsan",
    "password": "123456",
    "nickname": "张三",
    "email": "zhangsan@example.com"
  }'

成功响应：

{
  "code": 200,
  "message": "注册成功",
  "data": {
    "id": "u_abc123",
    "username": "zhangsan",
    "nickname": "张三",
    "email": "zhangsan@example.com",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
  }
}

错误场景：

条件	响应
用户名已存在	{ "code": 400, "msg": "用户名已存在" }
用户名过短/过长	{ "code": 400, "msg": "用户名长度需在2-32之间" }
密码过短	{ "code": 400, "msg": "密码长度不能少于6位" }

---

登录

POST 公开

/api/login

使用用户名和密码登录。支持 bcrypt 加密密码和旧版 SHA256 密码的自动兼容。

请求参数：

字段	类型	必填	说明
username	string	是	用户名
password	string	是	密码

请求示例：

curl -X POST http://localhost:3000/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "zhangsan",
    "password": "123456"
  }'

成功响应：

{
  "code": 200,
  "data": {
    "id": "u_abc123",
    "username": "zhangsan",
    "nickname": "张三",
    "email": "zhangsan@example.com",
    "avatar": "",
    "gender": "",
    "bio": "",
    "phone": "",
    "push_enabled": 1,
    "dnd_enabled": 0,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
  }
}

注意

响应中包含完整的用户信息（不含密码）和 JWT Token。前端需将 token 存储到本地，并在后续请求中通过 Authorization 头传递。

错误场景：

条件	响应
用户不存在	{ "code": 400, "msg": "用户不存在" }
密码错误	{ "code": 400, "msg": "密码错误" }

---

修改密码

POST JWT

/api/user/change-password

修改当前登录用户的密码。

请求参数：

字段	类型	必填	说明
oldPassword	string	是	原密码
newPassword	string	是	新密码，最少 6 位

请求示例：

curl -X POST http://localhost:3000/api/user/change-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "oldPassword": "123456",
    "newPassword": "654321"
  }'

成功响应：

{
  "code": 200,
  "message": "密码修改成功"
}

---

获取所有用户列表

GET JWT

/api/users

获取所有已注册用户的列表，包含在线状态。

请求示例：

curl http://localhost:3000/api/users \
  -H "Authorization: Bearer <token>"

成功响应：

{
  "code": 200,
  "data": [
    {
      "id": "u_abc123",
      "username": "zhangsan",
      "avatar": "",
      "nickname": "张三",
      "gender": "male",
      "bio": "Hello",
      "isOnline": 1
    },
    {
      "id": "u_def456",
      "username": "lisi",
      "avatar": "",
      "nickname": "李四",
      "gender": "",
      "bio": "",
      "isOnline": 0
    }
  ]
}

TIP

isOnline 字段基于当前活跃的 WebSocket 连接判断，1 表示在线，0 表示离线。