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.
17 Commits
1 Branch
0 Tags
401 MiB
 
 
 
 
 
Tree: f0f70c6137
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'f0f70c6137'
${ noResults }
crm-backend-matt/.qoder/repowiki/zh/content/API参考文档/认证API.md

22 KiB
Raw Blame History

认证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) - [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)

更新摘要

变更内容

  • 简化钉钉登录接口：从接收 LoginParam 对象（请求体）改为直接接收 authCode 参数（请求参数）
  • 统一扫码登录和OAuth重定向流程，使用相同的底层认证机制
  • 移除了第三方登录的复杂请求体结构，简化为简单的授权码传递

目录

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

简介

本文件为认证模块的API文档，覆盖用户登录、登出、获取当前用户信息、第三方登录（以钉钉为例）等接口。文档包含：

  • HTTP方法、URL路径、请求参数、响应格式与状态码
  • JWT令牌生成与校验机制
  • OAuth2集成流程（面向第三方平台）
  • 权限验证方式（基于角色与菜单）
  • 密码加密策略、会话管理与安全最佳实践
  • 完整请求/响应示例（成功与失败场景）
  • 第三方平台（钉钉）集成配置与使用示例

项目结构

认证模块位于 crm-auth 子模块中，主要包含控制器、安全配置、服务层、领域模型与第三方客户端。基础能力（统一结果封装、全局异常处理、工具类）位于 crm-base 模块。

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
  • SystemController.java
  • SecurityConfig.java
  • PermissionConfig.java
  • JwtAuthenticationFilter.java
  • TokenService.java
  • DataScopeInterceptor.java
  • SecurityExceptionHandlers.java
  • IAuthService.java
  • AuthServiceImpl.java
  • DingTalkAuthClient.java
  • ThirdPartyAuthClientFactory.java
  • AuthProperties.java
  • GlobalExceptionHandlerAdvice.java
  • Result.java
  • ResultCodeEnum.java

章节来源

  • AuthController.java
  • SecurityConfig.java
  • IAuthService.java
  • AuthServiceImpl.java
  • DingTalkAuthClient.java
  • GlobalExceptionHandlerAdvice.java
  • Result.java
  • 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
  • SystemController.java
  • SecurityConfig.java
  • PermissionConfig.java
  • JwtAuthenticationFilter.java
  • TokenService.java
  • DataScopeInterceptor.java
  • SecurityExceptionHandlers.java
  • IAuthService.java
  • AuthServiceImpl.java
  • DingTalkAuthClient.java
  • ThirdPartyAuthClientFactory.java
  • AuthUser.java
  • AuthIdentity.java
  • SysRole.java
  • SysMenu.java
  • LoginResultDTO.java
  • UserInfoDTO.java

架构总览

认证流程采用"控制器 -> 服务 -> 安全组件"的分层设计。登录成功后由TokenService签发JWT；后续请求通过JwtAuthenticationFilter进行无状态鉴权；权限控制通过注解与拦截器组合实现。

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
  • IAuthService.java
  • TokenService.java
  • 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
  • IAuthService.java:14-15
  • AuthServiceImpl.java:64-93
  • LoginResultDTO.java:13-23
  • GlobalExceptionHandlerAdvice.java
  • Result.java
  • ResultCodeEnum.java

登出接口

  • HTTP方法与路径
    • POST /api/auth/logout
  • 请求头
    • Authorization: Bearer {jwt}
  • 响应体
    • 统一结果封装
  • 状态码
    • 200：登出成功
    • 401/500：未认证或服务器错误
  • 说明
    • 若采用无状态JWT，登出通常为前端清除本地token；如需服务端黑名单，请结合缓存实现

Section sources

  • AuthController.java:36-41
  • GlobalExceptionHandlerAdvice.java
  • Result.java

获取当前用户信息

  • HTTP方法与路径
    • GET /api/auth/me
  • 请求头
    • Authorization: Bearer {jwt}
  • 响应体
    • 字段参考：UserInfoDTO
  • 状态码
    • 200：成功
    • 401：未认证或token无效
    • 500：服务器错误

Section sources

  • AuthController.java:43-47
  • UserInfoDTO.java:12-41
  • JwtAuthenticationFilter.java
  • GlobalExceptionHandlerAdvice.java
  • Result.java

权限与菜单

  • 典型接口
    • 获取当前用户权限/菜单（路径与实现见SystemController）
  • 权限验证
    • 基于角色与菜单的访问控制，配合注解与拦截器实现
  • 数据范围
    • DataScopeInterceptor按角色/部门限制数据可见性

Section sources

  • SystemController.java
  • PermissionConfig.java
  • DataScopeInterceptor.java
  • SysRole.java
  • SysMenu.java

依赖关系分析

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
  • IAuthService.java
  • AuthServiceImpl.java
  • TokenService.java
  • JwtAuthenticationFilter.java
  • DingTalkAuthClient.java
  • ThirdPartyAuthClientFactory.java
  • AuthUser.java
  • AuthIdentity.java
  • SysRole.java
  • SysMenu.java

性能考虑

  • JWT无状态鉴权减少会话存储压力，适合水平扩展
  • 建议对敏感接口启用限流与防重放
  • 第三方登录需设置合理的超时与重试策略
  • 用户信息与权限可缓存（如Redis），降低数据库压力
  • 分页与懒加载菜单/权限，避免一次性加载过多数据

故障排查指南

  • 常见错误
    • 401 未认证：检查Authorization头是否携带有效JWT
    • 403 权限不足：检查用户角色与菜单权限
    • 400 参数错误：检查请求参数是否符合接口定义（authCode不能为空）
    • 500 服务器错误：查看日志定位服务异常
  • 调试建议
    • 开启调试日志，关注JwtAuthenticationFilter与TokenService的解析与校验过程
    • 第三方登录失败时，检查回调地址、AppKey/Secret与网络连通性
    • 使用统一结果封装Result与ResultCodeEnum快速定位错误码

Section sources

  • GlobalExceptionHandlerAdvice.java
  • Result.java
  • ResultCodeEnum.java
  • JwtAuthenticationFilter.java
  • 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
  • DingTalkAuthClient.java
  • ThirdPartyAuthClientFactory.java
  • ThirdPartyUserInfo.java
  • 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
  • LoginResultDTO.java
  • UserInfoDTO.java
  • GlobalExceptionHandlerAdvice.java
  • Result.java
  • ResultCodeEnum.java