Java Web 后端实战笔记（六）：登录认证——JWT 令牌与 Filter 拦截器
前后端分离的接口开发做到登录认证这一步，基本上每个人都要卡一卡。我自己在学习 Java Web 后端过程中，被“传统 Session 方案在前后端分离场景下到底该怎么用”这个问题折磨过很久，后来换成 JWT 令牌配合 Filter 过滤器的方式才彻底想通。这篇笔记就完整记录这次登录认证实战：从最开始的难点拆解、JWT 令牌的生成与校验、Filter 拦截器设计，到最后的全链路联调和安全细节。适合已经会写一些接口、正准备着手实现登录模块的 Java 学习者，也适合需要快速复盘认证链路设计的在职开发者。
1. 为什么登录认证容易“拖后腿”：从 Session 到 JWT 的取舍
1.1 传统 Session 方案在前后端分离下的真实痛点
大学里做课设、平时写单体项目，最常见的登录方式就是 Session。用户登录成功后，后端把用户信息放进 Session，顺手把 SessionID 写进 Cookie，下一次请求带着 Cookie 过来，后端一查 Session 就知道“这个人是哪位”。这套机制在同一个 Tomcat、同一个进程、同一个域名下跑起来非常顺，几乎不用额外处理。
但一旦项目开始做前后端分离，问题就浮现了。前端可能是 App、可能是小程序、也可能是部署在另一个域名下的页面，Cookie 的跨域传递、同源策略会让整个认证链路变得异常脆弱。即便你能通过跨域配置把 Cookie 放行，后端 Session 默认存在单台服务器内存里，一旦服务扩容变成多实例，这个用户可能恰好被负载均衡到另一台机器上，那台机器上根本没有他的 Session，又得重新登录。
更麻烦的是，如果做移动端 App，很多网络库对 Cookie 的支持并不像浏览器那样透明，你需要自己手动维护 Cookie 存储、过期时间、并发请求时的 Cookie 同步，代码写起来非常难受。我刚开始从传统 JSP 项目转到前后端分离时，第一反应是“继续用 Session 不就行了吗”，结果一联调就发现手机端根本不是那么回事，Cookie 用起来各种别扭。
1.2 JWT 之所以流行的三个关键理由
JWT（JSON Web Token）解决的是“状态存哪”的问题。它把用户身份信息经过签名后打包成一个字符串，让客户端自己保存，服务端不保存会话状态，请求过来时只需要验证这个令牌本身合法、没有过期，就能直接相信令牌里携带的用户信息。
这带来三个非常实际的好处。第一是天然适合前后端分离，客户端拿到 token 之后，在请求头里带上就行，不用管 Cookie、不用管同源策略，跨域调用不会因为认证方式受阻碍。第二是天然支持水平扩展，服务端无状态，每个实例都能独立校验 token，不需要引入额外的会话同步组件或集中式缓存。第三是自包含，用户 ID、角色、过期时间等必要信息都能直接放进 token 里，后端少了一次甚至多次查库操作。
这里要特别提醒一下，JWT 不是加密技术，它只是签名技术。通过 Base64 解码，任何人都能直接看到 token 的载荷内容，所以不要在 token 里放密码、手机号、身份证号这类敏感信息。可以放用户 ID、用户名、角色标识这类不敏感的身份信息，真正需要保密的数据仍然要放在后端数据库里。
1.3 JWT 令牌的内部结构：三个部分的职责和边界
一个标准的 JWT 字符串由三段组成，用点号分隔，形如xxxxx.yyyyy.zzzzz。第一段是 Header，声明令牌类型和签名算法，一般长这样：{"alg":"HS256","typ":"JWT"}。第二段是 Payload，承载实际要传递的身份声明，可以放sub（主题）、name、iat（签发时间）、exp（过期时间）等字段。第三段是 Signature，用 Header 里指定的算法对前两段内容进行签名。
用生活里的场景来理解，JWT 很像是你的一张会员卡。卡片正面印着你的姓名和会员等级（Payload），外观看得出你是谁；卡片背面有条签名和防伪标签（Signature），商家可以通过扫描验证这张卡是不是官方签发的、有没有被篡改。但卡片本身并没有加密，别人捡到你的卡片也能读出正面的字。
Signature 的生成过程是把 Header 和 Payload 拼接起来，加上只有后端知道的密钥，用哈希算法算出一个签名值。只要密钥不泄露，任何人都无法伪造签名；只要 token 内容被改动任何一位，签名校验就会立刻失败。这一点是整个 JWT 方案的安全基石。
2. JWT 令牌生成与校验的代码落地：先想清楚这三件事
2.1 依赖选型：用一套稳定好维护的 JWT 库
Java 生态里 JWT 库不少，早期用过com.auth0:java-jwt，也见过很多人用io.jsonwebtoken:jjwt。我自己在实际项目中选择了jjwt的 0.11.5 版本，因为它的 API 设计比较清晰，builder 和 parser 两个入口就能完成大部分工作，而且对 HS256、RS256 的支持都很成熟。
0.11.x 版本之后，jjwt把 API、实现和 Jackson 适配拆成了三个独立包，需要一次性引入。我的 Maven 依赖配置如下：
<dependency> <groupId>io.jsonwebtoken</groupId> <artifactId>jjwt-api</artifactId> <version>0.11.5</version> </dependency> <dependency> <groupId>io.jsonwebtoken</groupId> <artifactId>jjwt-impl</artifactId> <version>0.11.5</version> <scope>runtime</scope> </dependency> <dependency> <groupId>io.jsonwebtoken</groupId> <artifactId>jjwt-jackson</artifactId> <version>0.11.5</version> <scope>runtime</scope> </dependency>如果你只想快速跑通，也可以直接用老版本 0.9.1，API 更简单，但 0.9.1 使用的是JwtParser链式校验，对密钥字节长度要求方面不如新版严格，而且维护时间更古老。新手建议直接从 0.11.x 起步，习惯上更贴近当前主流写法。
2.2 生成令牌：不要把一堆无关数据塞进 Payload
我封装了一个简单的工具类JwtHelper，核心方法就是根据用户 ID 和用户名生成 token。这段代码是整个登录认证的基础部件，后续登录接口、Filter 拦截器都要调用它：
public class JwtHelper { private static final String SECRET_KEY = "your-256-bit-secret-key-change-in-production"; private static final long EXPIRE_TIME = 24 * 60 * 60 * 1000L; // 24小时 private static final String CLAIM_USER_ID = "userId"; public static String generateToken(Long userId, String username) { return Jwts.builder() .setSubject(username) .claim(CLAIM_USER_ID, userId) .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() + EXPIRE_TIME)) .signWith(Keys.hmacShaKeyFor(SECRET_KEY.getBytes(StandardCharsets.UTF_8)), SignatureAlgorithm.HS256) .compact(); } }这里有一个非常容易踩的坑，必须单独拎出来说：Keys.hmacShaKeyFor要求传入的密钥字节长度至少为 256 位（32 个字节）。也就是说，如果你用一个很短的字符串当密钥，比如"secret"，程序会在启动后第一次调用生成 token 时才抛出WeakKeyException。这个报错在网上被问过无数遍，原因就是因为密钥太短，不是别的。
另外，请大家克制住往 claim 里塞数据的欲望。我见过有人把整个用户对象序列化后塞进 token，导致 token 长度达到几千字符，不仅浪费带宽，而且把大量用户信息长期暴露在客户端。遵循最小化原则，放能唯一定位用户的 ID 和必要的角色权限信息就够了。
2.3 解析令牌：异常处理比解析本身更值得花心思
校验和解析是认证的核心动作。调用方携带一个 token 过来，要么解析成功拿到用户信息，要么失败并明确知道失败原因。我把解析过程写成这样：
public static Claims parseToken(String token) { return Jwts.parserBuilder() .setSigningKey(Keys.hmacShaKeyFor(SECRET_KEY.getBytes(StandardCharsets.UTF_8))) .build() .parseClaimsJws(token) .getBody(); }最有价值的是对异常的分类处理。ExpiredJwtException表示令牌过期，前端收到该结果后应引导用户重新登录或刷新令牌；SignatureException表示签名不匹配，token 可能被篡改过；MalformedJwtException表示 token 本身格式不对。我在 Filter 里会把这些异常分别映射到不同的响应提示，而不是简单统一抛一个“认证失败”，这对前端排查问题帮助非常大。
生产环境还要考虑一个细节：不要在每个请求里重复构建 HMAC 密钥对象。Keys.hmacShaKeyFor和parserBuilder()都有创建成本，量级不大但没必要。可以把解析器做成静态字段、在类加载时初始化一次，或者交给 Spring 容器管理。像这种小优化，在高并发场景下还是能看出差距的。
2.4 过期时间怎么定：短令牌加长令牌的组合思路
工期紧的时候，很多人直接把过期时间定成 7 天、30 天，图省事。但令牌有效期越长，泄露后的风险窗口就越大。比较稳妥的组合方案是：短期 token（30 分钟到 2 小时）负责访问受保护接口，长期 refresh token（7 天到 14 天）负责在短期 token 过期后兑换新 token。短期 token 建议放在内存或请求头里，refresh token 可以考虑存到更安全的地方（比如 App 的钥匙串）。
如果你做的项目体量不大，本着“先跑通、再优化”的原则，令牌过期时间设为 24 小时完全够用。但最好把过期时间常量抽出来放到配置文件里，不要像示例代码那样直接写死在类里，因为后期调整频率很高，改代码重启再改回来很浪费时间。
3. Filter 拦截器设计：让“通行证检查”前置到所有接口
3.1 为什么用 Filter 而不是全部写在每个接口里
登录认证本质上是“统一入口校验”，它不能只约束某个接口，而是要对所有需要保护的接口生效。Filter 是 Java Servlet 规范规定的组件，它运行在请求进入 DispatcherServlet 之前，天然具备“全局前置处理”的能力。用 Filter 做认证，最核心的好处是认证逻辑与业务接口完全解耦，业务层什么都不用改，照常接收请求参数、返回业务结果。
有人可能会问，Spring 的 HandlerInterceptor 也有类似功能，该怎么选？我的判断是：如果只是做登录认证，两者都可以，但 Filter 更合适。因为 Filter 的作用范围更大、位置更靠前，连静态资源请求、非 Spring MVC 的路径都能拦截；HandlerInterceptor 则更贴近 Spring MVC 内部，适合需要拿到 Handler 信息做权限判断的场景。做粗粒度的登录认证，用 Filter 就够了。
Filter 本身是一个接口，只包含init、doFilter、destroy三个方法。实际开发中我们直接继承OncePerRequestFilter更省事，它可以保证在一次请求中过滤器只执行一次，避免多次包含（比如转发）时出现重复校验。
3.2 过滤器注册与路径放行：/* 和 /api/** 的说法要搞清楚
很多人第一次写 Filter 时，直接用@WebFilter(urlPatterns = "/api/**")注册，结果发现接口怎么都拦截不到，卡了半天才明白问题。Servlet 的路径匹配规则里根本没有 Ant 风格的/**，只有/*，它匹配所有路径。Spring 里的/api/**这种写法是 Spring Web 本身的路由匹配规则，用在 Filter 的urlPatterns上是行不通的。
如果你的项目使用 Spring Boot，我建议直接用FilterRegistrationBean注册过滤器，配置上更直观、容错率高。下面这段是注册登录认证过滤器并设置放行路径的代码：
@Configuration public class FilterConfig { @Bean public FilterRegistrationBean<AuthFilter> authFilterRegistration(AuthFilter authFilter) { FilterRegistrationBean<AuthFilter> registration = new FilterRegistrationBean<>(); registration.setFilter(authFilter); registration.addUrlPatterns("/*"); registration.setOrder(1); return registration; } }这里的setOrder(1)决定过滤器在链条中的执行顺序。如果你的项目里还有别的过滤器，比如跨域过滤器、日志过滤器，一定要想清楚先后顺序。跨域过滤器通常放在最前面，因为浏览器先做预检请求，如果跨域配置都没有生效，后续认证过滤器根本看不到正常请求。
3.3 放行规则的实现逻辑：白名单列表比黑名单好维护
过滤器拦截到所有请求之后，并不能一律拒绝。登录接口、注册接口、验证码接口等必须在未登录状态下也能访问，这些路径要放进白名单。我习惯把这部分规则配置成常量数组，在过滤器里逐个比对前缀，而不是用硬编码的 if-else 堆在doFilter方法里。
private static final String[] WHITE_LIST = { "/api/auth/login", "/api/auth/register" };判断逻辑是：请求路径命中了白名单，直接放行；没有命中，就去检查Authorization请求头里的 token；token 校验通过，放行；校验失败，写 401 响应返回。这里要注意路径匹配不能只做equals，很多接口下面还挂着子路径，比如登录接口如果是/api/auth/login，那基本不需要匹配子路径；如果是/api/doc/**这类目录，就需要做前缀匹配。实际工作中我通常写一个isWhiteList方法，兼容精确匹配和前缀匹配两种校验。
还有一个小细节：Filter 默认会拦截ERROR类型的分发。如果请求转发到/error时，它还会再执行一次认证逻辑，可能造成循环。如果遇到405、401之后页面表现奇怪，可以在过滤器里检查dispatcherType，只对REQUEST类型做认证拦截。
3.4 错误响应的统一格式：让 401 的返回体也能被后端直接消费
很多学习者在学着写 Filter 时，会忽略响应的输出格式，直接response.sendError(401)就完事了。这种写法的明显问题是，前端接入方拿到的响应体是 Servlet 容器默认的 HTML 错误页，而不是项目里其他接口返回的统一 JSON 结构，前端解析起来非常麻烦。
我的做法是，在认证失败时手动设置响应状态码和响应头，然后往外写一段统一的 JSON 错误消息：
response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); response.setContentType("application/json;charset=UTF-8"); response.getWriter().write("{\"code\":401,\"msg\":\"未登录或登录已过期\"}");这样前端拿到的是一个结构化返回体，可以统一走错误提示逻辑。这里还要注意response.getWriter()写入后要flush()，并且不要在之后试图继续调用业务接口，直接return结束过滤器的执行。
4. 登录认证全链路联调：三种请求场景逐一实测
4.1 登录接口：查余额、验密码、发令牌
登录接口本身不复杂，但它把前面所有内容串起来了。我的登录逻辑简化后是这样的：接收用户名和密码，查询数据库用户表，比对密码，成功后调用JwtHelper.generateToken生成令牌，再把令牌和用户基本信息一起返回给前端。
为了让这个例子完整，我模拟了一个极简的验证方法，密码校验处使用了 BCrypt 风格的加密思路。实际项目密码校验必须用加密算法验证，绝不能明文比对：
@PostMapping("/login") public Result login(@RequestBody LoginRequest request) { User user = userMapper.findByUsername(request.getUsername()); if (user == null || !passwordEncoder.matches(request.getPassword(), user.getPassword())) { return Result.fail("用户名或密码错误"); } String token = JwtHelper.generateToken(user.getId(), user.getUsername()); return Result.success(new LoginResponse(token, user.getUsername())); }这个过程中我重点想提醒两点。第一，登录接口本身必须放行，否则用户永远拿不到令牌，整个认证链路直接死锁。第二，登录成功后不要把 token 存到服务端 Session 里，JWT 方案要的就是无状态，再存一份会话状态就违背了设计初衷。
4.2 三种请求场景的实测结果
为了验证 Filter 是否真的把认证链路闭环了，我把项目跑起来，用接口测试工具分别打了三种场景。
场景一：请求/api/auth/login，传入正确的用户名密码，返回 JSON 数据中带有一串 JWT 令牌，状态码 200。这验证了白名单放行、登录接口、令牌生成三个环节都正常。
场景二：请求一个受保护接口/api/user/profile，在请求头中加入Authorization: Bearer <token>，后端从 token 中成功解析出用户 ID，查询到用户资料，返回 200。这验证了 Filter 对令牌的解析和放行逻辑。
场景三：请求同一个受保护接口，不带 token 或者带一个随机字符串，Filter 返回 401，JSON 错误信息为“未登录或登录已过期”。这验证了 Filter 的拦截逻辑生效。
三个场景的联调结果给了我一个很直观的感受：JWT 加 Filter 这套方案，最大的价值不是技术上的“花哨”，而是把认证判断逻辑统一抽离到一个点，业务接口完全感受不到认证的存在，这让后续的接口开发变得非常干净。
4.3 Token 到底放哪里：请求头方案对 Cookie 方案的降维打击
前端拿到 token 后，存储位置也要提前约定。主流方案有两个：一个是放在Authorization请求头里，形如Authorization: Bearer xxx；另一个是写进 Cookie 里，由浏览器自动携带。我明确推荐请求头方案。
Cookie 方案最大的问题在于失去了跨域灵活性。如果你的小程序、App 以后要接入，Cookie 的存储和携带方式在不同平台的表现截然不同，很容易出现“浏览器好用、手机端掉链子”的局面。而请求头方案很纯粹，任何能发 HTTP 请求的客户端都能轻松处理，前端只需要在拦截器里给请求统一加上这一项请求头即可。
还有一个安全层面的考虑：不要Authorization请求头和 Cookie 两边都放，那样不仅没有任何好处，反而增加了令牌暴露面。选择一种方式，全局统一，文档写清楚，前后端异步沟通好，这是最省心的做法。
4.4 一个隐藏的坑：Filter 中 path 取不到HttpServletRequest的完整 URL
联调过程中我发现了一个细节，有时候在 Filter 里想根据 URL 判断要不要放行，但拿到的 path 不是预期值。最常见的场景是项目配置了 context-path（比如/app），此时request.getRequestURI()会带上/app前缀，而你自己写的白名单前缀是/api/auth/login，前缀匹配失败，所有请求被拦截。
解决方式是：统一比较时把 context-path 抠掉，或者资源配置里把白名单直接写成带前缀的完整路径。这个问题不会每次都出现，但出现了会不明所以地排查很久。我建议在过滤器的白名单校验方法里，对request.getRequestURI()做一次 context-path 前缀剥离，再走白名单匹配。
5. 容易被忽略的安全细节与项目落地建议
5.1 密钥管理：硬编码密钥是认证链路上的第一风险点
我在前面的代码示例里直接写了一个字符串密钥，这是在演示方便，但生产环境绝对不能这么干。硬编码密钥意味着密钥跟着代码仓库走，任何一个能看到代码的人都能签发任意身份的 token，整个认证体系形同虚设。
正确的做法是把密钥放到环境变量或配置中心，通过@Value或 Spring Environment 读取。部署到不同环境时，各自配置各自的密钥，一旦怀疑泄露，立刻轮换密钥，并配合 token 过期时间让旧令牌快速失效。如果项目安全要求比较高，建议直接用非对称签名 RS256，私钥签发 token、公钥验证 token，公钥可以安全下发给各业务服务，私钥只保存在认证中心。
5.2 主动失效：JWT 无状态带来的“踢人下线”难题
JWT 的好处是无状态，但无状态也带来一个棘手的问题：token 一旦签发，在过期之前服务端无法主动让它失效。用户要退出登录，如果前端只是把 token 从本地删掉，那服务端并不知道这件事，被偷走的 token 仍然有效。用户被管理员封禁，也要等 token 自然过期才能生效。
这不是无法解决的，常见做法是维护一个 token 黑名单，把需要提前失效的 token 在数据库或缓存中标记，Filter 校验时先查黑名单，命中则拒绝访问。另一个思路是引入版本号字段，用户修改密码或封禁时递增版本号，校验 token 时对比版本号与数据库当前值是否一致。这些方案会给系统增加一点额外维护成本，但业务有“强制下线”需求时，这是不可避免的代价。
5.3 不要让日志成为令牌泄露的第二通道
很多项目会在 Filter 或拦截器里把请求信息原样打到日志里，方便调试。如果请求头中包含了Authorization，日志里就会完整记录 token，而日志经常会进入日志采集系统，流转到各种运维平台，泄露途径非常难追踪。
我的经验是在日志过滤器里面对敏感头做脱敏处理。具体来说，记录Authorization时只记录前 20 个字符和后 10 个字符，中间用星号代替；对请求体的打印也要小心，登录接口的密码字段一定要排除掉。这一个习惯在我接手过的几个项目里都派上过用场，成本极低收益却很高。
5.4 传输安全与算法强度：别让 HTTPS 和签名算法拖后腿
JWT 是通过请求头传输的明文 bearer token，一旦被截获，截获者就能冒充用户请求接口。所以生产环境务必全程使用 HTTPS，这是底线。如果在本地测试阶段不方便配置证书，也要保持清醒的认知：HTTP 环境下的 token 传输是不安全的，千万不要拿着内网接口联调的经验直接套到公网环境。
签名算法方面，HS256 用起来简单，但它属于对称算法，签发和验证用同一个密钥，任何掌握密钥的服务都能伪造 token，适合单服务或内部信任环境的场景。多服务、微服务架构下，更推荐 RS256 这类非对称算法，认证中心持有私钥签发 token，各业务服务只持有公钥负责验签，密钥分发和权限边界都会清晰很多。
6. 几个实战时最容易卡壳的边界问题
6.1 过滤器没有生效：先查启动类有没有被忽略
@WebFilter注解需要配合 Spring Boot 的组件扫描才能被注册。如果用@ServletComponentScan的时候扫描路径写错了，或者过滤器类所在的包没有被扫描到，就会发生“过滤器明明写了，但就是没有拦截效果”的情况。排查时先看一下启动类上的两个注解：@SpringBootApplication默认扫描当前包及其子包，如果你的过滤器在子包外面，尤其容易出问题。
换成FilterRegistrationBean方式之后，这类问题基本消失，因为过滤器的注册走的是配置类，不依赖注解扫描。实际项目里我个人的习惯是统一用FilterRegistrationBean，原因就是被这个坑伤过。
6.2 解析 token 抛异常的时机比想象中晚
我第一次写解析逻辑时，以为 token 格式非法会立刻抛出异常，结果发现Jwts.parserBuilder().build().parseClaimsJws(token)的校验非常严格，任何一位字符的变化都会在第一时间抛出SignatureException。但当 token 是纯垃圾字符串时，异常类型是MalformedJwtException，这个比较容易区分。
还有一个意想不到的坑是：如果 token 里没有任何过期时间，或者setExpiration设置的是过去时间，parseClaimsJws会抛出ExpiredJwtException。所以在生成 token 时务必设置一个合理的过期时间，而且解析异常时不要笼统地 catch 成Exception，要分类处理，否则前端永远只能得到一句笼统的“认证失败”，排查效率会非常低。
6.3 过滤器与 Spring 容器隔离：拿不到 Bean 时怎么办
有些初学者写的过滤器是一个纯 Servlet 类，没有交给 Spring 管理，结果在doFilter里想调用 Service 和 Mapper，发现注解注入的字段全是 null。这是因为 Servlet 规范要求过滤器由 Servlet 容器创建，但我们的业务 Bean 由 Spring 容器管理。
如果过滤器类本身加上了@Component或被 Spring 扫描管理，Spring 会先创建过滤器并完成依赖注入，再通过FilterRegistrationBean注册给容器，这种情况下注入 Bean 是没问题的。所以记住一点：过滤器类要交给 Spring 管理，而不要自己用new创建。
7. 学习这条路走下来，我最大的一个感受
JWT 加 Filter 这套登录认证方案，初看就是“发一个令牌、验一个令牌”这么简单，实际操作过程中牵扯出的边界问题却比想象中多得多。最耗费时间的往往不是代码本身，而是那些看似不起眼的小问题：密钥太短报错了、路径匹配规则写错了、Filter 里拿不到 Spring Bean、日志把 token 打出去了、白名单漏掉导致无法登录。
我给自己的排查建议是，遇到认证链路相关的问题，永远按“请求是否到了过滤器、白名单是否放行、token 是否能解析、业务接口是否被调用”这个顺序去查，一层层加日志确认。这种结构化排查思路，比对着输出结果瞎猜要快得多。
最后分享一个我自己很受用的小习惯：把 JWT 的生成、解析、异常分类封装成一个工具类并写好单元测试，之后不管是写业务接口还是配新环境，都不会再担心认证逻辑出问题。登录认证是后端开发里一个绕不过去的门槛，把这个环节吃透了，后面再做权限控制、多角色校验、单点登录，都会有一种豁然开朗的感觉。
