Rails 权限控制实战：用 Pundit 十分钟搞定授权

做 Rails 项目时，后台权限管理常常是最先失控的模块。初始阶段开发者习惯在控制器中堆砌条件判断，随着业务迭代，权限逻辑散落在视图与控制器多个文件中。修改一处规则需追溯多处代码，测试用例也变得难以维护。Pundit 提供了清晰的解决方案：为每个模型创建对应的 Policy 类，将所有权限判断集中到纯 Ruby 代码中。本教程引导你从零搭建完整的 Rails 授权架构，涵盖环境配置、策略编写、角色区分、数据过滤及自动化验证。

前置准备需确认项目运行在 Ruby 3.1 与 Rails 7.x 环境，并已完成基础用户认证模块，确保可获取当前登录用户实例。Pundit 采用纯 Ruby 设计理念，不依赖复杂宏或动态注入，掌握标准类定义即可上手。

终端执行 bundle add pundit 引入依赖。在 app/controllers/application_controller.rb 中混入 Pundit::Authorization 模块。此操作向控制器注入 authorize、policy_scope 等核心方法，所有继承自基类的控制器均可直接调用。运行 rails g pundit:install 生成基础文件。命令会在 app/policies/ 目录下创建 ApplicationPolicy 基类。生成完成后必须重启 Rails 开发服务器，否则 Zeitwerk 加载器无法识别新目录。建议在 ApplicationPolicy 的 initialize 中统一定义参数接收逻辑，并编写默认拒绝的拦截策略，后续所有业务 Policy 直接继承即可复用基础契约。

以典型博客系统为例，假设 Post 模型需满足严格权限矩阵：管理员查看全部并拥有完整操作权限；作者仅能查看自己的草稿及公开文章，且只能编辑个人内容；游客仅能访问公开文章。在 app/policies/post_policy.rb 中实现判定逻辑：

class PostPolicy < ApplicationPolicy
  def show?
    user.nil? ? record.public? : user.admin? || record.public? || user == record.author
  end

  def update?
    user&.admin? || user == record.author
  end

  def destroy?
    user&.admin?
  end

  class Scope < ApplicationPolicy::Scope
    def resolve
      return scope.all if user&.admin?
      if user
        scope.where(author: user).or(scope.where(public: true))
      else
        scope.where(public: true)
      end
    end
  end
end

基类自动注入的 user 代表当前请求用户，record 代表目标模型实例。方法命名严格遵循 Controller Action 规范。方法体只需返回布尔值，框架会根据返回值决定是否放行。若需传递额外上下文，可通过覆盖 initialize 接收自定义参数，并在调用 authorize 时同步传入。

控制器代码随之大幅精简：

class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])
    authorize @post
  end

  def update
    @post = Post.find(params[:id])
    authorize @post
    if @post.update(post_params)
      redirect_to @post
    else
      render :edit
    end
  end

  def destroy
    @post = Post.find(params[:id])
    authorize @post
    @post.destroy
    redirect_to posts_path
  end
end

每个 Action 仅需一行 authorize @post。Pundit 内部会根据模型类名自动查找同名 Policy，将当前用户与实例对象传入，并调用匹配的判定方法。授权失败时框架抛出 Pundit::NotAuthorizedError 标准异常，无需在每个 Action 手动编写重试或拦截逻辑。

列表场景需控制数据可见范围，直接查询全集会引发越权数据泄露。Pundit 提供 Scope 机制精准过滤结果集。在策略类内部定义嵌套的 Scope 已在上方代码块中展示。控制器通过以下方式调用：

def index
  @posts = policy_scope(Post)
end

resolve 方法接收初始查询对象，返回过滤后的 ActiveRecord Relation。管理员返回全集；已登录用户通过 or 组合查询个人内容与公开交集；未登录用户仅返回公开内容。policy_scope 调用后，列表渲染与分页查询自动应用该过滤条件，确保视图层永远只拿到安全数据。

团队协作中最易遗漏授权调用，ApplicationController 需配置验证钩子兜底：

class ApplicationController < ActionController::Base
  include Pundit::Authorization
  after_action :verify_pundit_authorization

  private

  def verify_pundit_authorization
    if action_name == "index"
      verify_policy_scoped
    else
      verify_authorized
    end
  end
end

after_action 会在请求响应前执行完整性检查。常规操作调用 verify_authorized，确保执行过授权判断；Index 操作调用 verify_policy_scoped，确保使用安全的数据查询。任何遗漏都会在开发环境直接抛出异常，配合 CI 流水线可有效拦截权限盲区。

实际落地需处理特定变体。认证系统使用非常规命名时，覆盖 pundit_user 方法返回实际对象即可无缝替换默认行为。授权失败需定制跳转时，使用 rescue_from Pundit::NotAuthorizedError 捕获异常并重定向至安全路径。策略文件体积过大时，利用模块抽离公共判断逻辑，通过 include 跨类复用。若需结合 Strong Parameters 控制可修改字段，在 Policy 中定义 permitted_attributes 区分角色白名单，控制器强参直接调用策略方法，消除硬编码。

基础架构跑通后，建议接入 RSpec 编写策略级单元测试，利用 Pundit 提供的 Matcher 覆盖各角色边界条件。中大型后台采用命名空间策略，通过数组参数路由至独立 Policy，实现前后端权限彻底解耦。配合 I18n 将错误提示多语言化，进一步提升可维护性。掌握 Policy 与 Scope 的协同模式后，授权模块将保持低维护成本与高扩展性，彻底告别权限逻辑蔓延的痛点。

本项目源码参考：https://github.com/varvet/pundit