14 KiB
14 KiB
认证接口
**本文引用的文件** - [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py) - [backend/app/core/security.py](file://backend/app/core/security.py) - [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py) - [backend/app/models/models.py](file://backend/app/models/models.py) - [backend/app/core/config.py](file://backend/app/core/config.py) - [backend/app/core/database.py](file://backend/app/core/database.py) - [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py) - [backend/app/main.py](file://backend/app/main.py) - [frontend/src/api/auth.js](file://frontend/src/api/auth.js) - [frontend/src/api/request.js](file://frontend/src/api/request.js) - [frontend/src/stores/user.js](file://frontend/src/stores/user.js)目录
简介
本文件为“用户认证接口”的完整API文档，覆盖以下三个核心接口：
- 用户登录
- 用户注册
- 获取当前用户信息
内容涵盖HTTP方法、URL路径、请求参数格式、响应数据结构、错误码、JWT令牌生成机制、密码验证流程、用户权限验证、OAuth2密码模式使用方法与安全注意事项、以及令牌过期处理与刷新机制的实现细节。同时提供成功与失败场景的请求/响应示例，并给出前后端集成要点。
项目结构
认证相关代码主要分布在后端的API层、安全模块、数据模型与配置模块；前端通过Axios封装统一请求，自动携带Authorization头。
graph TB
subgraph "后端"
A["API路由<br/>backend/app/api/v1/auth.py"]
B["安全模块<br/>backend/app/core/security.py"]
C["数据模型<br/>backend/app/models/models.py"]
D["配置<br/>backend/app/core/config.py"]
E["数据库连接<br/>backend/app/core/database.py"]
F["主应用入口<br/>backend/app/main.py"]
G["API聚合<br/>backend/app/api/v1/__init__.py"]
end
subgraph "前端"
H["认证API封装<br/>frontend/src/api/auth.js"]
I["请求拦截器<br/>frontend/src/api/request.js"]
J["用户状态存储<br/>frontend/src/stores/user.js"]
end
H --> I
I --> F
F --> G
G --> A
A --> B
A --> C
B --> D
B --> E
J --> H
图表来源
- backend/app/api/v1/auth.py
- backend/app/core/security.py
- backend/app/models/models.py
- backend/app/core/config.py
- backend/app/core/database.py
- backend/app/api/v1/init.py
- backend/app/main.py
- frontend/src/api/auth.js
- frontend/src/api/request.js
- frontend/src/stores/user.js
章节来源
- backend/app/api/v1/auth.py
- backend/app/core/security.py
- backend/app/models/models.py
- backend/app/core/config.py
- backend/app/core/database.py
- backend/app/api/v1/init.py
- backend/app/main.py
- frontend/src/api/auth.js
- frontend/src/api/request.js
- frontend/src/stores/user.js
核心组件
- 认证路由与控制器：定义登录、注册、获取当前用户三个接口，使用OAuth2密码模式进行认证。
- 安全模块：负责密码哈希与校验、JWT令牌生成与解析、当前用户与权限校验。
- 数据模型：User模型包含用户名、密码哈希、角色、激活状态等字段。
- 配置模块：提供API前缀、JWT密钥、算法、过期时间等配置。
- 数据库连接：异步SQLAlchemy会话管理。
- 前端请求封装：统一添加Authorization头，处理401等错误并跳转登录。
章节来源
- backend/app/api/v1/auth.py
- backend/app/core/security.py
- backend/app/models/models.py
- backend/app/core/config.py
- backend/app/core/database.py
- frontend/src/api/request.js
架构概览
认证流程采用OAuth2密码模式，客户端向登录接口发送用户名/密码，服务端验证后签发JWT访问令牌；后续请求由前端在请求头中携带Authorization: Bearer ，后端通过依赖注入解析并校验令牌，获取当前用户。
sequenceDiagram
participant FE as "前端应用"
participant API as "认证接口<br/>/api/v1/auth"
participant SEC as "安全模块<br/>JWT/密码"
participant DB as "数据库<br/>User表"
FE->>API : POST /api/v1/auth/login
API->>DB : 查询用户(用户名)
DB-->>API : 用户记录
API->>SEC : 校验密码
SEC-->>API : 校验结果
API->>SEC : 生成访问令牌
SEC-->>API : 返回JWT
API-->>FE : {access_token, token_type}
FE->>API : GET /api/v1/auth/me<br/>Authorization : Bearer <token>
API->>SEC : 解析JWT并校验
SEC->>DB : 查询用户(根据sub)
DB-->>SEC : 用户记录
SEC-->>API : 当前用户
API-->>FE : 用户信息
图表来源
- backend/app/api/v1/auth.py
- backend/app/core/security.py
- backend/app/models/models.py
- frontend/src/api/auth.js
- frontend/src/api/request.js
详细组件分析
接口定义与行为
-
用户登录
- 方法与路径：POST /api/v1/auth/login
- 认证方式：OAuth2密码模式（form-data）
- 请求体字段：
- username: 字符串，最小长度3，最大长度50
- password: 字符串，最小长度6，最大长度100
- 成功响应：
- access_token: 字符串（JWT）
- token_type: 字符串，默认"bearer"
- 错误码：
- 401：用户名或密码错误
- 403：账户已禁用
- 处理逻辑：
- 根据用户名查询用户
- 使用bcrypt校验密码
- 校验用户是否激活
- 生成JWT访问令牌并返回
-
用户注册
- 方法与路径：POST /api/v1/auth/register
- 请求体字段：
- username: 字符串，最小长度3，最大长度50
- password: 字符串，最小长度6，最大长度100
- staff_id: 可选整数
- role: 字符串，枚举(admin|manager|staff)，默认staff
- 成功响应：
- code: 整数，默认200
- message: 字符串，默认"注册成功"
- data.id: 新用户ID
- 错误码：
- 400：用户名已存在
- 处理逻辑：
- 检查用户名是否重复
- 生成密码哈希
- 创建用户记录并持久化
-
获取当前用户信息
- 方法与路径：GET /api/v1/auth/me
- 认证方式：Bearer Token（Authorization头）
- 成功响应：
- id: 整数
- username: 字符串
- role: 字符串
- is_active: 布尔
- last_login: 可选时间戳
- created_at: 时间戳
- 错误码：
- 401：无法验证凭据（无效/过期令牌）
- 403：需要管理员权限（若使用管理员依赖）
- 处理逻辑：
- 通过OAuth2 Bearer Scheme获取令牌
- 解析JWT载荷(sub为用户ID)
- 查询用户并返回
章节来源
- backend/app/api/v1/auth.py
- backend/app/schemas/schemas.py
- backend/app/core/security.py
- backend/app/models/models.py
JWT令牌生成机制
- 令牌内容：
- exp：过期时间（UTC）
- sub：用户ID（字符串）
- 签发过程：
- 使用配置中的SECRET_KEY与ALGORITHM（如HS256）进行签名
- 默认过期时间为ACCESS_TOKEN_EXPIRE_MINUTES（8小时）
- 解析过程：
- 从Authorization头提取Bearer Token
- 使用相同密钥与算法解码，获取payload
- 从payload取sub作为用户ID，查询用户是否存在且激活
章节来源
密码验证流程
- 存储：密码以哈希形式保存（bcrypt）
- 校验：接收明文密码与存储的哈希，使用bcrypt.checkpw进行比对
- 注册：注册时对明文密码生成哈希再存入数据库
章节来源
用户权限验证
- 当前用户：通过Bearer Token解析并查询用户
- 激活状态：仅激活用户可访问受保护资源
- 角色权限：提供管理员与经理权限校验依赖（用于特定接口）
章节来源
OAuth2密码模式使用方法与安全考虑
- 使用方法：
- 前端以application/x-www-form-urlencoded方式提交username与password到/login
- 服务端返回access_token
- 后续请求在Authorization头中携带Bearer
- 安全考虑：
- 必须通过HTTPS传输，避免令牌被窃听
- 令牌过期时间较短（默认8小时），建议实现刷新机制
- 前端仅本地存储令牌，避免泄露
- 服务端严格校验令牌与用户状态
章节来源
令牌过期处理与刷新机制
- 过期处理：
- 前端在401时提示“登录已过期”，清除本地令牌并跳转登录页
- 刷新机制：
- 当前实现未提供refresh_token接口
- 建议新增刷新令牌接口，或延长ACCESS_TOKEN_EXPIRE_MINUTES并配合短期会话策略
章节来源
依赖关系分析
classDiagram
class AuthRouter{
+POST /auth/login
+POST /auth/register
+GET /auth/me
}
class SecurityModule{
+verify_password()
+get_password_hash()
+create_access_token()
+decode_token()
+get_current_user()
+get_current_active_user()
}
class UserModel{
+id
+username
+password_hash
+role
+is_active
}
class Config{
+SECRET_KEY
+ALGORITHM
+ACCESS_TOKEN_EXPIRE_MINUTES
+API_PREFIX
}
class Database{
+get_db()
}
AuthRouter --> SecurityModule : "依赖"
AuthRouter --> UserModel : "读写"
SecurityModule --> Config : "读取"
SecurityModule --> Database : "依赖"
图表来源
- backend/app/api/v1/auth.py
- backend/app/core/security.py
- backend/app/models/models.py
- backend/app/core/config.py
- backend/app/core/database.py
章节来源
- backend/app/api/v1/auth.py
- backend/app/core/security.py
- backend/app/models/models.py
- backend/app/core/config.py
- backend/app/core/database.py
性能考量
- 密码哈希：bcrypt计算开销较高，建议在高并发场景下适当调整密钥迭代次数或使用更高效的硬件
- JWT解析：每次受保护请求均需解码与用户查询，建议缓存活跃用户信息或使用Redis等缓存层
- 数据库连接：使用异步连接池，合理设置池大小与超时，避免阻塞
- 前端拦截器：统一处理401错误，减少重复逻辑
[本节为通用指导，不直接分析具体文件]
故障排查指南
- 登录失败（401）：
- 检查用户名/密码是否正确
- 确认用户是否激活
- 无法访问受保护接口（401）：
- 检查Authorization头是否正确携带Bearer Token
- 确认令牌未过期
- 权限不足（403）：
- 确认用户角色是否满足接口要求
- CORS问题：
- 检查CORS允许的源与预检请求
- 前端401自动跳转：
- 确认本地存储的token是否被清理
- 检查请求拦截器是否正确添加Authorization头
章节来源
- frontend/src/api/request.js
- frontend/src/stores/user.js
- backend/app/api/v1/auth.py
- backend/app/core/security.py
结论
该认证系统基于OAuth2密码模式与JWT实现，具备基本的用户登录、注册与当前用户信息获取能力。建议后续增强刷新令牌机制与更细粒度的权限控制，并在生产环境强化安全配置（如HTTPS、密钥轮换、令牌审计等）。