# 认证API **本文引用的文件** - [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java) - [ResourceController.java](file://crm-auth/src/main/java/com/crm/auth/controller/ResourceController.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) - [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.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) ## 更新摘要 **变更内容** - AuthController增强了OpenAPI注解，为登录相关接口添加了@Operation注解和"登录"标签分类 - ResourceController完善了OpenAPI注解，为权限点管理接口添加了详细的@Operation注解和"权限点管理"标签 - 所有DTO类添加了@Schema注解，提供API文档的字段描述信息 - 改进了Swagger/OpenAPI文档生成质量，提供更好的API文档体验 ## 目录 1. [简介](#简介) 2. [项目结构](#项目结构) 3. [核心组件](#核心组件) 4. [架构总览](#架构总览) 5. [详细组件分析](#详细组件分析) 6. [依赖关系分析](#依赖关系分析) 7. [性能考虑](#性能考虑) 8. [故障排查指南](#故障排查指南) 9. [结论](#结论) 10. [附录](#附录) ## 简介 本文件为认证模块的API文档，覆盖用户登录、登出、获取当前用户信息、权限资源管理等接口。文档包含： - HTTP方法、URL路径、请求参数、响应格式与状态码 - JWT令牌生成与校验机制 - OAuth2集成流程（面向第三方平台） - 权限验证方式（基于角色与菜单） - 密码加密策略、会话管理与安全最佳实践 - 完整请求/响应示例（成功与失败场景） - 第三方平台（钉钉）集成配置与使用示例 - OpenAPI/Swagger文档集成说明 ## 项目结构 认证模块位于 crm-auth 子模块中，主要包含控制器、安全配置、服务层、领域模型与第三方客户端。基础能力（统一结果封装、全局异常处理、工具类）位于 crm-base 模块。 ```mermaid graph TB subgraph "crm-auth" AC["AuthController
@Tag: 认证"] RC["ResourceController
@Tag: 权限点管理"] 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 / ResourceNode"] DING["DingTalkAuthClient"] TPC["ThirdPartyAuthClientFactory"] end subgraph "crm-base" GHA["GlobalExceptionHandlerAdvice"] RES["Result / ResultCodeEnum"] end AC --> SVC RC --> 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) - [ResourceController.java](file://crm-auth/src/main/java/com/crm/auth/controller/ResourceController.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) - [ResourceController.java](file://crm-auth/src/main/java/com/crm/auth/controller/ResourceController.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) - [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) ## 核心组件 - 控制器层 - 认证控制器：提供登录、登出、获取当前用户信息等接口，已添加OpenAPI注解 - 资源控制器：提供权限资源管理接口，已完善OpenAPI注解 - 系统控制器：提供系统级鉴权相关接口（如权限列表、菜单树等） - 安全配置 - SecurityConfig：Spring Security配置，注册JWT过滤器、跨域、白名单等 - PermissionConfig：权限注解与数据权限拦截器装配 - 安全组件 - JwtAuthenticationFilter：从请求头解析JWT并构建认证上下文 - TokenService：JWT签发、校验、刷新与过期管理 - DataScopeInterceptor：数据范围拦截器，按角色/部门过滤数据 - SecurityExceptionHandlers：安全相关异常处理器 - 服务层 - IAuthService / AuthServiceImpl：认证业务逻辑（账号密码校验、第三方登录、用户信息查询、权限加载） - 第三方登录 - DingTalkAuthClient：钉钉OAuth2客户端实现 - ThirdPartyAuthClientFactory：第三方认证客户端工厂 - 领域模型 - AuthUser：用户实体 - AuthIdentity：第三方身份绑定 - SysRole / SysMenu：角色与菜单 - DTO与参数 - LoginResultDTO：登录返回结果，已添加@Schema注解 - UserInfoDTO：用户信息返回，已添加@Schema注解 - ResourceNode：权限资源节点，已添加@Schema注解 章节来源 - [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java) - [ResourceController.java](file://crm-auth/src/main/java/com/crm/auth/controller/ResourceController.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) - [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java) ## 架构总览 认证流程采用"控制器 -> 服务 -> 安全组件"的分层设计。登录成功后由TokenService签发JWT；后续请求通过JwtAuthenticationFilter进行无状态鉴权；权限控制通过注解与拦截器组合实现。 ```mermaid sequenceDiagram participant C as "客户端" participant AC as "AuthController" participant RC as "ResourceController" 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 : "用户信息" C->>RC : "GET /api/resources/list (管理员权限)" RC->>SVC : "获取权限资源树" SVC-->>RC : "ResourceNode列表" RC-->>C : "权限资源树" ``` 图表来源 - [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java) - [ResourceController.java](file://crm-auth/src/main/java/com/crm/auth/controller/ResourceController.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) ## 详细组件分析 ### 认证接口（登录相关） 认证接口已添加完整的OpenAPI注解，支持Swagger文档自动生成。 #### 钉钉扫码登录接口 - **HTTP方法与路径** - POST /api/auth/login/dingtalk - **请求参数** - authCode: 钉钉授权码（必填，查询参数） - **响应体** - 字段参考：LoginResultDTO（包含token和用户信息） - **状态码** - 200：登录成功 - 400/401/403/404/500：根据错误类型返回（由全局异常处理器统一封装） - **OpenAPI注解** - @Operation(summary = "钉钉登录（扫码/免登通用）", tags = "登录") - @Tag(name = "认证") - **说明** - 支持二维码登录和OAuth重定向两种流程，使用相同的底层认证机制 - 成功时返回JWT令牌及有效期 - 失败时返回统一错误码与消息 **Section sources** - [AuthController.java:30-34](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java#L30-L34) - [LoginResultDTO.java:18-22](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java#L18-L22) #### 登出接口 - **HTTP方法与路径** - POST /api/auth/logout - **请求头** - Authorization: Bearer {jwt} - **响应体** - 统一结果封装（Result） - **状态码** - 200：登出成功 - 401/500：未认证或服务器错误 - **OpenAPI注解** - @Operation(summary = "注销", tags = "登录") - **说明** - 若采用无状态JWT，登出通常为前端清除本地token；如需服务端黑名单，请结合缓存实现 **Section sources** - [AuthController.java:36-41](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java#L36-L41) #### 获取当前用户信息 - **HTTP方法与路径** - GET /api/auth/me - **请求头** - Authorization: Bearer {jwt} - **响应体** - 字段参考：UserInfoDTO（包含用户基本信息和菜单树） - **状态码** - 200：成功 - 401：未认证或token无效 - 500：服务器错误 - **OpenAPI注解** - @Operation(summary = "获取当前登录用户信息", tags = "登录") **Section sources** - [AuthController.java:43-47](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java#L43-L47) - [UserInfoDTO.java:18-40](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserInfoDTO.java#L18-L40) ### 权限资源管理接口 权限资源管理接口已添加完整的OpenAPI注解，支持Swagger文档自动生成。 #### 获取权限资源树 - **HTTP方法与路径** - GET /api/resources/list - **权限要求** - 需要ADMIN角色权限（@PreAuthorize("hasRole('ADMIN')")） - **响应体** - List：权限资源树节点列表 - **状态码** - 200：成功 - 403：权限不足 - **OpenAPI注解** - @Operation(summary = "获取权限资源树", tags = "权限点管理") **Section sources** - [ResourceController.java:28-32](file://crm-auth/src/main/java/com/crm/auth/controller/ResourceController.java#L28-L32) - [ResourceNode.java:23-60](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java#L23-L60) #### 新增编辑权限节点 - **HTTP方法与路径** - POST /api/resources/saveOrUpdate - **权限要求** - 需要ADMIN角色权限 - **请求体** - ResourceNode对象（包含id、parentId、name、type、sort、description、route、perms、denyBehavior、apiUrl、status、icon等字段） - **响应体** - ResourceNode：保存后的节点信息 - **状态码** - 200：成功 - 400：参数校验失败 - 403：权限不足 - **OpenAPI注解** - @Operation(summary = "新增编辑一级菜单/二级菜单/权限点", tags = "权限点管理") **Section sources** - [ResourceController.java:35-39](file://crm-auth/src/main/java/com/crm/auth/controller/ResourceController.java#L35-L39) - [ResourceNode.java:23-57](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java#L23-L57) #### 删除权限节点 - **HTTP方法与路径** - POST /api/resources/delete - **权限要求** - 需要ADMIN角色权限 - **请求参数** - id: 要删除的节点ID（必填） - **响应体** - 空响应体 - **状态码** - 200：成功 - 400：参数校验失败 - 403：权限不足 - **OpenAPI注解** - @Operation(summary = "删除一级菜单/二级菜单/权限点", tags = "权限点管理") **Section sources** - [ResourceController.java:42-47](file://crm-auth/src/main/java/com/crm/auth/controller/ResourceController.java#L42-L47) #### 上传图标 - **HTTP方法与路径** - POST /api/resources/icon/upload - **权限要求** - 需要ADMIN角色权限 - **请求参数** - file: 文件上传（multipart/form-data） - **响应体** - FileInfoDTO：文件信息 - **状态码** - 200：成功 - 400：文件格式或大小校验失败 - 403：权限不足 - **OpenAPI注解** - @Operation(summary = "上传图标", tags = "权限点管理") **Section sources** - [ResourceController.java:50-54](file://crm-auth/src/main/java/com/crm/auth/controller/ResourceController.java#L50-L54) ### 系统管理接口 系统管理接口提供用户、部门、菜单等系统级功能。 #### 获取菜单树 - **HTTP方法与路径** - GET /api/system/menus/tree - **响应体** - List：当前用户可见的菜单树 - **说明** - 根据用户权限动态返回可见菜单 **Section sources** - [SystemController.java:35-39](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java#L35-L39) #### 获取部门树 - **HTTP方法与路径** - GET /api/system/depts/tree - **响应体** - List：部门树结构 **Section sources** - [SystemController.java:43-49](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java#L43-L49) ## 依赖关系分析 ```mermaid classDiagram class AuthController { +loginByDingTalk(authCode) +logout() +me() } class ResourceController { +listAll() +saveOrUpdate(node) +delete(id) +uploadIcon(file) } class SystemController { +menuTree() +deptTree() +assignUserRoles(userId, roleIds) +assignUserDepts(userId, primaryDeptId, deptIds) +userPage(param) +userStats(deptId) } 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 LoginResultDTO { +token +userInfo } class UserInfoDTO { +id +username +mobile +email +avatar +deptId +deptName +menus } class ResourceNode { +id +parentId +name +type +sort +description +route +perms +denyBehavior +apiUrl +status +icon +children } AuthController --> IAuthService : "调用" ResourceController --> IAuthService : "调用" AuthServiceImpl ..|> IAuthService : "实现" AuthController --> TokenService : "签发/校验" JwtAuthenticationFilter --> TokenService : "解析/校验" AuthController --> DingTalkAuthClient : "第三方登录" DingTalkAuthClient <|-- ThirdPartyAuthClientFactory : "工厂创建" IAuthService --> LoginResultDTO : "返回" IAuthService --> UserInfoDTO : "返回" ResourceController --> ResourceNode : "操作" ``` 图表来源 - [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java) - [ResourceController.java](file://crm-auth/src/main/java/com/crm/auth/controller/ResourceController.java) - [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.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) - [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) - [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java) ## 性能考虑 - JWT无状态鉴权减少会话存储压力，适合水平扩展 - 建议对敏感接口启用限流与防重放 - 第三方登录需设置合理的超时与重试策略 - 用户信息与权限可缓存（如Redis），降低数据库压力 - 分页与懒加载菜单/权限，避免一次性加载过多数据 - 权限资源树可缓存，减少频繁查询 ## 故障排查指南 - 常见错误 - 401 未认证：检查Authorization头是否携带有效JWT - 403 权限不足：检查用户角色与菜单权限 - 400 参数错误：检查请求参数是否符合接口定义（authCode不能为空） - 500 服务器错误：查看日志定位服务异常 - 调试建议 - 开启调试日志，关注JwtAuthenticationFilter与TokenService的解析与校验过程 - 第三方登录失败时，检查回调地址、AppKey/Secret与网络连通性 - 使用统一结果封装Result与ResultCodeEnum快速定位错误码 - 利用Swagger文档验证接口参数和响应格式 **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无状态鉴权与灵活的第三方登录扩展，满足企业级应用的安全与可扩展需求。通过统一的异常处理与结果封装，提升了接口的稳定性与可维护性。最新的OpenAPI注解增强提供了更好的API文档体验，支持Swagger自动生成接口文档。建议在生产环境完善密钥管理、审计日志与监控告警，确保整体安全性与可靠性。 ## 附录 ### OpenAPI/Swagger文档集成 - **注解使用** - @Tag：为接口分组命名（如"认证"、"权限点管理"） - @Operation：为接口添加描述和标签 - @Schema：为DTO字段添加描述信息 - **文档访问** - Swagger UI：http://localhost:端口/swagger-ui.html - OpenAPI规范：http://localhost:端口/v3/api-docs **Section sources** - [AuthController.java:22-47](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java#L22-L47) - [ResourceController.java:28-54](file://crm-auth/src/main/java/com/crm/auth/controller/ResourceController.java#L28-L54) - [LoginResultDTO.java:18-22](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java#L18-L22) - [UserInfoDTO.java:18-40](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserInfoDTO.java#L18-L40) - [ResourceNode.java:23-60](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java#L23-L60) ### 安全最佳实践 - 密码加密策略 - 使用强哈希算法（如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，空响应体 - 获取权限资源树成功 - 请求：GET /api/resources/list（需要ADMIN权限） - 响应：200，包含ResourceNode列表 - 新增权限节点成功 - 请求：POST /api/resources/saveOrUpdate，Body包含ResourceNode - 响应：200，包含保存后的节点信息 **Section sources** - [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java) - [ResourceController.java](file://crm-auth/src/main/java/com/crm/auth/controller/ResourceController.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) - [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.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)