编写封装HTTP API的类时，遇HTTP 404等错误应抛出何种合适异常？

这问题问到点子上了——封装API抽象层的核心，就是既要把底层HTTP的琐碎细节给上层调用者藏起来，又得把错误信息传递得精准到位，让调用者能轻松区分「业务逻辑失败」和「API访问层失败」。

先说结论：优先自定义一套语义化的API访问异常体系，而不是用语言自带的通用异常，针对404这类特定状态码，要抛出对应细分的自定义异常。

为什么不直接用通用异常？ #

比如Java里的IOException、Python里的requests.exceptions.HTTPError，这类异常太宽泛了——上层调用者捕获到之后，根本没法直接判断是「网络断了」「资源不存在」还是「服务器炸了」，处理逻辑会变得混乱，也完全不符合你说的「针对API访问层失败的特定异常」需求。

怎么设计自定义异常？ #

建议分两层来做，兼顾语义清晰度和调试便利性：

• 根异常类：先定义一个所有API访问相关异常的父类，比如WebServiceAccessException，它可以携带通用的调试信息：HTTP状态码、请求URL、响应内容片段等，方便开发者排查问题。
• 细分异常类：针对不同的HTTP状态码，定义对应的子类，让异常语义化：
  • 对于404，专门定义ResourceNotFoundException，明确表示「请求的资源不存在」，上层调用者看到这个异常就知道该做什么（比如提示用户资源已删除、触发降级逻辑等）
  • 其他常见状态码也可以对应：WebServiceUnauthorizedException（401，未授权）、WebServiceForbiddenException（403，禁止访问）、WebServiceServerErrorException（5xx，服务器端错误）等

举个代码示例（Java风格） #

// 根异常：所有API访问失败的统一父类
public class WebServiceAccessException extends RuntimeException {
    private final int httpStatusCode;
    private final String requestUrl;

    public WebServiceAccessException(String message, int statusCode, String url, Throwable cause) {
        super(message, cause);
        this.httpStatusCode = statusCode;
        this.requestUrl = url;
    }

    // 提供getter方法，方便上层获取调试信息
    public int getHttpStatusCode() { return httpStatusCode; }
    public String getRequestUrl() { return requestUrl; }
}

// 针对404的细分异常
public class ResourceNotFoundException extends WebServiceAccessException {
    public ResourceNotFoundException(String resourceId, String requestUrl, Throwable cause) {
        super(String.format("Requested resource [ID: %s] was not found", resourceId), 404, requestUrl, cause);
    }
}

在抽象类里怎么用？ #

在你的API封装抽象类中，处理响应时判断状态码：

public User getUser(String userId) {
    HttpResponse response = sendRequest("/users/" + userId);
    if (response.getStatusCode() == 404) {
        throw new ResourceNotFoundException(userId, response.getRequestUrl(), response.getCause());
    }
    // 其他状态码的判断逻辑...
    return parseResponse(response);
}

上层调用者的处理逻辑会非常清晰：

try {
    User user = apiClient.getUser("123");
} catch (ResourceNotFoundException e) {
    // 精准处理「资源不存在」的场景
    showUserError("用户不存在，请检查ID");
    logger.error("Failed to fetch user: {}, request URL: {}", "123", e.getRequestUrl());
} catch (WebServiceAccessException e) {
    // 统一处理其他API访问问题（比如网络错误、服务器报错）
    handleApiAccessError(e);
}

核心原则 #

异常的设计要面向调用者的需求：调用者不需要知道「HTTP返回了404」，只需要知道「我要的东西找不到了」；而开发者需要足够的细节（状态码、请求URL）来排查问题。自定义异常刚好能平衡这两点。

内容的提问来源于stack exchange，提问作者Spade