本文介绍如何通过自定义过滤器（filter）在 spring 中统一校验 post 请求头中传递的静态密钥，实现安全逻辑与业务逻辑解耦，避免在每个 controller 方法中重复校验。
本文介绍如何通过自定义过滤器（filter）在 spring 中统一校验 post 请求头中传递的静态密钥，实现安全逻辑与业务逻辑解耦，避免在每个 controller 方法中重复校验。
在构建 RESTful API 时，若需基于静态密钥（如 secret: CONFIDENTIAL_SECRET）进行轻量级身份验证，不推荐将校验逻辑直接写入 Controller 层——这会导致安全逻辑分散、难以维护，且违反关注点分离原则。Spring 提供了灵活的拦截机制，其中 OncePerRequestFilter 是最佳实践方案：它确保每个请求仅执行一次校验，并在进入业务处理器前完成鉴权。
以下是一个适用于 Spring Boot 3.x（基于 Jakarta EE 9+ 和 WebFlux/Servlet 混合环境）的生产就绪型过滤器示例：
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;
import java.io.PrintWriter;
@Order(1) // 确保优先于其他过滤器（如 CORS、JWT 解析等）
@Component
public class ApiSecretFilter extends OncePerRequestFilter {
private static final String SECRET_HEADER = "secret";
private static final String EXPECTED_SECRET = "CONFIDENTIAL_SECRET"; // 建议从配置中心或 @Value 注入
@Override
protected void doFilterInternal(
HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain) throws ServletException, IOException {
String requestURI = request.getRequestURI();
// 仅对指定路径启用校验（支持前缀匹配，如 /v1/something）
if (requestURI.startsWith("/v1/something")) {
String providedSecret = request.getHeader(SECRET_HEADER);
if (providedSecret == null || !EXPECTED_SECRET.equals(providedSecret)) {
response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
response.setContentType("application/json;charset=UTF-8");
try (PrintWriter writer = response.getWriter()) {
writer.write("{\"error\":\"Invalid or missing secret header\"}");
}
return; // 终止请求，不再向下传递
}
}
// 校验通过，放行至后续过滤器或控制器
filterChain.doFilter(request, response);
}
}
✅ 关键优势说明：
- 解耦清晰：Controller 专注业务逻辑，无需感知认证细节；
- 可复用性强：同一过滤器可覆盖多个端点，支持正则或路径匹配扩展；
-
响应标准化：统一返回
401 Unauthorized与结构化错误体，利于前端统一处理； -
性能高效：
OncePerRequestFilter避免重复执行，适配异步非阻塞场景（WebFlux 兼容）。
⚠️ 注意事项：
- 静态密钥仅适用于内部系统间简单调用，不可用于面向公网的用户认证（应使用 OAuth2、JWT 或 API 网关鉴权）；
- 密钥值建议通过
@Value("${api.secret:CONFIDENTIAL_SECRET}")从application.yml注入，禁止硬编码； - 若使用 WebFlux（Reactor），需确认容器为 Servlet 容器（如 Tomcat）或显式注册
WebFilter（对应ServerWebExchange）——上述示例适用于传统 Servlet Stack；WebFlux 用户可改用WebFilter+ServerWebExchange实现等效逻辑； - 生产环境务必启用 HTTPS，防止密钥在传输中被窃听。
综上，利用 Spring 的过滤器机制实现 Header 密钥校验，是兼顾简洁性、可维护性与安全性的标准做法。它让认证成为横切关注点，真正实现“一处配置，全局生效”。
