Smithy 项目

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

Smithy 项目有两种类型：

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

提示

如果您想要一个带有实现的 API，请改用 ts#api 生成器。它会创建一个 Smithy 模型项目_以及_实现它的 TypeScript 服务器。

用法

生成 Smithy 项目

运行此生成器@aws/nx-plugin:smithy#project

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:smithy#project

yarn

$ yarn nx g @aws/nx-plugin:smithy#project

npm

$ npx nx g @aws/nx-plugin:smithy#project

bun

$ bunx nx g @aws/nx-plugin:smithy#project

VSCode

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

构建你的命令7

name必需

type

serviceshapes

directory

serviceName

namespace

subDirectory

preferInstallDependencies

true

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

选项

生成器选项7 个选项

name必需string

Smithy 项目名称

typeenum默认值: service

要创建的 Smithy 项目类型。可选择 service（包含服务形状的模型，可用于实现）或 shapes（可重用形状的形状库，在多个 Smithy 项目之间共享）。

serviceshapes

directorystring默认值: packages

Smithy 项目放置的父目录。

serviceNamestring

您的 Smithy 服务名称。默认使用提供的名称。不适用于形状库。

namespacestring

Smithy API 的命名空间。默认为你的 monorepo 作用域

subDirectorystring

Smithy 项目放置的子目录。默认为项目名称。

preferInstallDependenciesboolean默认值: true

是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

type = shapes

形状库

• 文件夹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 模型文件。

type = service

服务

• 文件夹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

pnpm nx build my-shapes

yarn

yarn nx build my-shapes

npm

npx nx build my-shapes

bun

bunx nx build my-shapes

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

依赖形状库

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

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

1. 将库的构建模型添加到消费项目的 smithy-build.json 中的 imports。路径相对于该文件，因此 ../ 段的数量与消费项目的嵌套深度相匹配 — 对于下面的 packages/my-api/model 是三个：

   {
     "version": "1.0",
     "sources": ["src/"],
     "imports": ["../../../dist/packages/my-shapes/build/model.json"],
     ...
   }

2. 将库的 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 会忽略重复但等效的形状定义。