Rack-Recaptcha 技术文档

1. 安装指南

要使用 Rack-Recaptcha，首先需要安装相关的 Ruby gem 包。你可以使用以下命令进行安装：

[sudo] gem install rack-recaptcha

安装完成后，需要在你的项目 Gemfile 文件中添加以下内容：

gem 'rack-recaptcha', :require => 'rack/recaptcha'

确保执行 bundle install 命令来更新项目的依赖。

2. 项目使用说明

Rack-Recaptcha 是一个 Rack 中间件，它可以通过 Recaptcha API 实现验证码的校验功能。要在你的应用程序中使用它，需要按照以下步骤进行配置：

1. 设置公开密钥（public key）和私有密钥（private key），你可以在 ReCaptcha 官网上注册获取。
2. 根据使用的框架，在相应的配置文件中添加 Rack-Recaptcha 中间件。

以下是一些常见框架的配置示例：

Sinatra

在 app.rb 文件中配置中间件：

use Rack::Recaptcha, :public_key => 'KEY', :private_key => 'SECRET'
helpers Rack::Recaptcha::Helpers

Padrino

在 app/app.rb 文件中配置中间件：

use Rack::Recaptcha, :public_key => 'KEY', :private_key => 'SECRET'
helpers Rack::Recaptcha::Helpers

Rails

在 application.rb 文件中配置中间件：

module YourRailsAppName
  class Application < Rails::Application
    ...
    config.gem 'rack-recaptcha', :lib => 'rack/recaptcha'
    config.middleware.use Rack::Recaptcha, :public_key => 'KEY', :private_key => 'SECRET'
  end
end

并在对应的 helper 或 controller 文件中包含 Rack::Recaptcha::Helpers 模块。

3. 项目 API 使用文档

Rack-Recaptcha 提供了一个助手模块 Rack::Recaptcha::Helpers，它可以为你的应用添加以下方法：

• recaptcha_tag :challenge：返回一个 JavaScript 验证码表单。
• recaptcha_tag :noscript：返回一个非 JavaScript 验证码表单。
• recaptcha_tag :ajax：返回一个 AJAX 验证码表单。

以下是一些使用示例：

# 返回 JavaScript 验证码表单
recaptcha_tag :challenge

# 返回非 JavaScript 验证码表单
recaptcha_tag :noscript, :height => 300, :width => 500

# 返回 AJAX 验证码表单
recaptcha_tag :ajax, :display => { :theme => 'red' }

可以使用 recaptcha_valid? 方法来检查验证是否通过。

if recaptcha_valid?
  # 验证通过
else
  # 验证失败
end

在测试环境中，可以通过以下方式覆盖 recaptcha_valid? 方法的行为：

# 使 recaptcha_valid? 返回 true
Rack::Recaptcha.test_mode!

# 使 recaptcha_valid? 返回 false
Rack::Recaptcha.test_mode! :return => false

4. 项目安装方式

请参考上述的安装指南，使用 Ruby gem 包管理器安装 Rack-Recaptcha。

[sudo] gem install rack-recaptcha

在 Gemfile 中添加 gem 'rack-recaptcha', :require => 'rack/recaptcha'，然后执行 bundle install。