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格式
- 缓存角色权限数据，减少数据库查询次数，提升接口响应速度
