Progetti Smithy

Smithy è un linguaggio di definizione delle interfacce per descrivere servizi e i dati che scambiano. Il generatore di progetti Smithy crea un progetto contenente un modello Smithy.

Esistono due tipi di progetto Smithy:

• Service (--type=service) — un modello che definisce un servizio e le sue operazioni. Questo è ciò che il generatore ts#api --framework=smithy crea per te insieme a un’implementazione TypeScript.
• Shape library (--type=shapes) — un modello che definisce forme riutilizzabili ma nessun servizio. Collega una shape library ai tuoi progetti Smithy per condividere forme tra di essi, invece di duplicare le definizioni in ciascuno.

Consiglio

Se desideri un’API con un’implementazione, usa invece il generatore ts#api. Crea un progetto di modello Smithy e un server TypeScript che lo implementa.

Utilizzo

Generare un Progetto Smithy

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - smithy#project
5. Compila i parametri richiesti
   • name: my-shapes
6. Clicca su Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

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

yarn

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

npm

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

bun

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

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	-	Nome del progetto Smithy
type	service | shapes	service	Il tipo di progetto Smithy da creare. Scegli tra service (un modello con una forma di servizio, pronto per un'implementazione) e shapes (una libreria di forme riutilizzabili, condivisa tra più progetti Smithy).
serviceName	string	-	Il nome del tuo servizio Smithy. Utilizza il nome fornito per impostazione predefinita. Non applicabile alle librerie di forme.
namespace	string	-	Il namespace per l'API Smithy. Per impostazione predefinita corrisponde allo scope del tuo monorepo
directory	string	packages	Directory principale dove viene posizionato il progetto Smithy.
subDirectory	string	-	La sotto-directory in cui viene posizionato il progetto Smithy. Per impostazione predefinita corrisponde al nome del progetto.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

type = shapes

Shape Library

• Directorymy-shapes

  • Directorysrc

    • main.smithy Le tue definizioni di forme condivise
  • smithy-build.json Configurazione di build Smithy
  • build.Dockerfile Costruisce e valida il modello
  • project.json Configurazione del progetto e target di build

Una shape library definisce forme e nient’altro:

$version: "2.0"

namespace com.example

structure Customer {
    @required
    id: String

    name: String
    email: String
}

Poiché una shape library non ha un servizio, il suo smithy-build.json non configura alcuna generazione di codice — la sua build valida il modello e lo assembla in un singolo file di modello JSON in dist/<my-shapes>/build/model/model.json.

type = service

Service

• Directorymy-service

  • Directorysrc

    • main.smithy La tua definizione di servizio
    • Directoryoperations

      • echo.smithy Un’operazione di esempio
  • smithy-build.json Configurazione di build Smithy, inclusa la generazione di codice
  • build.Dockerfile Costruisce il modello, la specifica OpenAPI e l’SDK Server TypeScript
  • project.json Configurazione del progetto e target di build

Un modello di servizio definisce una forma di servizio e le operazioni che espone:

$version: "2.0"

namespace com.example

use aws.protocols#restJson1

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

La build di un progetto di servizio genera una specifica OpenAPI e un SDK Server TypeScript in dist/<my-service>/build/.

Build

I progetti Smithy vengono costruiti utilizzando Docker, che esegue la Smithy CLI per validare il tuo modello:

pnpm

pnpm nx build my-shapes

yarn

yarn nx build my-shapes

npm

npx nx build my-shapes

bun

bunx nx build my-shapes

Dipendere da una Shape Library

La build di una shape library scrive un modello assemblato in dist/<my-shapes>/build/model/model.json. Questo singolo file contiene ogni forma definita dalla libreria, insieme a quelle da cui dipende, quindi un consumatore dichiara solo le librerie a cui fa riferimento direttamente.

Per dipendere da una shape library da un altro progetto Smithy, apporta tre modifiche al progetto consumatore:

1. I progetti Smithy vengono costruiti all’interno di un container, e alla build viene fornita la radice del workspace come contesto di build nominato. Aggiungi un COPY al build.Dockerfile del progetto consumatore, accanto a dove vengono copiati i suoi stessi sorgenti:

   # 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

2. Aggiungi il file copiato a imports nel smithy-build.json del progetto consumatore:

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

3. Aggiungi il target build della libreria come dipendenza del target compile del progetto consumatore nel suo project.json, in modo che il modello esista prima che il consumatore venga costruito:

   {
     "targets": {
       "compile": {
         "dependsOn": ["@my-scope/my-shapes:build"],
         ...
       }
     }
   }

Il tuo modello può ora fare riferimento alle forme della libreria con use:

$version: "2.0"

namespace com.example.api

use com.example.shared#Customer

structure GetCustomerOutput {
    @required
    customer: Customer
}

Le shape library possono dipendere da altre shape library allo stesso modo. Poiché il modello costruito di ogni libreria contiene già le proprie dipendenze, devi solo ripetere questi passaggi per le librerie a cui fai riferimento direttamente. Una libreria raggiunta da più di un percorso viene risolta una sola volta — Smithy ignora le definizioni di forme duplicate ma equivalenti.