跨域资源共享 (CORS)
在 Quarkus 中启用并配置 CORS 以指定允许的来源、方法和标头，指导浏览器安全地处理跨域请求。
跨域资源共享 (CORS) 使用 HTTP 标头安全地管理浏览器对来自外部来源的资源的请求。 通过指定允许的来源、方法和标头，Quarkus 服务器可以使用 CORS 过滤器来允许浏览器跨域请求资源，同时保持受控访问。 此机制增强了安全性并支持合法的跨域请求。 有关来源定义的更多信息，请参见Web Origin Concept。
启用 CORS 过滤器
要在您的应用程序中强制执行 CORS 策略，请将以下行添加到 `src/main/resources/application.properties` 文件中，以启用 Quarkus CORS 过滤器
quarkus.http.cors.enabled=true该过滤器拦截所有传入的 HTTP 请求，以识别跨域请求并应用配置的策略。 然后，该过滤器将 CORS 标头添加到 HTTP 响应，以通知浏览器有关允许的来源和访问参数。 对于预检请求，该过滤器会立即返回 HTTP 响应。 对于常规 CORS 请求，如果请求违反配置的策略，该过滤器会返回 HTTP 403 状态来拒绝访问；否则，如果策略允许，该过滤器会将请求转发到目标。
有关详细的配置选项，请参阅以下配置属性部分。
构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖
配置属性 |
类型 |
默认 |
|---|---|---|
CORS 允许的来源。 有效的 URL 的逗号分隔列表，例如 `http://www.quarkus.io,https://:3000`。 用正斜杠括起来的 URL 被解释为正则表达式。 环境变量： 显示更多 |
字符串列表 |
|
CORS 请求允许的 HTTP 方法。 有效的 HTTP 方法的逗号分隔列表，例如 `GET,PUT,POST`。 如果未设置，则过滤器默认允许任何 HTTP 方法。 默认值： 允许任何 HTTP 请求方法。 环境变量： 显示更多 |
字符串列表 |
|
CORS 请求允许的 HTTP 标头。 有效的标头的逗号分隔列表，例如 `X-Custom,Content-Disposition`。 如果未设置，则过滤器默认允许任何标头。 默认值： 允许任何 HTTP 请求标头。 环境变量： 显示更多 |
字符串列表 |
|
CORS 响应中公开的 HTTP 标头。 要公开的标头的逗号分隔列表，例如 `X-Custom,Content-Disposition`。 默认值： 不公开任何标头。 环境变量： 显示更多 |
字符串列表 |
|
通知浏览器它可以缓存预检请求结果的时间。 环境变量： 显示更多 |
||
告知浏览器，当请求的凭据模式 `Request.credentials` 设置为 `include` 时，是否允许前端 JavaScript 访问凭据。 默认值： 如果设置了 `quarkus.http.cors.origins` 属性并且与精确的 `Origin` 标头值匹配，则为 `true`。 环境变量： 显示更多 |
布尔值 |
|
关于 Duration 格式
要编写持续时间值，请使用标准的 `java.time.Duration` 格式。 有关更多信息，请参阅 Duration#parse() Java API 文档。 您还可以使用简化的格式，以数字开头
在其他情况下，简化格式将被转换为
|
CORS 配置示例
以下示例显示了完整的 CORS 过滤器配置，包括用于定义来源之一的正则表达式。
quarkus.http.cors.enabled=true (1)
quarkus.http.cors.origins=http://example.com,http://www.example.io,/https://([a-z0-9\\-_]+)\\\\.app\\\\.mydomain\\\\.com/ (2)
quarkus.http.cors.methods=GET,PUT,POST (3)
quarkus.http.cors.headers=X-Custom (4)
quarkus.http.cors.exposed-headers=Content-Disposition (5)
quarkus.http.cors.access-control-max-age=24H (6)
quarkus.http.cors.access-control-allow-credentials=true (7)| 1 | 启用 CORS 过滤器。 |
| 2 | 指定允许的来源，包括正则表达式。 |
| 3 | 列出跨域请求允许的 HTTP 方法。 |
| 4 | 声明客户端可以在请求中包含的自定义标头。 |
| 5 | 标识客户端可以访问的响应标头。 |
| 6 | 设置预检请求结果的缓存时长。 |
| 7 | 允许跨域请求中的 cookie 或凭据。 |
在 `application.properties` 文件中使用正则表达式时，请使用四个反斜杠 (``\\\\``) 转义特殊字符，以确保正确的行为。 例如
-
`\\\\.` 匹配文字 `.` 字符。
-
`\.` 将匹配任何单个字符作为正则表达式元数据字符。
|
不正确转义的模式可能会导致意外的行为或安全漏洞。 部署前始终验证正则表达式语法。 |
