Rivet Rust SDK 数据节点查询指南使用 DatacentersApi 的 datacenters_list 接口【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors导读本文是 Rivet Actors 开源仓库中 Rust SDKengine/sdks/rust/api-full数据节点 API 的实战指南围绕DatacentersApi的datacenters_list接口展开。你将学会如何在 Rust 中调用GET /datacenters获取集群全部数据节点Datacenter的标签、名称与公共 URL并深入理解该接口背后的服务端实现、认证机制与拓扑配置模型为构建跨地域、多数据节点的有状态 Actor 应用打下基础。一、接口总览DatacentersApi是 OpenAPI Generator 基于rivet-api-publicapi-public 包自动生成的 Rust API 客户端类完整定义见 DatacentersApi.md。该 API 目前只有一个端点方法HTTP 请求描述datacenters_listGET/datacenters列出集群中的所有数据节点所有 URI 均相对于配置的base_pathSDK 默认值为http://localhost见 configuration.rs实际部署时需替换为你的控制平面地址。在服务端该路由注册于 router.rsaxum::routing::get(datacenters::list)即axum框架下对GET /datacenters的 GET 处理。二、为什么需要数据节点列表在 Rivet 中数据节点Datacenter是集群拓扑的基本组成单元代表一个地域Region。对于面向全球用户的有状态 Actor、协作应用与 AI Agent 工作负载应用需要根据数据节点的分布来选择最近的数据节点部署 Actor就近调度减少延迟感知集群中所有可用的公共入口 URL向客户端暴露正确的连接地址结合DatacenterHealth等健康数据做故障转移与容错判断。datacenters_list正是为此提供的最轻量入口一次无参数调用即可拿到全部数据节点的静态信息。三、函数签名与参数SDK 生成的函数签名如下pub async fn datacenters_list( configuration: configuration::Configuration, ) - Resultmodels::DatacentersListResponse, ErrorDatacentersListError本接口不需要任何参数文档明确标注 This endpoint does not need any parameter。该接口无需分页游标、筛选条件或请求体请求只携带认证头与常规 HTTP 头。客户端真实实现位于 datacenters_api.rs核心调用链为let uri_str format!({}/datacenters, configuration.base_path); let mut req_builder configuration.client.request(reqwest::Method::GET, uri_str); if let Some(ref user_agent) configuration.user_agent { req_builder req_builder.header(reqwest::header::USER_AGENT, user_agent.clone()); } if let Some(ref token) configuration.bearer_access_token { req_builder req_builder.bearer_auth(token.to_owned()); };可以看到客户端使用reqwest发起 GET 请求仅附加User-Agent与 Bearer Token 两个 Header随后解析 JSON 响应。四、认证方式bearer_auth本接口要求bearer_authBearer Token 认证。SDK 侧通过Configuration结构体中的bearer_access_token字段提供configuration.rs字段类型默认值说明base_pathStringhttp://localhostAPI 服务地址user_agentOptionStringOpenAPI-Generator/2.3.14/rust请求 User-Agentclientreqwest::Clientreqwest::Client::new()HTTP 客户端bearer_access_tokenOptionStringNoneBearer 认证令牌服务端认证逻辑位于 ctx.rs当配置中启用了auth时请求必须携带 Token且通过subtle::ConstantTimeEq常量时间比较与admin_token校验防止时序侧信道攻击未携带 Token 或 Token 无效时返回 403 ForbiddenApiForbidden。若服务端配置未启用认证auth为None则跳过校验直接放行。五、HTTP 请求头Content-Type未定义GET 请求无请求体因此无需声明内容类型Acceptapplication/json响应以 JSON 返回客户端按ContentType::Json反序列化见 datacenters_api.rs。响应解析采用严格的内容类型校验只有application/json才能成功反序列化为DatacentersListResponse若返回text/plain或其他未知类型SDK 会抛出对应的反序列化错误。六、返回类型与响应模型函数的返回类型为 models::DatacentersListResponse其 Rust 结构定义如下datacenters_list_response.rs字段类型说明datacentersVecmodels::Datacenter数据节点列表paginationmodels::Pagination分页信息当前cursor为NoneDatacenter 模型每个数据节点包含三个字段datacenter.rs、Datacenter.md字段类型说明labeli32数据节点标签整数标识nameString数据节点名称urlString数据节点公共 URLPagination 模型pub struct Pagination { #[serde(rename cursor, default, ...)] pub cursor: OptionOptionString, }当前服务端实现固定返回Pagination { cursor: None }见下文源码即一次性返回全部数据节点无需翻页。七、服务端实现原理从源码结构看服务端处理函数位于 api-public/src/datacenters.rs核心逻辑list_inner如下async fn list_inner(ctx: ApiCtx) - ResultListResponse { ctx.auth().await?; Ok(ListResponse { datacenters: ctx .config() .topology() .datacenters .iter() .map(|dc| Datacenter { label: dc.datacenter_label, name: dc.name.clone(), url: dc.public_url.to_string(), }) .collect(), pagination: Pagination { cursor: None }, }) }关键结论可由源码直接印证数据来源是配置而非数据库datacenters_list直接读取控制平面配置中的topology.datacenters列表逐项映射为响应模型无任何存储查询。因此该接口返回的是静态拓扑视图反映控制平面启动时加载的集群配置。label对应配置中的datacenter_labelu16在响应模型中升级为i32url取自public_url即该地域对外可连接的公共入口认证先行ctx.auth().await?确保未授权请求在进入业务逻辑前即被拒绝。接口层通过#[utoipa::path]声明 OpenAPI 元数据operation_id datacenters_list与 SDK 生成的方法名一一对应这也是 Rust SDK 能从 OpenAPI 规范自动生成客户端的原因。八、拓扑配置模型数据节点从哪来要理解datacenters_list返回的数据需要了解控制平面的拓扑配置config/src/config/topology.rs。每个配置项如下配置字段类型说明nameString数据节点名称以 Map 形式配置时自动取自 keydatacenter_labelu16数据节点标签Map 配置时必须显式指定is_leaderbool是否为 Leader 数据节点public_urlUrl对外公共入口datacenters_list返回的url即此值peer_urlUrlapi-peer 服务地址数据节点间通信用proxy_urlOptionUrl其他数据节点可私密访问的 guard 服务地址缺省时回退到public_urlvalid_hostsOptionVecString允许访问该地域的区域性域名白名单用于区域端点校验拓扑配置支持两种写法DatacentersRepr::Map(HashMapString, Datacenter)推荐name 由 key 派生与DatacentersRepr::List(VecDatacenter)已废弃需显式指定 name。默认配置topology.rs 默认实现为单节点datacenter_label 1public_url指向http://127.0.0.1:{GUARD_PORT}。配置校验也在此模块完成config/mod.rs当集群存在多个数据节点时会校验所有节点均配置了valid_hosts确保区域性域名路由行为可预期。九、完整调用示例以下示例展示如何在 Rust 中配置客户端并调用datacenters_list。将 SDK 目录放入项目后在Cargo.toml中添加依赖[dependencies] rivet-api-full { path ./rivet-api-full }调用代码use rivet_api_full::apis::{configuration::Configuration, datacenters_api}; #[tokio::main] async fn main() - Result(), Boxdyn std::error::Error { // 1. 构造客户端配置 let mut configuration Configuration::new(); configuration.base_path http://localhost.to_owned(); // 替换为控制平面地址 configuration.bearer_access_token Some(your-admin-token.to_owned()); // 若服务端启用了认证 // 2. 调用 datacenters_list无参数 let response datacenters_api::datacenters_list(configuration).await?; // 3. 遍历数据节点 for dc in response.datacenters { println!(label{} name{} url{}, dc.label, dc.name, dc.url); } Ok(()) }运行后将输出类似取决于你的拓扑配置label1 namedefault urlhttp://127.0.0.1:7443如果服务端启用了认证而客户端未配置 Token将收到 403 错误如果配置了错误的 Token同样返回 403ApiForbiddenreason 为Invalid token。十、实战注意事项Token 安全bearer_access_token是管理员级令牌与admin_token常量时间比对切勿硬编码在源码或提交到版本库建议从环境变量或密钥管理服务注入。端点地址base_path必须指向实际运行的控制平面api-public服务而非 Actor 运行时。自托管部署时请参考仓库中的self-host目录配置。结果只读datacenters_list是只读查询返回数据直接来源于控制平面启动时的拓扑配置若修改了拓扑需要让控制平面重新加载配置后再查询接口本身不会触发刷新。分页字段保留虽然当前pagination.cursor恒为None但调用方应保留对该字段的处理逻辑以便未来服务端引入分页时平滑兼容。配合健康检查使用若需要感知数据节点的实时可达性与延迟rtt_ms、status可进一步查阅 DatacenterHealth 模型与HealthApi的health_fanout接口结合datacenters_list实现拓扑发现 健康探测的完整地域路由方案。参考资源接口文档DatacentersApi.md客户端实现datacenters_api.rs服务端实现api-public/src/datacenters.rs拓扑配置模型config/src/config/topology.rsSDK 总览rust/api-full README【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考