shenjianZ
3a9bf61839
- 新增项目基础配置：pom.xml 依赖管理、多环境配置（dev/prod）、Dockerfile、.env.example - 新增安全认证模块：JWT 工具类、JWT 过滤器、Spring Security 配置、自定义 UserDetails - 新增用户管理功能：注册/登录/查询/修改、角色管理（USER/ADMIN/ROOT）、分页查询、状态启禁用 - 新增密码重置功能：邮箱验证码发送、验证码校验重置、频率限制与过期机制 - 新增基础架构层：统一响应体 RestBean、全局异常处理、日志拦截器、Redis 工具类、JPA 配置 - 新增 Swagger/OpenAPI 文档配置与完整的 API 接口文档（API_DOCUMENT.md） - 新增数据库初始化 SQL 脚本（init.sql）
313 lines
4.7 KiB
Markdown
313 lines
4.7 KiB
Markdown
# API 接口文档
|
||
|
||
Base URL: `http://localhost:8080/api/v1`
|
||
|
||
在线文档: http://localhost:8080/swagger-ui/index.html
|
||
|
||
## 通用说明
|
||
|
||
### 响应格式
|
||
|
||
所有接口统一返回 `RestBean`：
|
||
|
||
```json
|
||
{
|
||
"status": 200,
|
||
"message": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 认证方式
|
||
|
||
需要认证的接口在请求头中携带 JWT Token：
|
||
|
||
```
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
登录/注册接口会返回 Token。
|
||
|
||
---
|
||
|
||
## 用户接口
|
||
|
||
### 注册
|
||
|
||
`POST /api/v1/user/register`
|
||
|
||
**公开接口**，无需认证。
|
||
|
||
请求体：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| username | String | 是 | 用户名，2-50 位 |
|
||
| password | String | 是 | 密码，6-64 位 |
|
||
| email | String | 否 | 邮箱 |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"username": "testuser",
|
||
"password": "123456",
|
||
"email": "test@example.com"
|
||
}
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"status": 200,
|
||
"message": "success",
|
||
"data": "eyJhbGciOiJIUzUxMiJ9..."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 登录
|
||
|
||
`POST /api/v1/user/login`
|
||
|
||
**公开接口**，无需认证。
|
||
|
||
请求体：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| username | String | 是 | 用户名 |
|
||
| password | String | 是 | 密码 |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"username": "testuser",
|
||
"password": "123456"
|
||
}
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"status": 200,
|
||
"message": "success",
|
||
"data": "eyJhbGciOiJIUzUxMiJ9..."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 获取用户信息
|
||
|
||
`GET /api/v1/user/info`
|
||
|
||
**需要认证**。
|
||
|
||
请求头：
|
||
|
||
```
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"status": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "testuser",
|
||
"email": "test@example.com",
|
||
"status": 1,
|
||
"role": "USER",
|
||
"createdAt": "2026-03-31 08:00:00",
|
||
"updatedAt": "2026-03-31 08:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 发送密码找回验证码
|
||
|
||
`POST /api/v1/user/password-reset/request`
|
||
|
||
**公开接口**，无需认证。
|
||
|
||
请求体：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| email | String | 是 | 已注册的邮箱 |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"email": "test@example.com"
|
||
}
|
||
```
|
||
|
||
频率限制：
|
||
- 两次请求间隔至少 60 秒
|
||
- 同一邮箱 1 小时内最多 5 次
|
||
|
||
---
|
||
|
||
### 验证码重置密码
|
||
|
||
`POST /api/v1/user/password-reset/confirm`
|
||
|
||
**公开接口**，无需认证。
|
||
|
||
请求体：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| email | String | 是 | 邮箱 |
|
||
| code | String | 是 | 6 位数字验证码 |
|
||
| newPassword | String | 是 | 新密码，6-64 位 |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"email": "test@example.com",
|
||
"code": "123456",
|
||
"newPassword": "newpass123"
|
||
}
|
||
```
|
||
|
||
验证码限制：
|
||
- 有效期 10 分钟
|
||
- 最多尝试 5 次
|
||
|
||
---
|
||
|
||
### 用户列表（管理员）
|
||
|
||
`GET /api/v1/user/list`
|
||
|
||
**需要认证 + ADMIN 角色**。
|
||
|
||
请求参数：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | Integer | 否 | 页码，默认 1 |
|
||
| size | Integer | 否 | 每页条数，默认 10 |
|
||
| keyword | String | 否 | 搜索关键词（用户名/邮箱） |
|
||
| role | String | 否 | 角色筛选（USER/ADMIN） |
|
||
| status | Integer | 否 | 状态筛选（1=正常 0=禁用） |
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"status": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"id": 1,
|
||
"username": "admin",
|
||
"email": "admin@example.com",
|
||
"status": 1,
|
||
"role": "ADMIN",
|
||
"createdAt": "2026-03-31 08:00:00",
|
||
"updatedAt": "2026-03-31 08:00:00"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"size": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 更新用户状态（管理员）
|
||
|
||
`PUT /api/v1/user/{userId}/status`
|
||
|
||
**需要认证 + ADMIN 角色**。
|
||
|
||
路径参数：
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| userId | Long | 用户 ID |
|
||
|
||
请求体：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| status | Integer | 是 | 1=启用，0=禁用 |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"status": 0
|
||
}
|
||
```
|
||
|
||
> 不允许修改自己的状态。
|
||
|
||
---
|
||
|
||
### 更新用户角色（管理员）
|
||
|
||
`PUT /api/v1/user/{userId}/role`
|
||
|
||
**需要认证 + ADMIN 角色**。
|
||
|
||
路径参数：
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| userId | Long | 用户 ID |
|
||
|
||
请求体：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| role | String | 是 | 角色名称：USER 或 ADMIN |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"role": "ADMIN"
|
||
}
|
||
```
|
||
|
||
> 不允许修改自己的角色。
|
||
|
||
---
|
||
|
||
## 错误码
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 成功 |
|
||
| 400 | 参数错误 / 请求格式错误 |
|
||
| 403 | 权限不足 / 账号被禁用 |
|
||
| 404 | 数据不存在 |
|
||
| 500 | 系统异常 |
|
||
|
||
业务错误码：
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 1001 | 用户不存在 |
|
||
| 1002 | 密码错误 |
|
||
| 1003 | 账号已被锁定 |
|