1. 项目概述为什么我们需要游标分页在构建现代Web应用尤其是涉及大量数据列表展示的后台管理系统或内容平台时分页是一个绕不开的核心功能。传统的分页方案比如我们最熟悉的LIMIT offset, size例如LIMIT 20, 10获取第3页的10条数据在数据量小的时候工作得很好。但随着数据量的增长尤其是在处理百万、千万级数据表时这种基于偏移量的分页会暴露出严重的性能问题。想象一下你要从一本1000页的书里翻到第999页。基于偏移量的做法是先数出前面998页的所有行数然后从那个位置开始读。数据库做LIMIT 9990, 10时也是类似的逻辑它需要先扫描并跳过前面的9990条记录才能找到第9991条记录开始的位置。当offset值非常大时这个“跳过”的操作会消耗大量的I/O和CPU资源导致查询越来越慢甚至可能拖垮数据库。这就是游标分页Cursor-based Pagination登场的时候了。它不再依赖不稳定的“页码”和“偏移量”而是依赖一个稳定、唯一的“游标”Cursor。这个游标通常是你数据表中的一个或多个有序且唯一的字段组合比如自增ID、创建时间戳或者是“姓氏名字”这样的复合键。客户端在请求下一页时不再说“我要第几页”而是说“我要上一页最后一条记录之后的数据”。数据库可以利用索引直接定位到游标指向的位置然后高效地读取后续的LIMIT条数据完全避免了“跳过”大量记录的开销。drizzle-cursor这个库就是专门为当下非常流行的 TypeScript ORM ——drizzle-orm量身打造的游标分页工具。它封装了生成游标条件、排序逻辑以及游标序列化/反序列化的复杂细节让你能用几行清晰的代码就为你的 Drizzle 查询加上高性能的游标分页能力。无论你的业务是需要单游标如按ID分页还是需要复杂的多列游标如按时间、状态、姓名等多字段组合分页它都能优雅地支持。2. 核心概念与设计思路拆解在深入代码之前我们必须先厘清游标分页的几个核心概念以及drizzle-cursor是如何围绕这些概念进行设计的。理解这些能帮助你在未来面对更复杂的分页场景时做出正确的决策。2.1 游标的本质一个稳定的定位点游标不是一个魔法字符串它的本质是一个或多个数据字段的值这些字段的组合必须能唯一且稳定地标识一条记录在排序序列中的位置。唯一性这是最重要的。如果游标不唯一那么“某个游标之后”这个条件就会变得模糊可能导致重复或丢失数据。最经典的唯一游标就是自增主键id。稳定性游标所基于的字段值在记录的生命周期内不应该改变。如果一条记录的“更新时间”字段因为某次更新而改变那么以它作为游标的一部分时这条记录在排序序列中的位置就可能“跳动”导致分页出现重复或遗漏。因此通常选择createdAt创建时间而非updatedAt更新时间作为时间游标。有序性游标字段必须是有序的这样我们才能定义“之前”和“之后”。数字、时间戳、按字母排序的字符串都满足这个条件。drizzle-cursor的设计正是基于此。它要求你明确指定一个primaryCursor主游标通常是主键和可选的多个cursors辅助游标。主游标保证了最基本的唯一性定位而辅助游标则用于定义更精细、更符合业务需求的排序规则。2.2 多列游标与排序规则的协同为什么需要多个游标考虑一个用户列表业务需求是“先按姓氏lastName升序同姓的再按名字firstName升序同名的再按ID升序”来分页。如果只使用ID作为游标虽然能分页但无法维持“姓氏-名字”这个业务排序。当你在第1页末尾假设是“张三ID:100”请求第2页时数据库需要找到所有“姓氏‘张’ AND 名字‘三’”的记录这依然可能是一个低效的全表扫描。drizzle-cursor的解决方案是让你将整个排序规则“编码”进游标。你定义的cursors数组顺序直接对应了SQLORDER BY子句的顺序。在生成下一页的WHERE条件时它会构建一个复杂的、但能被索引高效利用的复合条件。例如对于上述场景它会生成类似这样的SQL-- 假设上一页最后一条记录是 (lastName张, firstName三, id100) WHERE (lastName 张) OR (lastName 张 AND firstName 三) OR (lastName 张 AND firstName 三 AND id 100) ORDER BY lastName ASC, firstName ASC, id ASC LIMIT 10;这个WHERE条件可以被(lastName, firstName, id)上的复合索引完美支持查询效率极高。drizzle-cursor的强大之处就在于它自动为你构建了这个逻辑上正确、性能上优化的条件。2.3 序列化与安全性游标令牌Cursor Token直接将包含敏感数据如用户ID、邮箱的记录对象作为游标暴露给前端例如放在URL参数中是不安全的也显得臃肿。drizzle-cursor提供了serialize和parse方法。serialize: 将游标对象例如{lastName: ‘张’ firstName: ‘三’ id: 100}编码成一个紧凑的、不透明的字符串令牌Token。这个令牌通常是Base64编码的JSON或类似结构对客户端是安全的。parse: 将令牌字符串解码回游标对象用于服务端下一次查询。这个设计实现了前后端解耦。前端只需要存储和传递这个令牌字符串无需理解其内部结构。服务端通过cursor.where(token)就能直接使用非常简洁。注意虽然令牌本身不直接暴露数据但它是可解码的。如果游标字段包含敏感信息你需要在序列化前进行加密或哈希处理。drizzle-cursor提供了基础的序列化更复杂的安全需求需要你自行在业务层处理。3. 从零开始安装与基础配置理论铺垫完毕现在让我们动手将一个普通的 Drizzle 查询改造成支持游标分页。3.1 环境准备与安装首先确保你有一个使用 Drizzle ORM 的 TypeScript 项目。然后通过 npm 或你喜欢的包管理器安装drizzle-cursornpm install drizzle-cursor # 或 yarn add drizzle-cursor # 或 pnpm add drizzle-cursor这个库的 TypeScript 类型定义非常完善建议你同时查看其 TSDocs 文档这对于理解各种配置选项和泛型参数非常有帮助。3.2 定义数据模型与游标配置假设我们有一个users表其 Drizzle 模式定义如下// schema.ts import { pgTable, serial, varchar, timestamp } from drizzle-orm/pg-core; export const users pgTable(users, { id: serial(id).primaryKey(), lastName: varchar(last_name, { length: 100 }).notNull(), firstName: varchar(first_name, { length: 100 }).notNull(), email: varchar(email, { length: 255 }).notNull().unique(), createdAt: timestamp(created_at).defaultNow().notNull(), updatedAt: timestamp(updated_at).defaultNow().notNull(), });我们的分页需求是用户列表默认按注册时间倒序排列最新注册的在前对于同一时间注册的用户再按ID升序排列以保证顺序稳定。根据这个需求我们来创建游标配置// cursor-config.ts import { generateCursor } from drizzle-cursor; import { users } from ./schema; const cursorConfig { // 主游标必须是唯一且稳定的字段。这里使用自增ID它完美满足条件。 primaryCursor: { order: ASC, // ID本身是升序的这里保持ASC。注意主游标的排序方向会影响多列游标组合条件的生成逻辑。 key: id, // 在游标对象中的属性名 schema: users.id, // Drizzle 的列定义 }, // 辅助游标数组定义了主要的业务排序规则。 cursors: [ { order: DESC, // 注册时间倒序最新的在前 key: createdAt, // 在游标对象中的属性名 schema: users.createdAt, // Drizzle 的列定义 }, // 注意虽然主游标是id但为了确保createdAt相同时的顺序我们也可以把id放在cursors里。 // 但更常见的做法是只用业务字段做cursors用primaryCursor做最终唯一性保障。 // 这里我们选择不重复添加id到cursors因为primaryCursor已经起到了唯一排序作用。 ], } as const; // 使用 as const 获得最精确的类型推断 // 生成游标工具函数 export const userCursor generateCursor(cursorConfig);关键配置解析primaryCursor(主游标)这是分页的“定海神针”。它必须是一个绝对唯一的字段通常是你的主键PRIMARY KEY。它的作用是当所有辅助游标字段的值都相等时用它来做最终裁决确保每一条记录都有一个独一无二的位置。order属性需要根据该字段的实际索引顺序设置。cursors(辅助游标数组)这里的顺序就是ORDER BY的顺序。drizzle-cursor会严格按照这个数组的顺序来构建排序和查询条件。order属性决定了该字段的排序方向ASC升序DESC降序。key与schemakey是你希望在游标对象及最终查询结果中使用的属性名。schema是 Drizzle 的列对象用于类型检查和生成正确的SQL。重要警告官方文档强烈建议不要使用可为空Nullable的列作为游标。因为不同数据库如 PostgreSQL, MySQL对NULL值的排序处理不一致NULLS FIRST还是NULLS LAST这会导致分页行为不可预测极易出现数据重复或丢失。如果你的业务字段可能为空考虑使用一个非空的默认值如空字符串或一个特定日期或者重新设计你的排序逻辑。4. 实战在查询中集成游标分页有了配置好的userCursor我们就可以在数据查询中使用它了。drizzle-cursor完美适配 Drizzle 的两种主要查询方式db.select()和db.query。4.1 使用db.select()进行分页查询这是最直接的方式。userCursor提供了两个核心属性/方法.orderBy: 一个数组可以直接展开 (...cursor.orderBy) 传递到 Drizzle 查询的.orderBy()方法中。.where(): 一个函数它接收一个“上一条记录”对象或游标令牌并返回 Drizzle 的where条件。第一次查询时调用.where()不传参数表示从最开始获取。获取第一页数据import { db } from ./db; import { userCursor } from ./cursor-config; const PAGE_SIZE 20; async function getFirstPage() { const firstPage await db .select({ // 必须选择所有在游标配置中定义的字段 id: users.id, createdAt: users.createdAt, // 以及其他你需要的业务字段 lastName: users.lastName, firstName: users.firstName, email: users.email, }) .from(users) .orderBy(...userCursor.orderBy) // 应用排序规则 .where(userCursor.where()) // 第一次调用不传参获取起始位置 .limit(PAGE_SIZE); // 为下一页准备游标令牌 const lastItem firstPage[firstPage.length - 1]; let nextCursorToken: string | null null; if (lastItem) { nextCursorToken userCursor.serialize(lastItem); } return { items: firstPage, nextCursor: nextCursorToken, // 如果为null说明没有下一页了 }; }获取下一页数据当客户端携带上一页返回的nextCursor令牌请求下一页时async function getNextPage(cursorToken: string) { const nextPage await db .select({ id: users.id, createdAt: users.createdAt, lastName: users.lastName, firstName: users.firstName, email: users.email, }) .from(users) .orderBy(...userCursor.orderBy) // 排序规则必须始终一致 .where(userCursor.where(cursorToken)) // 传入游标令牌定位起始点 .limit(PAGE_SIZE); const lastItem nextPage[nextPage.length - 1]; let newNextCursor: string | null null; if (lastItem) { newNextCursor userCursor.serialize(lastItem); } return { items: nextPage, nextCursor: newNextCursor, }; }4.2 使用db.query进行关系型分页查询drizzle-cursor同样支持 Drizzle 的关系查询 API (db.query)这在需要联表查询时非常方便。async function getUsersWithPosts(cursorToken?: string) { const result await db.query.users.findMany({ // 选择列必须包含所有游标字段 columns: { id: true, createdAt: true, lastName: true, firstName: true, email: true, }, // 关联数据 with: { posts: { columns: { id: true, title: true }, limit: 5, // 每个用户只取最近5篇文章 }, }, // 应用游标分页 orderBy: userCursor.orderBy, // 注意这里不需要展开 ... where: cursorToken ? userCursor.where(cursorToken) : undefined, limit: PAGE_SIZE, }); // ... 处理结果和生成下一个游标 return result; }使用db.query时的关键细节orderBy: 直接传递userCursor.orderBy数组即可不需要展开操作符...。where:userCursor.where()返回的条件可以直接赋值。列选择警告使用columns对象筛选列时务必确保所有在primaryCursor和cursors中定义的字段都被包含在内例如id: true, createdAt: true。如果漏掉serialize函数将无法从结果对象中提取完整的游标信息导致下一页查询失败。这是一个非常容易踩的坑。4.3 处理边界情况与响应格式一个健壮的分页API还需要考虑一些边界情况空结果集与游标当查询结果为空时nextCursor应为null。最后一页当返回的结果数量小于PAGE_SIZE时意味着当前页是最后一页应将nextCursor设置为null告知客户端没有更多数据。统一的API响应设计一个统一的响应结构例如interface PaginatedResponseT { items: T[]; nextCursor: string | null; // 下一页的游标令牌null表示无下一页 hasMore: boolean; // 一个方便前端判断的布尔值 }在服务端hasMore可以简单地由items.length PAGE_SIZE来判断。5. 高级用法与性能优化指南掌握了基础用法后我们来看看如何应对更复杂的场景并确保分页查询始终保持高性能。5.1 构建复杂的多列游标假设有一个任务列表需要先按优先级priority降序高优先级在前再按截止日期dueDate升序快过期的在前最后按任务IDid升序分页。const taskCursorConfig { primaryCursor: { order: ASC, key: id, schema: tasks.id }, cursors: [ { order: DESC, key: priority, schema: tasks.priority }, // 高优先级在前 { order: ASC, key: dueDate, schema: tasks.dueDate }, // 早截止在前 // 注意如果 priority 和 dueDate 可能同时相同primaryCursor (id) 会确保顺序唯一 ], } as const;背后的SQL逻辑drizzle-cursor为这个配置生成的WHERE条件会非常精细-- 假设上一页最后一条记录是 (priority2, dueDate2023-10-27, id105) WHERE (priority 2) OR (priority 2 AND dueDate 2023-10-27) OR (priority 2 AND dueDate 2023-10-27 AND id 105) ORDER BY priority DESC, dueDate ASC, id ASC5.2 结合动态WHERE条件进行过滤业务中经常需要在分页的同时进行过滤例如“只查看某个用户的高优先级任务”。drizzle-cursor生成的where条件可以与其他where条件安全地组合。import { and, eq } from drizzle-orm; async function getUserHighPriorityTasks(userId: number, cursorToken?: string) { const baseCondition eq(tasks.assigneeId, userId); const cursorCondition cursorToken ? taskCursor.where(cursorToken) : undefined; const whereClause cursorCondition ? and(baseCondition, cursorCondition) // 使用 and 合并条件 : baseCondition; const result await db .select() .from(tasks) .where(whereClause) .orderBy(...taskCursor.orderBy) .limit(PAGE_SIZE); return result; }关键点使用 Drizzle 的and()或or()函数来组合条件。drizzle-cursor返回的条件本身就是一个 Drizzle SQL 条件对象可以无缝集成。5.3 索引策略让游标分页飞起来游标分页的性能优势完全建立在索引之上。如果没有合适的索引数据库将被迫进行全表扫描性能甚至可能差于偏移分页。索引设计黄金法则为你的ORDER BY子句创建复合索引。对于上面(priority DESC, dueDate ASC, id ASC)的排序在 PostgreSQL 中你可以创建索引CREATE INDEX idx_tasks_cursor ON tasks (priority DESC, dueDate ASC, id ASC);在 MySQL 中索引定义类似但需要注意 MySQL 8.0 才完全支持降序索引CREATE INDEX idx_tasks_cursor ON tasks (priority DESC, dueDate, id);(对于ASC字段可以省略ASC)。如何验证索引是否生效使用数据库的EXPLAIN或EXPLAIN ANALYZE命令来查看查询计划。一个高效的游标分页查询应该显示使用了你创建的复合索引进行“索引范围扫描”Index Range Scan而不是“全表扫描”Full Table Scan或“文件排序”Filesort。5.4 反向分页与“上一页”的实现游标分页天然是单向的向前。实现“上一页”功能需要一些技巧。常见的方案有两种客户端存储历史游标客户端在浏览过程中将每一页的“起始游标”即上一页的nextCursor对于第一页是一个空值存储下来例如在内存或Session中。当需要返回上一页时客户端将存储的“起始游标”发给服务端服务端用这个游标作为起点但排序方向需要反转。注意反转排序后取到的数据顺序是反的需要在服务端或客户端再次反转才能正确显示。drizzle-cursor本身不直接支持反向排序你需要创建另一套order: DESC的游标配置来处理。基于偏移量的模拟不推荐用于大数据集对于需要频繁跳转的界面如第5页跳第3页游标分页并不适合。如果业务强需求如此可以考虑在游标分页为主的基础上对前N页比如前1000条辅以缓存或偏移量查询。但这会显著增加系统复杂度。6. 常见问题、陷阱与排查实录在实际使用中我遇到了不少坑。这里记录下最常见的问题和解决方法希望能帮你节省大量调试时间。6.1 数据重复或丢失这是游标分页最致命的问题通常由以下原因导致游标字段值变更如果游标字段如updatedAt在分页过程中被更新记录的位置就会改变。当请求下一页时这条记录可能因为值变大/变小而再次出现或永远消失。解决使用不可变或很少变更的字段作为游标如id,createdAt。并发写入在分页查询的间隙如果有新数据插入到当前页之前的位置会导致后续分页出现重复新插入的数据被挤到后面如果有数据删除可能导致记录丢失跳过了本应属于下一页的数据。解决对于数据一致性要求极高的场景需要在事务隔离级别如REPEATABLE READ下进行查询或者使用基于时间点的快照。但这对性能有影响需要权衡。排序不稳定当游标字段组合不能唯一确定一条记录的位置时例如仅用createdAt分页但同一毫秒创建了多条记录这些记录的相对顺序在多次查询中可能不一致导致分页错乱。解决务必确保primaryCursor是一个绝对唯一的字段如主键。这样即使前面的cursors字段全部相同最终顺序也能由primaryCursor稳定决定。6.2 “Invalid Cursor” 或序列化错误现象调用cursor.parse(token)或cursor.where(token)时抛出错误。原因1游标令牌被篡改或损坏。排查检查令牌在传输过程中是否被正确编码/解码如URL编码问题。确保使用cursor.serialize()生成令牌并原样传递。原因2查询结果中缺少游标字段。排查这是最最常见的原因请再次检查你的db.select(...)或columns: {...}是否包含了游标配置中primaryCursor和所有cursors里定义的每一个字段。缺少任何一个字段serialize都会失败。原因3游标字段值为null或undefined。排查如前所述避免使用可为空的列作为游标。如果业务必须确保查询时该字段有值例如使用COALESCE设置默认值并且序列化/反序列化能处理null。6.3 查询性能没有提升现象使用了游标分页但查询速度依然很慢EXPLAIN显示没有用到索引。原因1没有为游标排序字段创建复合索引。解决立即为(cursor1_field, cursor2_field, ..., primary_cursor_field)创建索引排序方向与游标配置中的order一致。原因2WHERE条件中的其他过滤条件与索引前缀不匹配导致索引失效。解决调整索引顺序将最常用的等值过滤字段放在复合索引的最前面。例如如果总是按status active过滤那么索引应该是(status, cursor1_field, cursor2_field, primary_cursor_field)。原因3使用了函数或表达式操作游标字段。解决确保WHERE条件中直接使用列名而不是DATE(created_at)或UPPER(name)这样的表达式这会使索引失效。6.4 在联合查询或复杂子查询中的使用drizzle-cursor目前主要设计用于单表查询或 Drizzle 的关系查询 (db.query...with)。如果你需要在复杂的原生SQL联表查询中使用游标分页过程会变得繁琐。你需要确保子查询或联表结果中包含所有游标字段。手动将cursor.where()生成的SQL条件拼接到你的查询的WHERE子句中。手动将cursor.orderBy对应的排序字段拼接到ORDER BY子句。这要求你对drizzle-cursor生成的SQL有较深的理解并且失去了部分类型安全的好处。对于极度复杂的查询评估是否值得为了分页而重构查询或者考虑其他分页方案。7. 总结与个人实践心得经过在多个生产项目中实践drizzle-cursor我的体会是它极大地简化了在 Drizzle 生态中实现高性能分页的复杂度。它抽象得当接口清晰类型安全优秀。一旦你理解了游标分页的核心思想并正确配置它就能稳定可靠地工作。我个人最看重的一点是它强制我思考数据的排序逻辑和唯一性这本身就是一个良好的数据建模实践。它暴露了传统偏移分页的性能隐患推动团队在项目早期就关注大数据量下的列表性能。最后分享一个小心得在API设计上我倾向于同时返回nextCursor和一个hasMore布尔值。hasMore让前端UI可以简单地决定是否显示“加载更多”按钮而nextCursor则用于实际的下一页请求。两者结合既方便又清晰。游标分页是现代应用处理大数据列表的必备技能而drizzle-cursor是 Drizzle 用户手中一件非常趁手的工具。希望这篇详细的指南能帮助你顺利上手避开我当年踩过的那些坑。