Spring Security 中应优先使用内置 AuthenticationException 子类（如 BadCredentialsException），自定义异常需继承 AuthenticationException 并保持语义清晰，且必须在 AuthenticationProvider 中抛出以触发标准处理流程。
在 Spring Security 中，AuthenticationException 是认证失败时抛出的基类异常，它本身是受检异常（RuntimeException 的子类），用于统一表达“认证不通过”的语义。要自定义认证异常，通常不是直接继承 AuthenticationException 编写新异常类（虽然可行），而是更推荐复用其已有子类或按规范扩展——因为 Spring Security 内部大量依赖这些标准异常类型来触发对应处理逻辑（如跳转登录页、返回 401、填充错误信息等）。
优先使用 Spring Security 内置的认证异常子类
Spring Security 已提供多个语义明确的 AuthenticationException 子类，例如：
-
BadCredentialsException：用户名或密码错误 -
DisabledException：用户被禁用 -
LockedException：账户被锁定（如连续输错密码） -
AccountExpiredException：账户过期 -
CredentialsExpiredException：凭证（如密码）过期 -
InsufficientAuthenticationException：认证信息不足（如未提供 token）
这些异常会被 ExceptionTranslationFilter 自动识别，并交由 AuthenticationEntryPoint 处理（如返回 401 或重定向）。直接抛出它们，比自定义一个全新异常更安全、更符合框架约定。
需要自定义异常时：继承 AuthenticationException 并保持语义清晰
如果业务场景确实需要专属异常（比如“短信验证码已失效”、“微信授权临时 code 已过期”），可新建异常类，但需注意以下几点：
立即学习“Java免费学习笔记（深入）”；
- 继承
AuthenticationException，而非普通RuntimeException - 构造函数至少保留
String message和Throwable cause两个签名，方便链式传递上下文 - 避免覆盖默认序列化行为（除非有特殊需求）
- 建议添加一个
Serializable标识（虽非强制，但利于分布式环境）
示例：
public class WechatCodeExpiredException extends AuthenticationException implements Serializable {
public WechatCodeExpiredException(String msg) {
super(msg);
}
public WechatCodeExpiredException(String msg, Throwable cause) {
super(msg, cause);
}
}
在认证逻辑中正确抛出和处理自定义异常
自定义异常只有被 Spring Security 捕获并识别，才能触发标准流程。关键点：
- 在
AuthenticationProvider.authenticate()方法中，认证失败时直接throw new XXXException(...) - 不要在 Controller 层 catch 后再 throw 自定义异常——这会绕过 Security 过滤器链，导致 401 不生效
- 若需返回结构化错误响应（如 JSON），应配置全局异常处理器（
@ControllerAdvice），但仅用于补充日志或增强提示，不能替代 Security 原生异常机制 - 如需对特定异常定制响应，可实现
AuthenticationEntryPoint或重写SimpleUrlAuthenticationFailureHandler
补充：异常信息本地化与前端友好提示
异常消息不应直接暴露给前端（尤其含敏感信息）。推荐做法：
- 异常中只传英文简短 code 或 key（如
"wechat_code_expired"） - 在
messages.properties中配置多语言提示 - 通过统一错误响应包装器，将异常 key 映射为前端可读文案
- 避免在异常消息里拼接用户输入或数据库字段值
