Spring Boot 实战：基于 Redis + Token 实现分布式登录系统

ShaneD7712025-12-10 17:21

1. 设计思路

在分布式系统或前后端分离的架构中，我们需要一种无状态的登录方案。核心设计思路如下：

  1. 凭证机制 ：使用 Token（随机字符串）作为用户身份的唯一标识，替代传统的 Cookie。
  2. 数据存储 ：将用户的登录状态（Token 与用户信息的映射）存储在 Redis 中，利用其高性能和自动过期机制。
  3. 状态管理 ：
    • Redis：作为服务端共享的"会话存储中心"。
    • ThreadLocal：作为单次请求内的"上下文容器"，方便 Controller 和 Service 层获取用户信息。
  4. 请求拦截 ：采用 双拦截器模式，分离"Token 刷新"与"登录鉴权"的职责。

2. 代码实现

2.1 步骤一：发送短信验证码

验证码需要有短期的有效期（如 2 分钟），适合使用 Redis 的 String 结构存储。

  • Key : login:code:{手机号}
  • Value: 验证码数字
typescript 复制代码 
@Override
public Result sendCode(String phone) {
    // 1. 校验手机号格式
    if (RegexUtils.isPhoneInvalid(phone)) {
        return Result.fail("手机号格式错误");
    }

    // 2. 生成 6 位随机验证码
    String code = RandomUtil.randomNumbers(6);

    // 3. 保存验证码到 Redis
    // 设置 2 分钟过期
    stringRedisTemplate.opsForValue().set(RedisConstants.LOGIN_CODE_KEY + phone, code, 2, TimeUnit.MINUTES);

    // 4. 模拟发送短信（实际项目中调用短信服务商 API）
    log.debug("发送验证码成功，验证码：{}", code);
    return Result.ok();
}

2.2 步骤二：登录并生成 Token

登录成功后，我们需要生成 Token，并将用户对象存储为 Redis 的 Hash 结构。Hash 结构适合存储对象，且内存占用更优。

  • Key : login:token:{随机Token}
  • Value: User 对象的字段映射 (Hash)
ini 复制代码 
@Override
public Result login(LoginFormDTO loginForm) {
    String phone = loginForm.getPhone();

    // 1. 从 Redis 获取验证码并校验
    String cacheCode = stringRedisTemplate.opsForValue().get(RedisConstants.LOGIN_CODE_KEY + phone);
    String code = loginForm.getCode();
    if (cacheCode == null || !cacheCode.equals(code)) {
        return Result.fail("验证码错误");
    }

    // 2. 根据手机号查询用户（若不存在则注册，代码略）
    User user = query().eq("phone", phone).one();
    if (user == null) {
        user = createUserWithPhone(phone);
    }

    // 3. 生成随机 Token (作为登录令牌)
    String token = UUID.randomUUID().toString(true);

    // 4. 将 User 对象转为 HashMap 存储
    // 核心细节：StringRedisTemplate 要求 Value 必须是 String，
    // 所以必须将 Long 类型的 ID 强转为 String，否则会报 ClassCastException
    UserDTO userDTO = BeanUtil.copyProperties(user, UserDTO.class);
    Map<String, Object> userMap = BeanUtil.beanToMap(userDTO, new HashMap<>(),
            CopyOptions.create()
                    .setIgnoreNullValue(true)
                    .setFieldValueEditor((fieldName, fieldValue) -> fieldValue.toString()));

    // 5. 存储到 Redis
    String tokenKey = RedisConstants.LOGIN_USER_KEY + token;
    stringRedisTemplate.opsForHash().putAll(tokenKey, userMap);
    
    // 6. 设置有效期（例如 30 分钟）
    stringRedisTemplate.expire(tokenKey, RedisConstants.LOGIN_USER_TTL, TimeUnit.MINUTES);

    // 7. 返回 Token 给前端
    return Result.ok(token);
}
rust 复制代码 
Redis 数据库
│
├── Key: "login:token:xyz-123"  <-- 这是你设置的 Redis Key (Token)
│   │
│   └── Value (Hash结构)       <-- 这是一个大容器
│       ├── Field: "id"        --> Value: "101"   (必须是 String)
│       ├── Field: "nickName"  --> Value: "小明"  (必须是 String)
│       └── Field: "icon"      --> Value: "/a.jpg" (必须是 String)

2.3 步骤三：构建"双拦截器"防御体系

为了实现 "用户只要在使用 App，登录状态就一直有效" 的无感刷新体验，我们将拦截器拆分为两层。

