优雅处理业务异常：自定义异常与全局映射

后端错误处理重构：自定义业务异常与全局映射实践

在后端接口开发中，错误处理逻辑往往占据了大量代码篇幅。当参数校验失败或业务规则不满足（如资源不存在、状态不合法）时，直接在各层构建包含错误信息的 Response 对象会导致代码耦合度过高。这种做法不仅产生大量重复的样板代码，还难以保证整个 API 接口错误返回格式的一致性。

在 Quarkus 或标准的 JAX-RS 架构中，利用 自定义异常（Custom Exception） 结合 全局异常映射器（ExceptionMapper） 是实现业务逻辑与错误处理解耦的最佳实践。

核心问题分析

对于业务层面的阻断（如“余额不足”或“参数为空”），如果直接抛出原生的 RuntimeException，框架默认会将其视为服务器内部错误，返回 HTTP 500 状态码。这会带来两个问题：

1. 协议语义错误：业务校验失败通常属于客户端请求的问题，应当返回 HTTP 400 (Bad Request)，而非代表服务崩溃的 500。
2. 前端解析困难：原生异常缺乏结构化的错误码（Error Code），前端无法根据错误类型进行差异化处理（如弹窗提示 vs 跳转页面）。

因此，需要引入专门的业务异常类来承载业务错误信息。

1. 定义 BusinessException

首先，定义一个继承自 RuntimeException 的异常类。选择非受检异常（Unchecked Exception）是为了避免在每一层方法签名中显式声明异常，保持代码整洁。

该类除了包含错误信息（message）外，还应包含一个 code 字段，用于标识具体的业务错误类型。

/**
 * 自定义业务异常
 * 用于处理预期的业务阻断，如参数校验失败、资源未找到等
 */
public class BusinessException extends RuntimeException {
    
    private final String code;

    public BusinessException(String code, String message) {
        super(message);
        this.code = code;
    }

    public String getCode() {
        return code;
    }
}

同时，定义一个标准的错误响应对象（DTO），用于序列化 JSON 返回给客户端：

public class ErrorResponse {
    public String code;
    public String message;

    public ErrorResponse(String code, String message) {
        this.code = code;
        this.message = message;
    }
}

2. 实现全局异常映射器 (ExceptionMapper)

JAX-RS 规范提供了 ExceptionMapper 接口，允许拦截特定类型的异常并将其转换为 HTTP 响应。这一步是将“Java 异常”转换为“HTTP 协议”的关键。

创建一个实现类并添加 @Provider 注解，框架启动时会自动注册该组件。

import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;

@Provider
public class BusinessExceptionMapper implements ExceptionMapper<BusinessException> {

    @Override
    public Response toResponse(BusinessException e) {
        // 1. 构建统一的响应体
        ErrorResponse body = new ErrorResponse(e.getCode(), e.getMessage());
        
        // 2. 返回 HTTP 400 Bad Request
        // 业务异常通常意味着客户端请求参数或状态不符合业务要求
        return Response.status(Response.Status.BAD_REQUEST)
                       .entity(body)
                       .build();
    }
}

该映射器的作用在于：无论业务代码在何处抛出 BusinessException，最终都会流转到此处，统一封装为 HTTP 400 状态码和 JSON 格式的响应体。

3. 业务代码的简化

完成上述配置后，Controller (Resource) 层的代码结构将发生显著变化。

重构前（包含大量防御性代码）：

@GET
public Response getUserInfo(Long id) {
    if (id == null) {
        return Response.status(400).entity("ID不能为空").build();
    }
    User user = userService.findById(id);
    if (user == null) {
        return Response.status(400).entity("用户不存在").build();
    }
    return Response.ok(user).build();
}

重构后（关注点分离）：

@GET
public Response getUserInfo(Long id) {
    // 1. 校验逻辑：直接抛出异常
    if (id == null) {
        throw new BusinessException("INVALID_PARAM", "ID不能为空");
    }

    User user = userService.findById(id);
    
    // 2. 业务逻辑：直接抛出异常
    if (user == null) {
        throw new BusinessException("USER_NOT_FOUND", "用户不存在");
    }

    // 3. 正常流程：仅返回成功数据
    return Response.ok(user).build();
}