Rails多角色权限管理与数据分页查询完整实战代码

Ruby基于Rails框架实现多角色权限管理与数据分页查询完整实战代码案例

在后台管理系统的开发中，权限控制和数据分页是绕不开的两个核心场景。很多初学者在面对“不同角色看到不同内容”这类需求时，容易陷入复杂实现方案的泥潭。其实，在Ruby on Rails生态里，借助Devise和CanCanCan这两个成熟的组件，再加上一点封装思维，实现一套完整的RBAC权限控制和通用分页方案，并没有想象中那么复杂。

这套方案基于Rails 7开发，覆盖了超级管理员、运营管理员、普通员工三类角色的权限隔离，同时提供了可复用的分页工具。所有代码都遵循MVC规范，没有堆砌重型第三方组件，完全可以直接迁移到生产环境使用。

环境依赖

先看一下核心的技术栈：Ruby 3.2.2、Rails 7.1.0，数据库采用PostgreSQL 14。Gem依赖方面，Devise负责用户登录认证，CanCanCan处理RBAC权限控制，Kaminari作为分页插件，再加上pg驱动和bcrypt加密，这套组合足够应对大多数后台管理场景。

# Gemfile
gem 'devise'        # 用户登录认证
gem 'cancancan'     # RBAC权限控制
gem 'kaminari'      # 分页插件
gem 'pg'            # 数据库驱动
gem 'bcrypt'        # 密码加密

安装完成后，执行两条命令即可完成数据库初始化：bundle install和rails db:create && rails db:migrate。

数据库模型设计

1. 用户、角色、权限关联迁移文件

先建立用户与角色的关联关系。这里通过两个迁移文件实现：先创建roles表存储角色名称和权限数组，再给users表增加role_id外键。

# db/migrate/20260101000000_create_roles.rb
class CreateRoles < ActiveRecord::Migration[7.1]
  def change
    create_table :roles do |t|
      t.string :name, null: false, unique: true
      t.text :permissions, array: true, default: []
      t.timestamps
    end
  end
end

# db/migrate/20260101000001_add_role_id_to_users.rb
class AddRoleIdToUsers < ActiveRecord::Migration[7.1]
  def change
    add_reference :users, :role, foreign_key: true
  end
end

2. 模型代码

角色模型的核心是permissions字段，这里用serialize将数组序列化存储，并通过has_perm?方法检查权限。

# app/models/role.rb
class Role < ApplicationRecord
  serialize :permissions, Array
  validates :name, presence: true, uniqueness: true

  def has_perm?(perm_code)
    permissions.include?(perm_code)
  end
end

用户模型集成Devise后，通过belongs_to :role关联角色，并委托权限检查方法。注意这里通过delegate简化了调用方式。

# app/models/user.rb
class User < ApplicationRecord
  devise :database_authenticatable, :registerable,
         :recoverable, :rememberable, :validatable

  belongs_to :role
  delegate :has_perm?, to: :role

  def can_operate?(perm)
    role&.has_perm?(perm) || false
  end
end

3. 权限能力定义

CanCanCan的配置文件是权限校验的核心。这里根据can_operate?返回结果，为不同角色分配不同的操作权限。超级管理员拥有完整管理权限，运营管理员可以读写用户和订单但无权删除，普通员工只能查看订单。

# app/models/ability.rb
class Ability
  include CanCan::Ability

  def initialize(user)
    user ||= User.new

    if user.can_operate?('super_admin')
      can :manage, :all
    elsif user.can_operate?('operation')
      can [:read, :update], User
      can [:read, :create, :update], Order
      cannot :destroy, :all
    elsif user.can_operate?('staff')
      can :read, Order
      cannot [:create, :update, :destroy], User
    end
  end
end

通用分页工具封装

分页逻辑几乎每个列表页面都需要，但手动在每个控制器重复写分页代码实在不够优雅。这里封装了一个PaginationHelper模块，统一处理分页参数和数据返回格式。

# app/controllers/concerns/pagination_helper.rb
module PaginationHelper
  extend ActiveSupport::Concern

  included do
    helper_method :paginate_data
  end

  def paginate_data(model_scope, page_size = 10)
    page = params[:page] || 1
    model_scope.page(page).per(page_size)
  end
end

业务控制器实现

以订单列表为例，控制器通过load_and_authorize_resource自动校验权限，再调用封装好的分页方法。返回的JSON格式包含了数据、总数和页码信息，前端可以直接使用。

# app/controllers/orders_controller.rb
class OrdersController < ApplicationController
  load_and_authorize_resource
  include PaginationHelper

  def index
    @orders = paginate_data(Order.order(created_at: :desc), 15)

    render json: {
      code: 200,
      data: @orders,
      total: @orders.total_count,
      page: params[:page] || 1,
      page_size: 15
    }
  end

  private

  def order_params
    params.require(:order).permit(:order_no, :amount, :status)
  end
end

路由配置

路由配置很简单，用户登录和订单资源的CRUD接口各占一行：

# config/routes.rb
Rails.application.routes.draw do
  devise_for :users
  resources :orders, only: [:index, :create, :update]
end

初始化测试角色数据

数据初始化通过seeds文件完成。这里创建了三个角色：超级管理员拥有所有权限编码；运营管理员拥有user_read、order_create和order_update；普通员工只有order_read。同时创建了一个测试管理员用户，邮箱为admin@test.com，密码为12345678。

# db/seeds.rb
Role.create!(name: 'super_admin', permissions: %w[super_admin user_create user_delete order_manage])
Role.create!(name: 'operation', permissions: %w[operation user_read order_create order_update])
Role.create!(name: 'staff', permissions: %w[staff order_read])

super_role = Role.find_by(name: 'super_admin')
User.create!(email: 'admin@test.com', password: '12345678', role: super_role)

执行rails db:seed即可完成数据初始化。

功能测试说明

这套方案的几个关键验证点：

• 登录流程：访问/users/sign_in，未登录时自动跳转登录页
• 权限拦截：普通员工尝试访问订单编辑接口时，CanCanCan会返回403异常
• 分页示例：GET /orders?page=1返回结构化的分页数据
• 扩展方式：新增角色只需在seeds中添加新的Role记录并配置权限编码，无需修改控制器逻辑

优化拓展方案

如果要在生产环境中进一步打磨，可以考虑以下几个方向：

• 前端根据权限动态渲染按钮，无权限直接隐藏
• 分页工具增加排序和模糊查询参数，提高灵活性
• 增加全局异常捕获，统一返回错误JSON格式
• 缓存角色权限数据，减少数据库查询次数，提升接口响应速度