You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
13 KiB
13 KiB
跨域配置
**本文引用的文件** - [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java) - [application.yml](file://crm-app/src/main/resources/application.yml) - [CorsConfig.java](file://crm-base/src/main/java/com/crm/base/config/CorsConfig.java) - [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java) - [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java) - [application.yml](file://crm-auth/src/main/resources/application.yml)目录
简介
本章节面向跨域（CORS）配置模块，系统性说明：
- CORS策略配置与生效范围
- 允许的域名与方法集合、请求头与响应头定制
- 凭证处理（Cookie/Authorization）与安全性权衡
- 动态跨域配置与条件性启用
- 预检请求（OPTIONS）处理流程
- 开发环境与生产环境的差异化配置方案
- 常见问题定位与优化建议
项目结构
本项目采用多模块组织，跨域相关能力主要位于基础模块的通用配置中，并在认证模块的安全配置中进行集成。应用启动类负责加载各模块配置，最终由Spring MVC/WebFlux的CORS处理器统一生效。
graph TB
A["应用启动<br/>CrmAppApplication"] --> B["基础模块配置<br/>CorsConfig"]
A --> C["认证模块安全配置<br/>SecurityConfig"]
B --> D["Spring CORS 处理器"]
C --> D
D --> E["业务控制器<br/>Controller"]
图表来源
- CrmAppApplication.java
- CorsConfig.java
- SecurityConfig.java
章节来源
- CrmAppApplication.java
- CorsConfig.java
- SecurityConfig.java
核心组件
- 全局CORS配置：提供统一的跨域规则，包括允许的来源、方法、请求头、响应头以及是否允许携带凭证等。
- 安全配置集成：在认证模块中，将CORS与安全过滤器链结合，确保预检请求不被拦截，且后续鉴权流程正常。
- 属性注入与环境区分：通过配置文件或属性类，实现不同环境下的差异化CORS策略。
章节来源
- CorsConfig.java
- SecurityConfig.java
- AuthProperties.java
- application.yml
- application.yml
架构总览
下图展示了从浏览器发起跨域请求到服务端处理的完整链路，包括预检请求与实际请求的处理差异。
sequenceDiagram
participant Browser as "浏览器"
participant Server as "Spring MVC/Filter"
participant Cors as "CORS处理器"
participant Security as "安全过滤器链"
participant Controller as "业务控制器"
Browser->>Server : "发送跨域请求(可能为OPTIONS)"
Server->>Cors : "匹配CORS规则"
alt "预检请求(OPTIONS)"
Cors-->>Browser : "返回Access-Control-*响应头"
Server-->>Browser : "204/200 无业务响应体"
else "实际请求"
Cors-->>Security : "放行并继续过滤链"
Security-->>Controller : "鉴权通过后进入业务逻辑"
Controller-->>Browser : "业务响应+Access-Control-*响应头"
end
图表来源
- CorsConfig.java
- SecurityConfig.java
详细组件分析
全局CORS配置（CorsConfig）
- 作用：集中定义跨域策略，避免在各控制器重复配置。
- 关键能力：
- 允许的来源（Origin）：支持精确域名或通配符；生产环境建议使用白名单模式。
- 允许的方法：GET/POST/PUT/DELETE/OPTIONS等。
- 允许的请求头与响应头：如Content-Type、Authorization、自定义X-Header等。
- 凭证处理：是否允许携带Cookie或Authorization头，需配合前端设置withCredentials。
- 预检缓存：合理设置Access-Control-Max-Age以减少预检次数。
- 适用场景：前后端分离、微服务网关前置、静态资源跨域访问。
章节来源
- CorsConfig.java
安全配置集成（SecurityConfig）
- 作用：将CORS与安全过滤器链整合，保证预检请求不被拦截，同时确保后续鉴权流程有效。
- 关键点：
- OPTIONS请求放行：避免被JWT过滤器或权限校验阻断。
- 与认证模块的属性联动：根据环境变量或配置项切换严格/宽松策略。
- 与全局CORS的一致性：避免重复或冲突的规则导致行为不一致。
章节来源
- SecurityConfig.java
属性与环境区分（AuthProperties + application.yml）
- 作用：通过配置文件或属性类管理CORS相关参数，便于在不同环境切换策略。
- 常见配置项：
- 允许来源列表（逗号分隔或数组）
- 允许方法与请求头
- 是否允许凭证
- 预检缓存时间
- 开关控制（如仅在生产环境启用严格模式）
- 建议：
- 开发环境：可放宽限制，便于调试。
- 生产环境：最小化暴露面，严格白名单，谨慎开启凭证。
章节来源
- AuthProperties.java
- application.yml
- application.yml
动态跨域配置与条件性启用
- 动态来源解析：基于请求头或上下文动态计算允许来源，适用于多租户或动态子域名场景。
- 条件性启用：通过配置开关或环境标识，按需启用/禁用CORS或切换策略。
- 最佳实践：
- 优先使用白名单而非“*”通配，避免安全风险。
- 对敏感接口限制来源与方法，减少攻击面。
- 对预检缓存时间进行调优，平衡性能与灵活性。
章节来源
- CorsConfig.java
- SecurityConfig.java
- AuthProperties.java
- application.yml
预检请求处理与响应头定制
- 预检流程：浏览器先发送OPTIONS请求，服务端返回Access-Control-Allow-*头，确认允许后再发实际请求。
- 关键响应头：
- Access-Control-Allow-Origin：允许的来源
- Access-Control-Allow-Methods：允许的方法
- Access-Control-Allow-Headers：允许的请求头
- Access-Control-Expose-Headers：允许前端读取的响应头
- Access-Control-Allow-Credentials：是否允许凭证
- Access-Control-Max-Age：预检缓存时长
- 定制建议：
- 明确暴露必要响应头，避免前端读取受限。
- 合理设置Max-Age，降低频繁预检带来的延迟。
章节来源
- CorsConfig.java
- SecurityConfig.java
凭证处理与安全性
- 何时需要凭证：当后端需要读取Cookie或前端需要携带Authorization时。
- 风险点：
- 开启Allow-Credentials后，不能设置Allow-Origin为“*”。
- 必须严格限定Allow-Origin为可信来源。
- 前端配合：
- 设置withCredentials=true（XHR/fetch）。
- 确保后端正确返回Access-Control-Allow-Credentials。
章节来源
- CorsConfig.java
- SecurityConfig.java
开发环境与生产环境的差异化配置
- 开发环境：
- 可放宽来源与方法，便于联调。
- 可关闭严格校验，快速定位问题。
- 生产环境：
- 严格白名单来源，限制方法与请求头。
- 谨慎开启凭证，必要时引入网关层二次校验。
- 调整预检缓存时间，提升性能。
章节来源
- application.yml
- application.yml
- AuthProperties.java
依赖关系分析
CORS配置与安全配置之间存在协作关系：全局CORS负责跨域规则，安全配置确保预检请求不被拦截并与鉴权流程协同。
classDiagram
class CrmAppApplication {
+启动应用
}
class CorsConfig {
+配置允许来源
+配置允许方法
+配置请求头/响应头
+配置凭证
+配置预检缓存
}
class SecurityConfig {
+配置安全过滤器链
+放行OPTIONS
+与CORS协同
}
class AuthProperties {
+读取配置项
+环境区分
}
CrmAppApplication --> CorsConfig : "加载"
CrmAppApplication --> SecurityConfig : "加载"
SecurityConfig --> CorsConfig : "协同"
SecurityConfig --> AuthProperties : "读取配置"
图表来源
- CrmAppApplication.java
- CorsConfig.java
- SecurityConfig.java
- AuthProperties.java
章节来源
- CrmAppApplication.java
- CorsConfig.java
- SecurityConfig.java
- AuthProperties.java
性能考虑
- 预检缓存：合理设置Access-Control-Max-Age，减少浏览器重复预检。
- 最小化暴露：仅暴露必要的响应头，避免不必要的信息泄露。
- 来源白名单：避免使用“*”通配，减少无效匹配开销。
- 网关层优化：在网关层统一处理CORS，减轻应用服务器压力。
- 监控与度量：记录跨域失败率与预检频率，辅助容量规划。
[本节为通用指导，不直接分析具体文件]
故障排查指南
- 现象：浏览器控制台报“跨域错误”或“预检失败”
- 检查Access-Control-Allow-Origin是否正确返回且与请求来源一致。
- 若启用了凭证，确认未使用“*”作为来源。
- 现象：预检请求被拦截
- 检查安全过滤器链是否放行OPTIONS请求。
- 确认CORS配置已覆盖对应路径。
- 现象：前端无法读取响应头
- 检查Access-Control-Expose-Headers是否包含所需响应头。
- 现象：生产环境突然不可用
- 核对环境配置是否误用开发宽松策略。
- 检查来源白名单是否遗漏新域名或子域名。
章节来源
- CorsConfig.java
- SecurityConfig.java
- application.yml
结论
- 通过全局CORS配置与安全配置的协同，可实现灵活且安全的跨域策略。
- 开发环境应注重效率，生产环境应强调安全与性能。
- 预检缓存与最小化暴露是提升性能的关键。
- 建议在网关层统一治理CORS，增强可维护性与一致性。
[本节为总结性内容，不直接分析具体文件]
附录
- 常用响应头说明：
- Access-Control-Allow-Origin：允许的来源
- Access-Control-Allow-Methods：允许的方法
- Access-Control-Allow-Headers：允许的请求头
- Access-Control-Expose-Headers：允许前端读取的响应头
- Access-Control-Allow-Credentials：是否允许凭证
- Access-Control-Max-Age：预检缓存时长
- 最佳实践清单：
- 使用白名单而非“*”
- 谨慎开启凭证
- 明确暴露必要响应头
- 合理设置预检缓存
- 在网关层统一处理CORS
[本节为通用参考，不直接分析具体文件]