深入 models_pagination:Macro 后端类型安全游标分页基础设施解析

原创2026-10-30 10:36:402,331 阅读
文章标签:企业应用协同办公后端前端即时通讯AI Agent人工智能CRM桌面应用MCP Clients

深入 models_pagination:Macro 后端类型安全游标分页基础设施解析

Macro 是一个把邮件、聊天、文档、任务、Agent、通话与 CRM 统一到同一个工作区的协作平台,几乎所有列表接口都需要分页。models_pagination 就是这个后端里被绝大多数列表端点复用的共享分页机件:它把「游标编码」「排序契约」「axum 查询提取」三件事收敛到一处,让业务 crate 只关心自己的 SQL 与排序语义。读完本文,你将掌握该 crate 的三支柱 trait 契约、游标的序列化格式、Query/Paginator 的完整调用链,并能独立为任意实体接入或扩展一种新的排序方式。

一、定位与边界:它是分页机件,不是业务查询

crates/models_pagination/AGENTS.md 对该 crate 的定位给出了非常明确的两条线:

  • 它拥有:游标编码(cursor encoding)、排序 trait 契约(sort trait contracts),以及面向列表端点的 axum 查询参数提取。
  • 它不拥有:某个具体实体的实际查询与排序实现——那属于领域 crate(例如 soup、messages)。

边界同样被写死:它不依赖任何领域类型,只依赖纯分页相关的基础库(base64、ordered-float,以及可选的 axum 与 model-error-response)。这一点从 Cargo.toml 可以直接印证:

[features]
axum = ["dep:axum", "dep:model-error-response", "serde_json/unbounded_depth"]
docs = [
] # adds the doc attrs, the reason this is a feature is because of JsonSchema

[dependencies]
axum = { workspace = true, optional = true }
base64 = { workspace = true }
chrono = { workspace = true }
either = { workspace = true }
model-error-response = { path = "../model-error-response", optional = true }
ordered-float = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }

按 AGENTS.md 的列表,models_pagination 被二十多个 crate 复用,包括 ai_tools、calendar_events、call、channels、complete_graph、databases_sql、email、email_db_client、foreign_entity、github_pull_requests、graphql_activity、graphql_calendar、graphql_initiative、graphql_soup、macro_db_client、messages、model、model_notifications、models_email、models_soup、notification、notification_db_client、skills、soup、teams。

这种「机件下沉、语义上浮」的划分带来两个直接收益:分页协议的序列化格式在整个后端是统一的;新增实体时只需实现三个 trait,而不必重新发明一套 limit/offset 约定。

二、目录地图与阅读顺序

AGENTS.md 给出了「Start here」的入口清单,对应的真实文件如下:

文件 内容 作用
src/lib.rs crate 文档与重导出 声明三支柱契约,统一 pub use
src/cursor.rs Identify、Sortable、SortOn、Paginate/Paginated、Base64Str、Query 分页核心机制
src/sort.rs CreatedAt、Frecency、NotifiedAt、TouchedByMe、SimpleSortMethod 具体排序方法
src/collections.rs CollectBy、CollectByIds 集合辅助扩展
src/axum.rs BidirectionalCursor、CursorExtractErr、CursorOptionExt HTTP 层游标提取(feature axum)

crate 根文档把设计前提写成了三条「支柱」(src/lib.rs),并且用 #![deny(missing_docs)] 强制所有公开项都必须带文档:

  1. Iterator::Item 必须实现 Identify,以便取出条目的唯一 id;
  2. 目标排序方式必须实现 Sortable,用来声明「按什么类型排序」,例如 DateTime<Utc>;
  3. Iterator::Item 必须针对目标 Sortable 实现 SortOn。

三、游标数据模型:Cursor、CursorVal 与 Base64 封装

3.1 Cursor 的四个字段

分页游标的定义在 src/cursor.rs:

