1. 项目概述为什么我们需要一个更好的分页方案在构建现代Web应用特别是API服务时分页是一个绕不开的核心功能。无论是展示用户列表、文章流还是处理海量的交易记录我们都需要一种高效、可靠的方式来分批获取数据。如果你用过传统的LIMIT-OFFSET分页可能会遇到这样的场景当用户翻到第100页时数据库需要先费力地跳过前9900条记录性能随着页码的增加而急剧下降更糟糕的是如果在翻页过程中有新的数据插入或旧数据删除用户可能会看到重复的记录或者漏掉一些数据体验非常糟糕。这就是duffelhq/paginator要解决的问题。它是一个专门为 Elixir 生态中的 Ecto 数据库工具包设计的游标分页库。它不只是一个简单的工具更代表了一种更优的工程实践——用游标Cursor替代传统的页码偏移Offset从根本上解决上述的性能和一致性问题。我在处理高并发的数据流和API设计时曾深受传统分页之苦直到采用了游标分页系统的稳定性和响应速度才有了质的提升。这个库将这种复杂但高效的机制封装得非常优雅让开发者能轻松地在项目中落地。2. 核心原理游标分页 vs. 传统分页的深度解析要理解paginator的价值我们必须先彻底搞懂它背后的原理。这不仅仅是“怎么用”的问题更是“为什么用它”的决策依据。2.1 传统 Limit-Offset 分页的固有缺陷传统分页的逻辑很直观LIMIT 10 OFFSET 20意味着“跳过前20条取接下来的10条”。这种方式的缺陷是结构性的性能瓶颈OFFSET N的代价极高。数据库为了跳过前N条记录通常需要将这些记录全部读取、排序然后再丢弃。当 N 很大时比如翻到很深的页码这相当于执行了一个几乎全表扫描的查询只是最后不返回结果而已。我曾在一个百万级用户表的项目中亲眼见过一个OFFSET 50000的查询将数据库CPU打满。数据不一致性这是更隐蔽的问题。假设你第一次查询获取了第1页ID 1-10此时有一条新记录ID 11插入。当你查询第2页OFFSET 10时数据库会跳过前10条ID 1-10然后从第11条开始取。结果原本在第1页末尾的记录ID 10被“挤”到了第2页的开头而新插入的 ID 11 也会出现。用户就会看到重复的 ID 10 和新的 ID 11体验割裂。2.2 游标分页的工作原理与优势游标分页也叫 Keyset 分页采用了完全不同的思路。它不关心“第几页”只关心“从哪个位置开始”。核心机制它要求数据有一个唯一且有序的“游标字段组合”例如[inserted_at, id]。查询时不是告诉数据库“跳过多少”而是告诉它“请给我inserted_at大于某个时间点且id大于某个值的10条记录”。这个“某个时间点和ID”就是游标通常是一个不透明的、经过编码的字符串由上一页结果的最后一条记录的相关字段值生成。性能优势由于查询条件WHERE inserted_at ? AND id ?可以利用索引进行高效的范围查找数据库无需遍历和跳过任何无关记录。无论你要获取“下一页”还是“上一千页”查询成本几乎是恒定的只和每页的大小LIMIT有关。一致性保证因为查询锚定在具体的数据值上在两次查询之间无论之前的数据如何增删都不会影响“下一页”查询的结果集。你总是能稳定地获取到游标之后的那一批数据不会重复也不会丢失。注意游标分页的“代价”是你无法直接跳转到任意页码比如“跳到第100页”。但这对于无限滚动的Feed流、API的分页令牌next_token模式来说恰恰是优点而非缺点。2.3 Paginator 的设计哲学paginator库聪明地将这一套机制集成到了 Ecto 的查询生态中。它没有重新发明轮子而是通过扩展Repo模块增加了一个paginate/2函数。你的所有查询逻辑、where条件、join操作都保持不变只需要在最后调用paginate并指定游标字段和分页方向即可。它负责自动生成复杂的游标WHERE子句、处理边界条件、并返回一个包含数据条目和分页元数据前后游标、是否还有更多数据的结构化结果。这种“最小侵入”的设计让它在现有项目中集成起来异常顺畅。3. 从零开始在项目中集成与配置 Paginator理论讲透了我们来看实战。将paginator集成到你的 Elixir Phoenix 或纯 Ecto 项目中步骤非常清晰。3.1 安装与基础配置首先在mix.exs文件的deps函数中添加依赖。建议使用最新的稳定版本你可以去 Hex.pm 查看。def deps do [ {:paginator, ~ 1.2.0} ] end然后运行mix deps.get获取依赖。接下来在你的 Repo 模块中启用它。这通常位于lib/my_app/repo.exdefmodule MyApp.Repo do use Ecto.Repo, otp_app: :my_app, adapter: Ecto.Adapters.Postgres # 添加这一行 use Paginator end就这么简单。现在你的MyApp.Repo模块就拥有了paginate/2函数。这里有一个关键的实操心得确保你的数据库适配器是 PostgreSQL。虽然从原理上讲游标分页适用于任何支持索引和范围查询的数据库但截至我写这篇文章时paginator的官方测试和社区实践主要围绕 PostgreSQL。如果你在使用 MySQL 或其他数据库需要仔细测试因为查询语句的生成可能有所不同。3.2 第一个分页查询理解核心参数让我们从一个最简单的例子开始假设我们有一个posts表有id,title,inserted_at字段。# 1. 构建基础查询。注意ORDER BY 是必须的 query from(p in Post, order_by: [asc: p.inserted_at, asc: p.id]) # 2. 执行分页查询 page_result MyApp.Repo.paginate( query, cursor_fields: [:inserted_at, :id], # 指定游标字段 limit: 10 # 指定每页大小 ) # 3. 解析结果 %Paginator.Page{ entries: entries, # 当前页的数据列表这里是10篇Post metadata: metadata } page_result # metadata 结构如下 # %Paginator.Metadata{ # after: after_cursor, # 用于获取下一页的游标可能为nil # before: before_cursor,# 用于获取上一页的游标可能为nil # limit: 10, # 你设置的limit # total_count: nil # 默认不计算总数 # } IO.inspect(entries)核心参数解析cursor_fields:这是最重要的参数。它定义了游标的构成。它必须是一个列表元素可以是原子如:id表示默认升序也可以是元组{:field_name, :asc | :desc}来明确指定排序方向。关键原则这个列表定义的顺序和方向必须与你查询中order_by子句的顺序完全一致并且组合起来必须能唯一确定一条记录。通常的做法是使用时间戳字段inserted_at,updated_at加上主键id。limit: 每页返回的记录数。after: 一个不透明的游标字符串表示“从这个游标之后开始获取”。通常来自上一页结果的metadata.after。before: 一个不透明的游标字符串表示“从这个游标之前开始获取”。通常来自当前页结果的metadata.before用于实现“上一页”功能。include_total_count: 如果设置为truepaginator会额外执行一条SELECT COUNT(*)查询并将总数填入metadata.total_count。慎用此选项因为在超大表上执行COUNT(*)可能非常慢。很多API设计如Twitter、Facebook已经不返回总条数了只提供“是否有更多”的指示。3.3 实现完整的前后翻页流程理解了单次查询后我们模拟一个完整的API分页流程defmodule MyApp.PostController do use MyAppWeb, :controller def index(conn, params) do base_query from(p in Post, where: p.published true, order_by: [desc: p.published_at, asc: p.id]) # 从请求参数中获取游标和每页大小 cursor_after params[after] cursor_before params[before] page_size String.to_integer(params[page_size] || 20) # 构建分页选项 pagination_opts [ cursor_fields: [{:published_at, :desc}, :id], limit: page_size ] # 根据请求决定是向前翻还是向后翻 pagination_opts case {cursor_after, cursor_before} do {nil, nil} - pagination_opts # 第一页 {after_val, nil} - Keyword.put(pagination_opts, :after, after_val) {nil, before_val} - Keyword.put(pagination_opts, :before, before_val) # 通常 after 和 before 不会同时存在 end # 执行分页 %{entries: posts, metadata: metadata} MyApp.Repo.paginate(base_query, pagination_opts) # 构造API响应 json_data %{ data: Enum.map(posts, post_json/1), paging: %{ cursors: %{ before: metadata.before, after: metadata.after }, # 一个简单的指示是否还有更多数据 has_more: not is_nil(metadata.after) } } json(conn, json_data) end defp post_json(post) do %{id: post.id, title: post.title, published_at: post.published_at} end end这个例子展示了如何将paginator集成到 Web 控制器中。API 客户端第一次调用时不带游标获取第一页。响应中的paging.cursors.after就是下一页的“钥匙”。客户端下次请求时带上?afterxxxxx参数即可获取下一页。has_more字段可以方便前端判断是否显示“加载更多”按钮。4. 高级用法与实战技巧基础用法能解决80%的问题但paginator的真正威力在于它能处理复杂场景。下面分享几个我在实际项目中用到的进阶技巧。4.1 处理动态计算字段如搜索排名这是paginator一个非常强大的特性。假设我们有一个全文搜索功能需要根据ts_rank函数计算的相关性分数进行排序。这个分数不是数据库的静态字段而是动态计算出来的。paginator通过fetch_cursor_value_fun和cursor_fields中的函数选项来支持这一点。def search_posts(search_term, cursor \\ nil, limit \\ 20) do # 基础查询使用 PostgreSQL 全文搜索 base_query from(p in Post, where: fragment(to_tsvector(english, content) plainto_tsquery(english, ?), ^search_term), # 注意order_by 必须和 cursor_fields 定义的逻辑匹配 order_by: [ desc: fragment(ts_rank(to_tsvector(english, content), plainto_tsquery(english, ?)), ^search_term), desc: p.id # 用 id 作为第二排序字段保证唯一性 ] ) # 定义如何从结果行中提取游标值 fetch_fun fn # 当字段是 :rank 时我们执行一个子查询来计算该行的准确分数 schema, :rank - {:ok, %{rows: [[rank_value]]}} MyApp.Repo.query( SELECT ts_rank(to_tsvector(english, $1), plainto_tsquery(english, $2)), [schema.content, search_term] ) rank_value # 对于其他字段如 :id使用库提供的默认方法 schema, field - Paginator.default_fetch_cursor_value(schema, field) end # 定义游标字段其中 :rank 字段由一个动态表达式生成 cursor_fields [ {:rank, fn - # 这个动态表达式用于在 WHERE 条件中构造 rank 的比较逻辑 dynamic( [p], fragment(ts_rank(to_tsvector(english, ?), plainto_tsquery(english, ?)), p.content, ^search_term) ) end}, {:id, :desc} ] opts [cursor_fields: cursor_fields, limit: limit, fetch_cursor_value_fun: fetch_fun] opts if cursor, do: Keyword.put(opts, :after, cursor), else: opts MyApp.Repo.paginate(base_query, opts) end这个例子有点复杂但原理很清晰fetch_cursor_value_fun: 当paginator需要为当前页的最后一条记录生成游标时它会调用这个函数。对于动态字段:rank我们手动执行一个查询来计算其精确值对于:id则用库函数。cursor_fields中的函数当用户传递一个游标来查询“下一页”时paginator需要根据这个游标值构造WHERE条件。对于:rank字段它使用我们提供的匿名函数来生成一个 Ecto 动态查询dynamic这个查询片段会最终被转换成 SQL 的WHERE ts_rank(...) ?条件。实操心得这种动态字段的支持非常强大可以用于按复杂表达式、聚合函数结果甚至是关联子查询的结果进行分页。但代价是增加了查询的复杂度。务必为这些计算字段和主键字段建立复合索引否则性能会退化。4.2 多表关联查询的分页分页关联查询需要格外小心。一个常见的需求是分页获取文章列表并预加载每条文章的评论数和作者信息。query from(p in Post, left_join: c in assoc(p, :comments), left_join: a in assoc(p, :author), group_by: [p.id, a.id], select: %{ post: p, comment_count: count(c.id), author_name: a.name }, order_by: [desc: max(p.published_at), asc: p.id] # 注意聚合函数后的排序 ) # 错误的游标字段定义直接使用 p.published_at # cursor_fields: [{:published_at, :desc}, :id] # 这会导致错误因为SELECT里没有单独的p.published_at # 正确的游标字段定义需要与SELECT和ORDER BY匹配 cursor_fields [ {:published_at, fn - # 由于我们在order_by中使用了 max(p.published_at)这里也需要对应 dynamic([p], max(p.published_at)) end}, :id ] page Repo.paginate(query, cursor_fields: cursor_fields, limit: 15)关键点当查询中包含group_by、聚合函数或复杂的select映射时你的cursor_fields定义必须能够被正确地映射到最终的查询结果上。通常这意味着你需要像处理动态字段一样为那些在select中不是简单字段引用的排序项提供函数定义。同时确保order_by子句使用的表达式与cursor_fields定义的逻辑完全一致。4.3 索引策略为性能保驾护航游标分页的性能优势完全建立在索引之上。没有正确的索引它甚至可能比OFFSET更慢。黄金法则为cursor_fields中定义的所有字段组合创建一个复合索引并且索引的列顺序、排序方向必须与cursor_fields完全一致。对于我们的经典例子cursor_fields: [:inserted_at, :id]-- 在迁移文件中 CREATE INDEX posts_inserted_at_id_index ON posts (inserted_at, id);如果你的排序是降序的例如cursor_fields: [{:published_at, :desc}, :id]在 PostgreSQL 中你可以创建降序索引以获得最佳性能CREATE INDEX posts_published_at_desc_id_index ON posts (published_at DESC, id ASC);踩坑记录我曾经在一个项目中没有为游标字段创建索引当数据量达到几十万时分页查询突然变得非常慢。使用EXPLAIN ANALYZE分析查询计划后发现数据库在进行全表扫描和文件排序filesort。加上复合索引后查询时间从几百毫秒降到了几毫秒。这是一个必须进行的优化步骤。5. 常见问题、排查技巧与安全须知即使理解了原理在实际使用中还是会遇到各种问题。下面是我总结的一些常见坑点和解决方案。5.1 错误与异常排查问题现象可能原因解决方案** (ArgumentError) cursor fields must be a listcursor_fields参数格式错误可能传入了非列表值。检查cursor_fields是否是一个列表如[:id]或[{:created_at, :desc}, :id]。** (ArgumentError) order_by must be specified on the query传入paginate/2的 Ecto 查询没有指定order_by子句。游标分页必须有确定的排序。在调用paginate前确保你的查询包含了order_by。** (Postgrex.Error) ERROR 42703 (undefined column)游标字段在生成的 SQL 的 WHERE 或 SELECT 子句中不存在。1. 检查cursor_fields中的字段名是否拼写正确且存在于查询的源表中。2. 如果是关联查询或复杂 SELECT确保字段在上下文中可用可能需要使用as/1或修改select语句。分页结果出现重复或丢失记录1.cursor_fields的组合不能唯一确定一行。2. 数据在分页过程中被修改且排序字段被更新。1.确保游标字段组合是唯一的。最稳妥的做法是始终包含主键id作为最后一个游标字段。2. 避免使用如updated_at这种可能被频繁更新的字段作为唯一或主要的排序字段。如果必须用确保业务逻辑能处理这种边界情况。使用after游标返回空结果但应该还有数据游标值可能已损坏或来自不同的查询/排序条件。游标是与特定查询和cursor_fields定义绑定的。切勿将一个查询生成的游标用于另一个排序或条件不同的查询。每次分页都应使用相同的底层查询和cursor_fields。5.2 安全考量防止游标注入paginator在设计上考虑了安全性。游标是一个不透明的字符串通常是 Base64 编码的结构化数据。库内部会对其进行解码和验证。重要的是你不应该手动构造或修改游标值。Repo.paginate/4函数内部会检查传入的:before和:after参数如果检测到其中包含可执行代码Elixir 函数或原子它会主动抛出一个ArgumentError。这有效防止了潜在的“游标注入”攻击即攻击者通过伪造恶意的游标字符串来尝试执行任意代码。作为开发者你需要做的就是从metadata中获取游标并原封不动地传递给下一次paginate调用。不要尝试解析或生成它。5.3 性能监控与调试对于关键的分页查询建议进行监控。日志Ecto 的日志会输出paginate生成的最终 SQL。仔细查看WHERE子句确认它是否正确使用了游标条件如WHERE (created_at, id) (?, ?)并且没有额外的全表扫描。EXPLAIN ANALYZE如果发现某次分页查询变慢可以将paginate调用前的查询取出手动加上limit并用Repo.query(“EXPLAIN ANALYZE …”)执行查看查询计划确认是否使用了正确的索引。游标字段选择尽量选择单调递增且不常更新的字段作为主游标字段如自增ID、创建时间。使用updated_at需要谨慎因为记录更新会导致它在排序中的位置发生变化可能影响分页连续性。5.4 与 Phoenix 框架的深度集成在 Phoenix 项目中你可以创建一个通用的分页辅助函数用于规范控制器中的分页逻辑和响应格式。# lib/my_app_web/controllers/pagination_helpers.ex defmodule MyAppWeb.PaginationHelpers do import Plug.Conn def paginate_params(conn) do %{ after conn.params[after], before conn.params[before], page_size conn.params[page_size] || 25 } end def build_pagination_links(conn, metadata, base_path) do links %{} if metadata.before do links Map.put(links, :prev, build_url(conn, base_path, metadata.before, nil, metadata.limit)) end if metadata.after do links Map.put(links, :next, build_url(conn, base_path, nil, metadata.after, metadata.limit)) end links end defp build_url(conn, base_path, before_cursor, after_cursor, limit) do query_params %{page_size limit} query_params if before_cursor, do: Map.put(query_params, before, before_cursor), else: query_params query_params if after_cursor, do: Map.put(query_params, after, after_cursor), else: query_params MyAppWeb.Router.Helpers.url(conn) base_path ? URI.encode_query(query_params) end end然后在控制器中这样使用def index(conn, params) do pagination_params PaginationHelpers.paginate_params(conn) base_query from(Item, order_by: [desc: :inserted_at, asc: :id]) opts [ cursor_fields: [{:inserted_at, :desc}, :id], limit: String.to_integer(pagination_params[page_size]) ] | maybe_put_cursor(:after, pagination_params[after]) | maybe_put_cursor(:before, pagination_params[before]) %{entries: items, metadata: metadata} Repo.paginate(base_query, opts) links PaginationHelpers.build_pagination_links(conn, metadata, ~p/api/items) render(conn, :index, items: items, links: links) end defp maybe_put_cursor(opts, _key, nil), do: opts defp maybe_put_cursor(opts, key, value), do: Keyword.put(opts, key, value)这样你的 API 就能返回符合 HATEOAS 风格的、包含明确next和prev链接的分页响应了客户端无需自己拼接 URL体验更好。6. 总结与最佳实践提炼经过几个项目的深度使用duffelhq/paginator已经成为了我 Elixir 技术栈中处理分页的首选工具。它不仅仅是一个库更是一种最佳实践的体现。最后再分享几条凝结了实际教训的终极建议始终使用复合索引这是游标分页性能的基石。索引顺序务必与cursor_fields完全一致。上线前用真实数据量测试分页查询的执行计划。游标字段必须唯一且稳定最通用的模式是[排序时间字段, 主键ID]。时间字段决定大致顺序主键ID解决同一时间戳下的唯一性问题。避免使用可能被更新的字段作为唯一排序依据。不要暴露内部游标结构虽然游标是 Base64 编码的但不要依赖其结构。视其为不透明的令牌。这保证了后端排序逻辑变更比如从created_at改为updated_at时不会破坏已发出的客户端游标当然逻辑变更后旧游标会失效这是另一个需要处理的问题。在 API 设计中拥抱游标模式放弃“总页数”和“跳转到第N页”的概念。设计 API 时只返回data、next_cursor和has_more或prev_cursor。这更符合现代无限滚动和高效数据获取的理念。复杂查询先测试对于包含多表关联、聚合、复杂WHERE条件的查询先在开发环境用IO.inspect(Repo.to_sql(:all, query))打印出paginate前查询的 SQL确保其正确性。然后再进行分页并检查生成的最终 SQL 是否高效。游标分页是一个“想清楚了就一劳永逸”的基础设施。初期投入一点学习成本换来的是应用在数据增长时依然保持的丝滑性能。paginator库用简洁的 API 封装了所有复杂细节让开发者可以专注于业务逻辑这正是 Elixir 生态中优秀库的特质。
Elixir游标分页实战：用duffelhq/paginator解决API性能瓶颈
1. 项目概述为什么我们需要一个更好的分页方案在构建现代Web应用特别是API服务时分页是一个绕不开的核心功能。无论是展示用户列表、文章流还是处理海量的交易记录我们都需要一种高效、可靠的方式来分批获取数据。如果你用过传统的LIMIT-OFFSET分页可能会遇到这样的场景当用户翻到第100页时数据库需要先费力地跳过前9900条记录性能随着页码的增加而急剧下降更糟糕的是如果在翻页过程中有新的数据插入或旧数据删除用户可能会看到重复的记录或者漏掉一些数据体验非常糟糕。这就是duffelhq/paginator要解决的问题。它是一个专门为 Elixir 生态中的 Ecto 数据库工具包设计的游标分页库。它不只是一个简单的工具更代表了一种更优的工程实践——用游标Cursor替代传统的页码偏移Offset从根本上解决上述的性能和一致性问题。我在处理高并发的数据流和API设计时曾深受传统分页之苦直到采用了游标分页系统的稳定性和响应速度才有了质的提升。这个库将这种复杂但高效的机制封装得非常优雅让开发者能轻松地在项目中落地。2. 核心原理游标分页 vs. 传统分页的深度解析要理解paginator的价值我们必须先彻底搞懂它背后的原理。这不仅仅是“怎么用”的问题更是“为什么用它”的决策依据。2.1 传统 Limit-Offset 分页的固有缺陷传统分页的逻辑很直观LIMIT 10 OFFSET 20意味着“跳过前20条取接下来的10条”。这种方式的缺陷是结构性的性能瓶颈OFFSET N的代价极高。数据库为了跳过前N条记录通常需要将这些记录全部读取、排序然后再丢弃。当 N 很大时比如翻到很深的页码这相当于执行了一个几乎全表扫描的查询只是最后不返回结果而已。我曾在一个百万级用户表的项目中亲眼见过一个OFFSET 50000的查询将数据库CPU打满。数据不一致性这是更隐蔽的问题。假设你第一次查询获取了第1页ID 1-10此时有一条新记录ID 11插入。当你查询第2页OFFSET 10时数据库会跳过前10条ID 1-10然后从第11条开始取。结果原本在第1页末尾的记录ID 10被“挤”到了第2页的开头而新插入的 ID 11 也会出现。用户就会看到重复的 ID 10 和新的 ID 11体验割裂。2.2 游标分页的工作原理与优势游标分页也叫 Keyset 分页采用了完全不同的思路。它不关心“第几页”只关心“从哪个位置开始”。核心机制它要求数据有一个唯一且有序的“游标字段组合”例如[inserted_at, id]。查询时不是告诉数据库“跳过多少”而是告诉它“请给我inserted_at大于某个时间点且id大于某个值的10条记录”。这个“某个时间点和ID”就是游标通常是一个不透明的、经过编码的字符串由上一页结果的最后一条记录的相关字段值生成。性能优势由于查询条件WHERE inserted_at ? AND id ?可以利用索引进行高效的范围查找数据库无需遍历和跳过任何无关记录。无论你要获取“下一页”还是“上一千页”查询成本几乎是恒定的只和每页的大小LIMIT有关。一致性保证因为查询锚定在具体的数据值上在两次查询之间无论之前的数据如何增删都不会影响“下一页”查询的结果集。你总是能稳定地获取到游标之后的那一批数据不会重复也不会丢失。注意游标分页的“代价”是你无法直接跳转到任意页码比如“跳到第100页”。但这对于无限滚动的Feed流、API的分页令牌next_token模式来说恰恰是优点而非缺点。2.3 Paginator 的设计哲学paginator库聪明地将这一套机制集成到了 Ecto 的查询生态中。它没有重新发明轮子而是通过扩展Repo模块增加了一个paginate/2函数。你的所有查询逻辑、where条件、join操作都保持不变只需要在最后调用paginate并指定游标字段和分页方向即可。它负责自动生成复杂的游标WHERE子句、处理边界条件、并返回一个包含数据条目和分页元数据前后游标、是否还有更多数据的结构化结果。这种“最小侵入”的设计让它在现有项目中集成起来异常顺畅。3. 从零开始在项目中集成与配置 Paginator理论讲透了我们来看实战。将paginator集成到你的 Elixir Phoenix 或纯 Ecto 项目中步骤非常清晰。3.1 安装与基础配置首先在mix.exs文件的deps函数中添加依赖。建议使用最新的稳定版本你可以去 Hex.pm 查看。def deps do [ {:paginator, ~ 1.2.0} ] end然后运行mix deps.get获取依赖。接下来在你的 Repo 模块中启用它。这通常位于lib/my_app/repo.exdefmodule MyApp.Repo do use Ecto.Repo, otp_app: :my_app, adapter: Ecto.Adapters.Postgres # 添加这一行 use Paginator end就这么简单。现在你的MyApp.Repo模块就拥有了paginate/2函数。这里有一个关键的实操心得确保你的数据库适配器是 PostgreSQL。虽然从原理上讲游标分页适用于任何支持索引和范围查询的数据库但截至我写这篇文章时paginator的官方测试和社区实践主要围绕 PostgreSQL。如果你在使用 MySQL 或其他数据库需要仔细测试因为查询语句的生成可能有所不同。3.2 第一个分页查询理解核心参数让我们从一个最简单的例子开始假设我们有一个posts表有id,title,inserted_at字段。# 1. 构建基础查询。注意ORDER BY 是必须的 query from(p in Post, order_by: [asc: p.inserted_at, asc: p.id]) # 2. 执行分页查询 page_result MyApp.Repo.paginate( query, cursor_fields: [:inserted_at, :id], # 指定游标字段 limit: 10 # 指定每页大小 ) # 3. 解析结果 %Paginator.Page{ entries: entries, # 当前页的数据列表这里是10篇Post metadata: metadata } page_result # metadata 结构如下 # %Paginator.Metadata{ # after: after_cursor, # 用于获取下一页的游标可能为nil # before: before_cursor,# 用于获取上一页的游标可能为nil # limit: 10, # 你设置的limit # total_count: nil # 默认不计算总数 # } IO.inspect(entries)核心参数解析cursor_fields:这是最重要的参数。它定义了游标的构成。它必须是一个列表元素可以是原子如:id表示默认升序也可以是元组{:field_name, :asc | :desc}来明确指定排序方向。关键原则这个列表定义的顺序和方向必须与你查询中order_by子句的顺序完全一致并且组合起来必须能唯一确定一条记录。通常的做法是使用时间戳字段inserted_at,updated_at加上主键id。limit: 每页返回的记录数。after: 一个不透明的游标字符串表示“从这个游标之后开始获取”。通常来自上一页结果的metadata.after。before: 一个不透明的游标字符串表示“从这个游标之前开始获取”。通常来自当前页结果的metadata.before用于实现“上一页”功能。include_total_count: 如果设置为truepaginator会额外执行一条SELECT COUNT(*)查询并将总数填入metadata.total_count。慎用此选项因为在超大表上执行COUNT(*)可能非常慢。很多API设计如Twitter、Facebook已经不返回总条数了只提供“是否有更多”的指示。3.3 实现完整的前后翻页流程理解了单次查询后我们模拟一个完整的API分页流程defmodule MyApp.PostController do use MyAppWeb, :controller def index(conn, params) do base_query from(p in Post, where: p.published true, order_by: [desc: p.published_at, asc: p.id]) # 从请求参数中获取游标和每页大小 cursor_after params[after] cursor_before params[before] page_size String.to_integer(params[page_size] || 20) # 构建分页选项 pagination_opts [ cursor_fields: [{:published_at, :desc}, :id], limit: page_size ] # 根据请求决定是向前翻还是向后翻 pagination_opts case {cursor_after, cursor_before} do {nil, nil} - pagination_opts # 第一页 {after_val, nil} - Keyword.put(pagination_opts, :after, after_val) {nil, before_val} - Keyword.put(pagination_opts, :before, before_val) # 通常 after 和 before 不会同时存在 end # 执行分页 %{entries: posts, metadata: metadata} MyApp.Repo.paginate(base_query, pagination_opts) # 构造API响应 json_data %{ data: Enum.map(posts, post_json/1), paging: %{ cursors: %{ before: metadata.before, after: metadata.after }, # 一个简单的指示是否还有更多数据 has_more: not is_nil(metadata.after) } } json(conn, json_data) end defp post_json(post) do %{id: post.id, title: post.title, published_at: post.published_at} end end这个例子展示了如何将paginator集成到 Web 控制器中。API 客户端第一次调用时不带游标获取第一页。响应中的paging.cursors.after就是下一页的“钥匙”。客户端下次请求时带上?afterxxxxx参数即可获取下一页。has_more字段可以方便前端判断是否显示“加载更多”按钮。4. 高级用法与实战技巧基础用法能解决80%的问题但paginator的真正威力在于它能处理复杂场景。下面分享几个我在实际项目中用到的进阶技巧。4.1 处理动态计算字段如搜索排名这是paginator一个非常强大的特性。假设我们有一个全文搜索功能需要根据ts_rank函数计算的相关性分数进行排序。这个分数不是数据库的静态字段而是动态计算出来的。paginator通过fetch_cursor_value_fun和cursor_fields中的函数选项来支持这一点。def search_posts(search_term, cursor \\ nil, limit \\ 20) do # 基础查询使用 PostgreSQL 全文搜索 base_query from(p in Post, where: fragment(to_tsvector(english, content) plainto_tsquery(english, ?), ^search_term), # 注意order_by 必须和 cursor_fields 定义的逻辑匹配 order_by: [ desc: fragment(ts_rank(to_tsvector(english, content), plainto_tsquery(english, ?)), ^search_term), desc: p.id # 用 id 作为第二排序字段保证唯一性 ] ) # 定义如何从结果行中提取游标值 fetch_fun fn # 当字段是 :rank 时我们执行一个子查询来计算该行的准确分数 schema, :rank - {:ok, %{rows: [[rank_value]]}} MyApp.Repo.query( SELECT ts_rank(to_tsvector(english, $1), plainto_tsquery(english, $2)), [schema.content, search_term] ) rank_value # 对于其他字段如 :id使用库提供的默认方法 schema, field - Paginator.default_fetch_cursor_value(schema, field) end # 定义游标字段其中 :rank 字段由一个动态表达式生成 cursor_fields [ {:rank, fn - # 这个动态表达式用于在 WHERE 条件中构造 rank 的比较逻辑 dynamic( [p], fragment(ts_rank(to_tsvector(english, ?), plainto_tsquery(english, ?)), p.content, ^search_term) ) end}, {:id, :desc} ] opts [cursor_fields: cursor_fields, limit: limit, fetch_cursor_value_fun: fetch_fun] opts if cursor, do: Keyword.put(opts, :after, cursor), else: opts MyApp.Repo.paginate(base_query, opts) end这个例子有点复杂但原理很清晰fetch_cursor_value_fun: 当paginator需要为当前页的最后一条记录生成游标时它会调用这个函数。对于动态字段:rank我们手动执行一个查询来计算其精确值对于:id则用库函数。cursor_fields中的函数当用户传递一个游标来查询“下一页”时paginator需要根据这个游标值构造WHERE条件。对于:rank字段它使用我们提供的匿名函数来生成一个 Ecto 动态查询dynamic这个查询片段会最终被转换成 SQL 的WHERE ts_rank(...) ?条件。实操心得这种动态字段的支持非常强大可以用于按复杂表达式、聚合函数结果甚至是关联子查询的结果进行分页。但代价是增加了查询的复杂度。务必为这些计算字段和主键字段建立复合索引否则性能会退化。4.2 多表关联查询的分页分页关联查询需要格外小心。一个常见的需求是分页获取文章列表并预加载每条文章的评论数和作者信息。query from(p in Post, left_join: c in assoc(p, :comments), left_join: a in assoc(p, :author), group_by: [p.id, a.id], select: %{ post: p, comment_count: count(c.id), author_name: a.name }, order_by: [desc: max(p.published_at), asc: p.id] # 注意聚合函数后的排序 ) # 错误的游标字段定义直接使用 p.published_at # cursor_fields: [{:published_at, :desc}, :id] # 这会导致错误因为SELECT里没有单独的p.published_at # 正确的游标字段定义需要与SELECT和ORDER BY匹配 cursor_fields [ {:published_at, fn - # 由于我们在order_by中使用了 max(p.published_at)这里也需要对应 dynamic([p], max(p.published_at)) end}, :id ] page Repo.paginate(query, cursor_fields: cursor_fields, limit: 15)关键点当查询中包含group_by、聚合函数或复杂的select映射时你的cursor_fields定义必须能够被正确地映射到最终的查询结果上。通常这意味着你需要像处理动态字段一样为那些在select中不是简单字段引用的排序项提供函数定义。同时确保order_by子句使用的表达式与cursor_fields定义的逻辑完全一致。4.3 索引策略为性能保驾护航游标分页的性能优势完全建立在索引之上。没有正确的索引它甚至可能比OFFSET更慢。黄金法则为cursor_fields中定义的所有字段组合创建一个复合索引并且索引的列顺序、排序方向必须与cursor_fields完全一致。对于我们的经典例子cursor_fields: [:inserted_at, :id]-- 在迁移文件中 CREATE INDEX posts_inserted_at_id_index ON posts (inserted_at, id);如果你的排序是降序的例如cursor_fields: [{:published_at, :desc}, :id]在 PostgreSQL 中你可以创建降序索引以获得最佳性能CREATE INDEX posts_published_at_desc_id_index ON posts (published_at DESC, id ASC);踩坑记录我曾经在一个项目中没有为游标字段创建索引当数据量达到几十万时分页查询突然变得非常慢。使用EXPLAIN ANALYZE分析查询计划后发现数据库在进行全表扫描和文件排序filesort。加上复合索引后查询时间从几百毫秒降到了几毫秒。这是一个必须进行的优化步骤。5. 常见问题、排查技巧与安全须知即使理解了原理在实际使用中还是会遇到各种问题。下面是我总结的一些常见坑点和解决方案。5.1 错误与异常排查问题现象可能原因解决方案** (ArgumentError) cursor fields must be a listcursor_fields参数格式错误可能传入了非列表值。检查cursor_fields是否是一个列表如[:id]或[{:created_at, :desc}, :id]。** (ArgumentError) order_by must be specified on the query传入paginate/2的 Ecto 查询没有指定order_by子句。游标分页必须有确定的排序。在调用paginate前确保你的查询包含了order_by。** (Postgrex.Error) ERROR 42703 (undefined column)游标字段在生成的 SQL 的 WHERE 或 SELECT 子句中不存在。1. 检查cursor_fields中的字段名是否拼写正确且存在于查询的源表中。2. 如果是关联查询或复杂 SELECT确保字段在上下文中可用可能需要使用as/1或修改select语句。分页结果出现重复或丢失记录1.cursor_fields的组合不能唯一确定一行。2. 数据在分页过程中被修改且排序字段被更新。1.确保游标字段组合是唯一的。最稳妥的做法是始终包含主键id作为最后一个游标字段。2. 避免使用如updated_at这种可能被频繁更新的字段作为唯一或主要的排序字段。如果必须用确保业务逻辑能处理这种边界情况。使用after游标返回空结果但应该还有数据游标值可能已损坏或来自不同的查询/排序条件。游标是与特定查询和cursor_fields定义绑定的。切勿将一个查询生成的游标用于另一个排序或条件不同的查询。每次分页都应使用相同的底层查询和cursor_fields。5.2 安全考量防止游标注入paginator在设计上考虑了安全性。游标是一个不透明的字符串通常是 Base64 编码的结构化数据。库内部会对其进行解码和验证。重要的是你不应该手动构造或修改游标值。Repo.paginate/4函数内部会检查传入的:before和:after参数如果检测到其中包含可执行代码Elixir 函数或原子它会主动抛出一个ArgumentError。这有效防止了潜在的“游标注入”攻击即攻击者通过伪造恶意的游标字符串来尝试执行任意代码。作为开发者你需要做的就是从metadata中获取游标并原封不动地传递给下一次paginate调用。不要尝试解析或生成它。5.3 性能监控与调试对于关键的分页查询建议进行监控。日志Ecto 的日志会输出paginate生成的最终 SQL。仔细查看WHERE子句确认它是否正确使用了游标条件如WHERE (created_at, id) (?, ?)并且没有额外的全表扫描。EXPLAIN ANALYZE如果发现某次分页查询变慢可以将paginate调用前的查询取出手动加上limit并用Repo.query(“EXPLAIN ANALYZE …”)执行查看查询计划确认是否使用了正确的索引。游标字段选择尽量选择单调递增且不常更新的字段作为主游标字段如自增ID、创建时间。使用updated_at需要谨慎因为记录更新会导致它在排序中的位置发生变化可能影响分页连续性。5.4 与 Phoenix 框架的深度集成在 Phoenix 项目中你可以创建一个通用的分页辅助函数用于规范控制器中的分页逻辑和响应格式。# lib/my_app_web/controllers/pagination_helpers.ex defmodule MyAppWeb.PaginationHelpers do import Plug.Conn def paginate_params(conn) do %{ after conn.params[after], before conn.params[before], page_size conn.params[page_size] || 25 } end def build_pagination_links(conn, metadata, base_path) do links %{} if metadata.before do links Map.put(links, :prev, build_url(conn, base_path, metadata.before, nil, metadata.limit)) end if metadata.after do links Map.put(links, :next, build_url(conn, base_path, nil, metadata.after, metadata.limit)) end links end defp build_url(conn, base_path, before_cursor, after_cursor, limit) do query_params %{page_size limit} query_params if before_cursor, do: Map.put(query_params, before, before_cursor), else: query_params query_params if after_cursor, do: Map.put(query_params, after, after_cursor), else: query_params MyAppWeb.Router.Helpers.url(conn) base_path ? URI.encode_query(query_params) end end然后在控制器中这样使用def index(conn, params) do pagination_params PaginationHelpers.paginate_params(conn) base_query from(Item, order_by: [desc: :inserted_at, asc: :id]) opts [ cursor_fields: [{:inserted_at, :desc}, :id], limit: String.to_integer(pagination_params[page_size]) ] | maybe_put_cursor(:after, pagination_params[after]) | maybe_put_cursor(:before, pagination_params[before]) %{entries: items, metadata: metadata} Repo.paginate(base_query, opts) links PaginationHelpers.build_pagination_links(conn, metadata, ~p/api/items) render(conn, :index, items: items, links: links) end defp maybe_put_cursor(opts, _key, nil), do: opts defp maybe_put_cursor(opts, key, value), do: Keyword.put(opts, key, value)这样你的 API 就能返回符合 HATEOAS 风格的、包含明确next和prev链接的分页响应了客户端无需自己拼接 URL体验更好。6. 总结与最佳实践提炼经过几个项目的深度使用duffelhq/paginator已经成为了我 Elixir 技术栈中处理分页的首选工具。它不仅仅是一个库更是一种最佳实践的体现。最后再分享几条凝结了实际教训的终极建议始终使用复合索引这是游标分页性能的基石。索引顺序务必与cursor_fields完全一致。上线前用真实数据量测试分页查询的执行计划。游标字段必须唯一且稳定最通用的模式是[排序时间字段, 主键ID]。时间字段决定大致顺序主键ID解决同一时间戳下的唯一性问题。避免使用可能被更新的字段作为唯一排序依据。不要暴露内部游标结构虽然游标是 Base64 编码的但不要依赖其结构。视其为不透明的令牌。这保证了后端排序逻辑变更比如从created_at改为updated_at时不会破坏已发出的客户端游标当然逻辑变更后旧游标会失效这是另一个需要处理的问题。在 API 设计中拥抱游标模式放弃“总页数”和“跳转到第N页”的概念。设计 API 时只返回data、next_cursor和has_more或prev_cursor。这更符合现代无限滚动和高效数据获取的理念。复杂查询先测试对于包含多表关联、聚合、复杂WHERE条件的查询先在开发环境用IO.inspect(Repo.to_sql(:all, query))打印出paginate前查询的 SQL确保其正确性。然后再进行分页并检查生成的最终 SQL 是否高效。游标分页是一个“想清楚了就一劳永逸”的基础设施。初期投入一点学习成本换来的是应用在数据增长时依然保持的丝滑性能。paginator库用简洁的 API 封装了所有复杂细节让开发者可以专注于业务逻辑这正是 Elixir 生态中优秀库的特质。
