身份认证与应用安全 / 系统课时
引入依赖并完成基础配置
引入依赖并完成基础配置
基础接入只做两件事:让 Spring Boot 正确加载 Sa-Token Starter,并把 Token 名称与有效期交给统一配置。下面以 Spring Boot 3.x 与 Sa-Token 1.46.0 为例,完成依赖、YAML 配置和最小验证。
学习目标
- 根据 Spring Boot 主版本选择正确的 Sa-Token Starter
- 配置统一的
token-name与timeout并理解它们影响的客户端行为 - 通过一个最小接口验证应用实际读取到的 Sa-Token 配置
先匹配 Spring Boot 主版本
Sa-Token 为不同 Spring Boot 主版本提供了对应 Starter。Spring Boot 2.x 使用 sa-token-spring-boot-starter,3.x 使用 sa-token-spring-boot3-starter,4.x 使用 sa-token-spring-boot4-starter。不要只看包名相似就混用,否则容易在 Servlet API 或自动配置阶段出现兼容问题。
如果项目同时引入多个 Sa-Token 模块,应尽量保持版本一致。下面主示例固定使用 Spring Boot 3.x,因此选择 sa-token-spring-boot3-starter。
引入 Sa-Token Starter
下面是 pom.xml 的片段示例,需要放进现有 Maven 工程的 <dependencies> 节点中;它依赖已有的 Spring Boot Web 项目上下文,并不是一份完整 POM。
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-spring-boot3-starter</artifactId>
<version>1.46.0</version>
</dependency>生效行为:Maven 解析依赖后,Spring Boot 启动时会加载 Sa-Token 的相关自动配置。若项目不是 Spring Boot 3.x,应先替换为对应主版本的 Starter,再继续配置。
配置 Token 名称与有效期
在 src/main/resources/application.yml 中加入下面配置。token-name 决定客户端提交 Token 时使用的名称;timeout 表示 Token 有效期,单位为秒。
sa-token:
token-name: X-Token
timeout: 7200这份配置把 Token 名称统一为 X-Token,有效期设置为 7200 秒,也就是 2 小时。前后端分离时,如果客户端后续通过 Header 提交 Token,就必须使用同样的 X-Token 名称;修改服务端名称后,客户端也要同步调整。
用最小接口验证配置
在已有 Spring Boot 应用中新增下面完整 Controller。它只用于学习或本地验证,读取 Sa-Token 当前实际生效的配置,避免仅凭 YAML 猜测是否绑定成功。
package com.example.auth;
import java.util.LinkedHashMap;
import java.util.Map;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import cn.dev33.satoken.SaManager;
@RestController
@RequestMapping("/debug/sa-token/config")
public class SaTokenConfigController {
@GetMapping
public Map<String, Object> config() {
Map<String, Object> result = new LinkedHashMap<>();
// 直接读取运行时配置,验证 YAML 是否真正绑定到 Sa-Token。
result.put("tokenName", SaManager.getConfig().getTokenName());
result.put("timeout", SaManager.getConfig().getTimeout());
return result;
}
}预期结果:应用能够正常启动,并注册 GET /debug/sa-token/config。将 <PORT> 替换为实际 Spring Boot 监听端口;实际值可能不同,然后执行:
curl -s http://localhost:<PORT>/debug/sa-token/config预期输出:
{"tokenName":"X-Token","timeout":7200}如果返回值仍是默认 Token 名称或默认有效期,说明应用没有读取到这份配置,而不是客户端传 Token 的问题。
配置没有生效时怎么查
先确认 Starter 与 Spring Boot 主版本匹配,再检查 application.yml 的缩进和 sa-token 根节点是否正确。若项目使用 application-dev.yml、application-prod.yml 等 Profile,还要确认启动时真正激活的是哪一份配置。
接着检查是否存在重复配置覆盖当前值,以及多个 Sa-Token 依赖是否使用一致版本。最后重启应用并重新访问验证接口;只有运行时读取到 X-Token 和 7200,才说明基础配置已经闭环生效。