Pagy 迁移指南：从 WillPaginate/Kaminari 平滑过渡

Pagy 迁移指南：从 WillPaginate/Kaminari 平滑过渡

前言

在 Ruby on Rails 生态系统中，分页功能是几乎所有 Web 应用都会用到的核心组件。Pagy 作为新一代分页解决方案，以其卓越的性能和极低的内存占用脱颖而出。本文将详细介绍如何从传统的 WillPaginate 或 Kaminari 迁移到 Pagy 框架。

为什么选择 Pagy

在开始迁移之前，我们需要了解 Pagy 的几个关键优势：

1. 性能卓越：Pagy 的执行速度比传统分页库快 2-20 倍
2. 内存高效：内存占用比传统方案低 10-100 倍
3. 代码简洁：不污染模型层，保持代码整洁
4. 高度可定制：提供丰富的配置选项和扩展功能

迁移准备

基础环境配置

1. 安装 Pagy 并移除旧的分页库依赖
2. 创建 Pagy 初始化配置文件
3. 在 ApplicationController 中添加 include Pagy::Backend
4. 在 ApplicationHelper 中添加 include Pagy::Frontend

迁移步骤详解

1. 全局配置迁移

传统分页库通常有全局配置项，需要转换为 Pagy 的等效配置：

# WillPaginate 配置示例
WillPaginate.per_page = 10

# Kaminari 配置示例
Kaminari.configure do |config|
  config.max_per_page = 10
end

# Pagy 等效配置
Pagy::DEFAULT[:limit] = 10

2. 模型层清理

Pagy 的一个显著特点是它不会修改模型层。需要移除模型中的所有分页相关代码：

# 移除类似这样的代码
class Product < ApplicationRecord
  self.per_page = 15
end

3. 控制器层改造

控制器中的分页调用需要重写为 Pagy 风格：

# 旧代码 (WillPaginate/Kaminari)
@products = Product.some_scope.page(params[:page]).per(15)

# 新代码 (Pagy)
@pagy, @products = pagy(Product.some_scope, limit: 15)

4. 视图层调整

视图中的分页渲染需要更新：

<%# 旧代码 %>
<%= will_paginate @products %>

<%# 新代码 %>
<%== pagy_nav(@pagy) %>

迁移后验证

完成基础迁移后，需要进行全面测试：

1. 运行应用测试套件（如果有）
2. 手动浏览应用的所有分页界面
3. 检查分页功能是否正常工作
4. 验证分页样式是否保持原样

高级定制

如果应用有特殊的分页需求，Pagy 提供了丰富的定制选项：

分页样式调整

# 在初始化文件中配置
Pagy::DEFAULT[:size] = [3, 2, 2, 3] # 控制分页链接的显示数量

国际化支持

Pagy 内置了国际化支持，可以轻松实现多语言分页：

# 在初始化文件中启用
Pagy::I18n.load(locale: 'zh-CN')

常见问题解决

1. 分页样式异常：检查 CSS 是否与 Pagy 生成的 HTML 结构匹配
2. 分页参数错误：验证控制器中是否正确接收和处理了分页参数
3. 性能问题：确保使用了合适的索引和查询优化

结语

迁移到 Pagy 不仅能显著提升应用性能，还能简化代码结构。虽然迁移过程需要一些调整，但带来的长期收益是值得的。如果在迁移过程中遇到特殊问题，建议查阅 Pagy 的详细文档或寻求社区支持。

通过本指南，您应该能够顺利完成从 WillPaginate 或 Kaminari 到 Pagy 的迁移，让您的应用获得更好的分页体验。