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