如何为500级服务器错误响应添加自定义关联ID？

问题原因分析 #

你的@ServerResponseFilter对4xx响应有效但5xx无效，主要有两个核心原因：

1. 500级错误的响应实体通常不是String类型（比如容器默认生成的错误实体是HTML或结构化对象），导致过滤器里的instanceof String条件无法触发修改逻辑；
2. 未被捕获的RuntimeException触发的500错误，部分JAX-RS实现的默认异常处理流程可能跳过了你的过滤器逻辑。

解决方案 #

方案1：优化现有响应过滤器（优先尝试） #

修改过滤器，移除实体类型限制，改用响应头传递Correlation-ID（行业通用做法，更灵活且不破坏原有错误结构），同时确保覆盖所有4xx/5xx响应：

@ServerResponseFilter
public void modifyResponse(ContainerResponseContext responseContext) {
    Log.debugf("Calling modifyResponse with context %s", responseContext);
    String correlationId = MDC.get("correlation_id");
    
    if (responseContext.getStatus() >= 400 && correlationId != null) {
        // 添加规范的Correlation-ID响应头
        responseContext.getHeaders().add("X-Correlation-ID", correlationId);
        
        // 如需修改实体内容（可选）
        Object entity = responseContext.getEntity();
        String errorMsgPrefix = "Error with Correlation-ID " + correlationId + ": ";
        String finalErrorMessage;
        
        if (entity != null) {
            finalErrorMessage = errorMsgPrefix + entity.toString();
        } else {
            finalErrorMessage = errorMsgPrefix + responseContext.getStatusInfo().getReasonPhrase();
        }
        
        responseContext.setEntity(finalErrorMessage);
        responseContext.getHeaders().putSingle(HttpHeaders.CONTENT_TYPE, MediaType.TEXT_PLAIN);
    }
}

方案2：使用ExceptionMapper统一捕获异常 #

如果过滤器仍无法覆盖500级错误，创建全局异常映射器，直接处理所有未捕获的异常并生成带Correlation-ID的响应：

@Provider
public class GlobalExceptionMapper implements ExceptionMapper<Throwable> {

    @Override
    public Response toResponse(Throwable exception) {
        String correlationId = MDC.get("correlation_id");
        int statusCode = Response.Status.INTERNAL_SERVER_ERROR.getStatusCode();
        
        // 兼容WebApplicationException自定义状态码
        if (exception instanceof WebApplicationException) {
            statusCode = ((WebApplicationException) exception).getResponse().getStatus();
        }
        
        String errorMessage = String.format(
            "Error with Correlation-ID %s: %s",
            correlationId != null ? correlationId : "unknown",
            exception.getMessage() != null ? exception.getMessage() : "Internal Server Error"
        );
        
        return Response.status(statusCode)
                .header("X-Correlation-ID", correlationId)
                .entity(errorMessage)
                .type(MediaType.TEXT_PLAIN)
                .build();
    }
}

这个映射器会捕获所有未被处理的异常（包括手动抛出的WebApplicationException(500)），确保每一个500级响应都包含Correlation-ID。

方案3：结合使用过滤器和异常映射器 #

如果需要既统一处理异常，又复用过滤器的通用逻辑，可以让异常映射器生成基础响应，再通过过滤器添加Correlation-ID头——JAX-RS中异常映射器生成的响应会经过响应过滤器处理。

关键注意事项 #

• 优先用响应头传递Correlation-ID：相比修改实体内容，响应头不会干扰错误信息的结构化解析，更适合分布式日志聚合；
• 确保MDC中的correlation_id在整个请求生命周期中都能被访问到：比如在请求入口处（如Servlet过滤器）设置关联ID，避免在异常处理时MDC值丢失。

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