Java CompletableFuture handle 如何把异常转成统一结果

异步调用最容易让接口变得不稳定：成功时返回数据，失败时却变成异常，调用方不得不同时写两套分支。CompletableFuture.handle 的价值就在这里：它会在前置阶段正常完成或异常完成时都执行回调，回调同时拿到结果和 Throwable，然后把两条路径转换成同一种结果类型。

官方资料：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/concurrent/CompletableFuture.html

先把成功和失败收敛成同一种结果

假设订单页需要调用库存服务。库存查到数量时返回数据，超时或服务不可用时不希望让控制器到处捕获异常，可以先定义一个轻量结果对象：

record AsyncResult(T value, String code, Throwable error) {
    // 成功和失败共用一个返回类型，调用方不必再拆两条异常分支。
    static  AsyncResult ok(T value) {
        return new AsyncResult(value, "OK", null);
    }

    static  AsyncResult fail(String code, Throwable error) {
        // 保留原始异常，便于日志记录和后续判断是否需要重试。
        return new AsyncResult(null, code, error);
    }
}

CompletableFuture> stockResult = loadStock("SKU-100")
    .handle((value, error) -> {
        // handle 的两个参数不会同时有业务值：成功看 value，失败看 error。
        if (error == null) {
            return AsyncResult.ok(value);
        }
        return AsyncResult.fail("STOCK_UNAVAILABLE", rootCause(error));
    });

这里的关键不是把异常改成字符串，而是把“异步阶段的完成状态”转换成明确的领域结果。调用方只需判断 code 和 error，不会因为链条中途改用异常就改变接口形状。

handle 回调里要保留真正的异常根因

join() 或异步阶段传播异常时，外层经常出现 CompletionException。如果统一结果只保存外层包装，日志会显示“异步完成异常”，却看不出真正的超时、连接失败或业务异常。因此转换时可以沿着 cause 链找到根因：

static Throwable rootCause(Throwable error) {
    // 只拆常见的异步包装，避免无条件吞掉业务异常的类型。
    Throwable current = error;
    while ((current instanceof CompletionException
            || current instanceof ExecutionException)
            && current.getCause() != null) {
        current = current.getCause();
    }
    return current;
}

CompletableFuture> result = loadStock("SKU-100")
    .handle((value, error) -> {
        if (error == null) {
            return AsyncResult.ok(value);
        }
        Throwable cause = rootCause(error);
        // 可预期错误映射为业务码，未知错误仍携带根因交给上层记录。
        String code = cause instanceof TimeoutException
                ? "STOCK_TIMEOUT" : "STOCK_FAILED";
        return AsyncResult.fail(code, cause);
    });

不要在 handle 中无条件返回“成功但没有库存”。那会把服务故障和真实的零库存混为一谈，重试、告警和用户提示都会失去依据。只有业务上确认可以降级时，才把失败转换成带有明确来源的降级结果。

handle、exceptionally、whenComplete 怎么选

三个方法都能看到异常，但职责并不相同。选择前先问一句：这一步是在改变结果、补一个默认值，还是只记录信息？

例如只想记录耗时，不要用 handle 把异常改成成功：

CompletableFuture observed = loadOrder(id)
    .whenComplete((order, error) -> {
        // 观察阶段只记指标，不改变下游看到的成功或失败。
        metrics.record("order.load", error == null ? "ok" : "error");
    });

CompletableFuture fallback = loadOrder(id)
    .exceptionally(error -> {
        // 只有确定允许降级时才提供默认对象；否则继续抛给调用方。
        return cachedOrder(id, error);
    });

异步转换的线程边界和失败检查

非 Async 版本的回调可能由完成当前阶段的线程执行，所以 handle 中不宜放网络请求、文件读写或长时间锁等待。转换逻辑较重时使用专用执行器：

Executor resultExecutor = Executors.newFixedThreadPool(4);

CompletableFuture> result = loadStock("SKU-100")
    .handleAsync((value, error) -> {
        // 较重的错误映射放到独立执行器，避免占用业务完成线程。
        return error == null
                ? AsyncResult.ok(value)
                : AsyncResult.fail("STOCK_FAILED", rootCause(error));
    }, resultExecutor);

result.thenAccept(r -> {
    // 统一结果仍要检查失败状态，不能只判断 future 是否正常完成。
    if (!"OK".equals(r.code())) {
        reportFailure(r.error());
    }
});

还要留意一个边界：如果 handle 自己抛出异常，返回的阶段仍会异常完成；如果回调内部又发起异步补偿，应使用 exceptionallyCompose 等组合方法，而不是把另一个 CompletableFuture 直接塞进结果对象。

常见问题

handle 的 value 和 error 会同时有值吗？

正常完成时通常是 value 有值、error 为 null；异常完成时 value 为 null、error 有值。业务结果本身允许 null 时，要用完成状态和错误字段共同判断。

用 exceptionally 能不能替代 handle？

只能在结果类型不变、且只需要处理异常时替代。需要把成功和失败都映射为统一对象时，应该使用 handle。

whenComplete 会把异常吃掉吗？

它的设计是保留原阶段的结果或异常；除非观察回调自己抛出新的异常，否则不能把失败自动变成成功。

实际项目可以按这张速记来选：改变结果用 handle，异常兜底用 exceptionally，记录和清理用 whenComplete。无论选择哪一个，都要让失败状态可观察、让异常根因可追踪。