spring-addons CORS配置详解一个属性解决前后端跨域与预检请求难题【免费下载链接】spring-addonsAdditional Spring Boot auto-configuration for OAuth2 / OpenID REST项目地址: https://gitcode.com/gh_mirrors/sp/spring-addons在前后端分离的架构中spring-addons CORS配置往往是开发者最头疼的一环明明接口写好了浏览器却报 No Access-Control-Allow-Origin header预检请求OPTIONS又时不时被安全过滤器拦截。本文要介绍的是spring-addonsSpring Boot 的 OAuth2 / OpenID 自动配置增强库提供的一站式跨域解决方案——只需在配置文件中写上一段com.c4-soft.springaddons.oidc.cors属性就能同时搞定 CORS 过滤器注册、跨域策略定制与 OPTIONS 预检请求自动放行三大难题无需手写任何CorsFilter或WebMvcConfigurer代码。什么是 CORS 跨域问题先搞懂这 3 个概念面向新手我们先花 30 秒理清 CORS 的基础知识这样后面看配置才不会懵同源与跨域当浏览器访问http://localhost:4200的前端页面去请求http://localhost:8080的 API 时协议、域名、端口只要有一个不同就构成了跨域请求。简单请求与预检请求携带Authorization头、或使用PUT/DELETE等方法的请求浏览器会先发一个OPTIONS 预检请求探测服务器是否允许得到正确响应后才真正发出业务请求。CORS 响应头服务器通过Access-Control-Allow-*系列响应头告诉浏览器我允许哪些来源、方法、请求头。很多跨域报错本质是服务器没有正确返回这些响应头或者预检请求被安全过滤器提前拦截返回 401/403。而 spring-addons 恰好同时解决了这两个问题。一个属性搞定 CORS核心配置前缀与作用原理spring-addons 把整套 CORS 配置收敛到了一个统一的前缀下com.c4-soft.springaddons.oidc.cors只要在application.yml中配置了这个前缀下的任意属性库内部的自动配置就会触发对应条件类 HasCorsPropertiesCondition.java自动完成两件事自动注册 CORS 过滤器Servlet 环境注册CorsFilterReactiveWebFlux环境注册CorsWebFilter源码见 ServletConfigurationSupport.java 与 ReactiveConfigurationSupport.java。如果你已经自定义了过滤器自动配置会优雅地让位ConditionalOnMissingBean。自动放行 OPTIONS 预检请求默认情况下只要允许的方法包含*或OPTIONS预检请求就会自动加入permitAll不再被认证逻辑拦截。零代码跨域配置最简配置写法最省事的写法一行配置即可放开所有来源的跨域适合开发环境com: c4-soft: springaddons: oidc: cors: - path: /** allowed-origin-patterns: * allowed-methods: * allowed-headers: *注意cors是一个列表意味着你可以按路径配置多套策略比如/api/**一套、/public/**另一套。8 个配置项逐个拆解打造生产级跨域策略配置项的完整定义在 CorsProperties.java下面逐一说明配置项默认值作用说明path/**该条策略匹配的路径支持 Ant 风格通配符allow-credentialsnull是否允许携带 Cookie 等凭证前后端分离通常设为trueallowed-origin-patterns*允许的来源列表生产环境建议换成具体域名allowed-methods*允许的 HTTP 方法GET、POST、PUT、DELETE 等allowed-headers*允许的请求头如Authorization、Content-Typeexposed-headers*允许前端 JS 读取的响应头max-agenull预检结果的缓存时长秒减少重复预检请求disable-anonymous-optionsfalse设为true时不再自动放行 OPTIONS 请求生产环境推荐配置长尾关键词安全的前后端分离跨域配置上线前请收敛权限把*换成真实域名并开启凭证支持com: c4-soft: springaddons: oidc: cors: - path: /api/** allowed-origin-patterns: - https://app.example.com - https://admin.example.com allowed-methods: [GET, POST, PUT, DELETE, OPTIONS] allowed-headers: [Authorization, Content-Type] exposed-headers: [X-Total-Count] allow-credentials: true max-age: 3600这里有两个容易被忽视的安全要点allow-credentials: true时不能与allowed-origin-patterns: *混用浏览器规范禁止所以生产配置必须写明具体来源。spring-addons 使用allowedOriginPatterns而非allowedOrigins天然规避了与*搭配时的校验冲突这也是它的贴心之处。Cookie 与 CSRF 的联动如果前端要带 Cookie比如基于 Session 的客户端模式记得同步确认 SpringAddonsOidcProperties.java 中 client / resourceserver 的 CSRF 配置避免跨域通了、CSRF 又拦了的连环坑。预检请求自动放行的底层机制这是 spring-addons 最值得称道的细节。常规写法中即使配置了 CORSOPTIONS 预检请求仍可能被authenticated()规则拦截导致前端莫名报 403。spring-addons 在 ServletConfigurationSupport.java 的configureAccess方法中做了这样一件事凡是配置了 CORS 且允许OPTIONS或*的路径自动把这些路径的 OPTIONS 请求加入permitAll。这意味着你只需要关心跨域策略本身预检请求的放行逻辑完全交给框架少踩一个经典大坑。如果出于安全审计需要想关闭这个自动行为将对应条目的disable-anonymous-options设为true即可。常见问题排查清单如果配置后仍然报跨域错误按这个顺序自查配置前缀拼写com.c4-soft.springaddons.oidc.cors是连字符写法别写成驼峰。路径是否匹配前端请求路径是否命中了你配置的path未命中的请求不会应用该策略。是否自定义了过滤器如果自己注册了CorsFilter/CorsWebFilterspring-addons 的自动配置会自动失效此时需要自行处理。方法列表是否包含 OPTIONS如果allowed-methods里既没有*也没有OPTIONS预检请求不会自动放行。结合网关/BFF 场景如果是网关代理模式还需确认上游对 OPTIONS 的处理避免链路中某一环丢弃预检请求。总结对于基于spring-addons构建的 OAuth2 资源服务器或客户端应用CORS 配置从未如此简单一段com.c4-soft.springaddons.oidc.cors属性同时完成跨域策略定制、过滤器自动注册与预检请求自动放行Servlet 与 WebFlux 两种技术栈统一支持。把配置从开发环境的*平滑收敛到生产环境的精确域名前后端跨域这个困扰无数人的难题就这样被一个属性优雅化解。下次再遇到跨域报错不妨先检查一下你的 spring-addons CORS 配置是否写对了。【免费下载链接】spring-addonsAdditional Spring Boot auto-configuration for OAuth2 / OpenID REST项目地址: https://gitcode.com/gh_mirrors/sp/spring-addons创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考