You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
23 KiB
23 KiB
认证API接口
**本文档引用的文件** - [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java) - [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java) - [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java) - [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java) - [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java) - [LoginParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/LoginParam.java) - [UserPageParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/UserPageParam.java) - [LoginResultDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java) - [UserInfoDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserInfoDTO.java) - [UserListDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserListDTO.java) - [UserStatsVO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserStatsVO.java) - [AuthUserMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/AuthUserMapper.java) - [AuthIdentityMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/AuthIdentityMapper.java) - [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java) - [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java) - [AuthService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthService.java) - [IAuthUserService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthUserService.java) - [IAuthIdentityService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthIdentityService.java) - [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java) - [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java) - [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java) - [BusinessErrorException.java](file://crm-base/src/main/java/com/crm/base/domain/exception/BusinessErrorException.java) - [PermissionErrorException.java](file://crm-base/src/main/java/com/crm/base/domain/exception/PermissionErrorException.java) - [ResourceNotExistException.java](file://crm-base/src/main/java/com/crm/base/domain/exception/ResourceNotExistException.java) - [MissingParameterException.java](file://crm-base/src/main/java/com/crm/base/domain/exception/MissingParameterException.java) - [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.java) - [DataScopeTables.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeTables.java)更新摘要
所做更改
- 新增用户列表查询相关接口文档
- 添加用户统计功能说明
- 更新系统控制器接口定义
- 补充分页查询和统计接口的详细参数说明
目录
简介
本文件为认证模块的RESTful API文档，覆盖用户登录、登出、令牌刷新、用户信息查询以及用户列表管理等功能。文档包含每个接口的HTTP方法、URL路径、请求参数、响应格式、错误码、鉴权方式与调用频率限制说明，并提供最佳实践与常见问题解决方案。
项目结构
认证功能集中在 crm-auth 模块中，采用分层架构：
- 控制器层：对外暴露REST接口（包括认证和用户管理）
- 安全层：JWT过滤器、令牌服务、数据权限拦截器
- 服务层：业务逻辑（用户、身份、权限、用户列表管理）
- 持久层：MyBatis Mapper映射
- 基础库：统一结果封装、异常处理、通用配置
graph TB
Client["客户端"] --> AC["AuthController<br/>认证控制器"]
Client --> SC["SystemController<br/>系统控制器"]
AC --> TS["TokenService<br/>令牌服务"]
AC --> AUIS["AuthUserServiceImpl<br/>用户服务实现"]
AC --> AIS["AuthIdentityServiceImpl<br/>身份服务实现"]
SC --> AUIS
SC --> AIS
AUIS --> AUM["AuthUserMapper<br/>用户映射"]
AIS --> AIM["AuthIdentityMapper<br/>身份映射"]
AC --> JAF["JwtAuthenticationFilter<br/>JWT过滤器"]
AC --> DSI["DataScopeInterceptor<br/>数据范围拦截器"]
图表来源
- AuthController.java
- SystemController.java
- TokenService.java
- AuthUserServiceImpl.java
- AuthIdentityServiceImpl.java
- AuthUserMapper.java
- AuthIdentityMapper.java
- JwtAuthenticationFilter.java
- DataScopeInterceptor.java
章节来源
- AuthController.java
- SystemController.java
- SecurityConfig.java
核心组件
- 认证控制器：提供登录、登出、刷新令牌、获取当前用户信息等接口
- 系统控制器：提供用户列表查询、用户统计等管理功能
- 令牌服务：生成、校验、刷新JWT令牌，管理令牌生命周期
- JWT过滤器：从请求头解析并验证JWT，建立安全上下文
- 用户/身份服务：查询用户与身份信息，支撑登录与用户信息接口
- 统一结果与异常：标准化响应结构与全局异常处理
章节来源
- AuthController.java
- SystemController.java
- TokenService.java
- JwtAuthenticationFilter.java
- AuthUserServiceImpl.java
- AuthIdentityServiceImpl.java
- Result.java
- ResultCodeEnum.java
架构总览
认证流程的关键交互如下：
- 登录：客户端提交用户名/密码，服务端校验后签发JWT
- 受保护接口：客户端携带JWT，过滤器校验后放行
- 刷新令牌：使用刷新令牌换取新访问令牌
- 用户信息：基于已认证的上下文返回用户详情
- 用户管理：管理员通过系统控制器进行用户列表查询和统计
sequenceDiagram
participant C as "客户端"
participant F as "JwtAuthenticationFilter"
participant A as "AuthController"
participant S as "SystemController"
participant T as "TokenService"
participant U as "AuthUserServiceImpl"
participant I as "AuthIdentityServiceImpl"
Note over C,A : 登录流程
C->>A : POST /auth/login
A->>U : 校验用户凭据
U-->>A : 用户信息
A->>T : 生成访问令牌与刷新令牌
T-->>A : 令牌对象
A-->>C : 登录成功响应
Note over C,F : 受保护接口访问
C->>F : 携带Authorization : Bearer <token>
F->>F : 解析并校验JWT
F-->>S : 建立安全上下文
S-->>C : 用户列表或统计信息
图表来源
- AuthController.java
- SystemController.java
- JwtAuthenticationFilter.java
- TokenService.java
- AuthUserServiceImpl.java
- AuthIdentityServiceImpl.java
详细组件分析
认证控制器接口定义
- 登录
- HTTP方法：POST
- URL路径：/auth/login
- 请求体：用户名、密码（具体字段以LoginParam为准）
- 响应体：登录结果（包含访问令牌、刷新令牌、过期时间等，参考LoginResultDTO）
- 鉴权：无需鉴权
- 错误码：未找到用户、密码错误、参数缺失等（由全局异常处理器统一返回）
- 登出
- HTTP方法：POST
- URL路径：/auth/logout
- 请求体：无或可选令牌失效标识
- 响应体：标准成功响应
- 鉴权：需要有效访问令牌
- 错误码：令牌无效、会话不存在等
- 刷新令牌
- HTTP方法：POST
- URL路径：/auth/refresh
- 请求体：刷新令牌
- 响应体：新的访问令牌及过期时间
- 鉴权：无需鉴权（仅校验刷新令牌有效性）
- 错误码：刷新令牌无效、已过期等
- 获取当前用户信息
- HTTP方法：GET
- URL路径：/auth/user/info
- 请求体：无
- 响应体：用户基本信息（参考UserInfoDTO）
- 鉴权：需要有效访问令牌
- 错误码：未登录、用户不存在等
章节来源
- AuthController.java
- LoginParam.java
- LoginResultDTO.java
- UserInfoDTO.java
系统控制器接口定义（新增）
- 用户列表查询
- HTTP方法：GET
- URL路径：/system/users
- 请求参数：分页参数、搜索条件（用户名、状态等）
- 响应体：用户列表分页结果（参考UserListDTO）
- 鉴权：需要管理员权限
- 错误码：权限不足、参数错误等
- 用户统计信息
- HTTP方法：GET
- URL路径：/system/users/stats
- 请求参数：统计维度（按部门、角色、状态等）
- 响应体：用户统计数据（参考UserStatsVO）
- 鉴权：需要管理员权限
- 错误码：权限不足、统计维度无效等
新增 系统控制器提供了完整的用户管理能力，支持分页查询、条件筛选和统计分析功能。
章节来源
- SystemController.java
- UserPageParam.java
- UserListDTO.java
- UserStatsVO.java
令牌服务与JWT过滤器
- 令牌服务职责
- 生成访问令牌与刷新令牌
- 校验令牌签名与有效期
- 刷新令牌换取新访问令牌
- JWT过滤器职责
- 从请求头提取Authorization
- 解析并校验JWT
- 将用户信息注入安全上下文供后续接口使用
classDiagram
class TokenService {
+generateAccessToken(user) string
+generateRefreshToken(user) string
+validateToken(token) bool
+refreshAccessToken(refreshToken) string
}
class JwtAuthenticationFilter {
+doFilter(request, response, chain) void
-parseToken(request) string
-validateAndSetContext(token) void
}
TokenService <.. JwtAuthenticationFilter : "校验与刷新"
图表来源
- TokenService.java
- JwtAuthenticationFilter.java
章节来源
- TokenService.java
- JwtAuthenticationFilter.java
用户与身份服务
- 用户服务
- 根据用户名查询用户
- 校验密码
- 组装用户上下文
- 支持用户列表分页查询
- 提供用户统计分析功能
- 身份服务
- 查询用户身份关联信息
- 支持第三方身份集成（如钉钉等）
flowchart TD
Start(["登录入口"]) --> CheckParams["校验请求参数"]
CheckParams --> QueryUser["查询用户信息"]
QueryUser --> UserFound{"用户存在?"}
UserFound --> |否| ReturnError["返回用户不存在"]
UserFound --> |是| VerifyPwd["校验密码"]
VerifyPwd --> PwdOk{"密码正确?"}
PwdOk --> |否| ReturnPwdErr["返回密码错误"]
PwdOk --> |是| GenTokens["生成访问与刷新令牌"]
GenTokens --> ReturnSuccess["返回登录成功响应"]
图表来源
- AuthUserServiceImpl.java
- AuthIdentityServiceImpl.java
- AuthUserMapper.java
- AuthIdentityMapper.java
章节来源
- AuthUserServiceImpl.java
- AuthIdentityServiceImpl.java
- IAuthUserService.java
- IAuthIdentityService.java
数据权限与安全配置
- 数据范围拦截器：在查询时自动附加数据范围条件
- 安全配置：注册过滤器、白名单路径、跨域策略等
graph LR
SC["SecurityConfig"] --> JAF["JwtAuthenticationFilter"]
SC --> DSI["DataScopeInterceptor"]
DSI --> DST["DataScopeTables"]
图表来源
- SecurityConfig.java
- DataScopeInterceptor.java
- DataScopeTables.java
章节来源
- SecurityConfig.java
- DataScopeInterceptor.java
- DataScopeTables.java
依赖关系分析
- 控制器依赖服务层进行业务处理
- 服务层依赖Mapper进行数据访问
- 安全过滤器与令牌服务贯穿所有受保护接口
- 统一异常与结果封装确保一致的响应格式
graph TB
AC["AuthController"] --> AUIS["AuthUserServiceImpl"]
AC --> AIS["AuthIdentityServiceImpl"]
SC["SystemController"] --> AUIS
SC --> AIS
AUIS --> AUM["AuthUserMapper"]
AIS --> AIM["AuthIdentityMapper"]
AC --> TS["TokenService"]
AC --> JAF["JwtAuthenticationFilter"]
AC --> DSI["DataScopeInterceptor"]
图表来源
- AuthController.java
- SystemController.java
- AuthUserServiceImpl.java
- AuthIdentityServiceImpl.java
- AuthUserMapper.java
- AuthIdentityMapper.java
- TokenService.java
- JwtAuthenticationFilter.java
- DataScopeInterceptor.java
章节来源
- AuthController.java
- SystemController.java
- AuthService.java
性能考虑
- 令牌缓存：对频繁的用户信息查询可引入本地或分布式缓存以减少数据库压力
- 连接池：合理配置数据库连接池大小，避免连接耗尽
- 令牌长度：控制JWT负载大小，避免过大影响网络传输
- 限流策略：对登录与刷新接口实施速率限制，防止暴力破解与滥用
- 异步处理：耗时操作（如第三方身份校验）建议异步化
- 分页查询：用户列表查询必须使用分页，避免一次性加载大量数据
- 索引优化：为用户查询常用字段建立合适的数据库索引
[本节为通用指导，不直接分析具体文件]
故障排查指南
- 常见错误类型
- 参数缺失：检查请求体字段是否完整
- 用户不存在：确认用户名是否正确且已激活
- 密码错误：提示用户重试或重置密码
- 令牌无效：检查Authorization头格式与令牌是否过期
- 权限不足：检查用户角色与资源权限配置
- 分页参数错误：检查页码和每页数量是否在合理范围内
- 全局异常处理
- 统一异常处理器捕获业务异常并返回标准错误响应
- 日志与追踪
- 启用请求链路追踪以便定位问题
- 用户列表查询问题
- 检查分页参数是否有效
- 验证搜索条件是否符合预期
- 确认用户权限是否足够访问目标数据
章节来源
- GlobalExceptionHandlerAdvice.java
- BusinessErrorException.java
- PermissionErrorException.java
- ResourceNotExistException.java
- MissingParameterException.java
- Result.java
- ResultCodeEnum.java
结论
本认证模块通过清晰的层次划分与统一的异常处理机制，提供了稳定可靠的登录、登出、令牌刷新、用户信息查询以及用户列表管理功能。新增的系统控制器接口增强了用户管理能力，支持分页查询和统计分析。建议在接入时遵循最佳实践，结合限流与缓存优化性能，并通过完善的日志与监控保障系统稳定性。
[本节为总结性内容，不直接分析具体文件]
附录
接口清单与示例
- 登录
- 方法：POST
- 路径：/auth/login
- 请求体：{ "username": "string", "password": "string" }
- 响应体：{ "code": "number", "message": "string", "data": { "accessToken": "string", "refreshToken": "string", "expiresIn": "number" } }
- 鉴权：无
- 错误码：400参数缺失、401凭证错误、404用户不存在
- 登出
- 方法：POST
- 路径：/auth/logout
- 请求体：无
- 响应体：{ "code": "number", "message": "string", "data": null }
- 鉴权：需要有效访问令牌
- 错误码：401令牌无效、403权限不足
- 刷新令牌
- 方法：POST
- 路径：/auth/refresh
- 请求体：{ "refreshToken": "string" }
- 响应体：{ "code": "number", "message": "string", "data": { "accessToken": "string", "expiresIn": "number" } }
- 鉴权：无
- 错误码：400参数缺失、401刷新令牌无效
- 获取当前用户信息
- 方法：GET
- 路径：/auth/user/info
- 请求体：无
- 响应体：{ "code": "number", "message": "string", "data": { "userId": "string", "username": "string", "roles": ["string"], "permissions": ["string"] } }
- 鉴权：需要有效访问令牌
- 错误码：401未登录、404用户不存在
- 用户列表查询（新增）
- 方法：GET
- 路径：/system/users
- 请求参数：page=1&size=10&username=&status=
- 响应体：{ "code": "number", "message": "string", "data": { "records": [...], "total": "number", "current": "number", "size": "number" } }
- 鉴权：需要管理员权限
- 错误码：401未授权、403权限不足、400参数错误
- 用户统计信息（新增）
- 方法：GET
- 路径：/system/users/stats
- 请求参数：dimension=department|role|status
- 响应体：{ "code": "number", "message": "string", "data": { "totalUsers": "number", "byDepartment": {...}, "byRole": {...}, "byStatus": {...} } }
- 鉴权：需要管理员权限
- 错误码：401未授权、403权限不足、400统计维度无效
鉴权方式
- 访问令牌：Bearer Token，置于请求头 Authorization: Bearer
- 刷新令牌：用于换取新的访问令牌，需妥善保管
- 白名单接口：登录、刷新等接口无需鉴权
- 管理员权限：用户管理接口需要特定的管理员角色权限
调用频率限制
- 登录接口：建议限制同一IP每分钟不超过10次
- 刷新接口：建议限制同一用户每小时不超过50次
- 用户列表查询：建议限制同一用户每分钟不超过30次
- 统计接口：建议限制同一用户每分钟不超过10次
- 其他接口：按业务需求配置限流策略
最佳实践
- 前端存储：使用安全的存储方式保存令牌，避免XSS攻击
- 令牌轮换：定期刷新访问令牌，缩短有效期
- 错误处理：统一处理异常并给出友好提示
- 监控告警：对失败率与延迟进行监控与告警
- 分页查询：用户列表查询必须使用分页，避免大数据量传输
- 权限控制：严格区分普通用户和管理员权限
- 数据脱敏：敏感信息在响应中进行适当脱敏处理
[本节为概念性内容，不直接分析具体文件]