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

27 KiB
Raw Blame History

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

graph TB
subgraph "crm-auth"
AC["AuthController<br/>@Tag: 认证"]
RC["ResourceController<br/>@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
  • ResourceController.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
  • ResourceController.java
  • SystemController.java
  • SecurityConfig.java
  • IAuthService.java
  • AuthServiceImpl.java
  • DingTalkAuthClient.java
  • GlobalExceptionHandlerAdvice.java
  • Result.java
  • 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
  • ResourceController.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
  • ResourceNode.java

架构总览

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

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
  • ResourceController.java
  • IAuthService.java
  • TokenService.java
  • 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
  • LoginResultDTO.java:18-22

登出接口

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

Section sources

  • AuthController.java:36-41

获取当前用户信息

  • HTTP方法与路径
    • GET /api/auth/me
  • 请求头
    • Authorization: Bearer {jwt}
  • 响应体
    • 字段参考：UserInfoDTO（包含用户基本信息和菜单树）
  • 状态码
    • 200：成功
    • 401：未认证或token无效
    • 500：服务器错误
  • OpenAPI注解
    • @Operation(summary = "获取当前登录用户信息", tags = "登录")

Section sources

  • AuthController.java:43-47
  • UserInfoDTO.java:18-40

权限资源管理接口

权限资源管理接口已添加完整的OpenAPI注解，支持Swagger文档自动生成。

获取权限资源树

  • HTTP方法与路径
    • GET /api/resources/list
  • 权限要求
    • 需要ADMIN角色权限（@PreAuthorize("hasRole('ADMIN')")）
  • 响应体
    • List：权限资源树节点列表
  • 状态码
    • 200：成功
    • 403：权限不足
  • OpenAPI注解
    • @Operation(summary = "获取权限资源树", tags = "权限点管理")

Section sources

  • ResourceController.java:28-32
  • ResourceNode.java:23-60

新增编辑权限节点

  • 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
  • ResourceNode.java:23-57

删除权限节点

  • HTTP方法与路径
    • POST /api/resources/delete
  • 权限要求
    • 需要ADMIN角色权限
  • 请求参数
    • id: 要删除的节点ID（必填）
  • 响应体
    • 空响应体
  • 状态码
    • 200：成功
    • 400：参数校验失败
    • 403：权限不足
  • OpenAPI注解
    • @Operation(summary = "删除一级菜单/二级菜单/权限点", tags = "权限点管理")

Section sources

  • ResourceController.java:42-47

上传图标

  • 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

系统管理接口

系统管理接口提供用户、部门、菜单等系统级功能。

获取菜单树

  • HTTP方法与路径
    • GET /api/system/menus/tree
  • 响应体
    • List：当前用户可见的菜单树
  • 说明
    • 根据用户权限动态返回可见菜单

Section sources

  • SystemController.java:35-39

获取部门树

  • HTTP方法与路径
    • GET /api/system/depts/tree
  • 响应体
    • List：部门树结构

Section sources

  • SystemController.java:43-49

依赖关系分析

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
  • ResourceController.java
  • SystemController.java
  • IAuthService.java
  • AuthServiceImpl.java
  • TokenService.java
  • JwtAuthenticationFilter.java
  • DingTalkAuthClient.java
  • ThirdPartyAuthClientFactory.java
  • LoginResultDTO.java
  • UserInfoDTO.java
  • ResourceNode.java

性能考虑

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

故障排查指南

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

Section sources

  • GlobalExceptionHandlerAdvice.java
  • Result.java
  • ResultCodeEnum.java
  • JwtAuthenticationFilter.java
  • 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
  • ResourceController.java:28-54
  • LoginResultDTO.java:18-22
  • UserInfoDTO.java:18-40
  • ResourceNode.java:23-60

安全最佳实践

  • 密码加密策略
    • 使用强哈希算法（如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，空响应体
  • 获取权限资源树成功
    • 请求：GET /api/resources/list（需要ADMIN权限）
    • 响应：200，包含ResourceNode列表
  • 新增权限节点成功
    • 请求：POST /api/resources/saveOrUpdate，Body包含ResourceNode
    • 响应：200，包含保存后的节点信息

Section sources

  • AuthController.java
  • ResourceController.java
  • LoginResultDTO.java
  • UserInfoDTO.java
  • ResourceNode.java
  • GlobalExceptionHandlerAdvice.java
  • Result.java
  • ResultCodeEnum.java