190 lines
4.1 KiB
Markdown
190 lines
4.1 KiB
Markdown
# 认证管理模块 API 文档
|
|
|
|
> **文档版本**: v1.0
|
|
> **创建日期**: 2026-06-16
|
|
> **作者**: 张翔
|
|
> **状态**: 正式发布
|
|
|
|
---
|
|
|
|
## 目录
|
|
|
|
1. [概述](#概述)
|
|
2. [基础路径](#基础路径)
|
|
3. [认证接口](#认证接口)
|
|
- [用户名+密码登录](#用户名密码登录)
|
|
- [获取用户信息](#获取用户信息)
|
|
4. [数据模型](#数据模型)
|
|
- [LoginRequest](#loginrequest)
|
|
- [LoginResponse](#loginresponse)
|
|
- [UserInfo](#userinfo)
|
|
5. [响应码说明](#响应码说明)
|
|
|
|
---
|
|
|
|
## 概述
|
|
|
|
认证管理模块提供用户登录认证和用户信息查询功能。采用 Spring WebFlux 响应式编程，支持高并发场景。
|
|
|
|
## 基础路径
|
|
|
|
所有接口的基础路径为: `http://{host}:{port}/api/auth`
|
|
|
|
---
|
|
|
|
## 认证接口
|
|
|
|
### 用户名+密码登录
|
|
|
|
| 属性 | 值 |
|
|
|------|-----|
|
|
| **HTTP方法** | POST |
|
|
| **接口路径** | `/api/auth/login` |
|
|
| **所属文件** | `AuthHandler.java` |
|
|
|
|
**请求参数**:
|
|
|
|
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
|--------|------|------|--------|------|
|
|
| username | string | 是 | - | 用户名 |
|
|
| password | string | 是 | - | 密码 |
|
|
|
|
**成功响应** (200 OK):
|
|
|
|
```json
|
|
{
|
|
"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):
|
|
|
|
```json
|
|
{
|
|
"code": 400,
|
|
"message": "用户名或密码错误"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 获取用户信息
|
|
|
|
| 属性 | 值 |
|
|
|------|-----|
|
|
| **HTTP方法** | GET |
|
|
| **接口路径** | `/api/auth/users/{id}` |
|
|
| **所属文件** | `AuthHandler.java` |
|
|
|
|
**路径参数**:
|
|
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|
|--------|------|------|------|
|
|
| id | Long | 是 | 用户ID |
|
|
|
|
**成功响应** (200 OK):
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "获取用户信息成功",
|
|
"data": {
|
|
"id": 1,
|
|
"username": "admin",
|
|
"email": "admin@example.com",
|
|
"phone": "13800138000",
|
|
"nickname": "超级管理员",
|
|
"status": 1,
|
|
"roleId": 1
|
|
}
|
|
}
|
|
```
|
|
|
|
**失败响应** (400 Bad Request):
|
|
|
|
```json
|
|
{
|
|
"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}`
|