Spring Boot中如何为指定端点校验IFTTT-Service-Key请求头并排除Actuator端点

你提到Spring Security附带太多额外功能，但其实它的灵活性远超你想象——我们可以完全禁用那些不需要的默认模块（比如表单登录、HTTP Basic认证），只保留针对IFTTT-Service-Key的校验逻辑，同时借助它成熟的端点匹配规则，轻松实现「指定端点校验+排除Actuator」的需求。这比HandlerInterceptor更简洁、更符合Spring生态的最佳实践。

下面是具体的实现步骤：

1. 引入Spring Security依赖（如果未添加） #

如果你的项目还没引入Spring Security，先在pom.xml（Maven）中添加依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

2. 编写自定义密钥校验过滤器 #

这个过滤器只负责校验请求头中的IFTTT-Service-Key，逻辑和你之前的HandlerInterceptor类似，但更贴合Spring Security的生态：

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.security.authentication.BadCredentialsException;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.util.Collections;

public class IftttServiceKeyFilter extends OncePerRequestFilter {

    private final String validServiceKey;

    public IftttServiceKeyFilter(String validServiceKey) {
        this.validServiceKey = validServiceKey;
    }

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        String serviceKeyHeader = request.getHeader("IFTTT-Service-Key");
        
        // 校验密钥有效性
        if (!validServiceKey.equals(serviceKeyHeader)) {
            throw new BadCredentialsException("Incorrect value for IFTTT-Service-Key");
        }

        // 标记请求为已认证（可选，方便后续业务逻辑获取认证信息）
        Authentication authentication = new IftttServiceKeyAuthentication(serviceKeyHeader);
        SecurityContextHolder.getContext().setAuthentication(authentication);

        filterChain.doFilter(request, response);
    }

    // 自定义认证对象，仅满足接口要求即可
    private static class IftttServiceKeyAuthentication implements Authentication {
        private final String serviceKey;

        public IftttServiceKeyAuthentication(String serviceKey) {
            this.serviceKey = serviceKey;
        }

        @Override
        public boolean isAuthenticated() { return true; }
        @Override public void setAuthenticated(boolean isAuthenticated) throws IllegalArgumentException {}
        @Override public String getName() { return "IFTTT-Service"; }
        @Override public Collection<? extends GrantedAuthority> getAuthorities() { return Collections.emptyList(); }
        @Override public Object getCredentials() { return serviceKey; }
        @Override public Object getDetails() { return null; }
        @Override public Object getPrincipal() { return "IFTTT-Service"; }
    }
}

3. 配置Spring Security，精确控制校验范围 #

通过SecurityFilterChain配置，我们可以完全禁用默认安全模块，同时指定哪些端点需要校验、哪些需要排除：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    private final String validServiceKey;

    // 注入配置文件中的服务密钥
    public SecurityConfig(@Value("${ifttt.service-key}") String validServiceKey) {
        this.validServiceKey = validServiceKey;
    }

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            // 禁用所有不需要的默认模块
            .csrf(csrf -> csrf.disable())
            .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .formLogin(form -> form.disable())
            .httpBasic(basic -> basic.disable())
            
            // 配置端点权限规则
            .authorizeHttpRequests(auth -> auth
                // 排除Actuator所有端点
                .requestMatchers("/actuator/**").permitAll()
                // 可添加其他无需校验的端点，比如：.requestMatchers("/public/**").permitAll()
                // 剩余所有端点必须经过认证
                .anyRequest().authenticated()
            )
            
            // 添加自定义密钥校验过滤器，放在默认的用户名密码过滤器之前
            .addFilterBefore(new IftttServiceKeyFilter(validServiceKey), UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }
}

4. 统一异常处理（可选） #

为了返回和你现有代码一致的错误响应格式，添加全局异常处理器捕获校验失败的异常：

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.authentication.BadCredentialsException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import java.util.Collections;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BadCredentialsException.class)
    public ResponseEntity<ErrorResponse> handleBadCredentials(BadCredentialsException ex) {
        Error error = new Error(ex.getMessage());
        ErrorResponse errorResponse = new ErrorResponse(Collections.singletonList(error));
        return new ResponseEntity<>(errorResponse, HttpStatus.UNAUTHORIZED);
    }
}

为什么这个方案比HandlerInterceptor更好？ #

• 更简洁的端点匹配：Spring Security的requestMatchers支持Ant风格路径（比如/actuator/**）和MVC路径匹配，不需要自己编写复杂的URL匹配逻辑，避免出错。
• 更符合Spring生态：作为Spring官方的安全框架，后续如果需要扩展其他安全功能（比如角色权限、OAuth2），可以无缝集成。
• 无冗余功能：完全禁用了默认的登录模块，只保留你需要的密钥校验逻辑，没有多余负担。

如果坚持想用HandlerInterceptor改进现有代码，也可以通过PathMatcher实现端点匹配：

import org.springframework.web.util.PathMatcher;

@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
    PathMatcher pathMatcher = new AntPathMatcher();
    String requestUri = request.getRequestURI();
    
    // 跳过Actuator和其他无需校验的端点
    if (pathMatcher.match("/actuator/**", requestUri) || pathMatcher.match("/public/**", requestUri)) {
        return true;
    }
    
    // 执行密钥校验逻辑
    String serviceKeyHeader = request.getHeader("IFTTT-Service-Key");
    if (!myIftttServiceKey.equals(serviceKeyHeader)) {
        var error = new Error("Incorrect value for IFTTT-Service-Key");
        var errorResponse = new ErrorResponse(Collections.singletonList(error));
        throw new UnauthorizedException(errorResponse);
    }
    return true;
}

但相比之下，Spring Security方案的可维护性和扩展性更强，是更优的选择。

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