Shield 项目技术文档

1. 安装指南

首先，确保您的环境中已经安装了Ruby。接下来，使用以下命令通过RubyGems安装Shield项目：

gem install shield

2. 项目的使用说明

Shield是一个简单的认证库，它的目的是为应用提供保护。Shield的特点是代码简洁（大约110行Ruby代码），不会干扰现有代码，并且假设用户具备一定的编程能力。

Shield::Model

Shield::Model 是一个基本的协议，用于针对您的模型进行认证。它假设以下内容：

• 你会实现 User.fetch 方法，它接收登录字符串。
• 你有一个属性 crypted_password，可以存储多达192个字符。

实现模型协议的方法是包括 Shield::Model。

class User < Struct.new(:email, :crypted_password)
  include Shield::Model

  def self.fetch(email)
    user = new(email)
    user.password = "pass1234"

    return user
  end
end

通过包括 Shield::Model，你会得到所有进行认证所需的一般方法：

• 你会得到 User.authenticate 方法，它接收登录字符串和密码作为两个参数。
• 你会得到 User#password= 方法，它自动将明文密码转换为哈希形式并赋值给 #crypted_password。

支持邮箱和用户名登录

如果你的需求需要支持使用邮箱或用户名登录，你可以通过扩展 User.fetch 方法来实现：

class User < Sequel::Model
  include Shield::Model

  def self.fetch(identifier)
    filter(email: identifier).first || filter(username: identifier).first
  end
end

如果出于某些原因需要支持不区分大小写的登录，你可以将值转换为小写形式。

3. 项目API使用文档

Shield的API使用非常简单，主要包括以下几个部分：

Shield::Model

• User.fetch(email)：通过邮箱获取用户。
• User.authenticate(email, password)：通过邮箱和密码进行用户认证。
• User#password=：设置用户密码，并自动将其转换为哈希存储。

Shield::Helpers

Shield::Helpers 提供了一些在Rack应用程序上下文中使用的辅助方法，例如：

• authenticated(User)：检查当前是否有用户认证。
• login(User, login, password)：尝试登录用户。
• logout(User)：登出用户。

Shield::Middleware

Shield::Middleware 用于处理HTTP 401 Unauthorized响应，并将其重定向到登录页面。

use Shield::Middleware, "/login"
use Rack::Session::Cookie

4. 项目安装方式

如前所述，通过RubyGems安装Shield：

gem install shield

以上是Shield项目的基本安装和使用说明，希望对您的应用开发有所帮助。