身份认证与应用安全 / 系统课时
梳理 Sa-Token 认证链路
梳理 Sa-Token 认证链路
登录认证真正要跑通的不是一个 login 接口,而是一条“校验凭据→建立登录态→发回 Token→携带 Token→恢复身份”的闭环。本节把每一步的责任边界拆开,便于接入时快速判断问题发生在哪一段。
学习目标
- 区分业务侧账号密码校验与 Sa-Token 会话登录的职责
- 说清 Token 从生成、返回到后续请求被识别的完整链路
- 根据登录断点判断应检查凭据、Token 传递还是服务端登录状态
先分清密码校验和会话登录
Sa-Token 负责“这个请求当前是谁、是否已经登录”,但不会替业务系统查询用户表并自动判断账号密码是否正确。登录接口仍要先查询账号、校验密码摘要、检查账号状态;只有这些业务条件通过后,才调用 StpUtil.login(loginId) 建立登录态。
loginId 应使用稳定且唯一的业务账号标识,例如用户主键。它不是密码,也不应该随着昵称、手机号等可变资料改变。这样后续 Token 即使更新,服务端仍能稳定地把会话映射回同一账号。
登录成功时发生了什么
业务校验通过后,StpUtil.login(loginId) 会让 Sa-Token 为当前登录建立 Token 与账号标识之间的关联,并记录有效期等登录状态。前后端分离项目通常把 tokenName 和 tokenValue 返回给客户端;客户端保存后,在后续请求中按约定再次提交。

这条链路的关键是:Token 是客户端以后用来证明“我持有这个登录会话”的凭证,而 loginId 才是服务端识别账号的业务身份。两者不要混为同一个字段。
后续请求怎样恢复登录态
后续请求到达时,客户端需要按服务端配置的 Token 名称提交 Token 值。Sa-Token 从当前请求上下文读取 Token,再查询对应登录状态并检查其是否仍然有效;StpUtil.checkLogin() 校验通过后,业务代码就可以继续获取当前 loginId。
在前后端分离场景中,常见做法是把 Token 放在请求 Header 中,Header 名称与 token-name 配置保持一致。若登录接口已经成功,但下一次请求仍被判定未登录,优先检查客户端是否保存了正确 Token、请求是否真正带上它,以及名称是否一致。
按链路定位常见断点
| 现象 | 优先检查 |
|---|---|
| 账号密码正确却始终没有登录态 | 业务校验成功后是否真正调用了 StpUtil.login(loginId) |
| 登录接口返回成功,下一请求却未登录 | Token 是否返回、保存并按正确名称再次提交 |
| Token 已携带但服务端仍无法识别 | Token 名称、Token 值、有效期以及服务端登录状态是否匹配 |
| 单机正常,多实例后偶发掉登录 | 多个实例是否读取同一份会话持久化数据 |
把认证理解成这条闭环后,排错就不需要从控制器一直猜到数据库:先确认凭据校验,再确认登录态建立,再确认 Token 交付与回传,最后确认服务端能根据 Token 恢复账号身份。