Projetos Smithy

Smithy é uma linguagem de definição de interface para descrever serviços e os dados que eles trocam. O gerador de projetos Smithy cria um projeto contendo um modelo Smithy.

Existem dois tipos de projeto Smithy:

Serviço (--type=service) — um modelo que define um serviço e suas operações. Isso é o que o gerador ts#api --framework=smithy cria para você junto com uma implementação TypeScript.
Biblioteca de formas (--type=shapes) — um modelo que define formas reutilizáveis, mas nenhum serviço. Conecte uma biblioteca de formas aos seus projetos Smithy para compartilhar formas entre eles, em vez de duplicar as definições em cada um.

Uso

Gerar um Projeto Smithy

Execute este gerador@aws/nx-plugin:smithy#project

CLI
VSCode

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

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

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

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

Instale o Nx Console VSCode Plugin se ainda não o fez
Abra o console Nx no VSCode
Clique em Generate (UI) na seção "Common Nx Commands"
Procure por @aws/nx-plugin - smithy#project
Preencha os parâmetros obrigatórios
Clique em Generate

Monte seu comando7

nameObrigatório

type

Opções

Opções do gerador7 opções

nameObrigatóriostring: Nome do projeto Smithy
typeenumPadrão: service: O tipo de projeto Smithy a criar. Escolha entre service (um modelo com uma forma de serviço, pronto para uma implementação) e shapes (uma biblioteca de formas reutilizáveis, partilhada entre múltiplos projetos Smithy).
serviceshapes
directorystringPadrão: packages: Diretório pai onde o projeto Smithy é colocado.
serviceNamestring: O nome do seu serviço Smithy. Usa o nome fornecido por padrão. Não aplicável a bibliotecas de formas.
namespacestring: O namespace para a API Smithy. Usa como padrão o escopo do seu monorepo
subDirectorystring: O subdiretório onde o projeto Smithy é colocado. Por padrão, este é o nome do projeto.
preferInstallDependenciesbooleanPadrão: true: Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

Biblioteca de Formas

Directorymy-shapes
- Directorysrc
  - main.smithy Your shared shape definitions
- smithy-build.json Smithy build configuration
- project.json Project configuration and build targets

Uma biblioteca de formas define formas e nada mais:

$version: "2.0"

namespace com.example

structure Customer {
    @required
    id: String

    name: String
    email: String
}

Como uma biblioteca de formas não tem serviço, seu smithy-build.json não configura geração de código — construí-la valida o modelo e o monta em um único arquivo de modelo JSON em dist/<my-shapes>/build/model.json.

Serviço

Directorymy-service
- Directorysrc
  - main.smithy Your service definition
  - Directoryoperations
    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

Um modelo de serviço define uma forma de serviço e as operações que ele expõe:

$version: "2.0"

namespace com.example

use aws.protocols#restJson1

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

Construir um projeto de serviço gera uma especificação OpenAPI e um TypeScript Server SDK em dist/<my-service>/build/.

Construção

Projetos Smithy são construídos com o Smithy CLI, que valida seu modelo:

pnpm nx build my-shapes

yarn nx build my-shapes

npx nx build my-shapes

bunx nx build my-shapes

No macOS e Linux, o CLI é resolvido pelo mise, que a construção busca sob demanda, então não há nada para instalar — ele baixa e armazena em cache a versão fixada na primeira vez que você constrói. No Windows, é um pré-requisito que você instala por conta própria — consulte Construção no Windows.

Dependendo de uma Biblioteca de Formas

Construir uma biblioteca de formas escreve um modelo montado em dist/<my-shapes>/build/model.json. Este único arquivo contém todas as formas que a biblioteca define, junto com qualquer uma de que ela depende, então um consumidor só precisa declarar as bibliotecas que referencia diretamente.

Para depender de uma biblioteca de formas de outro projeto Smithy, faça duas alterações no projeto consumidor:

Adicione o modelo construído da biblioteca a imports no smithy-build.json do projeto consumidor. Os caminhos são relativos a esse arquivo, então o número de segmentos ../ corresponde à profundidade de aninhamento do projeto consumidor — três para packages/my-api/model abaixo:
```
{
  "version": "1.0",
  "sources": ["src/"],
  "imports": ["../../../dist/packages/my-shapes/build/model.json"],
  ...
}
```
Adicione o target build da biblioteca como uma dependência do target compile do projeto consumidor em seu project.json, para que o modelo exista antes que o consumidor construa:
```
{
  "targets": {
    "compile": {
      "dependsOn": ["@my-scope/my-shapes:build"],
      ...
    }
  }
}
```

Seu modelo agora pode referenciar as formas da biblioteca com use:

$version: "2.0"

namespace com.example.api

use com.example.shared#Customer

structure GetCustomerOutput {
    @required
    customer: Customer
}

Bibliotecas de formas podem depender de outras bibliotecas de formas da mesma maneira. Como o modelo construído de cada biblioteca já contém suas próprias dependências, você só precisa repetir essas etapas para as bibliotecas que você referencia diretamente. Uma biblioteca alcançada por mais de um caminho é resolvida uma vez — Smithy ignora definições de formas duplicadas, mas equivalentes.