在传统的单体应用中，HTTP 会话由 Web 容器直接管理，Tomcat 或 Jetty 会把 Session 对象保存在内存中，用户请求可以被路由到任意节点，如果第一次登录的请求打到了服务器 A，而下一个请求被负载均衡分发到了服务器 B，服务器 B 的容器中并没有之前创建的 Session，用户就会被认为是未登录的，业务上直接表现为频繁跳转到登录页。解决这个问题的核心思路就是把 Session 从单机的内存中剥离出来，存入一个所有节点都能访问的共享存储里，Redis 就是最常用的选择。Spring Session 的出现，让这个过程变得非常透明——开发者几乎不需要改动原有代码，只需要在 Spring Boot 中引入对应的 Starter 并完成几项配置，HttpSession 的读写就会自动转向 Redis，整个集群共享同一份 Session 数据。
理解 Spring Session 的工作机制
Spring Session 的核心思路是在 HttpSession 之上封装一层，通过一个自定义的 Filter 来拦截原始的 HttpServletRequest 和 HttpServletResponse。这个 Filter 会包装出一个 SessionRepositoryRequestWrapper，当应用代码调用 request.getSession() 时，实际上拿到的是 Spring Session 维护的 Session 实现，底层读写操作被代理到配置好的 SessionRepository 中。SessionRepository 就像是一个抽象的数据访问层，Spring Session 提供了多种实现：RedisOperationsSessionRepository 对应 Redis，JdbcOperationsSessionRepository 对应关系型数据库，还有基于 Hazelcast、MongoDB 的版本。
这种设计带来的好处是，你的业务代码完全不依赖 Servlet 容器的 Session 实现，更换后端存储甚至不需要改一行业务代码。同时，因为 Session 数据被持久化到外部存储，即使某台服务宕机，用户在其他节点上的请求依然可以读取到之前的会话，大大提升了系统的可用性。更值得关注的是，Spring Session 还支持 RESTful 场景下的 Header 方式传递 Session，虽然本文不重点展开，但了解这一点有助于你理解它的灵活性。
项目依赖与基础配置
在 Spring Boot 项目中整合 Spring Session，第一步是添加必要的 Maven 依赖。核心的 starter 是 spring-session-data-redis，它会自动引入 spring-session-core 和 spring-boot-starter-data-redis，保证 Spring Session 和 Redis 的自动配置无缝衔接。
<dependency>
<groupId>org.springframework.session</groupId>
<artifactId>spring-session-data-redis</artifactId>
</dependency>这里不需要再手动指定版本，因为当 Spring Boot 父 POM 里已经定义了 spring-session-bom，它会统一管理所有 Spring Session 模块的版本。如果你的项目还包含了 spring-boot-starter-web，Servlet 容器需要的支持也已经就绪。引入依赖后，Spring Boot 的自动装配会检测到 RedisConnectionFactory，默认启用 Redis 模式的 Session 存储，但我们仍然需要显式配置连接信息和一些重要参数，避免踩坑。
关于 Redis 的连接配置，你需要在 application.yml 或 application.properties 中指定 Redis 服务器的地址、端口和密码（如果有）。下面是一个典型的配置示例：
spring:
redis:
host: 127.0.0.1
port: 6379
password:
timeout: 3000ms
lettuce:
pool:
max-active: 8
max-idle: 8
min-idle: 0这里使用了 Lettuce 连接池，它是 Spring Boot 2.x 之后默认的 Redis 客户端。timeout 属性配置了命令等待超时的时间，建议不要使用默认的无限等待，避免线程阻塞。连接池的设置则根据服务并发量调整，上述数值适合中小规模的业务系统。完成这些基础配置后，Spring Session 就已经具备写入 Redis 的能力了。
启用 Spring Session 并定制行为
要让 Spring Boot 自动接管 Session 管理，你通常只需要在主配置类上添加 @EnableRedisHttpSession 注解。这个注解会触发一系列配置导入，包括创建 RedisOperationsSessionRepository Bean、注册 springSessionRepositoryFilter 等。但在 Spring Boot 环境中，这个注解其实不是强制使用的，因为 spring-session-data-redis 的自动配置类已经在底层完成了等价的工作，除非你需要自定义一些细节。
不过，为了更清晰地控制 Session 过期时间和 Cookie 名称等参数，建议在配置文件中显式声明，而不是依赖 Spring Session 的默认值。例如：
spring:
session:
timeout: 1800
redis:
namespace: myapp:session
flush-mode: on_save
store-type: redis这里的 timeout 单位是秒，1800 秒表示 Session 在无活动 30 分钟后失效。namespace 用来给存储在 Redis 中的键统一添加前缀，避免与其他系统共用同一个 Redis 实例时产生键冲突，所有 Session 数据将以 myapp:session:sessions: 和 myapp:session:expirations: 这样的形式保存。flush-mode 默认值是 on_save，表示每次 Session 更新都会立即写入 Redis，另一种模式 immediate 则会在每次 setAttribute 时立即刷新，适合对实时性要求极高的场景，但会带来一定的性能开销。
Cookie 相关的配置也值得注意。默认生成的 JSESSIONID Cookie 在跨域名或 HTTPS 场景下可能需要修改 same-site 属性，你可以在配置中通过 server.servlet.session.cookie 进行设定，比如 secure 和 http-only 标记。这些虽然不属于 Spring Session 的直接配置，但会直接影响分布式环境下的 Session 识别，比如在网关代理后需要确保 Cookie 路径和域设置正确。
编写代码进行验证
配置完成后，就可以通过一个简单的 Controller 来验证分布式 Session 是否生效。我们创建一个会话处理接口，用来写入和读取用户信息：
@RestController
public class SessionController {
@GetMapping("/set")
public String setSession(HttpSession session) {
session.setAttribute("username", "distributed-user");
return "Session 已保存，ID: " + session.getId();
}
@GetMapping("/get")
public String getSession(HttpSession session) {
Object username = session.getAttribute("username");
return "当前用户: " + (username != null ? username.toString() : "未登录");
}
}先启动一个应用实例，访问 /set 接口，返回 Session ID 后，再用该实例或另一个实例访问 /get，你会发现都能正确取出 username 的值。如果你有多台应用服务器连接到同一个 Redis，可以将项目打成两个不同端口的副本，通过 Nginx 分配请求，也能验证跨节点的共享效果。
测试时，可以直接打开 Redis 命令行客户端，输入 keys * 查看是否有 myapp:session:sessions: 开头的键，然后用 type 命令观察其数据结构——Spring Session 存储的是 hash 类型，字段包含 creationTime、lastAccessedTime、maxInactiveInterval 以及所有 session attribute。这种存储方式使得 Session 的查找和过期清理都非常高效。Spring Session 还会利用 Redis 的过期机制或自身的定时任务来清理过期的会话，确保存储空间不会无限增长。
常见问题与排查思路
在实际整合过程中，可能会遇到几个典型的问题。比如引入依赖后，访问接口一直报“Could not resolve placeholder”，通常是配置文件中的 spring.redis.host 未正确加载或者忘记配置 Redis 连接信息。Spring Boot 的自动配置在检测到 Redis 相关依赖后会尝试自动连接，如果连接失败，应用启动时就会抛异常。还有一个容易忽视的点是 Redis 版本兼容性，Spring Session 与 Lettuce 的版本需要匹配，如果项目自定义了 Lettuce 版本或使用了老版本的 Redis server，可能出现无法连接或命令不支持的报错。
另一个高频问题是 Session 序列化。当你在 Session 中存放自定义对象时，需要确保类实现了 java.io.Serializable 接口，否则写入 Redis 时会产生序列化异常。Spring Session 默认使用 JDK 序列化，你可以通过配置 RedisSerializer 将其切换为 JSON 序列化，但要注意 JSON 序列化可能丢失对象类型信息，取出时需要强制转型。稳妥的做法是在自定义对象上实现 Serializable 并保持一致，或者直接存储 String、基本类型的包装类等可序列化的数据。
此外，Cookie 导致 Session 丢失也是常见投诉。比如前端使用 Axios 请求时发现每次请求的 Session ID 都不同，这通常是因为跨域请求默认不携带 Cookie，需要设置 withCredentials 为 true，并在服务端配置跨域支持，允许携带凭证。Spring Boot 中可以通过 @CrossOrigin 注解或 CorsFilter 配置完成。
通过以上步骤，Spring Boot 与 Spring Session 的整合就顺利完成了。你不仅得到了一个集群友好的 Session 方案，还能借助 Redis 的高性能和持久化能力提升系统的整体可靠性。如果后续需要更换存储，只需替换对应的 Starter 和配置，业务代码几乎不受影响，这正是 Spring Session 架构设计的巧妙之处。
Spring_Session分布式SessionSpring_Boot修改时间：2026-08-12 07:18:41