Smithy 项目

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

Smithy 项目有两种类型：

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

用法

生成 Smithy 项目

VSCode
CLI

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

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

选项

参数	类型	默认值	描述
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 您的共享形状定义
- smithy-build.json Smithy 构建配置
- build.Dockerfile 构建和验证模型
- project.json 项目配置和构建目标

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

$version: "2.0"

namespace com.example

structure Customer {
    @required
    id: String

    name: String
    email: String
}

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

服务

文件夹my-service
- 文件夹src
  - main.smithy 您的服务定义
  - 文件夹operations
    echo.smithy 示例操作
- smithy-build.json Smithy 构建配置，包括代码生成
- build.Dockerfile 构建模型、OpenAPI 规范和 TypeScript Server SDK
- project.json 项目配置和构建目标

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

$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 项目使用 Docker 进行构建，它运行 Smithy CLI 来验证您的模型：

pnpm nx build my-shapes

yarn nx build my-shapes

npx nx build my-shapes

bunx nx build my-shapes

依赖形状库

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

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

Smithy 项目在容器内构建，构建时会将工作区根目录作为命名构建上下文提供。在消费项目的 build.Dockerfile 中添加 COPY，与复制其自身源代码的位置并列：
```
# Copy project files
COPY smithy-build.json .
COPY src src
COPY --from=workspace dist/packages/my-shapes/build/model/model.json deps/my-shapes.json
```

将复制的文件添加到消费项目的 smithy-build.json 中的 imports：

{
  "version": "1.0",
  "sources": ["src/"],
  "imports": ["deps/my-shapes.json"],
  ...
}

将库的 build 目标添加为消费项目的 compile 目标的依赖项（在其 project.json 中），以便在消费者构建之前模型已存在：
```
{
  "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 会忽略重复但等效的形状定义。