Spring Boot跨域问题终极解决方案:3种方案彻底告别CORS错误

liuian 2025-09-18 03:45 17 浏览

引言

"接口调不通？前端同事又双叒叕在吼跨域了！"
"明明Postman能通，浏览器却报OPTIONS 403？"
"生产环境跨域配置突然失效，凌晨3点被夺命连环Call？"

每个后端开发者都经历过被CORS（跨域资源共享）支配的恐惧。本文将手把手教你3种Spring Boot跨域解决方案，从注解到源码配置，从单接口到全局管控，附带防踩坑指南和线上应急预案，从此告别跨域噩梦！

一、跨域问题本质：30秒搞懂CORS核心机制

浏览器安全策略：同源策略（Same-Origin Policy）限制不同源的前后端交互
CORS破局关键：服务端通过HTTP响应头声明允许的跨域规则
核心响应头：

http

Access-Control-Allow-Origin: *                // 允许的域名（*为通配符）  
Access-Control-Allow-Methods: GET,POST        // 允许的HTTP方法  
Access-Control-Allow-Headers: Content-Type    // 允许的请求头  
Access-Control-Max-Age: 3600                  // 预检请求缓存时间（秒）

二、Spring Boot解决跨域的3种实战方案

方案1：@CrossOrigin注解（精准打击）

适用场景：仅需开放特定接口的跨域访问

java

@RestController
public class UserController {
    
    // 单个方法配置
    @CrossOrigin(origins = "https://your-frontend.com", 
                 methods = {RequestMethod.GET, RequestMethod.POST},
                 allowedHeaders = "Content-Type")
    @GetMapping("/api/user")
    public User getUser() {
        return new User("码农", 28);
    }

    // 类级别配置（作用于所有接口）
    @CrossOrigin(origins = "*")
    @RestController
    public class OpenApiController {
        // ...
    }
}

坑点预警：

若同时存在全局配置，注解配置会被覆盖！
不支持通配符子域名（如 *.domain.com）

方案2：全局配置（一劳永逸）

推荐指数：★★★★★
通过实现WebMvcConfigurer统一管理：

java

@Configuration
public class CorsConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")              // 所有接口
                .allowedOrigins("https://prod.com", "http://localhost:8080") 
                .allowedMethods("*")             // 允许所有方法
                .allowedHeaders("*")             // 允许所有头
                .allowCredentials(true)         // 允许携带Cookie
                .maxAge(1800);                   // 预检请求缓存时间
    }
}

避坑指南：

allowCredentials(true)时，allowedOrigins不能为*，必须明确指定域名！
若使用Spring Security，需额外配置cors()+csrf().disable()（见方案3）

方案3：过滤器（终极自由）

适用场景：需要动态控制跨域规则（如多租户系统）

java

@Bean
public FilterRegistrationBean<CorsFilter> corsFilter() {
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    CorsConfiguration config = new CorsConfiguration();
    
    config.setAllowCredentials(true);
    config.addAllowedOrigin("https://*.company.com"); // 支持通配符子域名
    config.addAllowedMethod("*");
    config.addAllowedHeader("*");
    config.setMaxAge(3600L);

    source.registerCorsConfiguration("/**", config);
    return new FilterRegistrationBean<>(new CorsFilter(source));
}

优势：

优先级最高，可覆盖其他配置
支持复杂逻辑（如从数据库读取允许的域名）

三、深度避坑：那些官方文档不会告诉你的秘密

1. 预检请求（Preflight）的阴谋

现象：前端POST请求变成OPTIONS请求
本质：浏览器对非简单请求自动发起预检请求
解决方案：

确保服务器正确处理OPTIONS方法（Spring Boot默认支持）
设置合理的maxAge减少预检次数

2. Spring Security的偷袭

症状：明明配置了跨域，却依然返回403
修复方案：

java

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.cors()                          // 启用CORS支持
            .and()
            .csrf().disable()               // 禁用CSRF（根据业务需要）
            .authorizeRequests()
            .anyRequest().permitAll();
    }

    // 关键！提供CorsConfigurationSource
    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration configuration = new CorsConfiguration();
        configuration.applyPermitDefaultValues();
        configuration.addAllowedMethod(HttpMethod.PUT); // 按需添加
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", configuration);
        return source;
    }
}

3. 生产环境突发跨域故障应急方案

临时允许所有域名（慎用！）：
java

allowedOrigins("*")

Nginx层统一加响应头：
nginx

location / {
    add_header 'Access-Control-Allow-Origin' '*';
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
    add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,Content-Type';
}

接口代理：通过后端调用第三方接口，规避浏览器限制

四、最佳实践总结

方案	适用场景	优点	缺点
@CrossOrigin	快速验证、少量接口	简单易用	配置分散，维护成本高
全局配置	标准项目	统一管理，优先级适中	无法动态调整
过滤器	需要动态规则/微服务网关	灵活性强，优先级最高	实现稍复杂