luoweijian
/
crm-backend-matt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
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.
16 Commits
1 Branch
0 Tags
401 MiB
 
 
 
 
 
Tree: 4759518aa0
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '4759518aa0'
${ noResults }
crm-backend-matt/.qoder/repowiki/zh/content/认证服务/认证服务.md

37 KiB
Raw Blame History

认证服务

**本文引用的文件** - [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java) - [application.yml](file://crm-app/src/main/resources/application.yml) - [AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java) - [application.yml](file://crm-auth/src/main/resources/application.yml) - [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java) - [PermissionConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/PermissionConfig.java) - [DataInitializer.java](file://crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java) - [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java) - [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) - [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) - [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRole.java) - [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java) - [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java) - [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java) - [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java) - [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.java) - [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java) - [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java) - [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.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) - [AuthLoginUser.java](file://crm-auth/src/main/java/com/crm/auth/security/AuthLoginUser.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) - [SecurityExceptionHandlers.java](file://crm-auth/src/main/java/com/crm/auth/security/SecurityExceptionHandlers.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) - [IAuthUserService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthUserService.java) - [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java) - [ISysRoleService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysRoleService.java) - [SysRoleServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysRoleServiceImpl.java) - [ISysMenuService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysMenuService.java) - [SysMenuServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysMenuServiceImpl.java) - [ISysDeptService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysDeptService.java) - [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.java) - [DeptTreeCache.java](file://crm-auth/src/main/java/com/crm/auth/service/DeptTreeCache.java) - [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java) - [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java) - [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java) - [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java) - [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java) - [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.java) - [DataOwnership.java](file://crm-base/src/main/java/com/crm/base/security/DataOwnership.java) - [DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java) - [DataScopeLevel.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeLevel.java) - [DataVisibilityContext.java](file://crm-base/src/main/java/com/crm/base/security/DataVisibilityContext.java) - [LoginUser.java](file://crm-base/src/main/java/com/crm/base/security/LoginUser.java) - [SecurityUtils.java](file://crm-base/src/main/java/com/crm/base/security/SecurityUtils.java) - [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java) - [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.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) - [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.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) - [TraceIdFilter.java](file://crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java) - [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java) - [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java) - [JacksonConfig.java](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java) - [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java) - [SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java) - [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java) - [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java) - [InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java) - [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java) - [CorsConfig.java](file://crm-base/src/main/java/com/crm/base/config/CorsConfig.java) - [Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java) - [ScheduledTaskProperties.java](file://crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java) - [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java) - [AssertUtils.java](file://crm-base/src/main/java/com/crm/base/utils/AssertUtils.java) - [BeanCopyUtils.java](file://crm-base/src/main/java/com/crm/base/utils/BeanCopyUtils.java) - [EnumUtils.java](file://crm-base/src/main/java/com/crm/base/utils/EnumUtils.java) - [ExcelUtil.java](file://crm-base/src/main/java/com/crm/base/utils/ExcelUtil.java) - [PageConverter.java](file://crm-base/src/main/java/com/crm/base/utils/PageConverter.java) - [ServletUtils.java](file://crm-base/src/main/java/com/crm/base/utils/ServletUtils.java) - [TreeUtils.java](file://crm-base/src/main/java/com/crm/base/utils/TreeUtils.java)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本技术文档围绕认证服务的用户认证、授权管理、权限控制等核心能力展开，涵盖JWT令牌机制、RBAC角色权限模型、数据权限控制、第三方登录集成等特性。同时提供用户管理、角色管理、菜单权限、部门管理等业务功能的API接口说明与使用示例，并解释安全过滤器链、异常处理、会话管理等安全机制，最后给出完整的配置指南与最佳实践建议。

项目结构

认证服务由应用启动模块与认证功能模块组成：

  • crm-app：应用入口与全局配置
  • crm-auth：认证与权限核心实现（控制器、服务、安全、领域模型、枚举、参数与DTO）
  • crm-base：通用基础能力（异常、结果封装、安全上下文、数据可见性、工具类、配置等）
graph TB
subgraph "应用层"
App["CrmAppApplication<br/>应用启动"]
end
subgraph "认证模块(crm-auth)"
AuthApp["AuthApplication<br/>认证应用启动"]
SecCfg["SecurityConfig<br/>安全配置"]
PermCfg["PermissionConfig<br/>权限配置"]
CtlAuth["AuthController<br/>认证接口"]
CtlSys["SystemController<br/>系统接口"]
SvcAuth["AuthServiceImpl<br/>认证服务"]
SvcUser["AuthUserServiceImpl<br/>用户服务"]
SvcRole["SysRoleServiceImpl<br/>角色服务"]
SvcMenu["SysMenuServiceImpl<br/>菜单服务"]
SvcDept["SysDeptServiceImpl<br/>部门服务"]
JwtF["JwtAuthenticationFilter<br/>JWT过滤器"]
TokS["TokenService<br/>令牌服务"]
DpIntc["DataScopeInterceptor<br/>数据范围拦截器"]
Cache["DeptTreeCache<br/>部门树缓存"]
end
subgraph "基础模块(crm-base)"
BaseEx["GlobalExceptionHandlerAdvice<br/>全局异常处理"]
SecCtx["SecurityUtils / LoginUser<br/>安全上下文"]
DataVis["DataScopeHelper / DataVisibilityContext<br/>数据可见性"]
MyBatis["MybatisPlusConfig<br/>持久化配置"]
Redis["RedisConfig<br/>缓存配置"]
Jackson["JacksonConfig<br/>序列化配置"]
Snow["SnowflakeIdWorker<br/>雪花ID生成"]
end
App --> AuthApp
AuthApp --> SecCfg
SecCfg --> JwtF
JwtF --> TokS
CtlAuth --> SvcAuth
CtlSys --> SvcUser
CtlSys --> SvcRole
CtlSys --> SvcMenu
CtlSys --> SvcDept
SvcAuth --> TokS
SvcUser --> SvcRole
SvcRole --> SvcMenu
SvcDept --> Cache
SecCfg --> DpIntc
DpIntc --> DataVis
SvcAuth --> SecCtx
SvcUser --> SecCtx
SvcRole --> SecCtx
SvcMenu --> SecCtx
SvcDept --> SecCtx

图表来源

  • CrmAppApplication.java
  • AuthApplication.java
  • SecurityConfig.java
  • JwtAuthenticationFilter.java
  • TokenService.java
  • AuthController.java
  • SystemController.java
  • AuthServiceImpl.java
  • AuthUserServiceImpl.java
  • SysRoleServiceImpl.java
  • SysMenuServiceImpl.java
  • SysDeptServiceImpl.java
  • DeptTreeCache.java
  • DataScopeInterceptor.java
  • GlobalExceptionHandlerAdvice.java
  • SecurityUtils.java
  • DataScopeHelper.java
  • MybatisPlusConfig.java
  • RedisConfig.java
  • JacksonConfig.java
  • SnowflakeIdWorker.java

章节来源

  • CrmAppApplication.java
  • AuthApplication.java
  • application.yml
  • application.yml

核心组件

  • 安全配置与安全过滤器链
    • SecurityConfig：定义请求白名单、鉴权规则、跨域、异常处理等
    • JwtAuthenticationFilter：解析请求头中的JWT，构建认证上下文
    • TokenService：JWT的签发、校验、刷新、注销等
  • 认证与授权服务
    • IAuthService/AuthServiceImpl：登录、登出、密码校验、第三方登录流程编排
    • IAuthUserService/AuthUserServiceImpl：用户CRUD、密码策略、状态管理
    • ISysRoleService/SysRoleServiceImpl：角色CRUD、角色-用户关联
    • ISysMenuService/SysMenuServiceImpl：菜单树、按钮权限、角色-菜单关联
    • ISysDeptService/SysDeptServiceImpl：部门树、用户-部门关联
  • 数据权限控制
    • DataScopeInterceptor：基于注解的数据范围注入SQL片段
    • DataScopeHelper/DataVisibilityContext：数据可见性上下文与计算
    • DataScope/@DataScope：声明式数据范围控制
  • 第三方登录集成
    • ThirdPartyAuthClientFactory：按类型创建第三方客户端
    • DingTalkAuthClient：钉钉登录实现
    • ThirdPartyAuthClient/ThirdPartyUserInfo：统一抽象与用户信息模型
  • 基础能力
    • GlobalExceptionHandlerAdvice：统一异常响应
    • Result/ResultCodeEnum：统一返回体与错误码
    • SecurityUtils/LoginUser：当前登录用户上下文
    • MybatisPlusConfig/RedisConfig/JacksonConfig/SnowflakeIdWorker：持久化、缓存、序列化、ID生成

章节来源

  • SecurityConfig.java
  • JwtAuthenticationFilter.java
  • TokenService.java
  • IAuthService.java
  • AuthServiceImpl.java
  • IAuthUserService.java
  • AuthUserServiceImpl.java
  • ISysRoleService.java
  • SysRoleServiceImpl.java
  • ISysMenuService.java
  • SysMenuServiceImpl.java
  • ISysDeptService.java
  • SysDeptServiceImpl.java
  • DataScopeInterceptor.java
  • DataScopeHelper.java
  • DataVisibilityContext.java
  • DataScope.java
  • ThirdPartyAuthClientFactory.java
  • DingTalkAuthClient.java
  • ThirdPartyAuthClient.java
  • ThirdPartyUserInfo.java
  • GlobalExceptionHandlerAdvice.java
  • Result.java
  • ResultCodeEnum.java
  • SecurityUtils.java
  • LoginUser.java
  • MybatisPlusConfig.java
  • RedisConfig.java
  • JacksonConfig.java
  • SnowflakeIdWorker.java

架构总览

认证服务采用分层架构与模块化设计：

  • 表现层：控制器暴露REST API
  • 服务层：业务编排与领域逻辑
  • 安全层：过滤器链、令牌服务、权限校验、数据范围拦截
  • 数据层：MyBatis Plus映射与数据库交互
  • 基础设施：Redis缓存、雪花ID、统一异常与结果封装
sequenceDiagram
participant Client as "客户端"
participant Filter as "JwtAuthenticationFilter"
participant Controller as "AuthController"
participant Service as "AuthServiceImpl"
participant Token as "TokenService"
participant DB as "数据库"
participant Cache as "Redis"
Client->>Filter : "携带Authorization请求"
Filter->>Filter : "解析JWT并校验签名"
Filter-->>Client : "未通过则拒绝访问"
Client->>Controller : "POST /auth/login"
Controller->>Service : "login(LoginParam)"
Service->>DB : "查询用户与身份"
DB-->>Service : "用户实体与角色/菜单"
Service->>Token : "生成JWT(含用户、角色、权限)"
Token->>Cache : "写入会话/黑名单(可选)"
Token-->>Service : "返回token"
Service-->>Controller : "LoginResultDTO"
Controller-->>Client : "200 OK {token, userInfo}"

图表来源

  • JwtAuthenticationFilter.java
  • AuthController.java
  • AuthServiceImpl.java
  • TokenService.java

详细组件分析

安全配置与过滤器链

  • SecurityConfig：集中配置放行路径、鉴权规则、跨域、异常处理器；注册数据范围拦截器
  • JwtAuthenticationFilter：从请求头提取JWT，调用TokenService完成校验与上下文填充
  • TokenService：负责JWT的创建、解析、续期、撤销；支持将令牌或黑名单存入Redis
  • 数据范围拦截器：在方法执行前注入数据范围条件，影响后续SQL
classDiagram
class SecurityConfig {
+配置白名单()
+配置鉴权规则()
+注册异常处理器()
+注册数据范围拦截器()
}
class JwtAuthenticationFilter {
+doFilter(request,response,chain)
+parseAndValidate(token)
}
class TokenService {
+createToken(user,roles,perms)
+validate(token)
+refresh(token)
+revoke(token)
}
class DataScopeInterceptor {
+preHandle(request,response,handler)
+buildScopeCondition()
}
SecurityConfig --> JwtAuthenticationFilter : "注册"
JwtAuthenticationFilter --> TokenService : "校验令牌"
SecurityConfig --> DataScopeInterceptor : "注册"

图表来源

  • SecurityConfig.java
  • JwtAuthenticationFilter.java
  • TokenService.java
  • DataScopeInterceptor.java

章节来源

  • SecurityConfig.java
  • JwtAuthenticationFilter.java
  • TokenService.java
  • DataScopeInterceptor.java

认证流程与JWT令牌机制

  • 登录流程：验证用户名/密码或第三方凭证，加载用户、角色、菜单权限，生成JWT并返回
  • 令牌内容：包含用户标识、角色集合、权限点集合、过期时间等
  • 令牌校验：过滤器自动解析并填充安全上下文，后续接口无需重复鉴权
  • 令牌刷新与注销：支持刷新过期令牌、主动注销使令牌失效
flowchart TD
Start(["开始"]) --> Parse["解析登录参数"]
Parse --> Validate{"参数有效?"}
Validate --> |否| Err["返回参数错误"]
Validate --> |是| LoadUser["加载用户与身份"]
LoadUser --> CheckPwd{"密码/凭证校验"}
CheckPwd --> |失败| Fail["返回认证失败"]
CheckPwd --> |成功| BuildPerms["构建角色与权限集合"]
BuildPerms --> GenToken["生成JWT令牌"]
GenToken --> SaveSession["写入会话/黑名单(可选)"]
SaveSession --> Return["返回登录结果"]
Return --> End(["结束"])
Err --> End
Fail --> End

图表来源

  • AuthController.java
  • AuthServiceImpl.java
  • TokenService.java

章节来源

  • AuthController.java
  • AuthServiceImpl.java
  • TokenService.java

RBAC权限模型与菜单权限

  • 角色-用户多对多：用户可拥有多个角色
  • 角色-菜单多对多：角色可访问多个菜单与按钮
  • 菜单类型：目录、菜单、按钮，用于前端路由与操作权限控制
  • 数据权限：通过数据范围枚举控制可见数据范围
erDiagram
AUTH_USER ||--o{ SYS_USER_ROLE : "拥有"
SYS_ROLE ||--o{ SYS_USER_ROLE : "分配给"
SYS_ROLE ||--o{ SYS_ROLE_MENU : "包含"
SYS_MENU ||--o{ SYS_ROLE_MENU : "被包含"
AUTH_USER ||--o{ SYS_USER_DEPT : "属于"
SYS_DEPT ||--o{ SYS_USER_DEPT : "包含"
AUTH_USER {
bigint id PK
string username
string password
int status
}
SYS_ROLE {
bigint id PK
string role_code
string role_name
}
SYS_MENU {
bigint id PK
string menu_code
string menu_name
enum type
int sort
}
SYS_DEPT {
bigint id PK
string dept_name
int parent_id
}
SYS_USER_ROLE {
bigint user_id FK
bigint role_id FK
}
SYS_ROLE_MENU {
bigint role_id FK
bigint menu_id FK
}
SYS_USER_DEPT {
bigint user_id FK
bigint dept_id FK
}

图表来源

  • AuthUser.java
  • SysRole.java
  • SysMenu.java
  • SysDept.java
  • SysUserRole.java
  • SysRoleMenu.java
  • SysUserDept.java
  • MenuTypeEnum.java
  • DataScopeEnum.java

章节来源

  • SysRoleServiceImpl.java
  • SysMenuServiceImpl.java
  • SysDeptServiceImpl.java
  • AuthUserServiceImpl.java

数据权限控制

  • 注解驱动：@DataScope声明数据范围级别（全部、本部门、本部门及子部门、仅本人等）
  • 拦截器注入：DataScopeInterceptor在方法执行前根据当前用户与注解动态拼接WHERE条件
  • 上下文支撑：DataVisibilityContext维护当前可见数据范围，供查询辅助方法使用
flowchart TD
Enter(["进入受保护方法"]) --> CheckAnno{"存在@DataScope?"}
CheckAnno --> |否| Proceed["直接执行业务逻辑"]
CheckAnno --> |是| Resolve["解析数据范围级别"]
Resolve --> BuildCond["构建SQL数据范围条件"]
BuildCond --> Inject["注入到查询上下文"]
Inject --> Proceed
Proceed --> Exit(["退出"])

图表来源

  • DataScopeInterceptor.java
  • DataScope.java
  • DataScopeHelper.java
  • DataVisibilityContext.java

章节来源

  • DataScopeInterceptor.java
  • DataScope.java
  • DataScopeHelper.java
  • DataVisibilityContext.java

第三方登录集成

  • 工厂模式：ThirdPartyAuthClientFactory根据类型创建对应第三方客户端
  • 统一接口：ThirdPartyAuthClient定义标准方法，如获取用户信息、绑定本地账号
  • 钉钉集成：DingTalkAuthClient实现钉钉OAuth流程与用户信息映射
  • 用户信息模型：ThirdPartyUserInfo标准化第三方返回的用户属性
classDiagram
class ThirdPartyAuthClientFactory {
+getClient(type) ThirdPartyAuthClient
}
class ThirdPartyAuthClient {
+getUserInfo(code) ThirdPartyUserInfo
+bindLocalAccount(userInfo) AuthUser
}
class DingTalkAuthClient {
+getUserInfo(code) ThirdPartyUserInfo
+bindLocalAccount(userInfo) AuthUser
}
class ThirdPartyUserInfo {
+string openId
+string nickname
+string avatar
+map extra
}
ThirdPartyAuthClientFactory --> ThirdPartyAuthClient : "创建实例"
DingTalkAuthClient ..|> ThirdPartyAuthClient

图表来源

  • ThirdPartyAuthClientFactory.java
  • ThirdPartyAuthClient.java
  • DingTalkAuthClient.java
  • ThirdPartyUserInfo.java

章节来源

  • ThirdPartyAuthClientFactory.java
  • DingTalkAuthClient.java
  • ThirdPartyAuthClient.java
  • ThirdPartyUserInfo.java

用户、角色、菜单、部门管理API

  • 用户管理
    • 新增/修改/删除/分页查询用户
    • 重置密码、启用/禁用状态
    • 绑定/解绑角色与部门
  • 角色管理
    • 新增/修改/删除/分页查询角色
    • 分配/回收菜单权限
    • 查看角色拥有的菜单树
  • 菜单管理
    • 新增/修改/删除/分页查询菜单
    • 构建菜单树（目录/菜单/按钮）
    • 按角色获取可用菜单
  • 部门管理
    • 新增/修改/删除/分页查询部门
    • 构建部门树
    • 用户-部门关联管理
sequenceDiagram
participant Admin as "管理员"
participant SysCtl as "SystemController"
participant RoleSvc as "SysRoleServiceImpl"
participant MenuSvc as "SysMenuServiceImpl"
participant DeptSvc as "SysDeptServiceImpl"
Admin->>SysCtl : "GET /system/role/list"
SysCtl->>RoleSvc : "list(page,param)"
RoleSvc-->>SysCtl : "分页结果"
SysCtl-->>Admin : "Result<List<Role>>"
Admin->>SysCtl : "POST /system/menu/tree"
SysCtl->>MenuSvc : "tree(roleId?)"
MenuSvc-->>SysCtl : "菜单树"
SysCtl-->>Admin : "Result<List<Menu>>"
Admin->>SysCtl : "POST /system/dept/tree"
SysCtl->>DeptSvc : "tree()"
DeptSvc-->>SysCtl : "部门树"
SysCtl-->>Admin : "Result<List<Dept>>"

图表来源

  • SystemController.java
  • SysRoleServiceImpl.java
  • SysMenuServiceImpl.java
  • SysDeptServiceImpl.java

章节来源

  • SystemController.java
  • SysRoleServiceImpl.java
  • SysMenuServiceImpl.java
  • SysDeptServiceImpl.java

会话管理与缓存

  • 会话存储：TokenService可将令牌或黑名单写入Redis，支持分布式环境下的令牌校验与注销
  • 部门树缓存：DeptTreeCache缓存部门树结构，减少频繁查询数据库
  • 配置项：通过AuthProperties与RedisConfig进行相关配置

章节来源

  • TokenService.java
  • DeptTreeCache.java
  • AuthProperties.java
  • RedisConfig.java

依赖关系分析

  • 模块内依赖
    • 控制器依赖服务层，服务层依赖领域模型与Mapper
    • 安全过滤器依赖令牌服务与安全上下文
    • 数据范围拦截器依赖数据可见性上下文
  • 模块间依赖
    • crm-auth依赖crm-base提供的异常、结果、安全上下文、工具类与配置
    • crm-app作为应用入口聚合各模块
graph LR
Ctl["控制器层"] --> Svc["服务层"]
Svc --> Model["领域模型/枚举"]
Svc --> Mapper["数据访问层"]
Filter["安全过滤器"] --> Token["令牌服务"]
Filter --> Ctx["安全上下文"]
Intc["数据范围拦截器"] --> Vis["数据可见性"]
AuthMod["crm-auth"] --> BaseMod["crm-base"]
AppMod["crm-app"] --> AuthMod

图表来源

  • AuthController.java
  • AuthServiceImpl.java
  • JwtAuthenticationFilter.java
  • TokenService.java
  • DataScopeInterceptor.java
  • DataVisibilityContext.java

章节来源

  • AuthController.java
  • AuthServiceImpl.java
  • JwtAuthenticationFilter.java
  • TokenService.java
  • DataScopeInterceptor.java
  • DataVisibilityContext.java

性能考虑

  • JWT无状态校验：服务端仅需校验签名与过期时间，降低会话存储压力
  • 缓存优化：部门树缓存、菜单树缓存可减少数据库访问
  • 批量操作：插入时使用批处理与去重更新策略提升写入性能
  • 索引设计：为常用查询字段建立索引（用户名、角色编码、菜单编码、部门父级等）
  • 连接池与超时：合理配置数据库连接池与Redis连接池，避免资源耗尽

[本节为通用指导，不直接分析具体文件]

故障排查指南

  • 常见异常
    • 认证失败：检查用户名/密码或第三方凭证是否正确
    • 权限不足：确认用户是否具备所需角色与菜单权限
    • 数据不可见：检查@DataScope注解与用户所属部门/角色数据范围
    • 令牌无效：检查Authorization头格式、令牌是否过期或被注销
  • 日志与追踪
    • 使用TraceIdFilter贯穿请求链路，便于定位问题
    • 全局异常处理器统一捕获并返回结构化错误信息
  • 调试建议
    • 开启Knife4j接口文档，快速验证接口行为
    • 检查Redis中令牌与黑名单状态
    • 查看数据库关联表（用户-角色、角色-菜单、用户-部门）一致性

章节来源

  • GlobalExceptionHandlerAdvice.java
  • TraceIdFilter.java
  • SecurityExceptionHandlers.java
  • Result.java
  • ResultCodeEnum.java

结论

认证服务以JWT为核心，结合RBAC与数据权限控制，提供了完整的安全体系。通过模块化设计与清晰的分层架构，实现了用户认证、授权管理、权限控制与第三方登录集成的统一方案。配合统一的异常处理、结果封装与缓存策略，具备良好的可扩展性与可维护性。

[本节为总结性内容，不直接分析具体文件]

附录

配置指南

  • 应用配置
    • application.yml：设置端口、数据库、Redis、JWT密钥与过期时间等
    • AuthProperties：认证相关自定义配置项
  • 安全配置
    • SecurityConfig：配置白名单、鉴权规则、跨域、异常处理器
    • PermissionConfig：权限相关配置
  • 基础配置
    • MybatisPlusConfig：分页、乐观锁、SQL注入器等
    • RedisConfig：连接池、序列化策略
    • JacksonConfig：日期、空值序列化策略
    • SnowflakeIdWorker：分布式ID生成策略

章节来源

  • application.yml
  • application.yml
  • AuthProperties.java
  • SecurityConfig.java
  • PermissionConfig.java
  • MybatisPlusConfig.java
  • RedisConfig.java
  • JacksonConfig.java
  • SnowflakeIdWorker.java

最佳实践建议

  • 令牌安全
    • 使用强密钥与合理的过期时间
    • 敏感操作二次校验（如密码修改、支付）
  • 权限设计
    • 最小权限原则，按需分配角色与菜单
    • 数据范围粒度适中，避免过度复杂
  • 缓存策略
    • 热点数据（部门树、菜单树）缓存，注意失效策略
    • 令牌黑名单与在线用户列表定期清理
  • 监控与审计
    • 记录登录、登出、权限变更等关键事件
    • 使用TraceId串联日志，便于问题定位

[本节为通用指导，不直接分析具体文件]