AI_OJ/docs/auth-api.md

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
• 描述: 用户登录获取访问令牌
• 认证要求: 无需认证

请求参数:

{
  "userAccount": "string",  // 用户账号
  "userPassword": "string"  // 用户密码
}

请求示例:

curl -X POST http://localhost:10011/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "userAccount": "admin",
    "userPassword": "password123"
  }'

响应示例:

{
  "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  // 刷新令牌

请求示例:

curl -X POST "http://localhost:10011/api/v1/auth/refresh?refreshToken=eyJhbGciOiJIUzI1NiJ9..."

响应示例:

{
  "success": true,
  "message": "操作成功",
  "data": {
    "id": null,
    "userAccount": null,
    "unionId": null,
    "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
    "expire": null
  }
}

3. 获取访问令牌

简化版的登录接口，仅返回访问令牌。

接口信息:

• URL: POST /api/v1/auth/auth
• 描述: 获取访问令牌（简化版登录）
• 认证要求: 无需认证

请求参数:

{
  "userAccount": "string",  // 用户账号
  "userPassword": "string"  // 用户密码
}

请求示例:

curl -X POST http://localhost:10011/api/v1/auth/auth \
  -H "Content-Type: application/json" \
  -d '{
    "userAccount": "admin",
    "userPassword": "password123"
  }'

响应示例:

{
  "success": true,
  "message": "操作成功",
  "data": "eyJhbGciOiJIUzI1NiJ9..."
}

4. 令牌验证

验证访问令牌的有效性。

接口信息:

• URL: POST /api/v1/auth/validate
• 描述: 验证访问令牌
• 认证要求: 可选的Authorization头

请求头:

Authorization: Bearer {access_token}  // 可选

请求示例:

curl -X POST http://localhost:10011/api/v1/auth/validate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

响应示例:

{
  "success": true,
  "message": "操作成功",
  "data": true
}

状态码说明

状态码	说明	描述
200	OK	请求成功
400	Bad Request	请求参数错误
401	Unauthorized	未授权访问或令牌无效
403	Forbidden	禁止访问
500	Internal Server Error	服务器内部错误

错误响应格式

{
  "success": false,
  "message": "错误描述",
  "data": null
}

常见错误码

错误信息	可能原因	解决方案
"用户不存在或密码错误"	用户账号或密码不正确	检查用户名和密码
"Refresh Token 已过期"	刷新令牌已过期	重新登录获取新令牌
"Refresh Token 已失效"	刷新令牌在Redis中不存在或已失效	重新登录获取新令牌
"系统错误"	服务间调用失败或系统异常	检查服务状态和网络连接

配置信息

JWT配置

jwt:
  secret: "12345678901234567890123456789012"  # 32字节密钥
  access-expire: 900000        # 15分钟（毫秒）
  refresh-expire: 604800000    # 7天（毫秒）

服务配置

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