Spring MVC：为废弃端点动态添加响应头的实现方案

核心思路 #

不用手动解析请求路径和反射方法，直接借助Spring MVC提供的HandlerInterceptor，精准匹配请求对应的Controller处理方法，再通过反射检查@Deprecated注解，动态添加响应头。

具体实现步骤 #

1. 编写废弃端点拦截器

创建HandlerInterceptor实现类，在请求处理阶段获取当前请求对应的Controller方法，检查是否标记了@Deprecated注解：

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.HandlerInterceptor;

@Component
public class DeprecatedEndpointInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // 仅处理Controller中的方法请求
        if (handler instanceof HandlerMethod handlerMethod) {
            // 优先检查方法上的@Deprecated注解
            Deprecated methodDeprecation = handlerMethod.getMethodAnnotation(Deprecated.class);
            if (methodDeprecation != null) {
                // 根据forRemoval属性设置响应头内容
                String headerValue = methodDeprecation.forRemoval() 
                    ? "true; 该端点即将被移除" 
                    : "true";
                response.setHeader("X-Deprecated", headerValue);
            } else {
                // 若方法无注解，检查Controller类上的@Deprecated（可选逻辑）
                Deprecated classDeprecation = handlerMethod.getBeanType().getAnnotation(Deprecated.class);
                if (classDeprecation != null) {
                    response.setHeader("X-Deprecated", "true; 该控制器下所有端点已废弃");
                }
            }
        }
        return true; // 放行请求
    }
}

2. 注册拦截器到Spring MVC

通过WebMvcConfigurer配置类，将拦截器加入Spring MVC的拦截链：

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcInterceptorConfig implements WebMvcConfigurer {

    private final DeprecatedEndpointInterceptor deprecatedEndpointInterceptor;

    // 构造注入拦截器
    public WebMvcInterceptorConfig(DeprecatedEndpointInterceptor deprecatedEndpointInterceptor) {
        this.deprecatedEndpointInterceptor = deprecatedEndpointInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(deprecatedEndpointInterceptor)
                .addPathPatterns("/api/**"); // 可根据业务调整拦截路径，用/**拦截所有请求
    }
}

关键优势 #

• 通用性强：自动适配所有标记了@Deprecated的Controller方法（或类），无需逐个端点配置
• 精准匹配：依赖Spring MVC自身的请求映射机制，避免手动解析路径导致的错误
• 兼容SpringDoc：和SpringDoc的废弃标记逻辑完全一致，不会产生冲突

可选扩展 #

• 可以添加额外响应头，比如X-Deprecated-Reason，提示替代端点路径：response.setHeader("X-Deprecated-Reason", "请使用 /api/v2/hello 替代")
• 在拦截器中添加日志输出，统计废弃端点的请求情况，方便后续优化

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