跨域处理（CORS）中间件

CORS（跨域资源共享）中间件用于允许或限制前端应用从不同源访问后端 API，是现代 Web API 开发的常用需求。通过合理配置 CORS，可以提升安全性、兼容性和开发效率。

CORS 中间件典型时序图

说明

CORS 中间件检查请求的来源、方法、头部等是否符合配置的跨域策略。

• 如果允许：请求会继续传递给下游处理器（如路由、控制器等），最终返回正常响应。
• 如果不允许：中间件会直接返回 CORS 错误响应，阻止请求进入后续处理流程。

快速启动

只需 3 步即可启用跨域支持：

import spire_web_hosting.*
import spire_web_http.*
import spire_web_cors.*

main() {
    // 1. 构建Web主机
    let builder = WebHost.createBuilder()

    // 2. 注册CORS服务
    builder.services.addCors()
    let host = builder.build()

    // 3. 启用CORS中间件（默认允许全部）
    host.useCors()
    host.run()
}

添加依赖

需要在依赖配置文件(cjpm.toml)中添加如下依赖：

[dependencies]
  spire_web_http = { path = "/spire_web_http"}
  spire_web_hosting = { path = "/spire_web_hosting"}
  spire_web_cors = { path = "/spire_web_cors"}
  spire_extensions_injection = { path = "/spire_extensions_injection"}

CORS 策略配置

支持自定义允许的来源、方法、头部、暴露头部、凭据等：

main() {
    let builder = WebHost.createBuilder()

    // 注册CORS服务:只允许127.0.0.1 GET和POST请求
    builder.services.addCors({options: CorsOptions =>

        //注册名为"localOnly"的CORS策略
        options.addPolicy("localOnly", {policy: CorsPolicyBuilder =>
            policy.withOrigins(["http://127.0.0.1"])
            policy.withMethods(["GET", "POST"])
            policy.withHeaders(["*"])
        })
    })

    let host = builder.build()
    host.useCors("localOnly")

    host.run()
}

• withOrigins：指定允许的来源，支持多个域名
• withMethods：指定允许的 HTTP 方法
• withHeaders：指定允许的请求头

>curl -H "Origin: http://evil.com" -v http://127.0.0.1:5000/user/test
// ...
< HTTP/1.1 200 OK
< connection: keep-alive
// ...

>curl -H "Origin: http://127.0.0.1" -v http://127.0.0.1:5000/user/test
// ...
< HTTP/1.1 200 OK
< access-control-allow-origin: http://127.0.0.1   // 跨域策略生效
< connection: keep-alive
// ...

最佳实践

• 生产环境建议严格配置允许的来源和方法，避免 allowAnyOrigin() 滥用。
• 若需支持带凭据的跨域（如 Cookie），不能使用 allowAnyOrigin()，需指定具体域名。
• 跨域配置应与前端协同测试，确保 OPTIONS 预检请求正常。
• 可结合 API 分组、版本等灵活分配策略。