当前位置： 首页 > news >正文

Sa-Token解决跨域问题的三种实践方案

news 2026/7/18 6:43:09

1. 为什么需要处理跨域问题？

跨域问题源于浏览器的同源策略（Same-Origin Policy），这是现代浏览器最基本的安全机制之一。简单来说，当你的前端页面（比如运行在http://localhost:8080）尝试通过AJAX请求后端API（比如http://api.example.com）时，浏览器会阻止这种请求，除非后端明确允许。

在实际开发中，前后端分离架构已经成为主流，前端可能部署在CDN或独立域名下，后端API则有专门的域名。这种情况下，跨域问题几乎不可避免。我曾接手过一个电商项目，前端使用Vue.js部署在static.shop.com，而后端API在api.shop.com，就因为没处理好CORS导致支付功能完全无法使用。

提示：即使前端和后端在同一台服务器，如果端口不同（如前端3000端口，后端8080端口）也会触发跨域限制。

2. Sa-Token全局过滤器基础配置

2.1 添加Sa-Token依赖

首先需要在项目中引入Sa-Token核心库。以Maven项目为例：

<dependency> <groupId>cn.dev33</groupId> <artifactId>sa-token-spring-boot-starter</artifactId> <version>1.45.0</version> </dependency>

我建议始终使用最新稳定版，因为Sa-Token团队会持续修复CORS相关的边界问题。曾经有个项目使用了较旧的1.38.0版本，在处理OPTIONS预检请求时会出现奇怪的拦截行为。

2.2 创建基础过滤器类

创建一个继承自SaServletFilter的全局过滤器：

