Rack Canonical Host 技术文档

本文档旨在帮助用户安装、使用和理解 Rack Canonical Host 项目。以下是项目的技术细节和使用指南。

1. 安装指南

要安装 Rack Canonical Host，请按照以下步骤操作：

• 将以下代码添加到您的应用程序的 Gemfile 中：

  gem 'rack-canonical-host'
  

• 执行以下命令：

  $ bundle
  

• 或者，您也可以自行安装：

  $ gem install rack-canonical-host
  

2. 项目使用说明

Rack Canonical Host 是一个 Rack 中间件，允许您为应用程序定义一个单一的主机名作为规范主机。对于其他主机名的请求将会重定向到这个规范主机。

环境特定配置

您可能不希望在本地开发时进行重定向。为了防止这种情况，您可以在生产环境中使用环境变量来设置规范主机名。

使用 Heroku 时，您可以这样操作：

$ heroku config:add CANONICAL_HOST=example.com

然后，可以这样配置中间件：

use Rack::CanonicalHost, ENV['CANONICAL_HOST'] if ENV['CANONICAL_HOST']

现在，只有在定义了规范主机名时，中间件才会被使用。

选项

如果您希望中间件忽略某些主机，可以使用 :ignore 选项，它接受一个字符串、正则表达式、proc 或这些对象的数组。

use Rack::CanonicalHost, 'example.com', ignore: 'api.example.com'

在这种情况下，对 api.example.com 主机的请求将不会被重定向。

或者，您可以传递一个块，其返回值将用作规范主机名。

use Rack::CanonicalHost do |env|
  case env['RACK_ENV'].to_sym
    when :staging then 'staging.example.com'
    when :production then 'example.com'
  end
end

如果您希望它仅在多域环境中的特定主机上响应，可以使用 :if 选项，它接受一个字符串、正则表达式、lambda 或 proc，或这些对象的数组。

use Rack::CanonicalHost, 'example.com', if: /.*\.example\.com/
use Rack::CanonicalHost, 'example.org',
  if: ->(uri) { uri.host == 'www.example.org' }

缓存控制

为了避免浏览器无限期缓存 301 重定向，建议设置一个过期时间，以备将来可能需要更改重定向。

# 由浏览器决定缓存策略（可能会无限期缓存）：
use Rack::CanonicalHost, 'example.com'

# 缓存重定向，最长一个小时：
use Rack::CanonicalHost, 'example.com', cache_control: 'max-age=3600'

# 阻止重定向的缓存：
use Rack::CanonicalHost, 'example.com', cache_control: 'no-cache'

3. 项目API使用文档

Rack Canonical Host 提供了以下API：

• Rack::CanonicalHost: 主要的中间件类，接受一个主机名和一个可选的哈希参数，用于配置忽略的主机、条件判断和缓存控制。

4. 项目安装方式

项目安装方式已在“安装指南”部分详细说明。请参考上述步骤进行安装。

以上是 Rack Canonical Host 的技术文档，希望对您的使用有所帮助。