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

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

一、项目概述

本案例基于Ruby on Rails 7开发，搭建一套后台管理系统核心能力：多角色RBAC权限控制+列表分页查询功能。系统划分超级管理员、运营管理员、普通员工三类角色，不同角色访问页面、操作数据权限隔离；同时封装通用分页工具类，适配所有数据表列表查询，降低重复编码成本。整套代码遵循Rails MVC规范，使用Devise做用户登录、CanCanCan实现权限校验，无第三方重型组件依赖，可直接迁移至生产环境。

二、环境依赖

Ruby 3.2.2
Rails 7.1.0
数据库：PostgreSQL 14
核心Gem依赖

ruby 复制代码

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

执行安装命令：

bash 复制代码

bundle install
rails db:create && rails db:migrate

三、数据库模型设计

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

ruby 复制代码

# 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. 模型代码

Role角色模型

ruby 复制代码

# 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

User用户模型（集成Devise）

ruby 复制代码

# 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. 权限能力定义（Ability权限配置）

ruby 复制代码

# 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

四、通用分页工具封装

封装全局分页方法，统一分页参数、数据返回格式

ruby 复制代码

# 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

五、业务控制器实现（订单列表示例）

ruby 复制代码

# app/controllers/orders_controller.rb
class OrdersController < ApplicationController
  load_and_authorize_resource # CanCan自动校验权限
  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

六、路由配置

ruby 复制代码

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

七、初始化测试角色数据

ruby 复制代码

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

海量精选技术文档和实战案例持续更新，敬请关注【风骏时光少年】