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.
18 KiB
18 KiB
认证核心功能
**本文引用的文件** - [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java) - [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java) - [IAuthService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthService.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) - [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java) - [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java) - [LoginParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/LoginParam.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) - [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java) - [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.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) - [AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java) - [application.yml](file://crm-auth/src/main/resources/application.yml)目录
简介
本文件围绕认证核心能力进行系统化说明，覆盖用户登录认证流程、JWT令牌生成与验证机制、会话管理实现。重点解析以下模块：
- AuthController中的登录接口
- AuthService中的认证逻辑（含密码校验、第三方登录扩展）
- JwtAuthenticationFilter中的过滤器链处理（请求鉴权、上下文注入）
- TokenService中的令牌管理服务（签发、刷新、过期策略） 同时涵盖密码加密存储、令牌刷新机制、登录状态管理等关键实现细节与使用示例。
项目结构
认证相关代码集中在 crm-auth 模块中，采用分层架构：
- 控制器层：对外暴露登录等接口
- 服务层：封装认证业务逻辑
- 安全层：过滤器、令牌服务、权限拦截器
- 领域模型：用户、身份、角色、菜单等实体及DTO/Param
- 数据访问层：MyBatis-Plus Mapper
- 配置层：安全配置、属性配置、应用启动类
graph TB
subgraph "crm-auth"
C["AuthController"] --> S["IAuthService / AuthServiceImpl"]
S --> M1["AuthUserMapper"]
S --> M2["AuthIdentityMapper"]
F["JwtAuthenticationFilter"] --> T["TokenService"]
F --> SC["SecurityConfig"]
T --> R["Redis(会话/黑名单)"]
A["AuthApplication"] --> SC
A --> C
end
图表来源
- AuthController.java
- AuthServiceImpl.java
- JwtAuthenticationFilter.java
- TokenService.java
- SecurityConfig.java
- AuthApplication.java
章节来源
- AuthController.java
- AuthServiceImpl.java
- JwtAuthenticationFilter.java
- TokenService.java
- SecurityConfig.java
- AuthApplication.java
核心组件
- AuthController：提供登录接口，接收登录参数并返回统一结果
- IAuthService/AuthServiceImpl：认证主流程，包含账号密码校验、第三方登录扩展、权限信息组装
- JwtAuthenticationFilter：Spring Security过滤器链中的JWT校验与上下文注入
- TokenService：JWT签发、解析、刷新、黑名单与过期管理
- SecurityConfig：安全过滤链、白名单、跨域等配置
- AuthProperties：JWT密钥、过期时间等认证相关配置
- 领域模型：LoginParam、LoginResultDTO、UserInfoDTO、AuthUser、AuthIdentity等
章节来源
- AuthController.java
- IAuthService.java
- AuthServiceImpl.java
- JwtAuthenticationFilter.java
- TokenService.java
- SecurityConfig.java
- AuthProperties.java
- LoginParam.java
- LoginResultDTO.java
- UserInfoDTO.java
架构总览
下图展示从HTTP请求到认证决策的完整链路，包括登录、鉴权、令牌签发与刷新。
sequenceDiagram
participant Client as "客户端"
participant Controller as "AuthController"
participant Service as "IAuthService"
participant DB as "AuthUserMapper/AuthIdentityMapper"
participant Token as "TokenService"
participant Filter as "JwtAuthenticationFilter"
participant Sec as "SecurityConfig"
Client->>Controller : "POST /auth/login"
Controller->>Service : "login(LoginParam)"
Service->>DB : "查询用户/身份"
DB-->>Service : "用户实体/身份信息"
Service->>Service : "密码校验/第三方校验"
Service->>Token : "签发JWT(含用户信息)"
Token-->>Service : "JWT字符串"
Service-->>Controller : "LoginResultDTO"
Controller-->>Client : "响应{token, userInfo}"
Note over Client,Sec : "后续请求携带Authorization : Bearer {token}"
Client->>Filter : "带Token的请求"
Filter->>Token : "解析并校验JWT"
Token-->>Filter : "Claims/是否有效"
Filter->>Sec : "设置SecurityContext"
Sec-->>Client : "放行或拒绝"
图表来源
- AuthController.java
- IAuthService.java
- AuthServiceImpl.java
- AuthUserMapper.java
- AuthIdentityMapper.java
- TokenService.java
- JwtAuthenticationFilter.java
- SecurityConfig.java
详细组件分析
AuthController 登录接口
- 职责：接收登录请求参数，调用认证服务，返回统一结果
- 输入：LoginParam（用户名/手机号/邮箱、密码、验证码等）
- 输出：LoginResultDTO（包含JWT、用户基本信息）
- 错误处理：参数校验失败、认证失败、系统异常统一包装为Result
章节来源
- AuthController.java
- LoginParam.java
- LoginResultDTO.java
IAuthService/AuthServiceImpl 认证逻辑
- 职责：实现登录主流程，包括账号密码校验、第三方登录扩展、权限信息组装
- 关键点：
- 根据标识类型（手机号/邮箱/用户名）定位用户
- 密码校验通过BCrypt或同类算法比对
- 支持第三方登录（如钉钉），通过ThirdPartyAuthClient获取外部用户信息并映射本地用户
- 组装用户信息与权限集合，供JWT载荷使用
- 扩展点：新增第三方登录源时，实现对应Client并在工厂中注册
flowchart TD
Start(["开始"]) --> Parse["解析登录参数"]
Parse --> FindUser["根据标识查找用户"]
FindUser --> UserFound{"找到用户?"}
UserFound --> |否| Error1["返回认证失败"]
UserFound --> |是| CheckPwd["校验密码/第三方授权"]
CheckPwd --> Valid{"校验通过?"}
Valid --> |否| Error2["返回认证失败"]
Valid --> |是| BuildInfo["构建用户信息与权限"]
BuildInfo --> IssueToken["调用TokenService签发JWT"]
IssueToken --> Return["返回LoginResultDTO"]
Error1 --> End(["结束"])
Error2 --> End
Return --> End
图表来源
- IAuthService.java
- AuthServiceImpl.java
- AuthUserMapper.java
- AuthIdentityMapper.java
章节来源
- IAuthService.java
- AuthServiceImpl.java
- AuthUser.java
- AuthIdentity.java
JwtAuthenticationFilter 过滤器链处理
- 职责：在Spring Security过滤器链中拦截请求，提取并校验JWT，注入当前登录用户上下文
- 处理流程：
- 从请求头提取Authorization
- 若存在且非空，调用TokenService解析并校验
- 校验通过后，将用户信息写入SecurityContext
- 未通过则直接拒绝或继续后续过滤器
- 白名单：由SecurityConfig配置，跳过鉴权的接口（如登录、健康检查）
sequenceDiagram
participant Client as "客户端"
participant Filter as "JwtAuthenticationFilter"
participant Token as "TokenService"
participant Sec as "SecurityConfig"
Client->>Filter : "HTTP请求(Authorization : Bearer ...)"
Filter->>Filter : "提取Token"
Filter->>Token : "解析并校验"
Token-->>Filter : "有效/无效"
alt "有效"
Filter->>Sec : "设置SecurityContext"
Filter-->>Client : "放行"
else "无效"
Filter-->>Client : "401/403"
end
图表来源
- JwtAuthenticationFilter.java
- TokenService.java
- SecurityConfig.java
章节来源
- JwtAuthenticationFilter.java
- SecurityConfig.java
TokenService 令牌管理服务
- 职责：JWT的签发、解析、刷新、黑名单与过期管理
- 核心能力：
- 签发：基于用户ID、角色、权限等信息生成JWT，设置过期时间
- 解析：校验签名、过期时间、黑名单；返回Claims
- 刷新：支持无感刷新，结合Redis记录刷新次数与滑动过期
- 黑名单：登出时将旧令牌的JTI加入黑名单，防止重用
- 会话：可选地维护在线用户列表与最近活跃时间
- 配置项：密钥、过期时间、刷新策略等来自AuthProperties
classDiagram
class TokenService {
+issue(user) String
+parse(token) Claims
+refresh(token) String
+blacklist(jti) void
+isBlacklisted(jti) boolean
+setOnline(userId, token) void
+removeOnline(userId) void
}
class AuthProperties {
+secretKey : String
+accessTokenExpire : long
+refreshTokenExpire : long
+blacklistEnabled : boolean
}
TokenService --> AuthProperties : "读取配置"
图表来源
- TokenService.java
- AuthProperties.java
章节来源
- TokenService.java
- AuthProperties.java
安全配置与启动
- SecurityConfig：定义过滤链、白名单、跨域、异常处理器等
- AuthApplication：应用入口，启用必要的注解与组件扫描
章节来源
- SecurityConfig.java
- AuthApplication.java
依赖关系分析
- 控制器依赖服务层，服务层依赖Mapper与第三方客户端
- 过滤器依赖TokenService与安全配置
- 配置中心集中管理JWT与认证相关参数
- Redis用于令牌黑名单与会话管理（由TokenService使用）
graph LR
AC["AuthController"] --> AS["IAuthService"]
AS --> AU["AuthUserMapper"]
AS --> AI["AuthIdentityMapper"]
JF["JwtAuthenticationFilter"] --> TS["TokenService"]
TS --> AP["AuthProperties"]
JF --> SC["SecurityConfig"]
图表来源
- AuthController.java
- IAuthService.java
- AuthUserMapper.java
- AuthIdentityMapper.java
- JwtAuthenticationFilter.java
- TokenService.java
- AuthProperties.java
- SecurityConfig.java
章节来源
- AuthController.java
- IAuthService.java
- JwtAuthenticationFilter.java
- TokenService.java
- AuthProperties.java
- SecurityConfig.java
性能考虑
- JWT解析开销：避免在高频路径重复解析，可在网关层缓存解析结果或使用短生命周期Access Token
- Redis访问：令牌黑名单与在线会话需控制读写频率，合理设置过期时间
- 数据库查询：用户与身份查询应加索引，避免N+1问题
- 并发安全：令牌刷新与黑名单操作需保证原子性，必要时使用分布式锁
- 序列化：用户信息DTO尽量精简，减少网络传输体积
[本节为通用指导，不直接分析具体文件]
故障排查指南
- 登录失败
- 检查LoginParam参数是否正确
- 确认用户是否存在、状态是否正常
- 核对密码加密算法与存储值一致
- 鉴权失败
- 检查Authorization头格式是否为Bearer
- 确认Token未被吊销且在有效期内
- 查看SecurityConfig白名单是否遗漏
- 令牌刷新异常
- 检查Refresh Token是否过期或被拉黑
- 确认Redis连接正常且键空间未污染
- 常见问题定位
- 查看日志中的认证失败原因码
- 检查AuthProperties配置项是否生效
- 使用调试工具打印SecurityContext内容
章节来源
- AuthController.java
- AuthServiceImpl.java
- JwtAuthenticationFilter.java
- TokenService.java
- application.yml
结论
本认证体系以JWT为核心，结合Spring Security过滤器链与Redis会话管理，实现了可扩展、可配置的登录认证与鉴权方案。通过清晰的层次划分与模块化设计，便于后续扩展第三方登录、细粒度权限控制与多端会话管理。建议在生产环境严格管理密钥、合理设置过期策略，并结合监控与审计提升安全性与可观测性。
[本节为总结性内容，不直接分析具体文件]
附录
- 使用示例（概念性步骤）
- 登录：POST /auth/login，提交LoginParam，服务端返回LoginResultDTO
- 访问受保护资源：在请求头添加Authorization: Bearer {token}
- 刷新令牌：调用刷新接口，传入有效的Refresh Token，获取新的Access Token
- 登出：调用登出接口，服务端将当前Token加入黑名单并清理会话
[本节为概念性说明，不直接分析具体文件]