身份认证与应用安全 / 系统课时
编写账号密码登录接口
编写账号密码登录接口
账号密码登录的关键不是“调用登录 API”,而是先在业务层确认账号真实存在、密码校验通过,再把稳定的用户 ID 交给 Sa-Token 建立会话。本文用一个最小 Spring Boot 接口跑通这条链路,并把密码处理和错误返回边界说明清楚。
学习目标
- 区分账号密码校验与 Sa-Token 会话建立各自负责的事情
- 使用密码哈希校验结果决定是否调用
StpUtil.login - 用 HTTP 请求验证合法凭证能登录、错误凭证会被拒绝
登录职责边界
StpUtil.login(loginId) 的职责是把一个已经确认身份的账号标记为登录,并创建对应会话。它不会替你查询用户,也不会判断密码是否正确。因此调用顺序必须是:查询账号 → 校验密码哈希 → 登录。

登录标识应使用数据库中的稳定主键,例如 userId。不要把用户名、密码或其他可变、敏感字段直接当作登录标识。
实现登录接口
片段示例:以下控制器依赖一个已接入 Spring Boot、Sa-Token 和 spring-security-crypto 的项目环境。示例用内存 Map 模拟账号查询,便于独立理解;生产项目应替换为数据库 Repository,并保存预先计算好的密码哈希。
package com.example.auth;
import cn.dev33.satoken.stp.StpUtil;
import org.springframework.http.HttpStatus;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;
import java.util.Map;
@RestController
@RequestMapping("/api/auth")
public class LoginController {
private final BCryptPasswordEncoder passwordEncoder = new BCryptPasswordEncoder();
private final Map<String, UserAccount> accounts;
public LoginController() {
accounts = Map.of(
"alice",
new UserAccount(
10001L,
"alice",
passwordEncoder.encode("P@ssw0rd!")
)
);
}
@PostMapping("/login")
public LoginResponse login(@RequestBody LoginRequest request) {
if (request == null || request.username() == null || request.password() == null) {
throw new ResponseStatusException(HttpStatus.UNAUTHORIZED, "账号或密码错误");
}
UserAccount account = accounts.get(request.username());
// 先验证业务凭证;失败时绝不能调用 StpUtil.login。
if (account == null || !passwordEncoder.matches(request.password(), account.passwordHash())) {
throw new ResponseStatusException(HttpStatus.UNAUTHORIZED, "账号或密码错误");
}
// 到这里身份已经确认,再让 Sa-Token 建立登录会话。
StpUtil.login(account.id());
return new LoginResponse(account.id(), account.username());
}
public record LoginRequest(String username, String password) {}
public record LoginResponse(long userId, String username) {}
private record UserAccount(long id, String username, String passwordHash) {}
}示例为了演示而在启动时生成哈希;真实系统应在注册或改密时生成哈希并持久化,登录时只调用 matches 校验。接口对“账号不存在”和“密码错误”返回同一类错误,可以避免向外部泄露账号是否存在。
验证登录结果
启动应用后,用正确凭证请求登录。将 <PORT> 替换为应用实际端口。
curl -sS -X POST "http://localhost:<PORT>/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"username":"alice","password":"P@ssw0rd!"}'预期输出:
{"userId":10001,"username":"alice"}响应成功只能说明这次身份校验与 StpUtil.login 已执行完成。把密码改成错误值时,接口应返回 HTTP 401,而且不会建立登录会话。
生产环境需要守住的边界
数据库中只保存强密码哈希及必要参数,不保存明文密码;日志也不要记录请求体中的密码。认证失败统一返回模糊错误,真正原因写入受控审计日志。账号锁定、验证码、失败次数限制等策略应放在调用 StpUtil.login 之前,因为它们都属于“是否允许建立会话”的业务判断。
当账号查询和密码验证完成后,StpUtil.login(userId) 才是认证链路的最后一步。这样可以确保 Sa-Token 管理的是已经被业务系统确认过的身份,而不是替业务层做凭证判断。