用户鉴权接口文档
概览
- 基础路径: /api
- 文档范围: 仅包含需要 JWT 鉴权的用户接口
- 鉴权方式:
- 优先读取请求头 X-Token
- Content-Type: application/json
统一响应格式
{
"code": 200,
"msg": "操作成功",
"data": {}
}
返回字段说明
| 字段 |
类型 |
说明 |
| code |
integer |
业务状态码，200 表示成功，其他值表示失败 |
| msg |
string |
响应消息 |
| data |
object/null |
业务数据，可能为对象、数组或 null |
通用鉴权失败响应示例
{
"code": 401,
"msg": "未登录或登录过期",
"data": null
}
{
"code": 401,
"msg": "登录已过期，请重新登录",
"data": null
}
1. 用户登出
- 路径: /api/user/logout
- 方法: POST
- 是否鉴权: 是
请求头
| 字段 |
类型 |
必填 |
说明 |
| X-Token |
string |
是 |
直接传入 JWT token |
说明:
- 该接口为无状态登出，服务端不维护黑名单，客户端删除 token 即视为登出。
请求 Body
无业务参数，可传空对象:
{}
成功响应示例
{
"code": 200,
"msg": "登出成功",
"data": null
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
固定为 200 |
| msg |
string |
固定为 登出成功 |
| data |
null |
无返回数据 |
2. 刷新 Token
- 路径: /api/user/refreshToken
- 方法: POST
- 是否鉴权: 是
请求头
| 字段 |
类型 |
必填 |
说明 |
| X-Token |
string |
是 |
直接传入 JWT token |
请求 Body
当前实现不读取业务请求体，可传空对象:
{}
成功响应示例
{
"code": 200,
"msg": "刷新成功",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx.yyy",
"expiresIn": 86400
}
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
固定为 200 |
| msg |
string |
固定为 刷新成功 |
| data.token |
string |
新生成的 JWT Token |
| data.expiresIn |
integer |
Token 剩余有效秒数 |
失败响应示例
{
"code": 400,
"msg": "用户不存在",
"data": null
}
3. 修改密码
- 路径: /api/user/changePassword
- 方法: POST
- 是否鉴权: 是
请求头
| 字段 |
类型 |
必填 |
说明 |
| X-Token |
string |
是 |
直接传入 JWT token |
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| oldPassword |
string |
是 |
旧密码。若用户此前已设置密码，则必须与当前密码一致 |
| newPassword |
string |
是 |
新密码，服务端会进行加密存储 |
请求示例
{
"oldPassword": "12345678",
"newPassword": "newPass@2026"
}
成功响应示例
{
"code": 200,
"msg": "密码修改成功",
"data": null
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
固定为 200 |
| msg |
string |
固定为 密码修改成功 |
| data |
null |
无返回数据 |
失败响应示例
{
"code": 400,
"msg": "参数错误",
"data": null
}
{
"code": 400,
"msg": "原密码错误",
"data": null
}
{
"code": 400,
"msg": "用户不存在",
"data": null
}
4. 修改昵称
- 路径: /api/user/updateNickname
- 方法: POST
- 是否鉴权: 是
请求头
| 字段 |
类型 |
必填 |
说明 |
| X-Token |
string |
是 |
直接传入 JWT token |
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| nickname |
string |
是 |
新昵称，不能为空，且最多 30 个字符 |
请求示例
{
"nickname": "新的昵称"
}
成功响应示例
{
"code": 200,
"msg": "昵称修改成功",
"data": null
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
固定为 200 |
| msg |
string |
固定为 昵称修改成功 |
| data |
null |
无返回数据 |
失败响应示例
{
"code": 400,
"msg": "参数错误",
"data": null
}
{
"code": 400,
"msg": "昵称不能为空",
"data": null
}
{
"code": 400,
"msg": "昵称不能超过30个字符",
"data": null
}
附录
鉴权头使用示例
X-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx.yyy
说明
- 所有接口返回均采用业务码放在 code 字段中的统一结构。
- 除 FailWithHTTP 场景外，大多数业务失败仍返回 HTTP 200，请客户端以 code 字段判断是否成功。
- 刷新 Token 接口当前仅依赖已登录用户身份，不读取 refreshToken 请求体字段。