@Configuration public class SaTokenFilter implements SaServletFilter { @Override public void addExcludes(String... paths) { // 不需要过滤的路径 } @Override public void setAuth(Object handler) { // 认证逻辑 } @Override public void setBeforeAuth(Object handler) { // 前置处理 } }

这个基础结构是三种解决方案的共同起点。注意setBeforeAuth方法，这是我们后续处理CORS的关键切入点。

3. 方案一：纯Sa-Token过滤器实现

3.1 核心代码实现

在setBeforeAuth方法中添加CORS处理逻辑：

@Override public void setBeforeAuth(Object handler) { HttpServletRequest request = (HttpServletRequest) handler; HttpServletResponse response = (HttpServletResponse) handler; // 设置允许的源 response.setHeader("Access-Control-Allow-Origin", "*"); // 允许的请求方法 response.setHeader("Access-Control-Allow-Methods", "POST, GET, OPTIONS, DELETE"); // 预检请求缓存时间 response.setHeader("Access-Control-Max-Age", "3600"); // 允许的请求头 response.setHeader("Access-Control-Allow-Headers", "x-requested-with, sa-token, Content-Type"); }

3.2 实际项目中的坑点

  1. 星号(*)限制：虽然设置为*很方便，但在需要传递cookie时（比如单点登录场景）必须指定具体域名，且要设置Access-Control-Allow-Credentials: true。我曾在SSO集成时花了半天排查为什么cookie不生效。

  2. OPTIONS请求处理：浏览器会先发送OPTIONS预检请求。很多开发者只处理了GET/POST却漏了OPTIONS，导致PUT/DELETE等方法失败。务必确保所有方法都被列出。

  3. Header大小写敏感：有些前端框架会自动转换header名称大小写，而后端可能区分大小写。建议统一使用小写，比如sa-token而非Sa-Token。

4. 方案二：结合Spring的CorsRegistry

4.1 混合配置方式

如果你同时使用Spring MVC，可以结合两种方案：

@Configuration public class WebMvcConfig implements WebMvcConfigurer { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/**") .allowedOrigins("*") .allowedMethods("*") .allowedHeaders("*") .exposedHeaders("sa-token"); } } // 同时在SaTokenFilter中保留基础CORS设置

这种组合方式特别适合大型项目，可以利用Spring更细粒度的路径控制，同时保持Sa-Token的认证逻辑。

4.2 优先级问题

Spring的CORS配置和Sa-Token过滤器的执行顺序很重要。实测发现：

  1. 简单请求（GET/POST）：先经过Spring CORS，再到Sa-Token
  2. 复杂请求（PUT/DELETE等）：OPTIONS请求会被Spring优先处理

这意味着如果你的Sa-Token过滤器对OPTIONS请求有特殊逻辑，可能需要调整。一个保险的做法是在SaTokenFilter中增加判断：

if ("OPTIONS".equals(request.getMethod())) { return; }

5. 方案三：基于注解的精细控制

5.1 @SaCheckCors注解实现

对于需要特殊CORS规则的接口，可以创建自定义注解：

@Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface SaCheckCors { String[] origins() default "*"; String[] methods() default {"GET", "POST"}; String[] headers() default {}; }

然后在过滤器中解析注解：

HandlerMethod handlerMethod = (HandlerMethod)handler; SaCheckCors corsConfig = handlerMethod.getMethodAnnotation(SaCheckCors.class); if (corsConfig != null) { response.setHeader("Access-Control-Allow-Origin", String.join(",", corsConfig.origins())); // 其他header设置... }

5.2 实际应用场景

这种方案特别适合：

  • 某些接口需要开放给特定合作伙伴域名
  • 不同接口支持不同的HTTP方法
  • 需要动态调整CORS策略的灰度发布场景

比如支付回调接口可能只允许来自支付平台的POST请求：

@PostMapping("/pay/callback") @SaCheckCors(origins = "https://payment-platform.com", methods = "POST") public Result payCallback() { // ... }

6. 生产环境最佳实践

6.1 安全加固建议

  1. 不要无脑使用*：根据项目实际需要设置允许的源，可以配置在application.yml中：
sa-token: cors: allowed-origins: - https://www.yourdomain.com - https://admin.yourdomain.com
  1. 限制暴露的Header：只暴露必要的Header，避免泄露敏感信息：
response.setHeader("Access-Control-Expose-Headers", "sa-token, content-length");
  1. 结合HTTPS：CORS+HTTP是不安全的组合，生产环境必须启用HTTPS。

6.2 性能优化

  1. 合理设置Max-Age：对于稳定的API，可以设置较长的缓存时间减少OPTIONS请求：
response.setHeader("Access-Control-Max-Age", "86400"); // 24小时
  1. 避免重复处理：在过滤器中添加判断，已经处理过的请求不再重复设置Header：
if (response.getHeader("Access-Control-Allow-Origin") != null) { return; }
  1. 网关层统一处理：如果项目使用微服务架构，可以考虑在API网关统一处理CORS，避免每个服务重复配置。

7. 疑难问题排查指南

7.1 常见错误现象

  1. 控制台报错但服务端日志无记录：通常是浏览器拦截了请求，根本未到达服务端。检查网络面板确认请求是否真的发出。

  2. POST变成OPTIONS：这是正常预检机制，检查你的服务是否正确响应了OPTIONS方法。

  3. 明明配置了CORS还是报错：

    • 检查是否有多个过滤器/拦截器覆盖了CORS头
    • 使用curl测试确认响应头是否正确：
      curl -I -X OPTIONS http://your-api.com/endpoint

7.2 调试技巧

  1. 浏览器无痕模式测试：避免缓存干扰，Chrome的隐身窗口是最干净的测试环境。

  2. 简化复现：创建一个最小化的测试接口，排除业务逻辑干扰：

@GetMapping("/test-cors") public String testCors() { return "CORS test"; }
  1. 查看完整请求链路：使用Charles或Fiddler抓包，对比请求和响应的完整Header信息。

8. 三种方案对比与选型建议

8.1 方案对比表

特性纯Sa-Token方案Spring混合方案注解方案
实现复杂度低中高
灵活性一般较好最好
性能影响小较小中等
适合场景简单项目Spring项目需要精细控制
维护成本低中较高

8.2 个人经验建议

根据我参与过的十几个项目经验：

  1. 初创项目/快速原型：选择方案一，简单直接，10分钟搞定。

  2. 标准Spring Boot应用：方案二最平衡，既利用Spring生态，又保持Sa-Token特性。

  3. 企业级复杂系统：特别是需要对接多第三方系统时，方案三的精细控制必不可少。

一个实际案例：我们有个金融项目需要对接5个外部支付渠道，每个渠道的CORS要求都不同，最终采用方案三为每个渠道接口单独配置，大大降低了维护难度。

http://www.cnnetsun.cn/news/3476927.html

相关文章：

  • STM32定时器中断原理与实现教程
  • GPIO接口详解：从基础概念到高级应用
  • UE5 MetaHuman实时口型同步：NVIDIA Audio2Face与Omniverse流送实战
  • ExpressJS与现代Node.js框架的对比与迁移策略
  • CyberChef完整指南：快速掌握网络数据操作的瑞士军刀
  • 文档太多理不清？Qwen-Agent智能文档处理让AI帮你搞定一切
  • CSharp: Recursion Algorithm
  • UE网络同步实战：从权威服务器到属性复制的多人游戏开发指南
  • MySQL 数据截断错误 #22001：原因分析与解决方案
  • C++实战：从零构建可扩展扑克牌游戏框架
  • 从入门到精通：yuzu模拟器带你畅玩Switch游戏的终极指南
  • 比喻失效？ChatGPT理解瓶颈突破方案：3类常见误用场景+2套动态类比校准法（附NASA/MIT验证的类比有效性数据）
  • 大语言模型如何控制人形机器人：从任务规划到运动执行的技术架构解析
  • AI机器人实现“事前推理”：从条件反射到自主决策的技术演进与应用实践
  • Xilinx 7系列FPGA配置架构与实战指南
  • Steam挂刀神器：24小时自动追踪四大平台饰品比例，轻松找到最佳交易时机
  • 如何构建企业级文档认知系统：Qwen-Agent的架构创新与ROI分析
  • DLSS-Enabler完整指南：让AMD和Intel显卡免费解锁DLSS超采样技术
  • 50欧姆阻抗标准的工程实践与技术解析
  • 数字IC设计中分段时钟树综合的关键技术与实践
  • Ubuntu 22.04安装Java指南：OpenJDK与Oracle JDK配置
  • 生产级机器学习服务化：从模型推理到可观测性落地
  • Laravel延迟任务机制与实战应用详解
  • 如何快速上手RISC-V模拟器Spike：完整实战指南
  • Rust游戏基地建设完全指南：从防御原理到实战技巧
  • Chrome扩展开发：JSON格式化工具实现指南
  • 基于C++20协程与并行算法构建高性能分布式计算框架的设计与实践
  • 什么是‘浑身拧巴’？揭秘高动态系统中的多物理场耦合张力
  • 韩红“走面儿”折射京圈文化变迁：方言保护与文化传承分析
  • Cesium贴地技术：原理、实现与优化实践