fix: 修复网关启动找不到服务的问题，修复jwt问题，修复自动导入失败问题。
This commit is contained in:
243
docs/auth-api.md
Normal file
243
docs/auth-api.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# AIOJ 认证服务 API 文档
|
||||
|
||||
## 概述
|
||||
|
||||
AIOJ认证服务提供JWT（JSON Web Token）为基础的用户认证和授权功能。该服务负责用户登录、令牌生成、令牌刷新和令牌验证。
|
||||
|
||||
**基础信息:**
|
||||
- 服务名称: auth-service
|
||||
- 基础路径: `/api`
|
||||
- API版本: v1
|
||||
- 认证方式: JWT Bearer Token
|
||||
- 数据格式: JSON
|
||||
|
||||
## JWT认证机制
|
||||
|
||||
### 访问令牌 (Access Token)
|
||||
- 有效期: 15分钟
|
||||
- 用途: 访问受保护的API接口
|
||||
- 格式: Bearer Token
|
||||
|
||||
### 刷新令牌 (Refresh Token)
|
||||
- 有效期: 7天
|
||||
- 用途: 获取新的Access Token
|
||||
- 存储位置: Redis
|
||||
|
||||
### 请求头格式
|
||||
```
|
||||
Authorization: Bearer {access_token}
|
||||
```
|
||||
|
||||
## API接口
|
||||
|
||||
### 1. 用户登录
|
||||
用户通过用户名和密码进行登录认证。
|
||||
|
||||
**接口信息:**
|
||||
- URL: `POST /api/v1/auth/login`
|
||||
- 描述: 用户登录获取访问令牌
|
||||
- 认证要求: 无需认证
|
||||
|
||||
**请求参数:**
|
||||
```json
|
||||
{
|
||||
"userAccount": "string", // 用户账号
|
||||
"userPassword": "string" // 用户密码
|
||||
}
|
||||
```
|
||||
|
||||
**请求示例:**
|
||||
```bash
|
||||
curl -X POST http://localhost:10011/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"userAccount": "admin",
|
||||
"userPassword": "password123"
|
||||
}'
|
||||
```
|
||||
|
||||
**响应示例:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "操作成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"userAccount": "admin",
|
||||
"unionId": null,
|
||||
"accessToken": "eyJhbGciOiJIUzI1NiJ9...",
|
||||
"refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
|
||||
"expire": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 令牌刷新
|
||||
使用刷新令牌获取新的访问令牌。
|
||||
|
||||
**接口信息:**
|
||||
- URL: `POST /api/v1/auth/refresh`
|
||||
- 描述: 刷新访问令牌
|
||||
- 认证要求: 无需认证
|
||||
|
||||
**请求参数:**
|
||||
```
|
||||
refreshToken=string // 刷新令牌
|
||||
```
|
||||
|
||||
**请求示例:**
|
||||
```bash
|
||||
curl -X POST "http://localhost:10011/api/v1/auth/refresh?refreshToken=eyJhbGciOiJIUzI1NiJ9..."
|
||||
```
|
||||
|
||||
**响应示例:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "操作成功",
|
||||
"data": {
|
||||
"id": null,
|
||||
"userAccount": null,
|
||||
"unionId": null,
|
||||
"accessToken": "eyJhbGciOiJIUzI1NiJ9...",
|
||||
"refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
|
||||
"expire": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 获取访问令牌
|
||||
简化版的登录接口，仅返回访问令牌。
|
||||
|
||||
**接口信息:**
|
||||
- URL: `POST /api/v1/auth/auth`
|
||||
- 描述: 获取访问令牌（简化版登录）
|
||||
- 认证要求: 无需认证
|
||||
|
||||
**请求参数:**
|
||||
```json
|
||||
{
|
||||
"userAccount": "string", // 用户账号
|
||||
"userPassword": "string" // 用户密码
|
||||
}
|
||||
```
|
||||
|
||||
**请求示例:**
|
||||
```bash
|
||||
curl -X POST http://localhost:10011/api/v1/auth/auth \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"userAccount": "admin",
|
||||
"userPassword": "password123"
|
||||
}'
|
||||
```
|
||||
|
||||
**响应示例:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "操作成功",
|
||||
"data": "eyJhbGciOiJIUzI1NiJ9..."
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 令牌验证
|
||||
验证访问令牌的有效性。
|
||||
|
||||
**接口信息:**
|
||||
- URL: `POST /api/v1/auth/validate`
|
||||
- 描述: 验证访问令牌
|
||||
- 认证要求: 可选的Authorization头
|
||||
|
||||
**请求头:**
|
||||
```
|
||||
Authorization: Bearer {access_token} // 可选
|
||||
```
|
||||
|
||||
**请求示例:**
|
||||
```bash
|
||||
curl -X POST http://localhost:10011/api/v1/auth/validate \
|
||||
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."
|
||||
```
|
||||
|
||||
**响应示例:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "操作成功",
|
||||
"data": true
|
||||
}
|
||||
```
|
||||
|
||||
## 状态码说明
|
||||
|
||||
| 状态码 | 说明 | 描述 |
|
||||
|--------|------|------|
|
||||
| 200 | OK | 请求成功 |
|
||||
| 400 | Bad Request | 请求参数错误 |
|
||||
| 401 | Unauthorized | 未授权访问或令牌无效 |
|
||||
| 403 | Forbidden | 禁止访问 |
|
||||
| 500 | Internal Server Error | 服务器内部错误 |
|
||||
|
||||
## 错误响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "错误描述",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
## 常见错误码
|
||||
|
||||
| 错误信息 | 可能原因 | 解决方案 |
|
||||
|----------|----------|----------|
|
||||
| "用户不存在或密码错误" | 用户账号或密码不正确 | 检查用户名和密码 |
|
||||
| "Refresh Token 已过期" | 刷新令牌已过期 | 重新登录获取新令牌 |
|
||||
| "Refresh Token 已失效" | 刷新令牌在Redis中不存在或已失效 | 重新登录获取新令牌 |
|
||||
| "系统错误" | 服务间调用失败或系统异常 | 检查服务状态和网络连接 |
|
||||
|
||||
## 配置信息
|
||||
|
||||
### JWT配置
|
||||
```yaml
|
||||
jwt:
|
||||
secret: "12345678901234567890123456789012" # 32字节密钥
|
||||
access-expire: 900000 # 15分钟（毫秒）
|
||||
refresh-expire: 604800000 # 7天（毫秒）
|
||||
```
|
||||
|
||||
### 服务配置
|
||||
```yaml
|
||||
spring:
|
||||
application:
|
||||
name: auth-service
|
||||
server:
|
||||
port: 10011
|
||||
servlet:
|
||||
context-path: /api
|
||||
```
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
1. **令牌存储**: Access Token应存储在内存或HttpOnly Cookie中
|
||||
2. **HTTPS传输**: 生产环境必须使用HTTPS协议
|
||||
3. **密钥管理**: JWT密钥应定期轮换，使用强密钥
|
||||
4. **令牌过期**: 合理设置令牌过期时间，平衡安全性和用户体验
|
||||
5. **错误处理**: 不要在错误信息中泄露敏感信息
|
||||
|
||||
## 使用流程
|
||||
|
||||
1. **用户登录**: 调用`/login`接口获取Access Token和Refresh Token
|
||||
2. **API访问**: 在请求头中携带Access Token访问受保护接口
|
||||
3. **令牌刷新**: Access Token过期时使用Refresh Token获取新的Access Token
|
||||
4. **令牌验证**: 可使用`/validate`接口验证Token有效性
|
||||
|
||||
## 联系信息
|
||||
|
||||
如有问题或建议，请联系开发团队。
|
||||
|
||||
---
|
||||
*文档版本: v1.0*
|
||||
*更新时间: 2025-12-14*
|
||||
Reference in New Issue
Block a user