Rivet Actors Rust SDK 解析NamespacesCreateResponse 响应模型与命名空间创建完整链路【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创建命名空间Namespace是使用 Rivet Actors 前必须理解的基础操作。本文以 Rust SDK 中NamespacesCreateResponse响应模型为切入点完整梳理其字段结构、与NamespacesCreateRequest的配对关系、POST /namespaces端点的服务端实现链路以及仓库中对应的集成测试帮助你在调用namespaces_create时准确解析返回值并理解其底层行为。一、NamespacesCreateResponse 模型概览NamespacesCreateResponse是POST /namespaces创建命名空间接口的响应体模型在 Rust SDK 中定义于 engine/sdks/rust/api-full/rust/src/models/namespaces_create_response.rsuse crate::models; use serde::{Deserialize, Serialize}; #[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)] pub struct NamespacesCreateResponse { #[serde(rename namespace)] pub namespace: Boxmodels::Namespace, } impl NamespacesCreateResponse { pub fn new(namespace: models::Namespace) - NamespacesCreateResponse { NamespacesCreateResponse { namespace: Box::new(namespace), } } }该模型仅有一个字段含义如下字段类型说明备注namespacemodels::Namespace创建成功后的命名空间完整对象必填序列化名称为namespace由Box包裹从派生 trait 可以看出该模型实现了Serialize/Deserialize可无缝对接 HTTP JSON 序列化与反序列化、Clone可安全传递、Debug便于日志打印、PartialEq便于测试断言等标准能力。Default派生的存在意味着在模型未填充完整时也可以构造默认实例但实际使用时请务必填充namespace字段。二、namespace 字段Namespace 对象详解响应中namespace字段承载了创建结果的全部信息Namespace模型定义于 engine/sdks/rust/api-full/rust/src/models/namespace.rs#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)] 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, }该对象包含四个字段字段类型说明create_tsi64命名空间的创建时间戳Unix 时间秒级可用于排序与分页游标display_nameString命名空间的展示名称用于界面展示可包含空格、Unicode 字符长度可较长nameString命名空间的唯一标识名遵循 DNS 子域命名规则全小写、可含数字与连字符namespace_idString命名空间的全局唯一 ID由服务端生成形如ns_datacenter_random带数据中心标签create_ts作为i64时间戳不仅在响应中供客户端展示服务端在namespaces_list接口中还会用它作为游标分页的排序依据见 engine/packages/api-peer/src/namespaces.rs 中list实现取末位命名空间的create_ts作为下一页cursor。三、配套请求模型NamespacesCreateRequest要理解响应模型必须同时掌握其请求配对。NamespacesCreateRequest定义于 engine/sdks/rust/api-full/rust/src/models/namespaces_create_request.rs#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)] pub struct NamespacesCreateRequest { #[serde(rename display_name)] pub display_name: String, #[serde(rename name)] pub name: String, }请求体仅需两个字段字段类型必填说明nameString是命名空间唯一名必须符合 DNS 子域规则小写字母、数字、连字符1~63 字符display_nameString是展示名称不能为空但可包含任意文本包括 Unicode从服务端结构体看CreateRequest标注了#[serde(deny_unknown_fields)]见 engine/packages/api-peer/src/namespaces.rs即请求中出现未知字段会直接报错客户端务必严格按模型传参。四、端点定义与调用方式4.1 API 端点NamespacesCreateResponse对应POST /namespaces端点完整端点说明见 engine/sdks/rust/api-full/rust/docs/NamespacesApi.md方法HTTP 请求说明namespaces_createPOST /namespaces创建命名空间namespaces_listGET /namespaces列出命名空间支持 limit、cursor、name、namespace_id 过滤namespaces_create的签名、鉴权与请求头信息如下函数签名models::NamespacesCreateResponse namespaces_create(namespaces_create_request)请求参数NamespacesCreateRequest必填返回类型NamespacesCreateResponse鉴权方式bearer_authBearer TokenContent-Typeapplication/jsonAcceptapplication/json4.2 HTTP 调用示例基于端点的 HTTP 语义可构造如下请求以localhost为例curl -X POST http://localhost/namespaces \ -H Authorization: Bearer YOUR_TOKEN \ -H Content-Type: application/json \ -d { name: my-first-namespace, display_name: My First Namespace }成功响应HTTP 200{ namespace: { namespace_id: ns_dc1_xxxxxxxxxxxxxxxx, name: my-first-namespace, display_name: My First Namespace, create_ts: 1758000000 } }4.3 Rust 端调用在 Rust 侧构造请求模型并调用NamespacesApi随后从响应中取出namespace对象即可use rivet_api::apis::namespaces_api; use rivet_api::models::{NamespacesCreateRequest, NamespacesCreateResponse}; let req NamespacesCreateRequest::new( My First Namespace.to_string(), // display_name my-first-namespace.to_string(), // name ); // 调用 namespaces_create返回 NamespacesCreateResponse let resp: NamespacesCreateResponse namespaces_api.namespaces_create(req).await?; let ns resp.namespace; println!(namespace_id: {}, ns.namespace_id); println!(name: {}, ns.name); println!(display_name: {}, ns.display_name); println!(create_ts: {}, ns.create_ts);五、服务端实现链路从 HTTP 到持久化5.1 API 网关层POST /namespaces的网关处理器位于 engine/packages/api-public/src/namespaces.rs。create处理器接收CreateRequest后调用create_inner其核心逻辑为首先执行ctx.auth().await?完成 Bearer Token 鉴权若当前数据中心是 Leader则直接调用rivet_api_peer::namespaces::create在本 DC 内完成创建若当前数据中心是 Follower则通过request_remote_datacenter将请求转发到 Leader 数据中心的POST /namespaces端点实现跨数据中心路由。该处理器同样以#[utoipa::path]注解生成 OpenAPI 文档与 SDK 中自动生成的模型文档保持一致这也解释了NamespacesCreateResponse.md这类文档的来源——它们由 OpenAPI Generator 依据服务端注解自动生成。5.2 核心业务层真正执行创建逻辑的是 engine/packages/api-peer/src/namespaces.rs 中的create函数其流程如下生成 ID调用Id::new_v1(ctx.config().dc_label())生成带数据中心标签的命名空间 ID保证全局唯一且可追溯到创建者 DC订阅事件分别订阅namespace::workflows::namespace::CreateComplete与Failed两个工作流事件分发工作流将namespace_id、name、display_name封装为Input派发到命名空间创建工作流并打上namespace_id标签等待结果通过tokio::select!竞争等待创建完成或失败事件失败时返回对应错误回读并返回创建成功后调用namespace::ops::get_local回读刚创建的命名空间包装为CreateResponse { namespace }返回。可见NamespacesCreateResponse中的namespace对象并非客户端提交的简单回显而是服务端工作流落库后回读的权威数据因此namespace_id与create_ts一定由服务端生成并填充。六、测试验证响应模型的边界行为仓库为命名空间创建提供了详尽的集成测试见 engine/packages/engine/tests/runner/api_namespaces_create.rs。这些测试同时验证了响应模型的字段完整性与服务端约束测试用例验证内容create_namespace_success创建成功后namespace.name与display_name与请求一致create_namespace_validates_returned_data响应中namespace_id非空、name/display_name正确、create_ts 0create_namespace_generates_unique_ids连续创建 5 个命名空间namespace_id全部唯一create_namespace_persists_data创建后可经namespaces_list按name查询回同一命名空间证明数据已持久化create_namespace_duplicate_name_fails重复name创建报错create_namespace_empty_name_fails/create_namespace_empty_display_name_fails空name/ 空display_name均失败create_namespace_invalid_special_charsname含下划线、空格、、点、斜杠均失败create_namespace_invalid_uppercasename含大写字母失败create_namespace_min_length_name/create_namespace_max_length_name单字符最小长度与 63 字符DNS 子域标签最大长度均通过create_namespace_from_leader/create_namespace_from_follower_routes_to_leader无论从 Leader 还是 Follower DC 调用返回的namespace_id都带 Leader DC 标签验证跨 DC 路由正确性create_namespace_with_long_display_name100 字符的display_name可正常往返display_name不受 DNS 名称规则限制create_namespace_with_unicode_display_name中文、emoji、西里尔文等 Unicodedisplay_name可正常保存与返回七、实战要点总结namespace_id由服务端生成客户端不应自行构造或假设 ID 格式应以响应中的namespace_id为准后续对命名空间内 Actor 的操作都会引用该 IDname与display_name分工明确name是系统级的唯一标识DNS 子域规则全小写、1~63 字符、仅字母数字连字符display_name是面向用户的展示文本允许 Unicode、允许较长创建失败时优先检查name是否符合命名规则响应可用PartialEq直接断言测试代码大量使用assert_eq!(response.namespace.name, ...)模式你在自己的单元测试中同样可以借助派生的PartialEq简化断言跨 DC 时关注 Leader 标签从 Follower DC 发起创建时请求会被内部转发至 Leader返回的namespace_id带 Leader DC 标签这是判断命名空间实际归属的有效手段模型文档的生成来源NamespacesCreateResponse.md属于 OpenAPI Generator 自动生成的模型参考文档与之配套的完整端点文档见 NamespacesApi.mdREADME 概览见 engine/sdks/rust/api-full/rust/README.md。掌握NamespacesCreateResponse的结构与创建链路后你就可以准确解析namespaces_create的返回值并在多数据中心部署中正确理解命名空间的归属与一致性语义。【免费下载链接】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），仅供参考