Spring Boot中@WebServlet如何正确抛出HTTP错误且不泄露类路径

你在使用@WebServlet标注的原生Servlet中尝试抛出错误时，遇到了两个核心问题：

1. 抛出ResponseStatusException时，容器返回500状态码，且响应message字段泄露了异常类路径
2. 抛出ServletException时，同样返回500错误，message包含异常类名，无法得到@RestController中那样的标准错误JSON格式

问题根源 #

@WebServlet是由Servlet容器（如Tomcat）直接托管的请求处理组件，完全不走Spring MVC的DispatcherServlet处理链。因此Spring内置的异常解析器（比如处理ResponseStatusException的ResponseStatusExceptionResolver）不会介入，抛出的异常会被容器默认错误处理逻辑捕获，返回通用的500错误，同时把异常的toString()结果作为message返回，导致类路径泄露。

下面提供两种可行的解决方案：

方案一：手动构造标准错误JSON响应 #

直接在Servlet中手动设置响应状态码，并生成符合Spring风格的JSON内容，无需依赖Spring的异常处理机制，实现简单直接：

import jakarta.servlet.annotation.WebServlet;
import jakarta.servlet.http.HttpServlet;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

@WebServlet("/path_to_servlet")
public class CustomServlet extends HttpServlet {
    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        // 设置响应状态码为400（Bad Request）
        resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
        // 指定响应内容类型为JSON
        resp.setContentType("application/json;charset=UTF-8");
        
        // 构造符合Spring错误格式的JSON字符串
        String timestamp = LocalDateTime.now().format(DateTimeFormatter.ISO_DATE_TIME);
        String errorJson = String.join("",
                "{",
                "\"timestamp\": \"" + timestamp + "\",",
                "\"status\": 400,",
                "\"error\": \"Bad Request\",",
                "\"message\": \"bad request.\",",
                "\"path\": \"" + req.getRequestURI() + "\"",
                "}"
        );
        
        // 将JSON写入响应流
        resp.getWriter().write(errorJson);
    }
}

方案二：复用Spring的ErrorAttributes生成标准响应 #

如果想复用Spring内置的错误格式生成逻辑，可以借助ErrorAttributes组件（Spring用来生成标准错误响应的核心类），需要让Servlet成为Spring管理的Bean：

import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.boot.web.servlet.error.ErrorAttributes;
import org.springframework.boot.web.servlet.error.ErrorAttributeOptions;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.ServletWebRequest;
import org.springframework.web.context.request.WebRequest;

import jakarta.servlet.annotation.WebServlet;
import jakarta.servlet.http.HttpServlet;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Map;

@Component
@WebServlet("/path_to_servlet")
public class CustomErrorServlet extends HttpServlet {

    private final ErrorAttributes errorAttributes;
    private final ObjectMapper objectMapper;

    // 构造注入Spring提供的组件
    public CustomErrorServlet(ErrorAttributes errorAttributes, ObjectMapper objectMapper) {
        this.errorAttributes = errorAttributes;
        this.objectMapper = objectMapper;
    }

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        // 构造Spring Web请求对象
        WebRequest webRequest = new ServletWebRequest(req, resp);
        
        // 获取Spring默认的错误属性模板
        Map<String, Object> errorMap = errorAttributes.getErrorAttributes(
                webRequest,
                ErrorAttributeOptions.of(ErrorAttributeOptions.Include.MESSAGE)
        );
        
        // 覆盖为我们需要的错误信息
        errorMap.put("timestamp", LocalDateTime.now().format(DateTimeFormatter.ISO_DATE_TIME));
        errorMap.put("status", HttpServletResponse.SC_BAD_REQUEST);
        errorMap.put("error", "Bad Request");
        errorMap.put("message", "bad request.");
        errorMap.put("path", req.getRequestURI());
        
        // 设置响应状态和内容类型
        resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
        resp.setContentType("application/json;charset=UTF-8");
        
        // 将Map转换为JSON并写入响应
        objectMapper.writeValue(resp.getWriter(), errorMap);
    }
}

额外说明 #

• 不要在原生Servlet中直接抛出Spring的ResponseStatusException，它不属于Servlet容器的异常处理范畴，只会被当作普通异常处理，返回500错误。
• 如果需要全局统一错误格式，也可以配置容器级别的错误页面，但这种方式灵活性较低，不如上述两种方法精准控制单个Servlet的响应。

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