pub struct Cursor<Id, C, F> {
    /// the unique id (e.g. i64, uuid, stc) that identifies the last entity
    /// on the previous page
    pub id: Id,
    /// the size of the previous page
    pub limit: usize,
    /// the value of the cursor
    /// this is usually a [CursorVal]
    pub val: C,
    /// the value we are filtering on
    pub filter: F,
}

四个字段各有明确职责:

  • id:上一页最后一条记录的主键,用于在排序值相同时做 tie-break(消除「同一时间戳元素顺序不稳定」导致的漏项/重复);
  • limit:上一页的页大小,服务端可以据此校验或复用分页规模;
  • val:排序维度信息,通常是一个 CursorVal;
  • filter:把过滤条件一并「烤」进游标,保证翻页时过滤语义不漂移。

由于 filter 是泛型参数,游标可以分化为两种常用形态(src/cursor.rs):

pub type CursorWithVal<Id, V> = Cursor<Id, CursorVal<V>, ()>;
pub type CursorWithValAndFilter<Id, V, F> = Cursor<Id, CursorVal<V>, F>;

同时提供了 map_filter,可以只替换过滤类型而保留其余字段(src/cursor.rs)。这在「HTTP 层收到的是一个宽松过滤器,领域层需要收紧成具体 AST」这类场景里非常实用——后文 soup 的 into_ast 就是典型用法。

3.2 CursorVal 与 Sortable

CursorVal 把「排序类型」和「该排序在上一页最后一项上的取值」打包在一起(src/cursor.rs):

pub struct CursorVal<C: Sortable> {
    /// the type that we are sorting on, must implement [Sortable]
    pub sort_type: C,
    /// the last value of the [Sortable] from the previous page
    pub last_val: C::Value,
}

pub trait Sortable: std::fmt::Debug {
    /// the value which we sort on e.g. Utc timestamp, float, etc
    type Value: std::fmt::Debug + std::cmp::Ord;
}

Sortable::Value 的约束是 Debug + Ord,这一点决定了整个设计的可用性:into_page 在需要本地兜底排序时,直接拿 last_val 作为排序键(见第五节)。把 sort_type 和 last_val 一起序列化,还带来一个重要的安全性收益:服务端可以从游标本身恢复排序方式,而不必信任客户端另外传的 sort 参数,因此翻页时不会出现「第一页按 created_at、第二页按 updated_at」的撕裂。

3.3 Base64Str:不透明游标的编码载体

客户端看到的游标永远是字符串。Base64Str<T> 用一个 String 字段加 PhantomData<T> 承载「期望反序列化成的类型」,并通过 #<a href="https://link.gitcode.com/i/d157f42e0fe6b133bcde0af53fcccb10" target="_blank">serde(transparent)] 让 JSON 形态就是一个纯字符串([src/cursor.rs):

#[derive(Debug, Serialize, Deserialize)]
#[serde(transparent)]
pub struct Base64Str<T> {
    data: String,
    #[serde(skip)]
    target: PhantomData<T>,
}

编码走「先 JSON 序列化,再标准 base64」(src/cursor.rs):

pub fn encode_json(val: T) -> Self {
    Self::encode(val, serialize_json_string)
}

解码侧同样分两步,并区分两类错误(src/cursor.rs):

