Rivet Actors Rust SDK 数据模型解析:Datacenter 与数据中心列表接口实战
Rivet Actors Rust SDK 数据模型解析:Datacenter 与数据中心列表接口实战
导读
本文围绕 Rivet Actors 官方 Rust SDK(rivet-api-public 生成客户端)中的 Datacenter 数据模型展开,完整讲解 Datacenter 的三个字段(label、name、url)及与之配套的 DatacentersApi::datacenters_list 接口、DatacentersListResponse 响应结构,并结合仓库中的服务端实现(api-public、config 拓扑配置、健康检查扇出)与源码级调用链,帮助你理解数据中心在 Rivet 多区域架构中的实际含义,并掌握在 Rust 中查询可用数据中心清单的完整写法。
一、Datacenter 模型:Rust SDK 中的数据结构
Datacenter 是 Rivet 开放 API 中用于描述一个数据中心(region)的基础模型,由 OpenAPI Generator 从服务端 schema 自动生成,其完整定义位于 engine/sdks/rust/api-full/rust/docs/Datacenter.md。
1.1 属性一览
| 名称 | 类型 | 说明 |
|---|---|---|
label |
i32 |
数据中心数值标识符,在整个集群拓扑内唯一 |
name |
String |
数据中心名称(人类可读的标识) |
url |
String |
数据中心对外服务的公网地址(public origin) |
对应的 Rust 结构体实现在 engine/sdks/rust/api-full/rust/src/models/datacenter.rs:
#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)]
pub struct Datacenter {
#[serde(rename = "label")]
pub label: i32,
#[serde(rename = "name")]
pub name: String,
#[serde(rename = "url")]
pub url: String,
}
impl Datacenter {
pub fn new(label: i32, name: String, url: String) -> Datacenter {
Datacenter { label, name, url }
}
}
从源码结构可以看到,该模型直接对应服务端 engine/packages/types/src/datacenters.rs 中的核心类型:
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
#[serde(deny_unknown_fields)]
pub struct Datacenter {
pub label: u16,
pub name: String,
pub url: String,
}
SDK 侧将服务端的 u16 展开为 i32,其余字段一一对应,并通过 #[serde(rename = "...")] 保证 JSON 序列化字段名与服务端完全一致。
1.2 字段含义:从拓扑配置到 API 响应
label、name、url 并非随意设计的抽象字段,它们直接映射到服务端的拓扑配置。在 engine/packages/config/src/config/topology.rs 中,每个数据中心的内部配置结构体包含更丰富的字段:
pub struct Datacenter {
pub name: String,
pub datacenter_label: u16,
pub is_leader: bool,
/// Public origin that can be used to connect to this region.
pub public_url: Url,
/// URL of the api-peer service
pub peer_url: Url,
/// URL of the guard service that other datacenters can access privately...
pub proxy_url: Option<Url>,
#[serde(default)]
pub valid_hosts: Option<Vec<String>>,
}
服务端将内部配置转换为 API 响应时(见下文 list_inner),只暴露其中三个对外字段:label ← datacenter_label、name ← name、url ← public_url.to_string()。也就是说:
label:内部拓扑中的datacenter_label,是路由、健康检查、Actor 归属判定等场景使用的唯一数值标识;name:配置中声明的数据中心名,通常用于日志与人工辨识;url:数据中心的公网入口地址(public_url),客户端可通过它连接该区域。
提示:从源码结构可以推断,
url的取值来自public_url,即"对外可连接该区域的公网 origin",与内部通信用的peer_url(api-peer 服务地址)和proxy_url(guard 服务私有地址)是两个不同的概念。
二、DatacentersApi:查询数据中心列表
Datacenter 模型本身只描述数据结构,真正消费它的是 DatacentersApi。该 API 的完整方法清单定义在 engine/sdks/rust/api-full/rust/docs/DatacentersApi.md。
2.1 接口定义
| 方法 | HTTP 请求 | 说明 |
|---|---|---|
datacenters_list() |
GET /datacenters |
列出全部可用数据中心 |
接口特征:
- Base URL:所有 URI 均相对于
http://localhost(实际使用时通过Configuration::base_path覆盖); - 参数:
datacenters_list不需要任何参数; - 返回类型:
models::DatacentersListResponse; - 鉴权:
bearer_auth(需要携带 Bearer Token); - 请求头:无 Content-Type;Accept 为
application/json。
2.2 Rust 客户端的实际实现
SDK 客户端方法实现在 engine/sdks/rust/api-full/rust/src/apis/datacenters_api.rs,其核心逻辑可以概括为:
pub async fn datacenters_list(
configuration: &configuration::Configuration,
) -> Result<models::DatacentersListResponse, Error<DatacentersListError>> {
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());
};
// ... 发送请求,按 status 区分成功与错误,JSON 反序列化为 DatacentersListResponse
}
从实现可以看出:这是一个无查询参数的 GET 请求,鉴权通过 Authorization: Bearer <token> 头完成;2xx 响应体按 application/json 反序列化为 DatacentersListResponse,非 2xx 则包装为 Error::ResponseError,类型化错误枚举为 DatacentersListError。
2.3 响应结构 DatacentersListResponse
GET /datacenters 的响应体模型为 DatacentersListResponse,定义见 engine/sdks/rust/api-full/rust/docs/DatacentersListResponse.md:
| 名称 | 类型 | 说明 |
|---|---|---|
datacenters |
Vec<models::Datacenter> |
数据中心数组 |
pagination |
models::Pagination |
分页信息 |
其 Rust 结构体在 engine/sdks/rust/api-full/rust/src/models/datacenters_list_response.rs:
#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)]
pub struct DatacentersListResponse {
#[serde(rename = "datacenters")]
pub datacenters: Vec<models::Datacenter>,
#[serde(rename = "pagination")]
pub pagination: Box<models::Pagination>,
}
注意:尽管响应中携带 pagination 字段,但从服务端实现看,该接口当前固定返回 Pagination { cursor: None }(单页返回全部数据中心),分页字段属于响应契约的通用结构预留。
三、服务端实现:GET /datacenters 的完整调用链
3.1 路由注册
/datacenters 路由在 engine/packages/api-public/src/router.rs 中注册:
.route("/datacenters", axum::routing::get(datacenters::list))
即由 datacenters::list 处理器承载该 GET 端点。
3.2 处理器与数据来源
核心实现在 engine/packages/api-public/src/datacenters.rs:
#[utoipa::path(
get,
operation_id = "datacenters_list",
path = "/datacenters",
responses((status = 200, body = ListResponse)),
security(("bearer_auth" = [])),
)]
pub async fn list(Extension(ctx): Extension<ApiCtx>) -> Response { ... }
async fn list_inner(ctx: ApiCtx) -> Result<ListResponse> {
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 },
})
}
这条调用链完整回答了"Datacenter 数据从哪来":
ctx.auth().await?—— 执行 Bearer 鉴权(与 SDK 文档中bearer_auth的声明一致);ctx.config().topology().datacenters—— 直接读取本地配置中的拓扑(Topology),遍历全部数据中心;- 每个配置项经投影转换,得到对外暴露的三字段
Datacenter。
响应体的类型层定义在 engine/packages/api-types/src/datacenters/list.rs:
#[derive(Serialize, Deserialize, ToSchema)]
#[serde(deny_unknown_fields)]
#[schema(as = DatacentersListResponse)]
pub struct ListResponse {
pub datacenters: Vec<rivet_types::datacenters::Datacenter>,
pub pagination: Pagination,
}
3.3 拓扑配置与 label 的语义
Topology 结构(engine/packages/config/src/config/topology.rs)约束如下:
datacenter_label:本实例所属数据中心的 label,必须包含在datacenters列表中;datacenters:包含本数据中心在内的全部数据中心集合;- 每个数据中心配置还包含
is_leader(是否为主数据中心)、peer_url、proxy_url、valid_hosts等内部字段。
配置解析支持两种写法:Hash 映射(HashMap<String, Datacenter>,name 从 key 派生)或 List(已废弃)。因此 GET /datacenters 返回的 label 集合,本质上就是整个部署拓扑中所有 datacenter_label 的枚举,客户端可据此了解当前环境有哪些可用的区域。
四、实战:在 Rust 中调用 datacenters_list
结合上文接口与模型,一个完整的最小可运行示例(基于生成的 SDK,依赖 reqwest/tokio)如下:
use rivet_api_full::apis::{configuration::Configuration, datacenters_api};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// 1. 构造配置:base_path 指向你的 Rivet API 地址,并携带 Bearer Token
let mut configuration = Configuration::new();
configuration.base_path = "https://api.example.com".to_string();
configuration.bearer_access_token = Some(std::env::var("RIVET_TOKEN")?);
// 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(())
}
4.1 典型用法
- 区域选择:将
label作为后续 Actor 创建 / 调度请求中的区域参数,例如搭配ActorsCreateApi指定在哪个数据中心启动有状态 Actor; - 多区域拓扑巡检:将
url用于构建到各区域的自定义健康探测(详见下文 DatacenterHealth 与/health/fanout); - 运维展示:将
name用于控制台、日志中的区域别名展示。
说明:
GET /datacenters返回的是"配置声明中存在"的数据中心;要了解各区域当前的运行健康状态与 RTT,应使用HealthApi::health_fanout(GET /health/fanout,返回Vec<DatacenterHealth>)。
五、延伸:DatacenterHealth 与数据中心健康扇出
与 Datacenter 密切相关的模型是 DatacenterHealth(engine/sdks/rust/api-full/rust/docs/DatacenterHealth.md),它描述单个数据中心的健康探测结果:
| 名称 | 类型 | 说明 |
|---|---|---|
datacenter_label |
i32 |
数据中心 label |
datacenter_name |
String |
数据中心名称 |
error |
Option<String> |
探测失败时的错误信息(可选) |
response |
Option<HealthResponse> |
健康探测的响应体(可选) |
rtt_ms |
Option<f64> |
往返时延(毫秒,可选) |
status |
HealthStatus |
健康状态(ok / error) |
服务端对应实现在 engine/packages/api-public/src/health.rs,其 fanout_inner 揭示了底层原理:
- 遍历
ctx.config().topology().datacenters中全部数据中心; - 本地数据中心(
dc.datacenter_label == ctx.config().dc_label())直接返回本地HealthResponse { runtime: "engine", status: "ok", version: env!("CARGO_PKG_VERSION") }; - 远程数据中心并发(
buffer_unordered(16))发起 HTTP 探测,send_health_checks同时请求peer_url + /health与proxy_url() + /health,各带 5 秒超时,任一失败即标记HealthStatus::Error并记录error字段; - 每次探测记录
rtt_ms(从发起请求到拿到结果的实际耗时)。
由此可见,Datacenter 的 label/name/url 三字段在多数据中心健康检查中同样承担关键角色:label 用于本地/远程判定,name 用于结果标识,url 体系(peer_url/proxy_url)用于实际探测。
另外,engine/packages/datacenter/src/ops/list_by_ping.rs 展示了数据中心的另一种消费方式:内部服务按 RTT 对数据中心排序(排除本区域后从缓存读取 LastRttKey,本地区域 RTT 记为 0),用于智能选择延迟最低的区域——这与开放 API 中只暴露静态拓扑信息的 Datacenter 模型形成互补:前者给客户端"有哪些区域",后者给内部调度"该优先用哪个区域"。
六、使用前提与限制
- 鉴权要求:
datacenters_list需要bearer_auth,未携带有效 Token 会返回 401 类错误;服务端通过ctx.auth().await?强制校验。 - 数据来源为静态拓扑:返回内容直接来自服务端
config.topology().datacenters,反映的是配置声明而非实时网络探测结果;需要实时状态请使用健康扇出接口。 - 字段投影:内部配置中的
is_leader、peer_url、proxy_url、valid_hosts等字段不会出现在Datacenter响应中,公开契约仅保留label、name、url。 - 分页字段:当前实现固定返回
Pagination { cursor: None },即一次返回全部数据中心;但响应类型已预留pagination结构,调用方应保持向后兼容的处理方式。 - 版本约束:SDK 由 OpenAPI 文档(版本 2.3.14)生成,字段序列化名称以
serde(rename = ...)标注为准,升级 SDK 时注意字段名不变、类型可能有u16/i32的宽化差异。
总结
Datacenter 是 Rivet Actors Rust SDK 中最基础也最实用的模型之一:label 提供区域唯一标识、name 提供可读名称、url 提供对外连接地址。配合 DatacentersApi::datacenters_list(GET /datacenters),开发者可以在 Rust 应用中一行配置即可枚举当前环境全部数据中心;再结合 DatacenterHealth 与 /health/fanout,即可构建"区域感知"的多数据中心客户端逻辑。无论你是为 Actor 选择就近调度区域,还是构建跨区域拓扑监控,理解这份模型及其背后的拓扑配置与健康扇出实现,都是用好 Rivet 多区域能力的第一步。