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.

Utilisation

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

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

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

Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
Ouvrez la console Nx dans VSCode
Cliquez sur Generate (UI) dans la section "Common Nx Commands"
Recherchez @aws/nx-plugin - smithy#project
Remplissez les paramètres requis
- name: my-shapes
Cliquez sur Generate

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

Bibliothèque de formes

Répertoiremy-shapes
- Répertoiresrc
  - main.smithy Your shared shape definitions
- smithy-build.json Smithy build configuration
- project.json Project configuration and build targets

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

Service

Répertoiremy-service
- Répertoiresrc
  - main.smithy Your service definition
  - Répertoireoperations
    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

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 TypeScript Server SDK dans dist/<my-service>/build/.

Construction

Les projets Smithy se construisent avec le Smithy CLI, qui valide votre modèle :

pnpm nx build my-shapes

yarn nx build my-shapes

npx nx build my-shapes

bunx nx build my-shapes

Sur macOS et Linux, le CLI est résolu par mise, que la construction récupère à la demande, donc il n’y a rien à installer — il télécharge et met en cache la version épinglée la première fois que vous construisez. Sur Windows, c’est un prérequis que vous installez vous-même — voir Building on Windows.

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.json. Ce fichier unique contient chaque forme que la bibliothèque définit, ainsi que 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 deux modifications au projet consommateur :

Ajoutez le modèle construit de la bibliothèque à imports dans le smithy-build.json du projet consommateur. Les chemins sont relatifs à ce fichier, donc le nombre de segments ../ correspond à la profondeur d’imbrication du projet consommateur — trois pour packages/my-api/model ci-dessous :
```
{
  "version": "1.0",
  "sources": ["src/"],
  "imports": ["../../../dist/packages/my-shapes/build/model.json"],
  ...
}
```
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.