pub enum Base64SerdeErr<E> {
    DecodeErr(#[from] DecodeError),
    SerdeErr(E),
}

DecodeErr 表示 base64 本身不合法,SerdeErr 表示 base64 合法但内容不是期望的结构。这个区分被 axum 层直接映射成了两种不同的 400 文案(见第八节)。

四、Query:把「首次请求」和「翻页请求」统一成一种类型

列表接口有两种入参:客户端第一次请求时只给排序方式;之后请求时会带上游标。Query 把这两种情况归一(src/cursor.rs):

pub enum Query<I, T: Sortable, F> {
    /// a Sort method T
    Sort(T, F),
    /// a [CursorWithVal]
    Cursor(CursorWithValAndFilter<I, T, F>),
}

围绕它的一组方法构成了业务层的公共工具箱:

方法 位置 语义
Query::new(Option<Cursor>, sort, filter) src/cursor.rs 有游标则 Cursor,否则 Sort
sort_method() src/cursor.rs 取出生效的排序方式,游标分支从 cursor.val.sort_type 取
filter() src/cursor.rs 取出过滤条件
vals() src/cursor.rs 返回 (Option<&Id>, Option<&Value>),Sort 分支返回 (None, None)
map_filter(cb) src/cursor.rs 纯映射过滤类型
try_map_filter(cb) src/cursor.rs 可失败的过滤类型映射
split_option() src/cursor.rs 把 Option<F> 过滤拆成 Either<Query<.., ()>, Query<.., F>>

vals() 是与数据库层对接的关键:查询实现只需问「有没有上一页的 id 与排序值」,即可决定走首屏查询还是 keyset 查询,无需 match 两种枚举分支。而 split_option() 解决的是类型层的麻烦——Query<I, T, Option<F>> 无法直接和 Query<I, T, ()> 放进同一个返回位置,拆成 Either 后即可由调用方按有无过滤分别处理。

在真实的 HTTP 处理器里,Query::new 几乎总是通过 CursorOptionExt::into_query 触达。以通知列表为例(crates/notification/src/inbound/http.rs):

cursor: Option<CursorWithValAndFilter<Uuid, CreatedAt, ()>>,
...
let query = cursor.into_query(CreatedAt, ());

也就是说,路由函数的参数直接声明为可选的强类型游标,再由扩展方法降级为 Query。默认排序、默认过滤器都在这一行显式给出,语义集中且可读。

五、Paginator:从 Iterator 到一页结果

Paginate 是扩展 Iterator 的入口 trait(src/cursor.rs),PaginateOn 则在其上叠加「条目已实现 SortOn」的约束,从而只需传排序方式而无需手写回调(src/cursor.rs):

pub trait Paginate: Iterator + Sized {
    fn paginate<Cb, S>(self, limit: usize, cb: Cb) -> Paginator<Self, Cb, S, ()>
    where
        Cb: FnMut(&<Self as Iterator>::Item) -> CursorVal<S>,
        S: Sortable;
}

pub trait PaginateOn<T: Sortable>: Paginate {
    fn paginate_on(
        self,
        limit: usize,
        sort: T,
    ) -> Paginator<Self, impl FnMut(&<Self as Iterator>::Item) -> CursorVal<T>, T, ()>
    where
        <Self as Iterator>::Item: SortOn<T>;
}

PaginateOn::paginate_on 的实现只有两行:先调用 <Item as SortOn<T>>::sort_on(sort) 拿到回调,再转交 paginate(src/cursor.rs)。这就是「排序语义」与「分页机件」解耦的具体落点。

Paginator 是一个构建器(src/cursor.rs),支持链式配置:

  • filter_on(f):把过滤条件写入游标,只有 Paginator<_, _, _, ()> 才有此方法(src/cursor.rs),即非法状态在类型层面被排除;
  • sort_asc() / sort_desc():设置本地兜底排序方向(src/cursor.rs);
  • into_page():产出 PaginatedCursor<T, Id, S, F>。

into_page 的判定逻辑值得逐行看(src/cursor.rs):

let res = match ensure_sort {
    Some(sort) => {
        let mut res: Vec<_> = iter.collect();
        res.sort_by_key(|r| {
            let cursor = cb(r);
            match sort {
                Direction::Asc => Either::Left(cursor.last_val),
                Direction::Desc => Either::Right(std::cmp::Reverse(cursor.last_val)),
            }
        });
        res.truncate(limit);
        res
    }
    None => iter.take(limit).collect(),
};

match res.len().cmp(&limit) {
    Ordering::Less => Paginated { items: res, next_cursor: None },
    Ordering::Equal | Ordering::Greater => Paginated {
        next_cursor: res
            .last()
            .map(|last| Cursor {
                id: last.id(),
                limit,
                val: cb(last),
                filter: filter_on,
            })
            .map(Base64Str::encode_json),
        items: res,
    },
}

三个关键结论:

