# 认证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 模块。 ```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)