如何在后端优雅地生成并传递动态错误提示？

在现代Web应用开发中，向前端返回清晰、准确且结构化的错误信息至关重要。这不仅能提升用户体验，还能简化前端应用的逻辑处理。然而，在复杂的业务场景下，如何优雅地处理那些需要动态生成的错误提示（例如，"密码错误，还剩2次尝试机会"），同时保持后端代码的整洁和职责分离，是一个常见的挑战。

本文将通过一个后台管理员登录验证的真实案例，详细介绍如何从一个基础的异常处理方案，逐步重构为一个专业、可维护且对前端友好的异常处理机制。

一、初始场景：登录失败计次与账户锁定

我们的需求很简单：在一个基于Spring Boot的后台管理系统中，实现管理员登录失败计次和临时锁定的功能。

• 核心安全策略：非超级管理员用户，在连续输错密码3次后，账户将被临时锁定15分钟。
• 用户体验要求：在用户输错密码时，需要明确告知其剩余的尝试次数；在账户被锁定时，需要告知其锁定时长。

在AdminAuthServiceImpl服务类中，我们很快实现了这个逻辑的核心代码：

scss 复制代码

// 伪代码 - 登录逻辑核心
// ...
if (!passwordEncoder.matches(loginDTO.getPassword(), adminUser.getPassword())) {
    // 增加失败次数
    Integer failCount = Optional.ofNullable(adminUser.getLoginFailCount()).orElse(0) + 1;
    adminUser.setLoginFailCount(failCount);
    
    // 如果失败次数达到3次，则锁定账户
    if (failCount >= 3) {
        adminUser.setStatus(2); // 设置状态为2：锁定
        // 在Redis中设置一个15分钟过期的锁定标记
        stringRedisTemplate.opsForValue().set("admin:lock:" + adminUser.getId(), "locked", 15, TimeUnit.MINUTES);
    }
    adminUserMapper.updateById(adminUser);
    throw new PasswordErrorException(ResultEnum.PASSWORD_ERROR);
}
// ...

代码逻辑本身没有问题，但一个新的挑战出现了：如何将"剩余尝试次数"或"账户已锁定"这类动态生成的信息，通过统一的JSON结构返回给前端？

二、探索问题：动态消息的传递困境

我们项目中已经建立了一套标准的异常处理流程：

1. 统一响应体 Result<T> ：所有API响应都包装在这个类中，包含code、message和data字段。
1. 错误码枚举 ResultEnum：定义了所有标准化的错误码和对应的静态错误消息。
1. 自定义业务异常 ：如 PasswordErrorException 等，它们在构造时接收一个 ResultEnum 对象。
1. 全局异常处理器 GlobalExceptionHandler ：负责捕获特定的业务异常，并将其转换为 Result 对象返回。

在这个体系下，GlobalExceptionHandler 的代码如下：

typescript 复制代码

// 原始的 GlobalExceptionHandler
@ExceptionHandler(PasswordErrorException.class)
public Result<String> handlePasswordErrorException(PasswordErrorException ex) {
    // 直接使用枚举中预设的静态消息："密码错误"
    return Result.error(ex.getResultEnum());
}

问题显而易见：Service 层虽然可以计算出剩余次数，但 PasswordErrorException 只能携带一个包含静态消息的 ResultEnum。我们精心构造的动态错误信息，无法被传递到 GlobalExceptionHandler，也就无法返回给前端。

三、解决方案的演进与最终选择

方案A：使用通用业务异常（存在缺陷）

一个直接的想法是，在 Service 层捕获所有异常，然后统一抛出一个可以携带任意字符串消息的 GeneralBusinessException。

typescript 复制代码

// Service层的catch块
catch (Exception e) {
    String errorMessage = ... // 动态生成错误消息
    throw new GeneralBusinessException(errorMessage);
}

// GlobalExceptionHandler中增加处理器
@ExceptionHandler(GeneralBusinessException.class)
public Result<String> handleGeneralBusinessException(GeneralBusinessException ex) {
    // 使用 Result.error(String message)
    return Result.error(ex.getMessage());
}

这个方案虽然能解决问题，但并不理想。Result.error(String message) 方法在我们的项目中只会设置 message，而 code 字段会是 null 或一个通用的失败码。这破坏了API错误响应的结构一致性，前端无法通过固定的 code 来判断具体的错误类型。

方案B：增强异常体系（最佳实践）

经过探讨，我们最终确定了一个更优雅的方案：在保持现有异常体系不变的基础上，对其进行微小的增强，使其能够携带动态消息。

这个方案分为三个核心步骤：

步骤 1：增强自定义异常类