第一层：Token 刷新拦截器 (RefreshTokenInterceptor)

  • 拦截路径 ：所有路径 (/**)
  • 职责 ：只要携带了 Token，就刷新 Redis 有效期，并保存用户信息到 ThreadLocal。不负责拦截请求。
java 复制代码 
public class RefreshTokenInterceptor implements HandlerInterceptor {

    private StringRedisTemplate stringRedisTemplate;

    // 构造函数注入 StringRedisTemplate
    public RefreshTokenInterceptor(StringRedisTemplate stringRedisTemplate) {
        this.stringRedisTemplate = stringRedisTemplate;
    }

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // 1. 获取请求头中的 token
        String token = request.getHeader("authorization");
        if (StrUtil.isBlank(token)) {
            return true; // 没 Token 也放行，交给下一道拦截器
        }

        // 2. 基于 token 获取 Redis 中的用户
        String key = RedisConstants.LOGIN_USER_KEY + token;
        Map<Object, Object> userMap = stringRedisTemplate.opsForHash().entries(key);

        // 3. 判断用户是否存在
        if (userMap.isEmpty()) {
            return true; // Token 无效或过期，也放行
        }

        // 4. 将查询到的 Map 转为 UserDTO 对象
        UserDTO userDTO = BeanUtil.fillBeanWithMap(userMap, new UserDTO(), false);

        // 5. 保存到 ThreadLocal (供后续业务使用)
        UserHolder.saveUser(userDTO);

        // 6. 【核心动作】刷新 Token 有效期
        stringRedisTemplate.expire(key, RedisConstants.LOGIN_USER_TTL, TimeUnit.MINUTES);

        // 7. 放行
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        // 请求结束，清理 ThreadLocal，防止内存泄漏
        UserHolder.removeUser();
    }
}

第二层：登录拦截器 (LoginInterceptor)

  • 拦截路径：敏感业务路径 (排除首页、登录接口等)
  • 职责 ：只检查 ThreadLocal 是否有用户。如果没有，则拦截并返回 401。
java 复制代码 
public class LoginInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // 1. 判断 ThreadLocal 中是否有用户
        if (UserHolder.getUser() == null) {
            // 2. 没有用户，拦截并返回 401 (未授权)
            response.setStatus(401);
            return false;
        }
        // 3. 有用户，放行
        return true;
    }
}

2.4 步骤四：配置拦截器 (MvcConfig)

在配置类中注册这两个拦截器，并通过 order 控制执行顺序：先刷新，后拦截。

typescript 复制代码 
@Configuration
public class MvcConfig implements WebMvcConfigurer {

    @Resource
    private StringRedisTemplate stringRedisTemplate;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 1. 注册刷新拦截器 (Order = 0, 最先执行)
        // 拦截所有请求，确保用户访问任何页面都能刷新 Token
        registry.addInterceptor(new RefreshTokenInterceptor(stringRedisTemplate))
                .addPathPatterns("/**")
                .order(0);

        // 2. 注册登录拦截器 (Order = 1, 后执行)
        // 只拦截需要保护的接口
        registry.addInterceptor(new LoginInterceptor())
                .excludePathPatterns(
                        "/user/login",
                        "/user/code",
                        "/blog/hot",
                        "/shop/**",
                        "/shop-type/**",
                        "/upload/**",
                        "/voucher/**"
                ).order(1);
    }
}

3. 业务层使用

在 Controller 或 Service 层，无需再操作 Request 或 Redis，直接从 ThreadLocal 获取当前登录用户即可。

java 复制代码 
@GetMapping("/me")
public Result me(){
    // 直接获取当前用户
    UserDTO user = UserHolder.getUser();
    return Result.ok(user);
}

4. 总结

这套 Redis + Token + 双拦截器 的方案具有以下优势：

  1. 高性能：Redis 的读写速度极快，不会拖慢请求响应。
  2. 无感刷新 ：通过 RefreshTokenInterceptor，解决了用户在使用过程4中 Token 突然过期的问题。
  3. 职责单一：登录逻辑只负责生成 Token，拦截器只负责鉴权，业务层只负责业务，代码结构清晰，耦合度低。
相关推荐
半桶水专家1 小时前
go语言中的结构体嵌入详解
开发语言·后端·golang
佳佳_3 小时前
关于在 Fabric.js 中注册字体覆盖的问题
后端·node.js
GoGeekBaird4 小时前
通过ChatGPT+Nano Banana定制一个 PPT 生成的工作流
后端
用户21411832636024 小时前
手把手教你部署AI视频复刻神器！一键生成Sora2级别视频
后端
计算机学姐4 小时前
基于SpringBoot的高校论坛系统【2026最新】
java·vue.js·spring boot·后端·spring·java-ee·tomcat
Victor3565 小时前
Hibernate（13） Hibernate的一级缓存是什么？
后端
毕设源码-赖学姐5 小时前
【开题答辩全过程】以 基于SpringBoot的健身房管理系统的设计与实现为例，包含答辩的问题和答案
java·spring boot·后端
Victor3565 小时前
Hibernate（14）什么是Hibernate的二级缓存？
后端
czlczl200209255 小时前
SpringBoot自动配置AutoConfiguration原理与实践
开发语言·spring boot·后端
heartbeat..6 小时前
Servlet 全面解析（JavaWeb 核心）
java·网络·后端·servlet
热门推荐
01GitHub 镜像站点02Linux下V2Ray安装配置指南03从快手“12·22”直播攻击事件看：一次教科书式的业务层饱和攻击04jdk21下载、安装（Windows、Linux、macOS）05Claude Code Skills 实用使用手册06UV安装并设置国内源072025 最新教程：注册并切换到美区 Apple ID08【踩坑笔记】50系显卡适配的 PyTorch 安装09电脑检测软件—图吧工具箱10Google Antigravity Agent 编辑器操作教程