Consul 授权解决方案技术文档

Consul 是一个用于 Ruby on Rails 的授权解决方案，它通过描述“可访问的事物集合”来控制用户可以查看或编辑的内容。本文将详细介绍如何安装、使用 Consul，并解释其 API 的使用方法。

1. 安装指南

要安装 Consul，您需要在 Rails 项目的 Gemfile 中添加以下行：

gem 'consul'

然后运行 bundle install 来安装 gem。

2. 项目的使用说明

2.1 描述应用程序的访问权限

您可以通过在 app/models/power.rb 中放置一个 Power 模型来描述应用程序的访问权限。在 Power 模型中，您可以定义当前用户可以访问的内容。例如：

class Power
  include Consul::Power

  def initialize(user)
    @user = user
  end

  power :users do
    User if @user.admin?
  end

  power :notes do
    Note.by_author(@user)
  end

  power :dashboard do
    true # 这是一个布尔类型的 power，用于控制访问数据库之外的内容
  end
end

2.2 查询 Power

您可以通过以下方式查询 Power：

power = Power.new(user)
power.notes  # 返回一个 ActiveRecord::Scope
power.notes? # 如果 Power#notes 返回一个 scope 且不为 nil，则返回 true
power.notes! # 如果 Power#notes 返回 nil，则抛出 Consul::Powerless 异常

2.3 定义不同操作的 Power

如果您需要为不同的操作定义不同的访问权限，可以使用不同的 Power：

class Power
  ...

  power :notes do
    Note.published
  end

  power :updatable_notes do
    Note.by_author(@user)
  end

  power :destroyable_notes do
    Note if @user.admin?
  end
end

2.4 布尔类型的 Power

布尔类型的 Power 用于控制访问数据库之外的内容：

class Power
  ...

  power :dashboard do
    true
  end
end

查询布尔类型的 Power：

power.dashboard? # => true
power.dashboard! # => 如果 Power#dashboard? 返回 false，则抛出 Consul::Powerless 异常

3. 项目 API 使用文档

3.1 Scope Powers (关系)

Scope Powers 用于限制对 ActiveRecord 模型的访问。例如：

class Power
  ...

  power :notes do
    Note.by_author(@user)
  end

  power :users do
    User if @user.admin?
  end
end

查询 Scope Powers：

power.notes  # 返回一个 ActiveRecord::Scope
power.notes? # 如果 Power#notes 返回一个 scope 且不为 nil，则返回 true
power.notes! # 如果 Power#notes 返回 nil，则抛出 Consul::Powerless 异常

3.2 检查给定对象的 Power

有时您只需要检查给定对象是否可访问：

class Power
  ...

  power :updatable_post? do |post|
    post.author == @user
  end
end

查询此类 Power：

power.updatable_post?(Post.last) # 如果帖子的作者是 @user，则返回 true
power.updatable_post!(Post.last) # 如果帖子的作者不是 @user，则抛出 Consul::Powerless 异常

3.3 其他类型的 Power

Power 可以返回任何类型的对象。例如，返回一个数组：

class Power
  ...

  power :assignable_note_states do
    if admin?
      %w[draft pending published retracted]
    else
      %w[draft pending]
    end
  end
end

查询此类 Power：

power.assignable_note_states # => ['draft', 'pending']
power.assignable_note_states? # => 返回 true
power.assignable_note_states! # => 如果 Power#assignable_note_states 返回 nil，则抛出 Consul::Powerless 异常

4. 项目安装方式

4.1 通过 Gemfile 安装

在 Rails 项目的 Gemfile 中添加以下行：

gem 'consul'

然后运行 bundle install 来安装 gem。

4.2 配置 Power 模型

在 app/models/power.rb 中创建 Power 模型，并定义您的访问权限逻辑：

class Power
  include Consul::Power

  def initialize(user)
    @user = user
  end

  power :users do
    User if @user.admin?
  end

  power :notes do
    Note.by_author(@user)
  end

  power :dashboard do
    true
  end
end

4.3 在控制器中集成 Power

在 ApplicationController 中集成 Power，以便在整个应用程序中使用：

class ApplicationController < ActionController::Base
  include Consul::Controller

  current_power do
    Power.new(current_user)
  end
end

现在，您可以在控制器和视图中使用 current_power 方法来访问当前的 Power。

通过以上步骤，您已经成功安装并配置了 Consul，可以开始使用它来控制应用程序的访问权限了。