gym-manage/gym-manage-api/docs/cuit-auth-api.md

认证管理模块 API 文档

文档版本: v1.0 创建日期: 2026-06-16 作者: 张翔 状态: 正式发布

---

目录

1. 概述
2. 基础路径
3. 认证接口
   • 用户名+密码登录
   • 获取用户信息
4. 数据模型
   • LoginRequest
   • LoginResponse
   • UserInfo
5. 响应码说明

---

概述

认证管理模块提供用户登录认证和用户信息查询功能。采用 Spring WebFlux 响应式编程，支持高并发场景。

基础路径

所有接口的基础路径为: http://{host}:{port}/api/auth

---

认证接口

用户名+密码登录

属性	值
HTTP方法	POST
接口路径	/api/auth/login
所属文件	AuthHandler.java

请求参数:

参数名	类型	必填	默认值	说明
username	string	是	-	用户名
password	string	是	-	密码

成功响应 (200 OK):

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 7200,
    "userInfo": {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "phone": "13800138000",
      "nickname": "超级管理员",
      "status": 1,
      "roleId": 1
    }
  }
}

失败响应 (400 Bad Request):

{
  "code": 400,
  "message": "用户名或密码错误"
}

---

获取用户信息

属性	值
HTTP方法	GET
接口路径	/api/auth/users/{id}
所属文件	AuthHandler.java

路径参数:

参数名	类型	必填	说明
id	Long	是	用户ID

成功响应 (200 OK):

{
  "code": 200,
  "message": "获取用户信息成功",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "phone": "13800138000",
    "nickname": "超级管理员",
    "status": 1,
    "roleId": 1
  }
}

失败响应 (400 Bad Request):

{
  "code": 400,
  "message": "无效的用户ID"
}

---

数据模型

LoginRequest

用户登录请求对象。

字段	类型	必填	说明	示例
username	string	是	用户名	admin
password	string	是	密码	Test@123

LoginResponse

用户登录响应对象。

字段	类型	说明	示例
accessToken	string	访问令牌	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
refreshToken	string	刷新令牌	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
tokenType	string	令牌类型	Bearer
expiresIn	Long	过期时间（秒）	7200
userInfo	UserInfo	用户信息	-

UserInfo

用户信息对象。

字段	类型	说明	示例
id	Long	用户ID	1
username	string	用户名	admin
email	string	邮箱	admin@example.com
phone	string	手机号	13800138000
nickname	string	昵称	超级管理员
status	Integer	状态：0-禁用，1-正常	1
roleId	Long	角色ID	1

---

响应码说明

响应码	说明
200	成功
400	请求参数错误（如用户名密码错误、无效的用户ID）
401	未授权（认证失败）
403	禁止访问
404	资源未找到
409	冲突（如重复数据）
500	服务器内部错误

---

业务规则

1. 登录成功后返回的 accessToken 用于后续接口的身份认证
2. accessToken 有效期为 2 小时（7200 秒）
3. refreshToken 用于刷新 accessToken，有效期为 7 天
4. 用户状态 status 为 0 时表示禁用，无法登录
5. 所有需要认证的接口需要在请求头中携带 Authorization: Bearer {accessToken}