Rivet Actors Rust SDK:NamespaceListResponse 模型与 namespace 列表分页实战解析

原创2026-09-17 17:29:061,905 阅读
文章标签:后端云原生Serverless任务调度工作流自动化微服务

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,流程如下:

  1. 通过 ctx.auth().await? 完成 bearer_auth 鉴权;
  2. 若当前节点是 leader,直接调用 rivet_api_peer::namespaces::list 在本地执行;
  3. 否则通过 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,根据查询参数分三条路径:

  1. 按 name 过滤:调用 namespace::ops::resolve_for_name_global 按名称精确解析,返回 0 或 1 个命名空间,pagination.cursor 固定为 None(单条结果无需分页);
  2. 按 namespace_ids / namespace_id 过滤:将废弃参数 namespace_ids 按逗号拆分解析为 Id 列表,与 namespace_id 合并后调用 namespace::ops::get_global 批量获取,pagination.cursor 同样为 None;
  3. 无条件列表:调用 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 请求的完整调用链为:

  1. SDK 组装 GET /namespaces?limit=&cursor=&name=&namespace_id= 请求并附加 Bearer 令牌;
  2. 服务端 api-public 入口鉴权后,非 leader 节点转发至 leader 数据中心;
  3. peer 层按参数选择“名称解析 / ID 批量获取 / 全量列表”三种路径;
  4. 全量列表路径进入 namespace_list operation,在 leader 的 UniversalDB 事务中以快照隔离级别流式扫描,默认 1000 条封顶并去重;
  5. 以最后一条 create_ts 生成游标,与命名空间数组一起封装为 NamespaceListResponse;
  6. 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. 延伸阅读

登录后查看全文
rivet