  1. 「满页即有下一页」是这里的判据:当结果数等于 limit 时仍会产出 next_cursor,因此调用方必须自己多取一行来分辨「最后一页刚好满」和「后面还有」。
  2. sort_asc/sort_desc 是逃生舱口,源码注释明确表示:理想情况应让数据库直接返回有序结果,这两个方法只在「拼接多个数据库查询」时才需要。
  3. next_cursor 由页内最后一项生成,id 与 val 都取自同一项,天然保证 tie-break 的一致性。

Paginated<T, U> 本身刻意做成 #<a href="https://link.gitcode.com/i/f474a43ea751e3b471989671f2700cf3" target="_blank">non_exhaustive],只允许通过 into_parts / from_parts / map 操作([src/cursor.rs),避免下游用结构体字面量绕过构造约束。

六、类型擦除:为什么需要一个 String 游标

泛型游标的完整类型 PaginatedCursor<T, I, C, F> 展开后会非常长,且不同排序方式对应不同类型,无法放进同一个枚举变体或同一个 HTTP 响应体。TypeEraseCursor 解决这个问题(src/cursor.rs):

pub type PaginatedCursor<T, I, C, F> = Paginated<T, Base64Str<CursorWithValAndFilter<I, C, F>>>;
pub type PaginatedOpaqueCursor<T> = Paginated<T, String>;

type_erase() 不改变任何数据,只是把 Base64Str 里的 String 取出来(src/cursor.rs),所以两种类型的 JSON 形态完全一致。该 trait 还为 Either<PaginatedCursor<..>, PaginatedCursor<..>> 提供了实现,使得「按 SimpleSortMethod 查」和「按 Frecency 查」的两个结果可以被同一段响应代码消费。

真实用法可以看 crates/notification/src/domain/service/ingress.rs:

let paginated = rows
    .into_iter()
    .paginate_on(limit as usize, CreatedAt)
    .into_page()
    .type_erase();

soup 则更进一步,把多个查询模态的页统一到一个输出枚举里,见 crates/soup/src/domain/ports.rs,其 TypeEraseCursor 实现在 SoupOutput 上完成。

七、内置排序方法与两个「伪装成排序的过滤器」

src/sort.rs 定义了开箱可用的排序类型。

7.1 SimpleSortMethod 与 CreatedAt

#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SimpleSortMethod {
    ViewedAt,
    UpdatedAt,
    CreatedAt,
    ViewedUpdated,
}

pub struct CreatedAt;

两者都实现 Sortable,Value 均为 DateTime<Utc>(src/sort.rs)。CreatedAt 之所以单独存在一个 unit struct,源码注释给了解释:部分场景只支持按创建时间排序,而不支持 SimpleSortMethod 的全部变体。SimpleSortMethod 还实现了 Display,实现方式是走 serde_json 序列化再裁掉引号(src/sort.rs),保证显示名与序列化名永远一致。

7.2 Frecency 与 FrecencyValue 的排序语义

Frecency 的游标值是一个自定义枚举(src/sort.rs):

pub enum FrecencyValue {
    FrecencyScore(f64),
    UpdatedAt(DateTime<Utc>),
}

它的 Ord 实现有三个必须注意的约定:

  • 两个 FrecencyScore 通过 OrderedFloat 比较,规避 f64 不实现 Ord 的问题;
  • 两个 UpdatedAt 直接比较时间戳;
  • 分数永远排在时间戳之前(FrecencyScore vs UpdatedAt 返回 Greater)。

第三条对应注释里的业务含义:当分页游标已经越过所有拥有 frecency 分数的条目后,退化到用 created_at/updated_at 继续排序。这不是随意的比较规则,而是游标推进状态机的编码方式。

7.3 TouchedByMe 与 NotifiedAt:同类型值如何区分

