Acl9 技术文档

本文档旨在帮助用户安装、使用和深入了解 Acl9 项目。以下内容将包括安装指南、项目使用说明以及项目 API 使用文档。

1. 安装指南

Acl9 是一个基于角色的授权系统，提供了简洁的领域特定语言（DSL）来保护你的 Rails 应用程序。

安装方式

Acl9 采用语义化版本控制，你只需将以下代码添加到你的 Gemfile 中即可（注意，对于 Rails 6+ 支持，需要 3.2 版本）：

gem 'acl9', '~> 3.2'

你需要 Ruby > 2.0。

• 对于 Rails 4，使用 2.x 版本：

gem 'acl9', '~> 2.0'

• 对于 Rails < 4，需要升级 Rails！

gem 'acl9', '~> 0.12'

运行以下命令安装依赖：

bundle install

2. 项目使用说明

以下是一些简单的示例来演示如何使用 Acl9。

访问控制

你直接在控制器中声明访问控制，这样对于任何查看控制器的开发者来说都是可见和明显的：

class Admin::SchoolsController < ApplicationController
  access_control do
    allow :support, :of => School
    allow :admins, :managers, :teachers, :of => :school
    deny :teachers, :only => :destroy

    action :index do
      allow anonymous, logged_in
    end

    allow logged_in, :only => :show
    deny :students
  end

  def index
    # ...
  end

  # ...
end

更多关于访问控制的信息可以在项目的 Wiki 中查看。

角色

Acl9 的另一部分是给用户分配和移除角色。查看以下示例时，请参考 访问控制 示例，你应该能够看到每个角色对应哪些访问控制规则。

假设我们要为某个学校创建一个管理员，不是全局管理员，而是特定学校的管理员：

user.has_role! :admin, school
user.has_role! :admin, of: school

如果我们有一些专门支持所有学校的支持人员，我们可以使用新的角色名称 :school_support，或者使用我们可以将角色分配给任何对象的事实，包括类，并这样做：

user.has_role! :support, School
user.has_role! :support, for: School

当支持人员离开这个团队时，我们需要移除这个角色：

user.has_no_role! :support, School
user.has_no_role! :support, at: School

更多关于角色的信息可以在项目的 Wiki 中查看。

3. 项目 API 使用文档

Acl9 提供了一系列的方法来管理访问控制和角色。以下是一些关键方法的简要说明：

• access_control: 在控制器中定义访问控制规则。
• allow: 允许特定的角色访问特定的操作。
• deny: 禁止特定的角色访问特定的操作。
• has_role!: 给用户分配一个角色。
• has_no_role!: 从用户移除一个角色。

更多方法和详细说明可以在项目的 Wiki 中找到。

4. 项目安装方式

除了通过 Gemfile 安装外，Acl9 还提供了一个 Rails 生成器来创建迁移、角色模型和更新主体模型以及可选的任意对象模型。

在应用目录下运行以下命令查看生成器的用法：

bin/rails g acl9:setup -h

按照指示完成安装过程。