深入 models_pagination:Macro 后端类型安全游标分页基础设施解析
深入 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)] 强制所有公开项都必须带文档:
Iterator::Item必须实现Identify,以便取出条目的唯一 id;- 目标排序方式必须实现
Sortable,用来声明「按什么类型排序」,例如DateTime<Utc>; 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,
},
}
三个关键结论:
- 「满页即有下一页」是这里的判据:当结果数等于
limit时仍会产出next_cursor,因此调用方必须自己多取一行来分辨「最后一页刚好满」和「后面还有」。 sort_asc/sort_desc是逃生舱口,源码注释明确表示:理想情况应让数据库直接返回有序结果,这两个方法只在「拼接多个数据库查询」时才需要。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直接比较时间戳; - 分数永远排在时间戳之前(
FrecencyScorevsUpdatedAt返回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 查询。
十二、容易踩坑的设计约定
into_page在len == limit时仍给游标。不要假设next_cursor.is_some()就意味着一定有下一页,除非你像 channels 路由那样多取一行。sort_asc/sort_desc不是常规排序手段。它们是「多条查询拼接」的逃生舱口,会把整个迭代器收进内存再排序,代价与数据集大小线性相关。Query::Sort分支的vals()返回(None, None)。数据库实现必须据此走首屏分支,不要对None做unwrap。- 类型擦除后不能再取回强类型。
type_erase()之后只有String,若下游还想按类型分派,应在擦除前match或使用Either的实现。 - 游标内嵌 filter 会放大体积。这也是 32KB 闸门存在的原因;把大过滤器放进游标会使翻页 URL 变得很长。
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 的任意列表端点新增分页或新增排序,就都只是按固定配方填空的工作。