这两个排序方法的游标值类型完全相同(都是 DateTime<Utc>),但序列化标记必须不同,否则一个游标可能被错误解码成另一种排序。源码对此给出了非常细的设计说明:

  • TouchedByMe(src/sort.rs):按请求用户最近一次修改实体的时间排序,数据来自 activity log;它同时是一个过滤器——从未修改过的实体没有排序值,因此不会出现在页中。序列化为 null。
  • NotifiedAt(src/sort.rs):按请求用户最近一次被通知的时间排序,数据来自 user_notification;同样是过滤器语义。它序列化为字符串 "notified_at" 而不是 null,注释写得很直白:值与 TouchedByMe 相同,标记是唯一能区分两者的东西。

实现方式是自定义 into/try_from,并用常量 NOTIFIED_AT_TAG 保证编解码对称:

const NOTIFIED_AT_TAG: &str = "notified_at";

impl TryFrom<String> for NotifiedAt {
    type Error = String;
    fn try_from(value: String) -> Result<Self, Self::Error> {
        if value == NOTIFIED_AT_TAG {
            Ok(NotifiedAt)
        } else {
            Err(format!("expected {NOTIFIED_AT_TAG:?}, got {value:?}"))
        }
    }
}

src/sort/test.rs 用两个测试把这个契约钉死:notified_at_marker_round_trips_as_a_string 断言序列化结果为 "notified_at",且能从该字符串还原;touched_and_notified_cursor_values_do_not_cross_decode 则构造同一时间戳下两种 CursorVal,断言互解必然失败(touched_by_me 与 null 都会被 NotifiedAt 拒绝)。这是「用测试保护协议兼容性」的典型做法——一旦有人把 NotifiedAt 改回 null 序列化,测试立即失败。

八、axum 集成:提取、校验与错误映射

启用 axum feature 后,crate 提供三个能力(src/lib.rs)。

8.1 可选游标提取器

Cursor<Id, CursorVal<Sort>, F> 实现了 OptionalFromRequestParts,从查询参数 cursor 读取字符串(src/axum.rs)。因此路由函数可以直接写:

cursor: Option<CursorWithValAndFilter<Uuid, SimpleSortMethod, ()>>,

无需手工 Query<HashMap<String, String>> 再解析。

8.2 32KB 长度闸门

解码前会先检查 base64 字符串长度(src/axum.rs):

let bytes = encoded.len();
if bytes > 32_000 {
    return Err(CursorExtractErr::SizeErr);
}

这是一道防滥用闸门:游标理论上可能内嵌复杂 filter,若不限长,攻击者可以构造超长参数迫使服务端做大量 JSON 反序列化。注意这里是「长度上限 32000 字节」,错误文案对外表述为 <32kb。

8.3 CursorExtractErr 的四类错误与 HTTP 映射

pub enum CursorExtractErr {
    DecodeErr(Base64SerdeErr<serde_json::Error>),
    SizeErr,
    InvalidQueryParamsErr,
    MutuallyExclusiveErr,
}

IntoResponse 把所有分支映射为 400 Bad Request,但文案不同(src/axum.rs):

变体 触发条件 响应消息
DecodeErr(DecodeErr) base64 非法 failed to decode cursor value
DecodeErr(SerdeErr) base64 合法但结构不符 the cursor contained unexpected data
SizeErr 长度超 32000 Query is too large, must be <32kb
InvalidQueryParamsErr query 参数无法解析 invalid cursor query parameters
MutuallyExclusiveErr 同时给了 cursor 与 previous_cursor provide only one of cursor or previous_cursor

错误分支上的 #[tracing::instrument(err(level = Level::WARN), skip(parts, state))] 让提取失败以 WARN 级别进入日志,同时不打印请求体与状态,兼顾可观测性与隐私。

8.4 BidirectionalCursor:同时支持上一页

src/axum.rs 提供了双向游标枚举:

pub enum BidirectionalCursor<Id, S: Sortable, F> {
    Next(Cursor<Id, CursorVal<S>, F>),
    Previous(Cursor<Id, CursorVal<S>, F>),
}

