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:

Service (--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.
Shape library (--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

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
- name: my-shapes
Clique em 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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Opções

Parâmetro	Tipo	Padrão	Descrição
name Obrigatório	string	-	Nome do projeto Smithy
type	service \| shapes	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).
serviceName	string	-	O nome do seu serviço Smithy. Usa o nome fornecido por padrão. Não aplicável a bibliotecas de formas.
namespace	string	-	O namespace para a API Smithy. Usa como padrão o escopo do seu monorepo
directory	string	packages	Diretório pai onde o projeto Smithy é colocado.
subDirectory	string	-	O subdiretório onde o projeto Smithy é colocado. Por padrão, este é o nome do projeto.
preferInstallDependencies	boolean	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

Shape Library

Directorymy-shapes
- Directorysrc
  - main.smithy Suas definições de formas compartilhadas
- smithy-build.json Configuração de build do Smithy
- build.Dockerfile Constrói e valida o modelo
- project.json Configuração do projeto e alvos de build

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/model.json.

Service

Directorymy-service
- Directorysrc
  - main.smithy Sua definição de serviço
  - Directoryoperations
    echo.smithy Uma operação de exemplo
- smithy-build.json Configuração de build do Smithy, incluindo geração de código
- build.Dockerfile Constrói o modelo, especificação OpenAPI e TypeScript Server SDK
- project.json Configuração do projeto e alvos de build

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 usando Docker, que executa a Smithy CLI para validar seu modelo:

pnpm nx build my-shapes

yarn nx build my-shapes

npx nx build my-shapes

bunx nx build my-shapes

Dependendo de uma Shape Library

Construir uma biblioteca de formas escreve um modelo montado em dist/<my-shapes>/build/model/model.json. Este único arquivo contém todas as formas que a biblioteca define, junto com quaisquer das quais 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 três alterações no projeto consumidor:

Projetos Smithy são construídos dentro de um contêiner, e o build recebe a raiz do workspace como um contexto de build nomeado. Adicione um COPY ao build.Dockerfile do projeto consumidor, ao lado de onde suas próprias fontes são copiadas:
```
# 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
```

Adicione o arquivo copiado a imports no smithy-build.json do projeto consumidor:

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

Adicione o alvo build da biblioteca como uma dependência do alvo compile do projeto consumidor em seu project.json, para que o modelo exista antes que o consumidor seja construído:
```
{
  "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.