Projets Smithy

Smithy est un langage de définition d’interface pour décrire les services et les données qu’ils échangent. Le générateur de projet Smithy crée un projet contenant un modèle Smithy.

Il existe deux types de projet Smithy :

• Service (--type=service) — un modèle qui définit un service et ses opérations. C’est ce que le générateur ts#api --framework=smithy crée pour vous aux côtés d’une implémentation TypeScript.
• Bibliothèque de formes (--type=shapes) — un modèle qui définit des formes réutilisables mais aucun service. Connectez une bibliothèque de formes à vos projets Smithy pour partager des formes entre eux, plutôt que de dupliquer les définitions dans chacun.

Astuce

Si vous voulez une API avec une implémentation, utilisez plutôt le générateur ts#api. Il crée un projet de modèle Smithy et un serveur TypeScript qui l’implémente.

Utilisation

Générer un projet Smithy

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - smithy#project
5. Remplissez les paramètres requis
   • name: my-shapes
6. Cliquez sur 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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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

Options

Paramètre	Type	Par défaut	Description
name Requis	string	-	Nom du projet Smithy
type	service | shapes	service	Le type de projet Smithy à créer. Choisissez entre service (un modèle avec une forme de service, prêt pour une implémentation) et shapes (une bibliothèque de formes réutilisables, partagée entre plusieurs projets Smithy).
serviceName	string	-	Le nom de votre service Smithy. Utilise le nom fourni par défaut. Non applicable aux bibliothèques de formes.
namespace	string	-	L'espace de noms pour l'API Smithy. Par défaut, correspond à la portée de votre monorepo
directory	string	packages	Répertoire parent où le projet Smithy est placé.
subDirectory	string	-	Le sous-répertoire dans lequel le projet Smithy est placé. Par défaut, il s'agit du nom du projet.
preferInstallDependencies	boolean	true	Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir à false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Sortie du générateur

type = shapes

Bibliothèque de formes

• Répertoiremy-shapes

  • Répertoiresrc

    • main.smithy Vos définitions de formes partagées
  • smithy-build.json Configuration de build Smithy
  • build.Dockerfile Construit et valide le modèle
  • project.json Configuration du projet et cibles de build

Une bibliothèque de formes définit des formes et rien d’autre :

$version: "2.0"

namespace com.example

structure Customer {
    @required
    id: String

    name: String
    email: String
}

Puisqu’une bibliothèque de formes n’a pas de service, son smithy-build.json ne configure aucune génération de code — la construire valide le modèle et l’assemble dans un seul fichier de modèle JSON à dist/<my-shapes>/build/model/model.json.

type = service

Service

• Répertoiremy-service

  • Répertoiresrc

    • main.smithy Votre définition de service
    • Répertoireoperations

      • echo.smithy Un exemple d’opération
  • smithy-build.json Configuration de build Smithy, incluant la génération de code
  • build.Dockerfile Construit le modèle, la spécification OpenAPI et le SDK serveur TypeScript
  • project.json Configuration du projet et cibles de build

Un modèle de service définit une forme de service et les opérations qu’il expose :

$version: "2.0"

namespace com.example

use aws.protocols#restJson1

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

La construction d’un projet de service génère une spécification OpenAPI et un SDK serveur TypeScript dans dist/<my-service>/build/.

Construction

Les projets Smithy se construisent en utilisant Docker, qui exécute la CLI Smithy pour valider votre modèle :

pnpm

pnpm nx build my-shapes

yarn

yarn nx build my-shapes

npm

npx nx build my-shapes

bun

bunx nx build my-shapes

Dépendre d’une bibliothèque de formes

La construction d’une bibliothèque de formes écrit un modèle assemblé dans dist/<my-shapes>/build/model/model.json. Ce fichier unique contient chaque forme que la bibliothèque définit, ainsi que toutes celles dont elle dépend, de sorte qu’un consommateur ne déclare jamais que les bibliothèques qu’il référence directement.

Pour dépendre d’une bibliothèque de formes depuis un autre projet Smithy, apportez trois modifications au projet consommateur :

1. Les projets Smithy se construisent à l’intérieur d’un conteneur, et le build reçoit la racine de l’espace de travail comme contexte de build nommé. Ajoutez un COPY au build.Dockerfile du projet consommateur, à côté de l’endroit où ses propres sources sont copiées :

   # 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. Ajoutez le fichier copié à imports dans le smithy-build.json du projet consommateur :

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

3. Ajoutez la cible build de la bibliothèque comme dépendance de la cible compile du projet consommateur dans son project.json, afin que le modèle existe avant que le consommateur ne se construise :

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

Votre modèle peut maintenant référencer les formes de la bibliothèque avec use :

$version: "2.0"

namespace com.example.api

use com.example.shared#Customer

structure GetCustomerOutput {
    @required
    customer: Customer
}

Les bibliothèques de formes peuvent dépendre d’autres bibliothèques de formes de la même manière. Puisque le modèle construit de chaque bibliothèque contient déjà ses propres dépendances, vous n’avez besoin de répéter ces étapes que pour les bibliothèques que vous référencez directement. Une bibliothèque atteinte par plus d’un chemin est résolue une seule fois — Smithy ignore les définitions de formes dupliquées mais équivalentes.