SpringBoot3+Sa-Token实现双Token认证实战指南

1. 项目背景与核心需求在当今的Web应用开发中身份认证和权限控制是每个系统都无法绕开的核心模块。传统的Session-Cookie方案在分布式环境下存在诸多局限而单纯的JWT方案又难以解决无感刷新和主动注销等问题。这正是双Token机制Access Token Refresh Token逐渐成为主流的原因。我最近在一个企业级后台管理系统中采用了SpringBoot3 Sa-Token的组合实现双Token认证过程中踩了不少坑也积累了一些实战经验。Sa-Token作为国产轻量级权限认证框架其API设计非常符合国人习惯最新版本对SpringBoot3的支持也相当完善。下面我将分享完整的实现方案和避坑指南。2. 技术选型与环境准备2.1 为什么选择Sa-Token相比Shiro和Spring SecuritySa-Token具有几个明显优势学习曲线平缓中文文档完善开箱即用的Token管理功能内置分布式会话支持丰富的插件生态如SSO、OAuth2对国产框架如Ruoyi、若依友好2.2 基础环境搭建首先创建SpringBoot3项目添加依赖dependency groupIdcn.dev33/groupId artifactIdsa-token-spring-boot3-starter/artifactId version1.34.0/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency配置application.ymlsa-token: token-name: satoken timeout: 1800 # token有效期30分钟 activity-timeout: -1 # 无操作不续期 is-share: false # 不共享token is-read-body: true is-read-head: true token-style: uuid # token生成策略注意SpringBoot3默认使用Jakarta EE 9与SpringBoot2的javax包不兼容这是第一个容易踩的坑。3. 双Token机制实现3.1 核心设计原理双Token机制的核心逻辑Access Token短期有效如30分钟用于业务请求Refresh Token长期有效如7天用于获取新Access TokenAccess Token过期后客户端用Refresh Token获取新Token服务端可主动使Refresh Token失效实现强制登出3.2 登录接口实现创建AuthControllerRestController RequestMapping(/auth) public class AuthController { PostMapping(/login) public Result login(RequestBody LoginDTO dto) { // 1. 模拟用户验证 if(!admin.equals(dto.getUsername()) || !123456.equals(dto.getPassword())) { return Result.fail(账号或密码错误); } // 2. 生成双Token String accessToken SaManager.getSaTokenAction().createTokenValue(); String refreshToken SaManager.getSaTokenAction().createTokenValue(); // 3. 写入Redis实际项目应设置不同有效期 SaManager.getSaTokenDao().set(accessToken, dto.getUsername(), 1800); SaManager.getSaTokenDao().set(refresh:refreshToken, dto.getUsername(), 604800); // 4. 返回客户端 MapString,String result new HashMap(); result.put(accessToken, accessToken); result.put(refreshToken, refreshToken); return Result.ok(result); } }3.3 Token刷新机制添加刷新接口PostMapping(/refresh) public Result refresh(RequestHeader(refresh-token) String refreshToken) { // 1. 验证refreshToken有效性 String username SaManager.getSaTokenDao().get(refresh:refreshToken); if(username null) { return Result.fail(401, RefreshToken已失效); } // 2. 生成新accessToken String newAccessToken SaManager.getSaTokenAction().createTokenValue(); SaManager.getSaTokenDao().set(newAccessToken, username, 1800); // 3. 返回新tokenrefreshToken不变 return Result.ok(Collections.singletonMap(accessToken, newAccessToken)); }4. 安全防护与最佳实践4.1 防止Token盗用几个关键防护措施设置HttpOnly和Secure的Cookie如果使用Cookie实现IP绑定机制登录时记录IP每次请求校验限制Refresh Token使用频率如1分钟最多刷新5次关键操作要求二次认证4.2 并发控制方案当多个请求同时触发Token刷新时可能出现Race Condition。解决方案// 使用Redis分布式锁 String lockKey refresh_lock: username; try { boolean locked redisTemplate.opsForValue() .setIfAbsent(lockKey, 1, 10, TimeUnit.SECONDS); if(!locked) { throw new RuntimeException(操作太频繁); } // 执行刷新逻辑... } finally { redisTemplate.delete(lockKey); }4.3 会话管理增强Sa-Token默认的会话存储可能不满足生产需求建议自定义Token存储策略Configuration public class SaTokenConfig { Bean public SaTokenDao saTokenDao() { return new SaTokenDaoRedis(); } }实现会话事件监听Component public class MySaTokenListener implements SaTokenListener { Override public void doLogin(String loginType, Object loginId, String tokenValue, HttpServletRequest request, HttpServletResponse response) { log.info(用户{}登录成功Token:{}, loginId, tokenValue); } }5. 常见问题排查指南5.1 Token失效异常处理当遇到token exchange failed错误时按以下步骤排查检查Redis连接是否正常验证Token存储的Key命名规则是否一致确认Token未超过有效期检查是否有其他服务清除了Redis数据5.2 SpringBoot3兼容性问题升级到SpringBoot3后可能遇到Jakarta包名变更导致ClassNotFound解决方案确保所有依赖都支持Jakarta EE 9自动配置类路径变化检查META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.importsRedis客户端兼容性推荐使用Lettuce而非Jedis5.3 跨域与Cookie问题前端获取不到Token的常见原因跨域配置未包含凭证模式Bean public CorsFilter corsFilter() { UrlBasedCorsConfigurationSource source new UrlBasedCorsConfigurationSource(); CorsConfiguration config new CorsConfiguration(); config.setAllowCredentials(true); // 关键配置 config.addAllowedOriginPattern(*); config.addAllowedHeader(*); config.addAllowedMethod(*); source.registerCorsConfiguration(/**, config); return new CorsFilter(source); }前端Axios未设置withCredentials: true6. 性能优化建议6.1 Token存储优化使用Hash结构存储Token元数据// 代替简单的Key-Value存储 redisTemplate.opsForHash().put( user:token: username, access_token, tokenInfo );启用Redis管道批量操作redisTemplate.executePipelined((RedisCallbackObject) connection - { connection.stringCommands().set( (access: accessToken).getBytes(), username.getBytes(), Expiration.seconds(1800), RedisStringCommands.SetOption.UPSERT ); return null; });6.2 无感刷新方案前端可按照这个逻辑实现无感刷新async function requestWithRetry(url, options, retryCount 0) { try { const response await fetch(url, options); if (response.status 401 retryCount 2) { const refreshResponse await refreshToken(); if (refreshResponse.success) { options.headers.Authorization Bearer ${refreshResponse.accessToken}; return requestWithRetry(url, options, retryCount 1); } } return response; } catch (error) { // 错误处理 } }7. 扩展功能实现7.1 踢人下线功能实现强制下线某个用户的所有会话public void kickUser(String username) { // 1. 查找用户所有活跃Token SetString tokens redisTemplate.keys(access:*); for (String key : tokens) { if(username.equals(redisTemplate.opsForValue().get(key))) { redisTemplate.delete(key); } } // 2. 清除Refresh Token redisTemplate.delete(refresh:* username); }7.2 登录设备管理记录用户登录设备信息public void recordLoginDevice(String username, HttpServletRequest request) { String deviceId request.getHeader(Device-ID); if(deviceId null) { deviceId DigestUtils.md5Hex(request.getRemoteAddr() request.getHeader(User-Agent)); } String key user:devices: username; redisTemplate.opsForZSet().add( key, deviceId, System.currentTimeMillis() ); // 保留最近5个设备 redisTemplate.opsForZSet().removeRange(key, 0, -6); }在实际项目中双Token机制配合Sa-Token可以构建出既安全又灵活的身份认证体系。我建议在正式上线前做好以下几项验证Token过期逻辑测试包括并发刷新场景各种异常情况下的降级方案完整的压力测试特别是Token生成和验证环节安全审计重点关注Token生成算法和存储方式