尧图网页设计 
Rivet ActorsDatacentersListResponse模型深度解析GET /datacenters响应结构、Rust SDK 用法与服务端实现【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actorsRivet Actors 为有状态工作负载AI Agent、协作应用、持久化执行提供了数据中心拓扑抽象而DatacentersListResponse正是其公开 API 中GET /datacenters端点的标准响应模型。本文以 DatacentersListResponse.md 为骨架结合仓库内 Rust SDK 生成源码与服务端 axum 实现完整讲解该模型的字段结构、嵌套类型、Rust 调用方式以及响应数据在服务端拓扑配置中的真实来源。读完本文你将能直接在自己的 Rust 项目中调用datacenters_list并正确解析多数据中心列表也能理解该响应在服务端是如何从配置构造出来的。一、模型概览响应体的两个核心字段DatacentersListResponse是 OpenAPI Generator 从服务端 OpenAPI 规范版本 2.3.14为GET /datacenters自动生成的 Rust 响应类型。它只包含两个字段且均为必填名称类型说明是否可选datacentersVecmodels::Datacenter数据中心列表必填paginationmodels::Pagination分页信息必填对应的 Rust 结构体定义位于 datacenters_list_response.rs源码通过serde属性把字段名直接映射为 JSON 键名#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)] pub struct DatacentersListResponse { #[serde(rename datacenters)] pub datacenters: Vecmodels::Datacenter, #[serde(rename pagination)] pub pagination: Boxmodels::Pagination, }一个典型的响应 JSON 示例如下{ datacenters: [ { label: 1, name: default, url: http://127.0.0.1:6080 } ], pagination: { cursor: null } }其中pagination被装箱为Boxmodels::Pagination这是生成代码的常见优化把可嵌套的大对象放在堆上减少结构体拷贝时的栈开销。SDK 还提供了便捷构造函数DatacentersListResponse::new(datacenters, pagination)见 datacenters_list_response.rs方便在测试或 mock 场景下手工构造响应。二、嵌套模型一Datacenter单数据中心描述datacenters数组的元素类型是Datacenter它描述单个数据中心的基本信息。字段定义如下见 Datacenter.md 与 datacenter.rs名称类型说明labeli32数据中心编号标签用于在集群内唯一定位某个 DCnameString数据中心名称urlString数据中心的公开访问地址pub struct Datacenter { #[serde(rename label)] pub label: i32, #[serde(rename name)] pub name: String, #[serde(rename url)] pub url: String, }值得注意的一个细节是类型宽度差异SDK 中label是i32而服务端共享类型 types/src/datacenters.rs 中对应字段label: u16拓扑配置 topology.rs 中同样是u16。这是 OpenAPI Generator 生成客户端时常见的类型放大行为服务端 u16 → 客户端 i32在实际使用中不会造成数据丢失。三、嵌套模型二Pagination游标分页pagination字段描述列表结果的分页状态见 Pagination.md 与 pagination.rs名称类型说明是否可选cursorOptionString分页游标可选pub struct Pagination { #[serde(rename cursor, default, with ::serde_with::rust::double_option, skip_serializing_if Option::is_none)] pub cursor: OptionOptionString, }这里使用了serde_with::rust::double_option双 Option 序列化策略外层Option表示字段缺失内层Option表示字段显式为null。这种设计可以严格区分「JSON 中没这个键」和「JSON 中这个键是 null」两种状态。当前版本中GET /datacenters返回的数据中心数量有限因此服务端总是返回cursor: None详见下文第四节但保留该字段保证了协议的前向兼容——未来数据中心数量增长需要分页时客户端无需改动解析逻辑。四、数据从哪来GET /datacenters端点与服务端实现DatacentersListResponse由公开 API 的datacenters_list方法返回。端点信息见 DatacentersApi.md方法HTTP 请求说明datacenters_listGET/datacenters获取全部数据中心请求参数无鉴权bearer_authBearer TokenAcceptapplication/json服务端实现位于 api-public/src/datacenters.rs路由在 router.rs 中以axum::routing::get(datacenters::list)注册。核心逻辑非常清晰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 }, }) }从源码可以提炼出三条关键实现事实鉴权前置ctx.auth().await?在构造响应前强制校验 Bearer Token未携带有效凭证的请求会走ApiError::from(err).into_response()返回错误响应这与 SDK 文档中标注的bearer_auth安全要求一一对应。数据来自静态拓扑配置响应不是查询数据库而是遍历ctx.config().topology().datacenters配置结构见 topology.rs把每个配置项的datacenter_label、name、public_url映射为响应中的label、name、url三个字段。也就是说GET /datacenters反映的是当前部署实例「认识」的所有数据中心而不是动态注册表。分页当前恒为空pagination.cursor始终为None配合Box装箱与double_option序列化策略JSON 输出中该字段通常呈现为cursor: null。服务端响应类型ListResponse的定义见 api-types/src/datacenters/list.rs它通过#[schema(as DatacentersListResponse)]声明自己在 OpenAPI 规范中的对外名称这正是生成 SDK 模型DatacentersListResponse的命名来源同时#[serde(deny_unknown_fields)]要求客户端发送未知字段时报错保证协议严格性。共享类型 types/src/datacenters.rs 中的Datacenter { label: u16, name: String, url: String }则是服务端与 SDK 之间契约的最终定义者。五、Rust SDK 实战调用datacenters_list5.1 引入依赖rivet-api-full是仓库内生成的 Rust 客户端API 版本 2.3.14见 README.md。将包放入项目目录后在Cargo.toml中声明路径依赖[dependencies] rivet-api-full { path ./rivet-api-full }生成包的 API 索引、模型清单与安装说明均可查阅 engine/sdks/rust/api-full/rust/README.md。5.2 构造配置并发起请求SDK 客户端函数签名定义在 apis/datacenters_api.rspub async fn datacenters_list( configuration: configuration::Configuration, ) - Resultmodels::DatacentersListResponse, ErrorDatacentersListError从生成源码可以看到请求的完整拼装过程datacenters_api.rs请求行GET {base_path}/datacenters其中base_path来自Configuration默认http://localhost附加User-Agent头若配置了user_agent附加Authorization: Bearer token若配置了bearer_access_token成功非 4xx/5xx时按Content-Type: application/json反序列化为DatacentersListResponse失败时封装为Error::ResponseError内含状态码、响应体与类型化错误枚举DatacentersListErrordatacenters_api.rs目前仅有UnknownValue兜底分支。实际调用示例use rivet_api_full::apis::{configuration::Configuration, datacenters_api}; #[tokio::main] async fn main() - Result(), Boxdyn std::error::Error { let mut config Configuration::new(); // 指向你的 Rivet Actors 部署实例 config.base_path https://api.example.com.to_string(); // 公开 API 需要 Bearer Token 鉴权对应服务端 ctx.auth() 校验 config.bearer_access_token Some(YOUR_TOKEN.to_string()); let resp datacenters_api::datacenters_list(config).await?; for dc in resp.datacenters { println!(label{} name{} url{}, dc.label, dc.name, dc.url); } // resp.pagination.cursor 当前恒为 None可直接忽略 Ok(()) }5.3 解析要点遍历resp.datacenters即可获得全部数据中心label可作为部署/调度场景中的机房标识resp.pagination虽然必填但当前版本恒返回cursor: None无需强制分页循环若收到Error::ResponseError说明服务端返回了 4xx/5xx例如 Token 缺失或过期可按response_content.status区分错误类型。六、服务端拓扑配置理解datacenters数据的源头要读懂响应内容需要了解服务端拓扑配置的结构。Topology配置类型定义在 topology.rspub struct Topology { /// Must be included in datacenters pub datacenter_label: u16, /// Map of all datacenters, including this datacenter. pub datacenters: DatacentersRepr, }单个数据中心配置项topology.rs包含配置字段类型说明nameString数据中心名称映射到响应namedatacenter_labelu16编号标签映射到响应labelis_leaderbool是否为领导数据中心用于调度选址public_urlUrl公开访问地址映射到响应urlpeer_urlUrl数据中心间 peer 通信地址proxy_urlOptionUrl可选代理地址valid_hostsOptionVecString可选主机白名单list_inner正是把每个配置项的datacenter_label/name/public_url分别填入响应字段因此响应的url与peer_url的含义不同——url是面向外部的公开地址。配置默认值topology.rs包含一个名为default、is_leader: true、public_url指向本机 guard 默认端口的数据中心这也是本地默认部署下单条记录响应的来源。七、模型在 API 生态中的位置从 README.md 的模型清单可以看到DatacentersListResponse属于公开 API 的只读查询类响应模型与EnvoysListResponseGET /envoys、RunnersListResponseGET /runners并列构成集群资源清单类接口。它的上游是 DatacentersApi.datacenters_list下游嵌套 Datacenter 与 Pagination 两个模型。理解这一模型后你可以顺藤摸瓜地掌握 Rivet Actors 公开 API 中「列表类接口统一携带 pagination」「资源描述统一使用 label/name/url 三要素」的通用设计惯例。八、使用注意事项小结鉴权不可省略datacenters_list要求 Bearer Token未认证请求会被服务端ctx.auth()拦截api-public/src/datacenters.rs数据是静态快照响应来自拓扑配置而非实时数据库配置变更后需重新请求才能反映最新状态类型宽度差异SDK 中label: i32对应服务端u16在合法取值范围内可放心转换pagination字段需解析但暂无用当前恒为null游标客户端应容忍该字段存在协议兼容但不必实现分页循环逻辑字段严格性服务端#[serde(deny_unknown_fields)]意味着客户端若手工构造请求体携带未知字段将被拒绝反序列化响应时 SDK 同样遵循该结构约束。通过本文的梳理你可以将DatacentersListResponse直接用于自身的集群拓扑发现场景如选择url发起跨数据中心请求、用label做区域路由也能在排查问题时快速定位到 api-public/src/datacenters.rs 与 topology.rs 这两处关键实现。【免费下载链接】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），仅供参考 Rivet Actors `DatacentersListResponse` 模型深度解析：`GET /datacenters` 响应结构、Rust SDK 用法与服务端实现
Rivet ActorsDatacentersListResponse模型深度解析GET /datacenters响应结构、Rust SDK 用法与服务端实现【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actorsRivet Actors 为有状态工作负载AI Agent、协作应用、持久化执行提供了数据中心拓扑抽象而DatacentersListResponse正是其公开 API 中GET /datacenters端点的标准响应模型。本文以 DatacentersListResponse.md 为骨架结合仓库内 Rust SDK 生成源码与服务端 axum 实现完整讲解该模型的字段结构、嵌套类型、Rust 调用方式以及响应数据在服务端拓扑配置中的真实来源。读完本文你将能直接在自己的 Rust 项目中调用datacenters_list并正确解析多数据中心列表也能理解该响应在服务端是如何从配置构造出来的。一、模型概览响应体的两个核心字段DatacentersListResponse是 OpenAPI Generator 从服务端 OpenAPI 规范版本 2.3.14为GET /datacenters自动生成的 Rust 响应类型。它只包含两个字段且均为必填名称类型说明是否可选datacentersVecmodels::Datacenter数据中心列表必填paginationmodels::Pagination分页信息必填对应的 Rust 结构体定义位于 datacenters_list_response.rs源码通过serde属性把字段名直接映射为 JSON 键名#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)] pub struct DatacentersListResponse { #[serde(rename datacenters)] pub datacenters: Vecmodels::Datacenter, #[serde(rename pagination)] pub pagination: Boxmodels::Pagination, }一个典型的响应 JSON 示例如下{ datacenters: [ { label: 1, name: default, url: http://127.0.0.1:6080 } ], pagination: { cursor: null } }其中pagination被装箱为Boxmodels::Pagination这是生成代码的常见优化把可嵌套的大对象放在堆上减少结构体拷贝时的栈开销。SDK 还提供了便捷构造函数DatacentersListResponse::new(datacenters, pagination)见 datacenters_list_response.rs方便在测试或 mock 场景下手工构造响应。二、嵌套模型一Datacenter单数据中心描述datacenters数组的元素类型是Datacenter它描述单个数据中心的基本信息。字段定义如下见 Datacenter.md 与 datacenter.rs名称类型说明labeli32数据中心编号标签用于在集群内唯一定位某个 DCnameString数据中心名称urlString数据中心的公开访问地址pub struct Datacenter { #[serde(rename label)] pub label: i32, #[serde(rename name)] pub name: String, #[serde(rename url)] pub url: String, }值得注意的一个细节是类型宽度差异SDK 中label是i32而服务端共享类型 types/src/datacenters.rs 中对应字段label: u16拓扑配置 topology.rs 中同样是u16。这是 OpenAPI Generator 生成客户端时常见的类型放大行为服务端 u16 → 客户端 i32在实际使用中不会造成数据丢失。三、嵌套模型二Pagination游标分页pagination字段描述列表结果的分页状态见 Pagination.md 与 pagination.rs名称类型说明是否可选cursorOptionString分页游标可选pub struct Pagination { #[serde(rename cursor, default, with ::serde_with::rust::double_option, skip_serializing_if Option::is_none)] pub cursor: OptionOptionString, }这里使用了serde_with::rust::double_option双 Option 序列化策略外层Option表示字段缺失内层Option表示字段显式为null。这种设计可以严格区分「JSON 中没这个键」和「JSON 中这个键是 null」两种状态。当前版本中GET /datacenters返回的数据中心数量有限因此服务端总是返回cursor: None详见下文第四节但保留该字段保证了协议的前向兼容——未来数据中心数量增长需要分页时客户端无需改动解析逻辑。四、数据从哪来GET /datacenters端点与服务端实现DatacentersListResponse由公开 API 的datacenters_list方法返回。端点信息见 DatacentersApi.md方法HTTP 请求说明datacenters_listGET/datacenters获取全部数据中心请求参数无鉴权bearer_authBearer TokenAcceptapplication/json服务端实现位于 api-public/src/datacenters.rs路由在 router.rs 中以axum::routing::get(datacenters::list)注册。核心逻辑非常清晰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 }, }) }从源码可以提炼出三条关键实现事实鉴权前置ctx.auth().await?在构造响应前强制校验 Bearer Token未携带有效凭证的请求会走ApiError::from(err).into_response()返回错误响应这与 SDK 文档中标注的bearer_auth安全要求一一对应。数据来自静态拓扑配置响应不是查询数据库而是遍历ctx.config().topology().datacenters配置结构见 topology.rs把每个配置项的datacenter_label、name、public_url映射为响应中的label、name、url三个字段。也就是说GET /datacenters反映的是当前部署实例「认识」的所有数据中心而不是动态注册表。分页当前恒为空pagination.cursor始终为None配合Box装箱与double_option序列化策略JSON 输出中该字段通常呈现为cursor: null。服务端响应类型ListResponse的定义见 api-types/src/datacenters/list.rs它通过#[schema(as DatacentersListResponse)]声明自己在 OpenAPI 规范中的对外名称这正是生成 SDK 模型DatacentersListResponse的命名来源同时#[serde(deny_unknown_fields)]要求客户端发送未知字段时报错保证协议严格性。共享类型 types/src/datacenters.rs 中的Datacenter { label: u16, name: String, url: String }则是服务端与 SDK 之间契约的最终定义者。五、Rust SDK 实战调用datacenters_list5.1 引入依赖rivet-api-full是仓库内生成的 Rust 客户端API 版本 2.3.14见 README.md。将包放入项目目录后在Cargo.toml中声明路径依赖[dependencies] rivet-api-full { path ./rivet-api-full }生成包的 API 索引、模型清单与安装说明均可查阅 engine/sdks/rust/api-full/rust/README.md。5.2 构造配置并发起请求SDK 客户端函数签名定义在 apis/datacenters_api.rspub async fn datacenters_list( configuration: configuration::Configuration, ) - Resultmodels::DatacentersListResponse, ErrorDatacentersListError从生成源码可以看到请求的完整拼装过程datacenters_api.rs请求行GET {base_path}/datacenters其中base_path来自Configuration默认http://localhost附加User-Agent头若配置了user_agent附加Authorization: Bearer token若配置了bearer_access_token成功非 4xx/5xx时按Content-Type: application/json反序列化为DatacentersListResponse失败时封装为Error::ResponseError内含状态码、响应体与类型化错误枚举DatacentersListErrordatacenters_api.rs目前仅有UnknownValue兜底分支。实际调用示例use rivet_api_full::apis::{configuration::Configuration, datacenters_api}; #[tokio::main] async fn main() - Result(), Boxdyn std::error::Error { let mut config Configuration::new(); // 指向你的 Rivet Actors 部署实例 config.base_path https://api.example.com.to_string(); // 公开 API 需要 Bearer Token 鉴权对应服务端 ctx.auth() 校验 config.bearer_access_token Some(YOUR_TOKEN.to_string()); let resp datacenters_api::datacenters_list(config).await?; for dc in resp.datacenters { println!(label{} name{} url{}, dc.label, dc.name, dc.url); } // resp.pagination.cursor 当前恒为 None可直接忽略 Ok(()) }5.3 解析要点遍历resp.datacenters即可获得全部数据中心label可作为部署/调度场景中的机房标识resp.pagination虽然必填但当前版本恒返回cursor: None无需强制分页循环若收到Error::ResponseError说明服务端返回了 4xx/5xx例如 Token 缺失或过期可按response_content.status区分错误类型。六、服务端拓扑配置理解datacenters数据的源头要读懂响应内容需要了解服务端拓扑配置的结构。Topology配置类型定义在 topology.rspub struct Topology { /// Must be included in datacenters pub datacenter_label: u16, /// Map of all datacenters, including this datacenter. pub datacenters: DatacentersRepr, }单个数据中心配置项topology.rs包含配置字段类型说明nameString数据中心名称映射到响应namedatacenter_labelu16编号标签映射到响应labelis_leaderbool是否为领导数据中心用于调度选址public_urlUrl公开访问地址映射到响应urlpeer_urlUrl数据中心间 peer 通信地址proxy_urlOptionUrl可选代理地址valid_hostsOptionVecString可选主机白名单list_inner正是把每个配置项的datacenter_label/name/public_url分别填入响应字段因此响应的url与peer_url的含义不同——url是面向外部的公开地址。配置默认值topology.rs包含一个名为default、is_leader: true、public_url指向本机 guard 默认端口的数据中心这也是本地默认部署下单条记录响应的来源。七、模型在 API 生态中的位置从 README.md 的模型清单可以看到DatacentersListResponse属于公开 API 的只读查询类响应模型与EnvoysListResponseGET /envoys、RunnersListResponseGET /runners并列构成集群资源清单类接口。它的上游是 DatacentersApi.datacenters_list下游嵌套 Datacenter 与 Pagination 两个模型。理解这一模型后你可以顺藤摸瓜地掌握 Rivet Actors 公开 API 中「列表类接口统一携带 pagination」「资源描述统一使用 label/name/url 三要素」的通用设计惯例。八、使用注意事项小结鉴权不可省略datacenters_list要求 Bearer Token未认证请求会被服务端ctx.auth()拦截api-public/src/datacenters.rs数据是静态快照响应来自拓扑配置而非实时数据库配置变更后需重新请求才能反映最新状态类型宽度差异SDK 中label: i32对应服务端u16在合法取值范围内可放心转换pagination字段需解析但暂无用当前恒为null游标客户端应容忍该字段存在协议兼容但不必实现分页循环逻辑字段严格性服务端#[serde(deny_unknown_fields)]意味着客户端若手工构造请求体携带未知字段将被拒绝反序列化响应时 SDK 同样遵循该结构约束。通过本文的梳理你可以将DatacentersListResponse直接用于自身的集群拓扑发现场景如选择url发起跨数据中心请求、用label做区域路由也能在排查问题时快速定位到 api-public/src/datacenters.rs 与 topology.rs 这两处关键实现。【免费下载链接】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），仅供参考