Rivet Actors Rust SDK:NamespaceListResponse 模型与 namespace 列表分页实战解析
Rivet Actors Rust SDK:NamespaceListResponse 模型与 namespace 列表分页实战解析
NamespaceListResponse 是 Rivet Actors 公开 API 中 GET /namespaces 接口的响应模型,封装了命名空间列表与游标分页信息。本文以 NamespaceListResponse.md 为核心,结合 Rust SDK 源码、namespaces 服务端实现与底层数据操作,完整讲解该模型的结构、字段语义、分页机制及实际调用方式,帮助读者掌握用 Rivet 管理多个命名空间(namespace)时“如何拉取、如何翻页、如何按名称或 ID 过滤”的完整链路。
1. 模型概览:NamespaceListResponse 的结构
在 Rust SDK 中,NamespaceListResponse 定义于 namespace_list_response.rs,由 OpenAPI Generator 依据 rivet-api-public 的 OpenAPI 规范(版本 2.3.14)自动生成。其字段如下:
| 字段名 | 类型 | 说明 |
|---|---|---|
namespaces |
Vec<models::Namespace> |
当前页返回的命名空间列表,可包含 0 个或多个元素 |
pagination |
models::Pagination |
游标分页信息,用于请求下一页数据 |
对应的 Rust 结构体为:
#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)]
pub struct NamespaceListResponse {
#[serde(rename = "namespaces")]
pub namespaces: Vec<models::Namespace>,
#[serde(rename = "pagination")]
pub pagination: Box<models::Pagination>,
}
impl NamespaceListResponse {
pub fn new(
namespaces: Vec<models::Namespace>,
pagination: models::Pagination,
) -> NamespaceListResponse {
NamespaceListResponse {
namespaces,
pagination: Box::new(pagination),
}
}
}
两个字段通过 #<a href="https://link.gitcode.com/i/4610c46fa010b546398199cc49c79e24" target="_blank">serde(rename = "...")] 与 JSON 响应中的 namespaces、pagination 键严格对应,可直接由 serde_json::from_str 反序列化(该转换发生在 [namespaces_api.rs 中)。pagination 使用 Box 包裹是 SDK 对递归类型结构的通用处理方式,不影响序列化结果。
该模型与 GET /namespaces 接口一一对应,服务端返回的 JSON 形如:
{
"namespaces": [ ... ],
"pagination": { "cursor": "..." }
}
1.1 列表元素:Namespace 模型
namespaces 数组中的每个元素是 Namespace,其结构定义于 namespace.rs:
| 字段名 | 类型 | 说明 |
|---|---|---|
namespace_id |
String |
命名空间的全局唯一 ID |
name |
String |
命名空间名称(作为过滤与解析的关键标识) |
display_name |
String |
展示名称,用于界面展示 |
create_ts |
i64 |
创建时间戳(Unix 毫秒),同时是游标分页的排序键 |
对应结构体:
pub struct Namespace {
#[serde(rename = "create_ts")]
pub create_ts: i64,
#[serde(rename = "display_name")]
pub display_name: String,
#[serde(rename = "name")]
pub name: String,
#[serde(rename = "namespace_id")]
pub namespace_id: String,
}
1.2 分页字段:Pagination 模型
pagination 字段的类型是 Pagination,定义于 pagination.rs:
pub struct Pagination {
#[serde(rename = "cursor", default, with = "::serde_with::rust::double_option",
skip_serializing_if = "Option::is_none")]
pub cursor: Option<Option<String>>,
}
cursor 是下一页游标,语义如下:
Some(Some(cursor)):存在下一页,将游标值原样回传给GET /namespaces?cursor=...即可翻页;Some(None)/None:已到达最后一页,无更多数据(服务端在名称过滤、ID 过滤两种场景下会显式返回cursor: None,见下文源码分析)。
2. 获取列表:namespaces_list 接口调用
NamespaceListResponse 由 NamespacesApi 中的 namespaces_list 异步函数返回,实现在 namespaces_api.rs。其完整签名如下:
pub async fn namespaces_list(
configuration: &configuration::Configuration,
limit: Option<i32>,
cursor: Option<&str>,
name: Option<&str>,
namespace_ids: Option<&str>,
namespace_id: Option<Vec<String>>,
) -> Result<models::NamespaceListResponse, Error<NamespacesListError>>
对应 GET {base_path}/namespaces,HTTP 细节为:
- Authorization:
bearer_auth,SDK 在 namespaces_api.rs 中通过configuration.bearer_access_token自动附加Bearer令牌; - Accept:
application/json; - 所有过滤参数均以 Query 参数形式发送(
limit、cursor、name、namespace_ids、namespace_id)。
2.1 查询参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit |
Option<i32> |
否 | 单页返回的最大条数,不传时服务端默认取 1000 |
cursor |
Option<&str> |
否 | 上一页返回的游标,用于翻页 |
name |
Option<&str> |
否 | 按命名空间名称精确过滤 |
namespace_ids |
Option<&str> |
否 | 逗号分隔的 ID 列表(已废弃,建议改用 namespace_id) |
namespace_id |
Option<Vec<String>> |
否 | 按一个或多个命名空间 ID 过滤,以 multi 方式编码为重复 Query 参数 |
2.2 最小调用示例
use rivet_api::apis::{configuration::Configuration, namespaces_api};
let config = Configuration {
base_path: "https://api.rivet.gg".to_string(),
bearer_access_token: Some("YOUR_API_TOKEN".to_string()),
..Default::default()
};
let response = namespaces_api::namespaces_list(
&config,
Some(100), // limit
None, // cursor(首页)
None, // name
None, // namespace_ids(废弃参数)
None, // namespace_id
).await?;
for ns in &response.namespaces {
println!("{} | {} | created_at={}", ns.namespace_id, ns.name, ns.create_ts);
}
2.3 游标翻页示例
利用 response.pagination.cursor 持续请求,直到游标为空:
let mut cursor: Option<String> = None;
loop {
let response = namespaces_api::namespaces_list(
&config, Some(50), cursor.as_deref(), None, None, None,
).await?;
for ns in &response.namespaces {
println!("{}", ns.name);
}
match response.pagination.cursor {
Some(Some(next)) => cursor = Some(next),
_ => break, // 游标为 None / Some(None):已到最后一页
}
}
3. 服务端实现:响应从何而来
3.1 API 入口层
GET /namespaces 的处理器是 namespaces.rs 中的 list,流程如下:
- 通过
ctx.auth().await?完成bearer_auth鉴权; - 若当前节点是 leader,直接调用
rivet_api_peer::namespaces::list在本地执行; - 否则通过
request_remote_datacenter将请求转发到 leader 数据中心执行。
响应类型 ListResponse 定义在 api-types/src/namespaces/list.rs,与 SDK 模型完全一致(#[schema(as = NamespaceListResponse)] 保证 OpenAPI 名称对齐):
#[derive(Serialize, Deserialize, ToSchema)]
#[serde(deny_unknown_fields)]
#[schema(as = NamespaceListResponse)]
pub struct ListResponse {
pub namespaces: Vec<rivet_types::namespaces::Namespace>,
pub pagination: crate::pagination::Pagination,
}
3.2 三种查询路径与游标生成逻辑
peer 层实现位于 api-peer/src/namespaces.rs,根据查询参数分三条路径:
- 按
name过滤:调用namespace::ops::resolve_for_name_global按名称精确解析,返回 0 或 1 个命名空间,pagination.cursor固定为None(单条结果无需分页); - 按
namespace_ids/namespace_id过滤:将废弃参数namespace_ids按逗号拆分解析为Id列表,与namespace_id合并后调用namespace::ops::get_global批量获取,pagination.cursor同样为None; - 无条件列表:调用
namespace::ops::list,并以返回列表最后一个命名空间的create_ts作为下一页游标:
let cursor = namespaces_res
.namespaces
.last()
.map(|ns| ns.create_ts.to_string());
Ok(ListResponse {
namespaces: namespaces_res.namespaces,
pagination: Pagination { cursor },
})
由此可以确认游标分页的核心事实:游标值即最后一个元素的 create_ts(Unix 毫秒时间戳字符串),以创建时间作为排序键推进分页。
3.3 底层数据操作:limit 默认值与去重
最终的列表查询落在 namespace/src/ops/list.rs 的 namespace_list operation 中:
let limit = input.limit.unwrap_or(1000); // Default limit to 1000
let mut stream = tx.get_ranges_keyvalues(
universaldb::RangeOption {
mode: StreamingMode::Iterator,
..(&keys::subspace()).into()
},
Snapshot,
);
关键行为:
- 默认 limit 为 1000:调用方未传
limit时,单页最多返回 1000 个命名空间; - 以流式(
StreamingMode::Iterator)遍历命名空间键子空间,配合Snapshot隔离级别读取; - 通过
HashSet对namespace_id去重(同一命名空间的多个名称键只保留一个),并用get_local::get_inner取回完整命名空间数据; - 达到
limit上限即提前break,避免全量扫描; - 该 operation 要求运行在 leader 节点,非 leader 会返回
Namespace::NotLeader错误(这也解释了 3.1 中为何需要转发到 leader)。
4. 完整工作流:从模型到数据的一次请求
将上述各层串联,一次 namespaces_list 请求的完整调用链为:
- SDK 组装
GET /namespaces?limit=&cursor=&name=&namespace_id=请求并附加 Bearer 令牌; - 服务端
api-public入口鉴权后,非 leader 节点转发至 leader 数据中心; - peer 层按参数选择“名称解析 / ID 批量获取 / 全量列表”三种路径;
- 全量列表路径进入
namespace_listoperation,在 leader 的 UniversalDB 事务中以快照隔离级别流式扫描,默认 1000 条封顶并去重; - 以最后一条
create_ts生成游标,与命名空间数组一起封装为NamespaceListResponse; - SDK 依据 HTTP 200 +
application/json将响应反序列化为NamespaceListResponse结构体。
整个过程体现了 Rivet Actors 在多数据中心架构下的典型设计:客户端始终只与公共 API 交互,实际数据读取统一收敛到 leader 节点完成,而 NamespaceListResponse 正是这条链路的最终产物,是开发者通过 Rust SDK 管理命名空间时最常用的响应模型。
5. 使用要点与注意事项
- 翻页必须携带游标:
pagination.cursor为Some(Some(_))时表示还有下一页,将其原样传给下次请求的cursor参数;出现None表示已到末尾。注意 Rust SDK 中Option<Option<String>>的双层结构,外层None与内层None都表示“无下一页”。 - 过滤与分页互斥:按
name或按namespace_id过滤时服务端返回单批结果且游标为None,无需也不应继续翻页。 - 废弃参数:
namespace_ids(逗号分隔字符串)已被标记为 Deprecated,应改用namespace_id(重复 Query 参数,可传多个)。 - 默认上限:不传
limit时服务端默认返回最多 1000 个命名空间,大量数据时务必使用分页而非依赖单次请求。 - 错误处理:SDK 将 4xx/5xx 响应包装为
Error<NamespacesListError>,调用时建议用match或?统一处理鉴权失败、非 leader 等异常场景。
6. 延伸阅读
- NamespacesApi.md:
namespaces_list/namespaces_create接口的完整参数与返回类型说明; - Namespace.md:列表元素模型字段说明;
- namespaces.rs:公共 API 入口与多数据中心转发逻辑;
- api-peer/src/namespaces.rs:peer 层查询路径与游标生成;
- namespace/src/ops/list.rs:底层命名空间列表查询与 limit 默认值实现。