咨询符合最佳实践的Spring Boot JWT认证项目结构

Great question—structuring your Spring Boot JWT auth setup properly will save you tons of headaches down the line, especially when scaling or maintaining the codebase. Let’s break down a clean, industry-standard structure that aligns perfectly with the classes you’ve already built.

核心目录结构 #

Here’s a hierarchical breakdown that follows Spring Boot best practices and separates concerns clearly:

src/main/java/com/yourcompany/yourapp/
├── auth/                     # 认证核心模块（所有JWT相关代码的容器）
│   ├── config/               # 安全配置类
│   │   └── SecurityConfig.java  # 配置Security Filter Chain、AuthenticationManager等
│   ├── filter/               # 自定义过滤器
│   │   └── CustomAuthFilter.java
│   ├── service/              # 认证业务服务
│   │   ├── CustomUserDetailsService.java
│   │   └── CustomJwtService.java
│   ├── exception/            # 认证专属异常处理
│   │   └── CustomEntryPoint.java
│   └── controller/           # 认证API端点
│       └── CustomAuthController.java
├── common/                   # 通用工具/复用代码（可选但强烈推荐）
│   ├── dto/                  # 认证相关数据传输对象
│   │   ├── LoginRequest.java
│   │   └── AuthResponse.java
│   ├── util/                 # 通用工具类
│   │   └── JwtConstants.java
│   └── exception/            # 全局异常处理器
│       └── GlobalAuthExceptionHandler.java
└── model/                    # 数据库实体类
    └── User.java

各目录职责详解 #

1. auth/ - 认证核心模块 #

This is the heart of your JWT implementation, with subdirectories organized by responsibility:

• config/: 放置SecurityConfig.java——这里是你配置SecurityFilterChain、将CustomAuthFilter加入过滤链、定义AuthenticationManager Bean、设置CustomEntryPoint作为未授权请求处理器，以及配置无需认证的公开端点（如/login或/register）的地方。
• filter/: 存放你的CustomAuthFilter——这个类负责拦截入站请求、从请求头解析JWT令牌、验证令牌有效性，并将已认证用户信息存入Spring Security上下文。
• service/: 包含认证相关的业务逻辑：
  • CustomUserDetailsService: 实现Spring的UserDetailsService接口，从数据库（或其他数据源）加载用户数据，并转换为UserDetails对象供认证管理器验证。
  • CustomJwtService: 封装所有JWT专属逻辑——生成访问/刷新令牌、从令牌中提取用户名、验证令牌签名和过期时间。
• exception/: 存放CustomEntryPoint（实现AuthenticationEntryPoint接口），负责在用户尝试访问受保护资源但未通过认证时，返回统一格式的错误响应。
• controller/: 存放CustomAuthController——在这里定义你的REST端点，比如/login（生成令牌）和/refresh-token（用刷新令牌获取新的访问令牌）。

2. common/ - 通用模块 #

这个目录存放不严格绑定认证但为其提供支持的复用代码：

• dto/: 数据传输对象，比如LoginRequest（包含用户名、密码字段）和AuthResponse（包含accessToken、refreshToken字段），避免在API请求/响应中暴露敏感的实体数据。
• util/: 工具类或常量类——例如JwtConstants.java可以存储令牌过期时间、密钥名称、请求头名称（如Authorization）等。
• exception/: 全局异常处理器（比如带有@RestControllerAdvice注解的GlobalAuthExceptionHandler），用于捕获并格式化AuthenticationException或JwtException等异常，返回包含错误码、消息和时间戳的统一JSON响应。

3. model/ - 实体模块 #

存放数据库实体类，比如User.java，映射到你的用户表。CustomUserDetailsService会获取该类的实例，并将其转换为Spring Security所需的UserDetails对象。

额外的最佳实践建议 #

• 配置与代码分离: 将JWT密钥、令牌过期时间等配置值存入application.yml，而非硬编码在代码中。示例：

  jwt:
    secret: your-strong-random-secret-key
    access-token-expiry: 3600000  # 1小时（毫秒）
    refresh-token-expiry: 86400000  # 24小时（毫秒）
  

• 遵循单一职责原则: 每个类只做一件事——不要把JWT生成逻辑和用户数据查询混在一起，也不要把过滤器逻辑和异常处理混在一起。
• 使用官方依赖: 坚持使用Spring Security的启动器(spring-boot-starter-security)和最新的JJWT库(jjwt-api, jjwt-impl, jjwt-jackson)处理JWT，避免使用已废弃的代码。
• 编写测试: 为CustomJwtService（测试令牌生成/验证）、CustomUserDetailsService（测试用户加载）和CustomAuthFilter（测试令牌解析与认证逻辑）添加单元测试。

内容的提问来源于stack exchange，提问作者Denis Stephanov