smithy-bindgen

该crate提供用于从smithy接口生成Rust绑定的宏。对于大多数使用smithy接口生成Rust源代码的场景，这可以消除对 build.rs 和 codegen.toml 文件 的需求。codegen.toml 仍需要生成其他语言的绑定。

欢迎反馈！

这是代码生成宏的第一版，受 wit-bindgen 启发。如果您使用了 codegen.toml，请告诉我们这个宏是否可以作为替代品使用。（一个已知的遗漏：此宏中尚不可用 params 设置，来自 codegen.toml）未来可能引入其他变体：用于特定actor的接口、特定提供者的接口等。

快速入门

建议在 mod 声明内部使用 smithy_bindgen! 宏，或者在一个独立的Rust源文件中单独使用，以避免与您的代码发生符号冲突。

如果您使用的是wasmcloud的一方接口，您可以指定其路径名称（相对于wasmcloud/interfaces仓库），然后指定其命名空间

// [dependencies]
// smithy-bindgen = "0.1"

mod httpserver {
  smithy_bindgen::smithy_bindgen!("httpserver/httpserver.smithy","org.wasmcloud.interfaces.httpserver");
}
use httpserver::{HttpRequest,HttpResponse};

如果您在本地定义了smithy接口，您可以加载它

mod amazing_foo {
  smithy_bindgen::smithy_bindgen!(
     { path: "./amazing_foo.smithy" }, "org.example.interfaces.foo"
  );
}
use amazing_foo::{Bazinga, Wowza};

以下列出了其他语法形式。

注意 这并不替换wasmCloud接口crate的所有功能。一些wasmCloud接口crate包含一些不是smithy文件的一部分的手动生成的辅助函数。例如，wasmcloud-interface-httpserver 包含 impl Default 和一些 HttpResponse 构造函数。这些不是由 smithy_bindgen! 生成的。我们计划将这些额外的辅助函数移入未来的wasmcloud SDK中。

语法

宏smithy_bindgen!的第一个参数可以采用三种形式之一。第二个参数是用于代码生成的命名空间。

• 一个wasmcloud第一方接口

  单文件参数是相对于wasmcloud接口git仓库的相对路径 wasmcloud/interfaces

  smithy_bindgen!("httpserver/httpserver.smithy", "org.wasmcloud.interfaces.httpserver");
  

  上述是以下内容的简写

  smithy_bindgen!({
    url: "https://cdn.jsdelivr.net.cn/gh/wasmcloud/interfaces",
    files: ["httpserver/httpserver.smithy"]
  }, "org.wasmcloud.interfaces.httpserver" );
  

• 一个模型源

  smithy-bindgen!({
    path: "../interfaces/foo.smithy",
  }, "org.example.interfaces.foo" );
  

• 模型源数组

  smithy-bindgen!([
    { path: "../interfaces/foo.smithy" },
    { url: "keyvalue/keyvalue.smithy" },
  ], "org.example.interfaces.foo" );
  

模型源规范

模型源包含一个url，用于http(s)下载，或一个path，用于本地文件系统访问，作为基础，加上files，一个可选的文件路径列表，它附加到基础上以构建完整的URL下载路径和本地文件路径。在连接来自files数组的子路径时，根据需要插入或删除'/'，以确保在基础和子路径之间恰好有一个。 url必须以'http://'或'https://'开始。如果path是相对文件系统路径，则相对于包含Cargo.toml的文件夹。如果url或path包含.smithy文件的完整路径，则可以省略files。

以下所有都是（语法上）有效的模型源

{ url: "https://example.com/interfaces/foo.smithy" }
{ url: "https://example.com/interfaces", files: [ "foo.smithy", "bar.smithy" ]}
{ path: "../interfaces/foo.smithy" }
{ path: "../interfaces", files: ["foo.smithy", "bar.smithy"]}

这些都是等效的

{ path: "/usr/share/interfaces/timer.smithy" }
{ path: "/usr/share/interfaces", files: [ "timer.smithy" ] }
{ path: "/usr/share/interfaces/", files: [ "timer.smithy" ] }

如果一个模型源结构不包含URL基础和路径基础，则使用github wasmcloud接口仓库的URL

url: "https://cdn.jsdelivr.net.cn/gh/wasmcloud/interfaces"

为什么代码生成器需要加载多个smithy文件？这样接口就可以共享数据结构中的公共符号。大多数smithy接口已经从命名空间org.wasmcloud.model导入符号，该命名空间定义在wasmcloud-model.smithy中。bindgen工具通过组装来自所有smithy源和命名空间的内存中的模式模型来解析所有符号，然后遍历内存中的模型，只为在smithy_bindgen!的第二个参数中声明的命名空间中的模式元素生成代码。

jsdelivr.net URLs

cdn.jsdelivr.net镜像开源github仓库。URL语法可以可选地包含github分支、标签或commit sha。

常见文件

在编译模型时始终自动包含Wasmcloud常见模型文件（如果您使用过codegen.toml文件，您可能记得它们要求显式指定所有基础模型。）

命名空间

模型可以通过使用use命令包含在其他模型中定义的符号。只有命名空间中定义的符号（smithy_bindgen!的第二个参数）将包含在生成的代码中。