我们为需要传递动态消息的异常类（如 PasswordErrorException 和 AccountForbiddenException）增加一个新的构造函数。这个构造函数接收一个字符串作为参数，用于传递我们动态生成的错误信息。

scala 复制代码

// 文件路径: zhimengjing-backend/src/main/java/com/sf/zhimengjing/common/exception/PasswordErrorException.java
@Getter
public class PasswordErrorException extends RuntimeException {
    private final ResultEnum resultEnum;

    public PasswordErrorException(ResultEnum resultEnum) {
        super(resultEnum.getMessage());
        this.resultEnum = resultEnum;
    }

    // 【新增的构造函数】
    public PasswordErrorException(String dynamicMessage) {
        super(dynamicMessage); // 将动态消息传递给父类
        this.resultEnum = ResultEnum.PASSWORD_ERROR; // 关联一个基础的错误码
    }
}

步骤 2：升级全局异常处理器

接下来，我们升级 GlobalExceptionHandler，让它能够"智能地"处理增强后的异常。它会优先使用异常对象中携带的动态消息，而不是枚举中的静态消息。

less 复制代码

// 文件路径: zhimengjing-backend/src/main/java/com/sf/zhimengjing/exception/handle/GlobalExceptionHandler.java
@ExceptionHandler(PasswordErrorException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
public Result<String> handlePasswordErrorException(PasswordErrorException ex) {
    log.warn("捕获到密码错误或账户锁定异常: {}", ex.getMessage());
    // 1. 先用枚举创建Result，确保 code 是正确的
    Result<String> result = Result.error(ex.getResultEnum());
    // 2. 用异常中携带的动态消息，覆盖掉默认消息
    result.setMessage(ex.getMessage());
    return result;
}

这种写法巧妙地利用了我们已有的 Result.error(ResultEnum) 方法，先保证了 code 的正确性，再用动态消息覆盖 message，完全不需要修改 Result.java 文件。

步骤 3：在 Service 层应用新方案

万事俱备，现在 AdminAuthServiceImpl 的 catch 块可以写得非常清晰：在计算出详细的错误信息后，直接用对应的异常类进行包装并抛出。

ini 复制代码

// 文件路径: zhimengjing-backend/src/main/java/com/sf/zhimengjing/service/impl/AdminAuthServiceImpl.java
// ...
catch (Exception e) {
    String errorMessage = e.getMessage();
    Long adminId = (adminUser != null) ? adminUser.getId() : null;

    if (e instanceof PasswordErrorException) {
        errorMessage = "密码错误";
        if (adminUser != null && adminUser.getRoleId() != 1L) {
            int remainingAttempts = 3 - Optional.ofNullable(adminUser.getLoginFailCount()).orElse(0);
            if (remainingAttempts <= 0) {
                errorMessage = String.format("您的账户已被锁定，请在 %d 分钟后重试。", 15);
            } else {
                errorMessage = String.format("密码错误，还剩 %d 次尝试机会。", remainingAttempts);
            }
        }
        recordLoginLog(adminId, loginDTO.getUsername(), ip, userAgent, 0, errorMessage);
        // 抛出携带动态消息的 PasswordErrorException
        throw new PasswordErrorException(errorMessage); 

    } else if (e instanceof AccountForbiddenException) {
        errorMessage = String.format("您的账户已被禁用或锁定，请在 %d 分钟后重试或联系管理员。", 15);
        recordLoginLog(adminId, loginDTO.getUsername(), ip, userAgent, 0, errorMessage);
        // 抛出带有动态消息的 AccountForbiddenException
        throw new AccountForbiddenException(errorMessage);

    } else {
        // 对于其他不需要动态消息的异常，直接记录日志并重新抛出
        recordLoginLog(adminId, loginDTO.getUsername(), ip, userAgent, 0, e.getMessage());
        throw e;
    }
}

四、结论

通过对现有异常体系进行微小的、非侵入式的增强，我们成功地实现了一个既能保持代码结构清晰、又能向前端提供丰富动态信息的错误处理机制。这种方案充分利用了项目中已有的良好设计，体现了软件开发中"开闭原则"的思想，是值得在团队中推广的最佳实践。最终，前端可以稳定地接收到如下所示的、信息量十足的JSON响应，从而极大地提升了用户体验。

json 复制代码

// 密码错误时的响应
{
  "code": 1006,
  "message": "密码错误，还剩 2 次尝试机会。",
  "data": null
}

// 账户锁定时期的响应
{
  "code": 1002,
  "message": "您的账户已被禁用或锁定，请在 15 分钟后重试或联系管理员。",
  "data": null
}