Spring Security实现JWT Filter的最佳实践及相关问题咨询

关于继承BasicAuthenticationFilter的疑问 #

很多早期公开示例选择继承BasicAuthenticationFilter实现JWT逻辑，完全是历史习惯导致的路径依赖，没有架构设计层面的必然性。
BasicAuthenticationFilter是Spring Security内置专门处理HTTP Basic认证的过滤器，默认在过滤器链中的位置刚好处于请求头解析节点、位于用户名密码认证过滤器之前。早期开发者写JWT逻辑时，懒得手动配置自定义过滤器的插入顺序，就直接继承这个类、重写doFilterInternal方法，把原本解析Basic请求头的逻辑替换成JWT解析逻辑，直接复用它在链路上的默认站位，省掉手动配置顺序的步骤而已。
它和HTTP Basic认证没有强绑定关系：你继承之后完全可以删掉所有和Basic认证相关的逻辑，只保留JWT处理代码。这种写法唯一的问题是会给新手造成“JWT认证和Basic认证有依赖”的误导，现在已经不推荐这么写。

关于过滤器命名差异的疑问 #

命名为JWTAuthenticationFilter还是JWTAuthorizationFilter，本质是开发者对过滤器职责边界的界定不同，没有绝对的对错：

• 认证（Authentication）的核心是解决「你是谁」的问题，即校验凭证有效性、确认用户身份
• 授权（Authorization）的核心是解决「你能访问什么」的问题，即校验身份对应的资源访问权限
  早期部分开发者把过滤器命名为JWTAuthorizationFilter，是因为他们把JWT签发逻辑（也就是用户提交用户名密码登录、校验身份后发令牌的流程）单独放在了登录接口/专门的认证过滤器中，这个自定义过滤器只负责在每次请求时解析已签发的JWT，把用户身份和权限信息填充到安全上下文中，供后续的授权拦截器做权限校验使用——在他们的逻辑划分里，这个过滤器是为后续授权环节提供上下文支撑的，所以加了Authorization的前缀。
  不过现在行业内更通用的命名是JwtAuthenticationFilter：毕竟这个过滤器的核心动作是完成请求的身份校验、填充已认证的身份对象，属于认证链路的环节。尤其Spring Security 6之后已经内置了同名的AuthorizationFilter类，再用JWTAuthorizationFilter命名很容易和内置组件混淆，不推荐使用。

JWT认证实现最佳实践 #

• 不要继承BasicAuthenticationFilter，优先选择继承OncePerRequestFilter实现自定义过滤器，它能保证每个请求只执行一次过滤逻辑，没有多余的内置逻辑耦合。注册过滤器时，手动指定将其插入到UsernamePasswordAuthenticationFilter之前即可，不需要依赖其他内置过滤器的站位。
• 过滤器核心逻辑保持精简，固定为三步：
  1. 从请求头Authorization字段中提取前缀为Bearer 的令牌串，没有对应头或前缀不匹配时直接放行，交给后续过滤器链处理未认证场景
  2. 对提取到的令牌做合法性校验：验签、判断是否过期、校验签发方合法性，校验不通过时直接返回401状态，或交由全局认证异常处理器处理
  3. 校验通过后解析令牌中存储的用户ID、权限集合，构造标记为已认证的UsernamePasswordAuthenticationToken对象，存入SecurityContextHolder的上下文中后放行请求
• 不要在JWT过滤器中混入权限校验逻辑，权限判断交给Spring Security内置的授权拦截器统一处理，保持职责单一。
• JWT签发逻辑不要放在过滤器中实现：用户提交用户名密码登录、身份校验通过后签发JWT的流程，应该放在专门的登录接口中完成，过滤器只负责后续请求的令牌解析与身份上下文填充。

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