Spring Boot后端代理API时如何精确转发HTTP错误状态

本文探讨了在使用spring boot作为代理转发外部api请求时，前端接收到通用错误（如“0 unknown”）而非实际http错误状态（如409 conflict）的问题。通过修改后端控制器，确保精确地将外部api的http状态码转发给前端，从而解决客户端错误信息不准确的痛点。

在现代微服务架构中，后端服务经常需要充当代理，转发前端对外部API的请求。这种模式简化了前端的复杂度，并提供了额外的安全层。然而，当外部API返回错误时，如何确保这些错误状态码（如409 Conflict, 400 Bad Request等）能够准确无误地传递给前端，是一个常见的挑战。有时，前端可能会收到一个模糊的“0 Unknown”错误，而实际的网络请求中却显示了正确的HTTP状态码，这给调试带来了极大困扰。

问题场景分析

考虑一个典型的应用架构：一个Angular前端应用通过Java Spring Boot后端与多个外部API进行交互。Spring Boot后端作为这些API的代理层。当外部API返回一个非2xx的HTTP状态码（例如，409 Conflict）时，理想情况下，Spring Boot后端应该将这个状态码原样转发给Angular前端。然而，实际情况可能并非如此，前端有时会接收到一个通用的错误，例如“0 Unknown”，而通过浏览器开发者工具查看网络请求时，却能清晰地看到后端返回了正确的HTTP状态码。

这通常发生在后端使用WebClient进行外部调用，并返回ResponseEntity类型时。例如，以下代码片段展示了一个服务层方法，它使用WebClient调用外部API，并期望返回一个不带响应体的ResponseEntity：

// Service 层：负责与外部API通信
public ResponseEntity addForward(String username, String forward) {
    return localApiClient.put()
            .uri(baseUrl + username + "/targets/" + forward)
            .contentType(MediaType.APPLICATION_JSON)
            .exchangeToMono(ClientResponse::toBodilessEntity) // 将响应体丢弃，只保留状态和头部
            .block(REQUEST_TIMEOUT); // 阻塞等待结果，返回ResponseEntity
}

// Controller 层：暴露给前端的API接口
@PutMapping("/{username}/targets/{forward}")
public ResponseEntity addForward(
        @PathVariable("username") String username, @PathVariable("forward") String forward) {
    return api.addForward(username, forward); // 直接返回服务层的结果
}

尽管exchangeToMono(ClientResponse::toBodilessEntity)旨在将外部API的HTTP状态码封装到ResponseEntity中，但当这个ResponseEntity直接从控制器返回时，某些情况下，前端可能无法正确解析其状态，或者中间件、框架的默认错误处理机制可能介入，导致原始状态码的丢失。这种不一致性使得前端难以根据实际的错误类型进行逻辑处理和用户反馈。

解决方案：精确转发HTTP状态码

解决此问题的关键在于，在Spring Boot控制器层显式地构建一个新的ResponseEntity，并仅包含从服务层获取到的HTTP状态码。这确保了响应的简洁性和明确性，避免了任何潜在的默认行为或隐式内容可能对前端解析造成干扰。

修改后的控制器方法如下所示：

import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MyController {

    private final MyApiService api; // 假设这是注入的服务层接口

    public MyController(MyApiService api) {
        this.api = api;
    }

    @PutMapping("/{username}/targets/{forward}")
    public ResponseEntity addForward(
            @PathVariable("username") String username, @PathVariable("forward") String forward) {
        // 调用服务层方法获取包含外部API响应状态的ResponseEntity
        ResponseEntity serviceResponse = api.addForward(username, forward);

        // 创建一个新的ResponseEntity，仅包含从服务层响应中提取的HTTP状态码
        // 这样做确保了响应体是空的，并且只传递了精确的状态码
        return new ResponseEntity<>(serviceResponse.getStatusCode());
    }

    // 假设MyApiService接口和其实现如下
    // public interface MyApiService {
    //     ResponseEntity addForward(String username, String forward);
    // }
    //
    // @Service
    // public class MyApiServiceImpl implements MyApiService {
    //     private final WebClient localApiClient;
    //     private final String baseUrl = "http://external-api.com/"; // 外部API基地址
    //     private final Duration REQUEST_TIMEOUT = Duration.ofSeconds(5);
    //
    //     public MyApiServiceImpl(WebClient.Builder webClientBuilder) {
    //         this.localApiClient = webClientBuilder.build();
    //     }
    //
    //     @Override
    //     public ResponseEntity addForward(String username, String forward) {
    //         return localApiClient.put()
    //                 .uri(baseUrl + username + "/targets/" + forward)
    //                 .contentType(MediaType.APPLICATION_JSON)
    //                 .exchangeToMono(ClientResponse::toBodilessEntity)
    //                 .block(REQUEST_TIMEOUT);
    //     }
    // }
}

代码解析：

FreeTTS

FreeTTS是一个免费开源的在线文本到语音生成解决方案，可以将文本转换成MP3，

下载

1. ResponseEntity serviceResponse = api.addForward(username, forward);：这行代码调用服务层方法，该方法通过WebClient与外部API通信，并返回一个ResponseEntity对象。即使外部API返回错误（例如409），这个ResponseEntity对象内部也应该包含正确的HTTP状态码。
2. serviceResponse.getStatusCode()：从服务层返回的ResponseEntity中提取出HttpStatus枚举值。
3. new ResponseEntity(serviceResponse.getStatusCode())：创建一个全新的ResponseEntity实例。这个新的ResponseEntity将只设置HTTP状态码，并且不包含任何响应体。这种显式构造确保了Spring框架在序列化响应时，只会发送HTTP状态码和必要的头部信息，而不会引入任何可能导致前端解析错误的默认或空内容。

通过这种方式，即使外部API返回了409 Conflict，前端也能准确地接收到409状态码，而不是模糊的“0 Unknown”错误。这种方法强制后端仅传递最核心的HTTP状态信息，从而提高了API响应的透明度和可预测性。

最佳实践与注意事项

虽然上述解决方案能够有效解决前端接收通用错误的问题，但在实际应用中，还有一些重要的考虑事项和最佳实践：

1. 错误响应体处理： 上述方案仅转发了HTTP状态码，丢弃了外部API可能返回的错误详情（响应体）。如果前端需要显示具体的错误信息，则不能使用ClientResponse::toBodilessEntity。

   • 替代方案： 可以使用exchangeToMono(ClientResponse::toEntity)来获取包含响应体的ResponseEntity或ResponseEntity。然后，在控制器中可以根据需要选择性地转发整个ResponseEntity，或者从其体中提取错误信息并构建自定义的错误响应。

   • 示例（转发错误体）：

     // Service 层 (假设外部API返回JSON错误体)
     public ResponseEntity addForwardWithBody(String username, String forward) {
         return localApiClient.put()
                 .uri(baseUrl + username + "/targets/" + forward)
                 .contentType(MediaType.APPLICATION_JSON)
                 .exchangeToMono(clientResponse -> {
                     if (clientResponse.statusCode().isError()) {
                         // 如果是错误响应，则捕获整个响应体
                         return clientResponse.toEntity(String.class); 
                     } else {
                         // 成功时仍可选择丢弃体，或返回完整ResponseEntity
                         return clientResponse.toBodilessEntity().map(r -> new ResponseEntity<>(r.getStatusCode()));
                     }
                 })
                 .block(REQUEST_TIMEOUT);
     }
     
     // Controller 层
     @PutMapping("/{username}/targets/{forward}")
     public ResponseEntity addForwardWith