|
|
|
|
# 认证API
|
|
|
|
|
|
|
|
|
|
<cite>
|
|
|
|
|
**本文引用的文件**
|
|
|
|
|
- [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)
|
|
|
|
|
- [PermissionConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/PermissionConfig.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)
|
|
|
|
|
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.java)
|
|
|
|
|
- [SecurityExceptionHandlers.java](file://crm-auth/src/main/java/com/crm/auth/security/SecurityExceptionHandlers.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)
|
|
|
|
|
- [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)
|
|
|
|
|
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
|
|
|
|
|
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
|
|
|
|
|
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)
|
|
|
|
|
- [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.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)
|
|
|
|
|
</cite>
|
|
|
|
|
|
|
|
|
|
## 更新摘要
|
|
|
|
|
**变更内容**
|
|
|
|
|
- 简化钉钉登录接口:从接收 LoginParam 对象(请求体)改为直接接收 authCode 参数(请求参数)
|
|
|
|
|
- 统一扫码登录和OAuth重定向流程,使用相同的底层认证机制
|
|
|
|
|
- 移除了第三方登录的复杂请求体结构,简化为简单的授权码传递
|
|
|
|
|
|
|
|
|
|
## 目录
|
|
|
|
|
1. [简介](#简介)
|
|
|
|
|
2. [项目结构](#项目结构)
|
|
|
|
|
3. [核心组件](#核心组件)
|
|
|
|
|
4. [架构总览](#架构总览)
|
|
|
|
|
5. [详细组件分析](#详细组件分析)
|
|
|
|
|
6. [依赖关系分析](#依赖关系分析)
|
|
|
|
|
7. [性能考虑](#性能考虑)
|
|
|
|
|
8. [故障排查指南](#故障排查指南)
|
|
|
|
|
9. [结论](#结论)
|
|
|
|
|
10. [附录](#附录)
|
|
|
|
|
|
|
|
|
|
## 简介
|
|
|
|
|
本文件为认证模块的API文档,覆盖用户登录、登出、获取当前用户信息、第三方登录(以钉钉为例)等接口。文档包含:
|
|
|
|
|
- HTTP方法、URL路径、请求参数、响应格式与状态码
|
|
|
|
|
- JWT令牌生成与校验机制
|
|
|
|
|
- OAuth2集成流程(面向第三方平台)
|
|
|
|
|
- 权限验证方式(基于角色与菜单)
|
|
|
|
|
- 密码加密策略、会话管理与安全最佳实践
|
|
|
|
|
- 完整请求/响应示例(成功与失败场景)
|
|
|
|
|
- 第三方平台(钉钉)集成配置与使用示例
|
|
|
|
|
|
|
|
|
|
## 项目结构
|
|
|
|
|
认证模块位于 crm-auth 子模块中,主要包含控制器、安全配置、服务层、领域模型与第三方客户端。基础能力(统一结果封装、全局异常处理、工具类)位于 crm-base 模块。
|
|
|
|
|
|
|
|
|
|
```mermaid
|
|
|
|
|
graph TB
|
|
|
|
|
subgraph "crm-auth"
|
|
|
|
|
AC["AuthController"]
|
|
|
|
|
SC["SystemController"]
|
|
|
|
|
SEC["SecurityConfig"]
|
|
|
|
|
PERM["PermissionConfig"]
|
|
|
|
|
JAF["JwtAuthenticationFilter"]
|
|
|
|
|
TS["TokenService"]
|
|
|
|
|
DSI["DataScopeInterceptor"]
|
|
|
|
|
SEH["SecurityExceptionHandlers"]
|
|
|
|
|
SVC["IAuthService / AuthServiceImpl"]
|
|
|
|
|
DP["AuthProperties"]
|
|
|
|
|
ENT["AuthUser / AuthIdentity / SysRole / SysMenu"]
|
|
|
|
|
DTO["LoginResultDTO / UserInfoDTO"]
|
|
|
|
|
DING["DingTalkAuthClient"]
|
|
|
|
|
TPC["ThirdPartyAuthClientFactory"]
|
|
|
|
|
end
|
|
|
|
|
subgraph "crm-base"
|
|
|
|
|
GHA["GlobalExceptionHandlerAdvice"]
|
|
|
|
|
RES["Result / ResultCodeEnum"]
|
|
|
|
|
end
|
|
|
|
|
AC --> SVC
|
|
|
|
|
SC --> SVC
|
|
|
|
|
AC --> TS
|
|
|
|
|
JAF --> TS
|
|
|
|
|
SEC --> JAF
|
|
|
|
|
SEC --> DSI
|
|
|
|
|
PERM --> SEC
|
|
|
|
|
SVC --> ENT
|
|
|
|
|
SVC --> DTO
|
|
|
|
|
DING --> TPC
|
|
|
|
|
AC --> DING
|
|
|
|
|
AC --> TPC
|
|
|
|
|
GHA --> RES
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
图表来源
|
|
|
|
|
- [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)
|
|
|
|
|
- [PermissionConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/PermissionConfig.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)
|
|
|
|
|
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.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)
|
|
|
|
|
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
|
|
|
|
|
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
|
|
|
|
|
- [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.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)
|
|
|
|
|
|
|
|
|
|
章节来源
|
|
|
|
|
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
|
|
|
|
|
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.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)
|
|
|
|
|
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.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)
|
|
|
|
|
|
|
|
|
|
## 核心组件
|
|
|
|
|
- 控制器层
|
|
|
|
|
- 认证控制器:提供登录、登出、获取当前用户信息等接口
|
|
|
|
|
- 系统控制器:提供系统级鉴权相关接口(如权限列表、菜单树等)
|
|
|
|
|
- 安全配置
|
|
|
|
|
- SecurityConfig:Spring Security配置,注册JWT过滤器、跨域、白名单等
|
|
|
|
|
- PermissionConfig:权限注解与数据权限拦截器装配
|
|
|
|
|
- 安全组件
|
|
|
|
|
- JwtAuthenticationFilter:从请求头解析JWT并构建认证上下文
|
|
|
|
|
- TokenService:JWT签发、校验、刷新与过期管理
|
|
|
|
|
- DataScopeInterceptor:数据范围拦截器,按角色/部门过滤数据
|
|
|
|
|
- SecurityExceptionHandlers:安全相关异常处理器
|
|
|
|
|
- 服务层
|
|
|
|
|
- IAuthService / AuthServiceImpl:认证业务逻辑(账号密码校验、第三方登录、用户信息查询、权限加载)
|
|
|
|
|
- 第三方登录
|
|
|
|
|
- DingTalkAuthClient:钉钉OAuth2客户端实现
|
|
|
|
|
- ThirdPartyAuthClientFactory:第三方认证客户端工厂
|
|
|
|
|
- 领域模型
|
|
|
|
|
- AuthUser:用户实体
|
|
|
|
|
- AuthIdentity:第三方身份绑定
|
|
|
|
|
- SysRole / SysMenu:角色与菜单
|
|
|
|
|
- DTO与参数
|
|
|
|
|
- LoginResultDTO:登录返回结果
|
|
|
|
|
- UserInfoDTO:用户信息返回
|
|
|
|
|
|
|
|
|
|
章节来源
|
|
|
|
|
- [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)
|
|
|
|
|
- [PermissionConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/PermissionConfig.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)
|
|
|
|
|
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.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)
|
|
|
|
|
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
|
|
|
|
|
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.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)
|
|
|
|
|
- [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)
|
|
|
|
|
|
|
|
|
|
## 架构总览
|
|
|
|
|
认证流程采用"控制器 -> 服务 -> 安全组件"的分层设计。登录成功后由TokenService签发JWT;后续请求通过JwtAuthenticationFilter进行无状态鉴权;权限控制通过注解与拦截器组合实现。
|
|
|
|
|
|
|
|
|
|
```mermaid
|
|
|
|
|
sequenceDiagram
|
|
|
|
|
participant C as "客户端"
|
|
|
|
|
participant AC as "AuthController"
|
|
|
|
|
participant SVC as "IAuthService"
|
|
|
|
|
participant TS as "TokenService"
|
|
|
|
|
participant JF as "JwtAuthenticationFilter"
|
|
|
|
|
participant DB as "数据库"
|
|
|
|
|
C->>AC : "POST /api/auth/login/dingtalk?authCode={code}"
|
|
|
|
|
AC->>SVC : "login(DINGTALK, authCode)"
|
|
|
|
|
SVC->>DB : "查询用户与密码校验"
|
|
|
|
|
DB-->>SVC : "用户信息/角色/菜单"
|
|
|
|
|
SVC-->>AC : "认证通过"
|
|
|
|
|
AC->>TS : "签发JWT"
|
|
|
|
|
TS-->>AC : "返回token"
|
|
|
|
|
AC-->>C : "登录成功{token, expires}"
|
|
|
|
|
C->>AC : "GET /api/auth/me (携带Authorization : Bearer {token})"
|
|
|
|
|
AC->>JF : "解析JWT并构建认证上下文"
|
|
|
|
|
JF-->>AC : "认证成功"
|
|
|
|
|
AC->>SVC : "获取当前用户信息"
|
|
|
|
|
SVC-->>AC : "UserInfoDTO"
|
|
|
|
|
AC-->>C : "用户信息"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
图表来源
|
|
|
|
|
- [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)
|
|
|
|
|
- [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)
|
|
|
|
|
|
|
|
|
|
## 详细组件分析
|
|
|
|
|
|
|
|
|
|
### 钉钉扫码登录接口
|
|
|
|
|
- HTTP方法与路径
|
|
|
|
|
- POST /api/auth/login/dingtalk
|
|
|
|
|
- 请求参数
|
|
|
|
|
- authCode: 钉钉授权码(必填)
|
|
|
|
|
- 响应体
|
|
|
|
|
- 字段参考:LoginResultDTO
|
|
|
|
|
- 状态码
|
|
|
|
|
- 200:登录成功
|
|
|
|
|
- 400/401/403/404/500:根据错误类型返回(由全局异常处理器统一封装)
|
|
|
|
|
- 说明
|
|
|
|
|
- **已简化**:从原来的请求体接收 LoginParam 对象改为直接接收 authCode 参数
|
|
|
|
|
- 支持二维码登录和OAuth重定向两种流程,使用相同的底层认证机制
|
|
|
|
|
- 成功时返回JWT令牌及有效期
|
|
|
|
|
- 失败时返回统一错误码与消息
|
|
|
|
|
|
|
|
|
|
**更新** 简化了钉钉登录接口的参数传递方式,从复杂的请求体结构改为简单的查询参数
|
|
|
|
|
|
|
|
|
|
**Section sources**
|
|
|
|
|
- [AuthController.java:30-34](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java#L30-L34)
|
|
|
|
|
- [IAuthService.java:14-15](file://crm-auth/src/main/java/com/crm/auth/service/IAuthService.java#L14-L15)
|
|
|
|
|
- [AuthServiceImpl.java:64-93](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java#L64-L93)
|
|
|
|
|
- [LoginResultDTO.java:13-23](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java#L13-L23)
|
|
|
|
|
- [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)
|
|
|
|
|
|
|
|
|
|
### 登出接口
|
|
|
|
|
- HTTP方法与路径
|
|
|
|
|
- POST /api/auth/logout
|
|
|
|
|
- 请求头
|
|
|
|
|
- Authorization: Bearer {jwt}
|
|
|
|
|
- 响应体
|
|
|
|
|
- 统一结果封装
|
|
|
|
|
- 状态码
|
|
|
|
|
- 200:登出成功
|
|
|
|
|
- 401/500:未认证或服务器错误
|
|
|
|
|
- 说明
|
|
|
|
|
- 若采用无状态JWT,登出通常为前端清除本地token;如需服务端黑名单,请结合缓存实现
|
|
|
|
|
|
|
|
|
|
**Section sources**
|
|
|
|
|
- [AuthController.java:36-41](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java#L36-L41)
|
|
|
|
|
- [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)
|
|
|
|
|
|
|
|
|
|
### 获取当前用户信息
|
|
|
|
|
- HTTP方法与路径
|
|
|
|
|
- GET /api/auth/me
|
|
|
|
|
- 请求头
|
|
|
|
|
- Authorization: Bearer {jwt}
|
|
|
|
|
- 响应体
|
|
|
|
|
- 字段参考:UserInfoDTO
|
|
|
|
|
- 状态码
|
|
|
|
|
- 200:成功
|
|
|
|
|
- 401:未认证或token无效
|
|
|
|
|
- 500:服务器错误
|
|
|
|
|
|
|
|
|
|
**Section sources**
|
|
|
|
|
- [AuthController.java:43-47](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java#L43-L47)
|
|
|
|
|
- [UserInfoDTO.java:12-41](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserInfoDTO.java#L12-L41)
|
|
|
|
|
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.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)
|
|
|
|
|
|
|
|
|
|
### 权限与菜单
|
|
|
|
|
- 典型接口
|
|
|
|
|
- 获取当前用户权限/菜单(路径与实现见SystemController)
|
|
|
|
|
- 权限验证
|
|
|
|
|
- 基于角色与菜单的访问控制,配合注解与拦截器实现
|
|
|
|
|
- 数据范围
|
|
|
|
|
- DataScopeInterceptor按角色/部门限制数据可见性
|
|
|
|
|
|
|
|
|
|
**Section sources**
|
|
|
|
|
- [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java)
|
|
|
|
|
- [PermissionConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/PermissionConfig.java)
|
|
|
|
|
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.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)
|
|
|
|
|
|
|
|
|
|
## 依赖关系分析
|
|
|
|
|
```mermaid
|
|
|
|
|
classDiagram
|
|
|
|
|
class AuthController {
|
|
|
|
|
+loginByDingTalk(authCode)
|
|
|
|
|
+logout()
|
|
|
|
|
+me()
|
|
|
|
|
}
|
|
|
|
|
class IAuthService {
|
|
|
|
|
+login(type, authCode)
|
|
|
|
|
+logout(token)
|
|
|
|
|
+getCurrentUserInfo()
|
|
|
|
|
}
|
|
|
|
|
class AuthServiceImpl
|
|
|
|
|
class TokenService {
|
|
|
|
|
+createToken()
|
|
|
|
|
+validateToken()
|
|
|
|
|
+refreshToken()
|
|
|
|
|
}
|
|
|
|
|
class JwtAuthenticationFilter {
|
|
|
|
|
+doFilter()
|
|
|
|
|
}
|
|
|
|
|
class DingTalkAuthClient {
|
|
|
|
|
+getUserInfo(authCode)
|
|
|
|
|
}
|
|
|
|
|
class ThirdPartyAuthClientFactory {
|
|
|
|
|
+getClient()
|
|
|
|
|
}
|
|
|
|
|
class AuthUser
|
|
|
|
|
class AuthIdentity
|
|
|
|
|
class SysRole
|
|
|
|
|
class SysMenu
|
|
|
|
|
AuthController --> IAuthService : "调用"
|
|
|
|
|
AuthServiceImpl ..|> IAuthService : "实现"
|
|
|
|
|
AuthController --> TokenService : "签发/校验"
|
|
|
|
|
JwtAuthenticationFilter --> TokenService : "解析/校验"
|
|
|
|
|
AuthController --> DingTalkAuthClient : "第三方登录"
|
|
|
|
|
DingTalkAuthClient <|-- ThirdPartyAuthClientFactory : "工厂创建"
|
|
|
|
|
IAuthService --> AuthUser : "操作"
|
|
|
|
|
IAuthService --> AuthIdentity : "绑定"
|
|
|
|
|
IAuthService --> SysRole : "角色"
|
|
|
|
|
IAuthService --> SysMenu : "菜单"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
图表来源
|
|
|
|
|
- [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)
|
|
|
|
|
- [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)
|
|
|
|
|
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
|
|
|
|
|
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.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)
|
|
|
|
|
|
|
|
|
|
## 性能考虑
|
|
|
|
|
- JWT无状态鉴权减少会话存储压力,适合水平扩展
|
|
|
|
|
- 建议对敏感接口启用限流与防重放
|
|
|
|
|
- 第三方登录需设置合理的超时与重试策略
|
|
|
|
|
- 用户信息与权限可缓存(如Redis),降低数据库压力
|
|
|
|
|
- 分页与懒加载菜单/权限,避免一次性加载过多数据
|
|
|
|
|
|
|
|
|
|
## 故障排查指南
|
|
|
|
|
- 常见错误
|
|
|
|
|
- 401 未认证:检查Authorization头是否携带有效JWT
|
|
|
|
|
- 403 权限不足:检查用户角色与菜单权限
|
|
|
|
|
- 400 参数错误:检查请求参数是否符合接口定义(authCode不能为空)
|
|
|
|
|
- 500 服务器错误:查看日志定位服务异常
|
|
|
|
|
- 调试建议
|
|
|
|
|
- 开启调试日志,关注JwtAuthenticationFilter与TokenService的解析与校验过程
|
|
|
|
|
- 第三方登录失败时,检查回调地址、AppKey/Secret与网络连通性
|
|
|
|
|
- 使用统一结果封装Result与ResultCodeEnum快速定位错误码
|
|
|
|
|
|
|
|
|
|
**Section sources**
|
|
|
|
|
- [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)
|
|
|
|
|
- [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)
|
|
|
|
|
|
|
|
|
|
## 结论
|
|
|
|
|
认证模块采用分层清晰、职责明确的架构,结合JWT无状态鉴权与灵活的第三方登录扩展,满足企业级应用的安全与可扩展需求。通过统一的异常处理与结果封装,提升了接口的稳定性与可维护性。最新的钉钉登录接口简化了参数传递方式,提高了接口的易用性和性能。建议在生产环境完善密钥管理、审计日志与监控告警,确保整体安全性与可靠性。
|
|
|
|
|
|
|
|
|
|
## 附录
|
|
|
|
|
|
|
|
|
|
### 安全最佳实践
|
|
|
|
|
- 密码加密策略
|
|
|
|
|
- 使用强哈希算法(如BCrypt)存储密码,禁止明文存储
|
|
|
|
|
- 定期轮换盐值与算法版本
|
|
|
|
|
- 会话管理
|
|
|
|
|
- 优先采用无状态JWT;如需强制下线,引入黑名单或短期令牌+刷新令牌机制
|
|
|
|
|
- 合理设置JWT过期时间,避免过长
|
|
|
|
|
- 传输安全
|
|
|
|
|
- 全站HTTPS,启用HSTS
|
|
|
|
|
- 严格校验CORS与CSRF防护
|
|
|
|
|
- 第三方登录
|
|
|
|
|
- 校验state参数防CSRF
|
|
|
|
|
- 最小化权限范围,及时撤销不再使用的授权
|
|
|
|
|
- 审计与监控
|
|
|
|
|
- 记录登录、登出、授权失败等关键事件
|
|
|
|
|
- 对异常IP与高频请求进行告警与封禁
|
|
|
|
|
|
|
|
|
|
### 第三方平台(钉钉)集成配置与使用示例
|
|
|
|
|
- 配置项
|
|
|
|
|
- AppKey、AppSecret、回调地址、域名白名单等(参考AuthProperties)
|
|
|
|
|
- 流程
|
|
|
|
|
- 前端跳转至钉钉授权页,获取授权码
|
|
|
|
|
- 后端使用授权码调用钉钉API换取用户信息
|
|
|
|
|
- 绑定或创建本地用户,签发JWT
|
|
|
|
|
- 使用示例
|
|
|
|
|
- **简化后的请求**:POST /api/auth/login/dingtalk?authCode={授权码}
|
|
|
|
|
- 响应:成功返回LoginResultDTO(含token与过期时间)
|
|
|
|
|
|
|
|
|
|
**Section sources**
|
|
|
|
|
- [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java)
|
|
|
|
|
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
|
|
|
|
|
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
|
|
|
|
|
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)
|
|
|
|
|
- [LoginResultDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java)
|
|
|
|
|
|
|
|
|
|
### 请求与响应示例(成功与失败)
|
|
|
|
|
- 钉钉扫码登录成功
|
|
|
|
|
- 请求:POST /api/auth/login/dingtalk?authCode=abc123
|
|
|
|
|
- 响应:200,包含token与expires
|
|
|
|
|
- 钉钉扫码登录失败
|
|
|
|
|
- 请求:POST /api/auth/login/dingtalk?authCode=invalid_code
|
|
|
|
|
- 响应:400或401,包含错误码与消息
|
|
|
|
|
- 获取用户信息成功
|
|
|
|
|
- 请求:GET /api/auth/me,Header携带Authorization
|
|
|
|
|
- 响应:200,包含用户基本信息与角色/菜单
|
|
|
|
|
- 登出成功
|
|
|
|
|
- 请求:POST /api/auth/logout,Header携带Authorization
|
|
|
|
|
- 响应:200,空响应体
|
|
|
|
|
|
|
|
|
|
**Section sources**
|
|
|
|
|
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.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)
|
|
|
|
|
- [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)
|