Rack CORS Middleware 使用与配置指南

本文档将详细介绍如何安装、使用以及配置 Rack::Cors 中间件，以支持跨域资源共享（CORS）。

1. 安装指南

要安装 Rack::Cors，可以使用以下命令：

gem install rack-cors

或者，在你的 Gemfile 中添加以下代码：

gem 'rack-cors'

然后执行 bundle install 命令。

2. 项目使用说明

Rack::Cors 是一个 Rack 兼容的中间件，用于为 web 应用程序提供 CORS 支持。CORS 规范允许 web 应用程序在不使用 JSONP 等替代方法的情况下，进行跨域 AJAX 调用。

配置说明

Rails 配置

对于 Rails 项目，需要在应用启动时添加这个中间件。一个实用的方法是使用初始化文件。例如，以下配置将允许从任何来源对任何资源进行 GET、POST、PATCH 或 PUT 请求：

# config/initializers/cors.rb

Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins '*'
    resource '*', headers: :any, methods: [:get, :post, :patch, :put]
  end
end

注意：如果使用 --api 选项创建应用，配置将自动生成在 config/initializers/cors.rb 中。

使用 insert_before 确保在中间件堆栈的起始位置运行 Rack::Cors，以避免被其他中间件（如 Rack::Cache）干扰。

Rack 配置

如果你在使用 Rack，可以在 config.ru 文件中配置 Rack::Cors：

use Rack::Cors do
  allow do
    origins 'localhost:3000', '127.0.0.1:3000',
            /\Ahttp:\/\/192\.168\.0\.\d{1,3}(:\d+)?\z/

    resource '/file/list_all/', :headers => 'x-domain-token'
    resource '/file/at/*',
        methods: [:get, :post, :delete, :put, :patch, :options, :head],
        headers: 'x-domain-token',
        expose: ['Some-Custom-Response-Header'],
        max_age: 600
  end

  allow do
    origins '*'
    resource '/public/*', headers: :any, methods: :get

    resource '/api/v1/*',
        headers: :any,
        methods: :get,
        if: proc { |env| env['HTTP_HOST'] == 'api.example.com' }
  end
end

配置参考

中间件选项

• debug (boolean)：启用调试日志和 X-Rack-CORS HTTP 头部，用于调试。
• logger (Object 或 Proc)：指定用于日志记录的日志器。如果提供一个 proc，它将在需要日志器时被调用。

来源 (Origins)

来源可以指定为字符串、正则表达式或 \* 允许所有来源。

安全提示： 使用正则表达式时，小心不要过于宽松。例如，表达式 /https:\/\/example\.com/ 会匹配 example.com.randomdomainname.co.uk。建议使用字符串开始和结束锚点，如 \Ahttps:\/\/example\.com\z。

来源还可以通过以下形式的块动态指定：

  origins { |source, env| true || false }

资源 (Resource)

资源路径可以指定为精确字符串匹配（/path/to/file.txt）或带有 \* 通配符（/all/files/in/*）。资源可以接受以下选项：

• methods (string 或 array 或 :any)：允许的 HTTP 方法。
• headers (string 或 array 或 :any)：请求中允许的 HTTP 头部。
• expose (string 或 array)：响应中可以公开的 HTTP 头部。
• credentials (boolean，默认：false)：设置 Access-Control-Allow-Credentials 响应头部。
• max_age (number)：设置 Access-Control-Max-Age 响应头部。
• if (Proc)：如果 proc 的结果为 true，则将请求处理为有效的 CORS 请求。
• vary (string 或 array)：添加到 'Vary' 头部的 HTTP 头部列表。

3. 项目API使用文档

由于 Rack::Cors 是一个中间件，因此它没有特定的 API。但是，它通过 HTTP 响应头提供 CORS 支持。以下是一些关键的响应头部：

• Access-Control-Allow-Origin：指定允许的来源。
• Access-Control-Allow-Methods：指定允许的 HTTP 方法。
• Access-Control-Allow-Headers：指定允许的 HTTP 头部。
• Access-Control-Allow-Credentials：指定是否允许凭证。
• Access-Control-Max-Age：指定预请求的缓存时间。

4. 项目安装方式

项目安装方式已在“安装指南”部分详细说明。可以通过 Ruby 的包管理器（Gem）安装 Rack::Cors。

gem install rack-cors

或在 Gemfile 中添加以下代码：

gem 'rack-cors'

然后执行：

bundle install

以上就是 Rack::Cors 中间件的使用和配置指南。遵循这些步骤，可以帮助你成功地在你的 Rails 或 Rack 应用中实现 CORS。