Progetti Smithy

Smithy è un linguaggio di definizione delle interfacce per descrivere i 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.

Utilizzo

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

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

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

Shape Library

Directorymy-shapes
- Directorysrc
  - main.smithy Le tue definizioni di forme condivise
- smithy-build.json Configurazione di build Smithy
- 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.json.

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
- ssdk.rolldown.config.mjs Raggruppa il TypeScript Server SDK generato
- 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 TypeScript Server SDK in dist/<my-service>/build/.

Build

I progetti Smithy vengono compilati con la Smithy CLI, che valida il tuo modello:

pnpm nx build my-shapes

yarn nx build my-shapes

npx nx build my-shapes

bunx nx build my-shapes

Su macOS e Linux la CLI viene risolta da mise, che la build recupera su richiesta, quindi non c’è nulla da installare — scarica e memorizza nella cache la versione fissata la prima volta che esegui la build. Su Windows è un prerequisito che devi installare tu stesso — vedi Building on Windows.

Dipendere da una Shape Library

La build di una shape library scrive un modello assemblato in dist/<my-shapes>/build/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 due modifiche al progetto consumatore:

Aggiungi il modello compilato della libreria a imports nel smithy-build.json del progetto consumatore. I percorsi sono relativi a quel file, quindi il numero di segmenti ../ corrisponde a quanto profondamente è annidato il progetto consumatore — tre per packages/my-api/model qui sotto:
```
{
  "version": "1.0",
  "sources": ["src/"],
  "imports": ["../../../dist/packages/my-shapes/build/model.json"],
  ...
}
```
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 esegua la build:
```
{
  "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 compilato 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.