Smithy 项目

Smithy 是一种用于描述服务及其交换数据的接口定义语言。Smithy 项目生成器创建一个包含 Smithy 模型的项目。

Smithy 项目有两种类型：

服务 (--type=service) — 定义服务及其操作的模型。这是 ts#api --framework=smithy 生成器为您创建的内容，同时还包含 TypeScript 实现。
形状库 (--type=shapes) — 定义可重用形状但不包含服务的模型。将形状库连接到您的 Smithy 项目以在它们之间共享形状，而不是在每个项目中重复定义。

用法

生成 Smithy 项目

CLI
VSCode

pnpm nx g @aws/nx-plugin:smithy#project --name=my-shapes

yarn nx g @aws/nx-plugin:smithy#project --name=my-shapes

npx nx g @aws/nx-plugin:smithy#project --name=my-shapes

bunx nx g @aws/nx-plugin:smithy#project --name=my-shapes

您还可以执行试运行以查看哪些文件会被更改

pnpm nx g @aws/nx-plugin:smithy#project --name=my-shapes --dry-run

yarn nx g @aws/nx-plugin:smithy#project --name=my-shapes --dry-run

npx nx g @aws/nx-plugin:smithy#project --name=my-shapes --dry-run

bunx nx g @aws/nx-plugin:smithy#project --name=my-shapes --dry-run

安装 Nx Console VSCode Plugin 如果您尚未安装
在VSCode中打开Nx控制台
点击 Generate (UI) 在"Common Nx Commands"部分
搜索 @aws/nx-plugin - smithy#project
填写必需参数
- name: my-shapes
点击 Generate

选项

参数	类型	默认值	描述
name 必需	string	-	Smithy 项目名称
type	service \| shapes	service	要创建的 Smithy 项目类型。可选择 service（包含服务形状的模型，可用于实现）或 shapes（可重用形状的形状库，在多个 Smithy 项目之间共享）。
serviceName	string	-	您的 Smithy 服务名称。默认使用提供的名称。不适用于形状库。
namespace	string	-	Smithy API 的命名空间。默认为你的 monorepo 作用域
directory	string	packages	Smithy 项目放置的父目录。
subDirectory	string	-	Smithy 项目放置的子目录。默认为项目名称。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

形状库

文件夹my-shapes
- 文件夹src
  - main.smithy Your shared shape definitions
- smithy-build.json Smithy build configuration
- project.json Project configuration and build targets

形状库仅定义形状，不包含其他内容：

$version: "2.0"

namespace com.example

structure Customer {
    @required
    id: String

    name: String
    email: String
}

由于形状库没有服务，其 smithy-build.json 不配置代码生成 — 构建它会验证模型并将其组装成位于 dist/<my-shapes>/build/model.json 的单个 JSON 模型文件。

服务

文件夹my-service
- 文件夹src
  - main.smithy Your service definition
  - 文件夹operations
    echo.smithy An example operation
- smithy-build.json Smithy build configuration, including code generation
- ssdk.rolldown.config.mjs Bundles the generated TypeScript Server SDK
- project.json Project configuration and build targets

服务模型定义一个服务形状及其公开的操作：

$version: "2.0"

namespace com.example

use aws.protocols#restJson1

@title("MyService")
@restJson1
service MyService {
    version: "1.0.0"
    operations: [
        Echo
    ]
}

构建服务项目会生成 OpenAPI 规范和 TypeScript Server SDK 到 dist/<my-service>/build/。

构建

Smithy 项目使用 Smithy CLI 构建，它会验证您的模型：

pnpm nx build my-shapes

yarn nx build my-shapes

npx nx build my-shapes

bunx nx build my-shapes

在 macOS 和 Linux 上，CLI 由 mise 解析，构建会按需获取它，因此无需安装任何东西 — 它会在您第一次构建时下载并缓存固定版本。在 Windows 上，它是您需要自行安装的先决条件 — 请参阅在 Windows 上构建。

依赖形状库

构建形状库会将组装的模型写入 dist/<my-shapes>/build/model.json。这个单一文件包含库定义的每个形状，以及它依赖的任何形状，因此消费者只需声明它直接引用的库。

要从另一个 Smithy 项目依赖形状库，需要对消费项目进行两处更改：

将库的构建模型添加到消费项目的 smithy-build.json 中的 imports。路径相对于该文件，因此 ../ 段的数量与消费项目的嵌套深度相匹配 — 对于下面的 packages/my-api/model 是三个：
```
{
  "version": "1.0",
  "sources": ["src/"],
  "imports": ["../../../dist/packages/my-shapes/build/model.json"],
  ...
}
```
将库的 build 目标添加为消费项目的 project.json 中 compile 目标的依赖项，以便在消费者构建之前模型已存在：
```
{
  "targets": {
    "compile": {
      "dependsOn": ["@my-scope/my-shapes:build"],
      ...
    }
  }
}
```

您的模型现在可以使用 use 引用库的形状：

$version: "2.0"

namespace com.example.api

use com.example.shared#Customer

structure GetCustomerOutput {
    @required
    customer: Customer
}

形状库可以以相同的方式依赖其他形状库。由于每个库的构建模型已经包含其自己的依赖项，您只需要对直接引用的库重复这些步骤。通过多个路径到达的库只会解析一次 — Smithy 会忽略重复但等效的形状定义。