Rivet API 数据模型解析DatacenterHealth 与数据中心健康度探测Fanout【免费下载链接】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 开源仓库中 DatacenterHealth 模型文档 为核心完整讲解该模型的字段结构、序列化规则以及它背后的GET /health/fanout健康度探测接口的实现原理。读完本文你将掌握 Rivet 多数据中心场景下健康状态的数据组织方式能够正确解析各 SDK 中返回的 DatacenterHealth 数据并理解服务端是如何并发探测各数据中心并汇总结果的。一、模型定位一次健康探测的“单数据中心结果”在 Rivet 的公开 APIrivet-api-public中DatacenterHealth并不是一个独立接口的返回体而是GET /health/fanout接口返回的 HealthFanoutResponse 中datacenters数组的单个元素类型。它的职责是描述对某一个具体数据中心的健康检查结果包括该数据中心的标识、健康状态、往返延迟RTT以及可选的详细响应或错误信息。从服务端源码看该结构在 engine/packages/api-public/src/health.rs 中定义如下#[derive(Debug, Serialize, Deserialize, ToSchema)] pub struct DatacenterHealth { pub datacenter_label: u16, pub datacenter_name: String, pub status: HealthStatus, pub rtt_ms: Optionf64, pub response: OptionHealthResponse, pub error: OptionString, }它被嵌套在FanoutResponse对外即HealthFanoutResponse中pub struct FanoutResponse { pub datacenters: VecDatacenterHealth, }也就是说一次/health/fanout调用会返回所有已配置数据中心的健康状态数组而数组中的每一项就是一个DatacenterHealth实例。二、字段完整说明下表完整继承了 DatacenterHealth.md 中的属性定义字段名类型说明是否必填datacenter_labeli32Rust SDK 为 i32服务端内部为 u16数据中心标签用于唯一标识某个数据中心必填datacenter_nameString数据中心名称必填errorOptionString探测失败时的错误信息可选responseOptionHealthResponse成功时的健康响应详情可选rtt_msOptionf64探测往返时延单位毫秒可选statusHealthStatus健康状态枚举必填字段间存在明显的组合关系可以归纳为两种结果形态成功形态status Ok同时携带response健康响应详情与rtt_ms往返时延error为None失败形态status Error同时携带error错误描述与rtt_msresponse为None。需要特别指出的是无论成功还是失败rtt_ms都会被填充见下文源码分析它代表这次探测实际消耗的时间因此不能仅凭rtt_ms是否存在来判断健康状态必须以status字段为准。2.1 关联类型HealthStatusstatus字段的类型是 HealthStatus 枚举序列化值如下枚举变体序列化值OkokErrorerror对应服务端定义health.rs使用了#[serde(rename_all snake_case)]因此 JSON 传输中为小写字符串ok/error。2.2 关联类型HealthResponse成功时的response字段类型为 HealthResponse包含三个必填字符串字段字段名类型说明runtimeString运行时标识statusString状态描述versionString版本号在服务端源码中本地数据中心探测会直接构造该响应runtime固定为engine、status固定为ok、version取编译时的CARGO_PKG_VERSION见 health.rs。三、SDK 中的序列化细节Rust / TypeScript / GoDatacenterHealth模型在多个官方 SDK 中均有对应实现理解各语言的命名与序列化映射有助于跨语言联调。3.1 Rust SDKRust 版本实现位于 engine/sdks/rust/api-full/rust/src/models/datacenter_health.rs由 OpenAPI Generator 生成特点如下所有字段使用#[serde(rename ...)]显式声明 JSON 字段名为snake_case三个可选字段error、response、rtt_ms使用serde_with::rust::double_option包裹并配合skip_serializing_if Option::is_none可区分字段缺失与显式 null两种语义提供了便捷构造函数new(datacenter_label, datacenter_name, status)可选字段默认置为None见 datacenter_health.rs。一个典型的 Rust 使用示例use rivet_api_public::models::{DatacenterHealth, HealthStatus}; // 构造 let health DatacenterHealth::new(1, us-east.to_string(), HealthStatus::Ok); // 反序列化JSON 字段为 snake_case let json r#{ datacenter_label: 1, datacenter_name: us-east, status: ok, rtt_ms: 12.5, response: { runtime: engine, status: ok, version: 2.3.14 } }#; let parsed: DatacenterHealth serde_json::from_str(json).expect(parse);3.2 TypeScript SDKTypeScript 版本位于 engine/sdks/typescript/api-full/src/api/types/DatacenterHealth.ts接口字段采用camelCase命名datacenterLabel、datacenterName、rttMs而序列化层 engine/sdks/typescript/api-full/src/serialization/types/DatacenterHealth.ts 通过core.serialization.property(rtt_ms, ...)将 camelCase 字段映射回 wire 格式的 snake_case保证与 HTTP JSON 报文一致。3.3 Go SDKGo 版本位于 engine/sdks/go/api-full/types.go字段同样以 snake_case JSON tag 暴露与 Rust / TypeScript 的传输格式保持一致。所有 SDK 的 schema 定义最终统一来源于 engine/artifacts/openapi.jsonDatacenterHealth组件位于其中这保证了跨语言的一致性。四、服务端实现/health/fanout 如何工作理解字段含义之后再来看服务端是如何产生这些数据的。核心逻辑位于 engine/packages/api-public/src/health.rs 的fanout/fanout_inner鉴权fanout_inner首先调用ctx.auth().await?要求调用方具备数据中心读取权限该接口在 OpenAPI 中声明了bearer_auth安全方案见 HealthApi.md。枚举数据中心从ctx.config().topology().datacenters读取全部已配置的数据中心逐个发起探测。本地数据中心直查如果某个数据中心的datacenter_label等于当前进程所属数据中心标签ctx.config().dc_label()则不走网络请求直接本地构造HealthResponse状态固定为Ok。远程数据中心 HTTP 探测对远程数据中心通过send_health_checks并发发起两个 HTTP GET 请求详见下文。并发扇出使用buffer_unordered(16)将全部数据中心的探测任务并发执行最多同时进行 16 个全部完成后汇总为VecDatacenterHealth返回。4.1 远程探测的细节send_health_checkshealth.rs对每个远程数据中心同时发起两个健康检查{peer_url}/health对等节点peer的健康端点{proxy_url}/health代理proxy的健康端点。两个请求通过tokio::try_join!并发执行各自带5 秒超时timeout(Duration::from_secs(5))。判定逻辑为peer检查必须成功非 2xx 即判定失败并bail!proxy检查成功后将其 JSON 响应解析为HealthResponse作为最终结果。失败时错误信息被记录到tracing::warn!日志并写入DatacenterHealth.error字段status置为Error。4.2 RTT 的度量方式无论本地还是远程每个数据中心的探测任务都会在开始时记录Instant::now()health.rs完成后用start.elapsed().as_secs_f64() * 1000.0计算毫秒级时延写入rtt_ms。因此rtt_ms反映的是包含网络往返在内的整体探测耗时可用于评估各数据中心的链路质量。五、调用方式与返回示例health_fanout接口定义见 HealthApi.mdHTTP 方法GET路径/health/fanout参数无鉴权Bearer Tokenbearer_authAcceptapplication/json返回类型HealthFanoutResponse一次典型的响应报文如下{ datacenters: [ { datacenter_label: 0, datacenter_name: local-dc, status: ok, rtt_ms: 0.023, response: { runtime: engine, status: ok, version: 2.3.14 } }, { datacenter_label: 1, datacenter_name: remote-dc-a, status: error, rtt_ms: 5120.4, error: Proxy health check returned status: 503 } ] }上例中第一个元素对应本地数据中心时延极低、直接本地构造第二个元素对应远程数据中心探测失败status errorrtt_ms接近 5 秒超时上限response为null。这也印证了前文的字段组合规律成功看response失败看error时延始终在rtt_ms。六、实用要点小结DatacenterHealth是/health/fanout返回数组中单个数据中心的健康快照必须与 HealthFanoutResponse 配合使用。判断健康与否只能看statusok/error不要依赖response或error是否存在来推断。rtt_ms成功失败都会返回接近 5 秒通常意味着远程探测超时。各 SDK 的 JSON 传输格式统一为snake_caseTypeScript 接口层使用 camelCase序列化层负责映射。服务端通过buffer_unordered(16)并发探测全部数据中心本地直查、远程走 peer/proxy 双端点各 5 秒超时实现细节可继续阅读 engine/packages/api-public/src/health.rs 及 OpenAPI 定义 中的DatacenterHealth组件。【免费下载链接】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），仅供参考