提取时同时读取 cursor 与 previous_cursor:两者都给直接报 MutuallyExclusiveErr,只给一个则构造对应变体,都不给返回 Ok(None)。这一设计与 CursorOptionExt::into_query 配合,使「首屏 / 下一页 / 上一页」三种请求在同一个处理器内用一次 match 就能分流。

九、集合辅助:CollectByIds 与 CollectBy

src/collections.rs 是围绕 Identify 的两个轻量扩展,用于分页后的二次装配(避免 N+1 查询):

pub trait CollectByIds<A>: Iterator<Item = A> where A: Identify, <A as Identify>::Id: Hash + Eq {
    fn collect_by_ids(self) -> HashMap<<A as Identify>::Id, A>;
}

pub trait CollectBy: Iterator {
    fn group_by<F, Id>(self, cb: F) -> HashMap<Id, Vec<Self::Item>>
    where F: FnMut(&Self::Item) -> Id, Id: Hash + Eq;
}

collect_by_ids 让「先拿到一批 id,再批量查实体,最后按 id 回填」变成 O(1) 查找;group_by 则用于「一对多」的批量装配(例如把消息按会话分组)。两者都要求 Id: Hash + Eq,因此可以直接以 Uuid 或字符串 id 为键。

十、实战:接入一个列表端点的完整链路

以频道列表为例,可以看到这个 crate 在真实请求中是如何串起来的(crates/channels/src/inbound/list_router.rs):

async fn get_channels_handler<S, Auth>(
    State(service): State<ChannelListRouterState<S, Auth>>,
    authorization: MacroAuthorizationExtractor<Auth, UserOrInternal>,
    Query(params): Query<GetChannelsQueryParams>,
    cursor: Option<CursorWithValAndFilter<Uuid, SimpleSortMethod, ()>>,
) -> Result<Json<ApiChannelListPage>, ChannelListRouterErr> {
    let limit = params.limit.unwrap_or(DEFAULT_CHANNEL_LIST_LIMIT).clamp(1, MAX_CHANNEL_LIST_LIMIT);
    let res = service.inner.get_channels(GetChannelsRequest {
        macro_id: user.macro_user_id.clone(),
        // Fetch one extra row so pagination can distinguish a full final
        // page from a page with more results.
        limit: Some(limit.saturating_add(1)),
        include_frecency: true,
        query: cursor.into_query(SimpleSortMethod::UpdatedAt, ()).map_filter(|_| None),
    }).await.map_err(|_| ChannelListRouterErr::Internal)?;

    let has_more = res.len() > limit as usize;
    let Paginated { items, next_cursor, .. } = res
        .into_iter()
        .paginate_on(limit as usize, SimpleSortMethod::UpdatedAt)
        .filter_on(())
        .into_page()
        .type_erase();
    ...
}

这里几乎用到了全部关键接口,也演示了第五节提到的「多取一行」约定:limit + 1 用于判断 has_more,随后 paginate_on(limit) 只取 limit 条并生成游标,最后在响应里用 next_cursor.filter(|_| has_more) 屏蔽掉「满页但已无更多」时的假游标。

再看 soup 的复杂场景:它把多个数据源的迭代器 chain 起来,再用 sort_asc/sort_desc 做本地归并截断(crates/soup/src/domain/service.rs):

let paginator = main_soup?
    .chain(email_soup?)
    .chain(comms_soup?)
    ...
    .chain(foreign_entity_soup?)
    .paginate_on(limit.into(), sort_method)
    .filter_on(entity_filter);

let page = match sort_direction {
    SoupSortDirection::Asc => paginator.sort_asc(),
    SoupSortDirection::Desc => paginator.sort_desc(),
}.into_page();

这正是源码注释里「stitching multiple database queries together」所指的场景——当单条 SQL 无法完成全量排序时,Paginator 承担了归并职责。

十一、配方:新增一种排序方法

AGENTS.md 的 Recipes 小节给出了三段式路径,结合源码可以展开为可执行步骤:

src/sort.rs(impl Sortable/SortOn)→ 调用方为其条目类型实现 Identify → 其列表查询

第一步:在 src/sort.rs 定义排序类型并实现 Sortable

#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub struct MySort;

impl Sortable for MySort {
    type Value = DateTime<Utc>;  // 或任何 Debug + Ord 的类型
}

如果新排序与已有排序共享 Value 类型(如 DateTime<Utc>),务必像 NotifiedAt 那样给一个唯一的序列化标记,否则游标会被跨类型误解码——这是本项目已经踩过并写进测试的坑。

第二步:为列表条目实现 Identify

参考 soup 的实现(crates/models_soup/src/item.rs):SoupItem<T> 的 Id 是 Uuid,id() 对每个枚举变体分别取主键。

第三步:为条目实现 SortOn<T>

soup 的写法是直接复用内部时间戳访问器(crates/models_soup/src/item.rs):

impl<T> SortOn<SimpleSortMethod> for SoupItem<T> {
    fn sort_on(sort: SimpleSortMethod) -> impl FnMut(&Self) -> CursorVal<SimpleSortMethod> {
        move |v| CursorVal { sort_type: sort, last_val: v.cursor_timestamp(sort) }
    }
}

同时,领域层还需把新排序接入自己的查询抽象。soup 用 SoupQuery 的四组构造器区分首屏与翻页(crates/soup/src/domain/models.rs):new_sort_* 构造 Query::Sort,new_cursor_* 构造 Query::Cursor,并通过 into_ast() 用 try_map_filter 把高层过滤器编译成 EntityFilterAst。按同一模式扩展一个新变体,SQL 层就能通过 Query::vals() 拿到 (id, last_val) 做 keyset 查询。

十二、容易踩坑的设计约定

  1. into_page 在 len == limit 时仍给游标。不要假设 next_cursor.is_some() 就意味着一定有下一页,除非你像 channels 路由那样多取一行。
  2. sort_asc/sort_desc 不是常规排序手段。它们是「多条查询拼接」的逃生舱口,会把整个迭代器收进内存再排序,代价与数据集大小线性相关。
  3. Query::Sort 分支的 vals() 返回 (None, None)。数据库实现必须据此走首屏分支,不要对 None 做 unwrap。
  4. 类型擦除后不能再取回强类型。type_erase() 之后只有 String,若下游还想按类型分派,应在擦除前 match 或使用 Either 的实现。
  5. 游标内嵌 filter 会放大体积。这也是 32KB 闸门存在的原因;把大过滤器放进游标会使翻页 URL 变得很长。
  6. NotifiedAt 与 TouchedByMe 不可互换。两者 Value 相同,只靠序列化标记区分,任何改动都必须同步更新 crates/models_pagination/src/sort/test.rs 中的交叉解码测试。

十三、验证方式

AGENTS.md 的 Checks 小节给出的验证命令是:

cargo test -p models_pagination

并注明需 SQLX_OFFLINE 未设置。该 crate 的依赖列表里并没有 sqlx,从仓库结构推断,这条要求来自工作区层面的统一约定(sqlx 离线元数据会影响编译期检查的加载路径),因此在该 crate 上单独跑测试时应保持与工作区一致的环境。若要验证下游集成行为,可参考 crates/soup/src/domain/service/tests.rs 中的 paginate_on(0, SimpleSortMethod::CreatedAt).into_page() 写法——用 limit = 0 断言「空页不产生游标」,以及同文件中的 frecency_should_paginate 用例。

结语

models_pagination 的价值不在于分页本身,而在于把「游标即协议」这件事用类型系统固定下来:Identify 保证有稳定的 tie-break 键,Sortable 保证排序值可比较可序列化,SortOn 保证条目知道自己在某个维度上的取值,Query 让首屏与翻页共用一条代码路径,Paginator 在不牺牲数据库排序能力的前提下提供归并逃生口。理解了这五者的分工,为 Macro 的任意列表端点新增分页或新增排序,就都只是按固定配方填空的工作。

登录后查看全文
macro