Proyectos Smithy

Smithy es un lenguaje de definición de interfaces para describir servicios y los datos que intercambian. El generador de proyectos Smithy crea un proyecto que contiene un modelo Smithy.

Hay dos tipos de proyecto Smithy:

• Service (--type=service) — un modelo que define un servicio y sus operaciones. Esto es lo que el generador ts#api --framework=smithy crea para ti junto con una implementación TypeScript.
• Shape library (--type=shapes) — un modelo que define formas reutilizables pero ningún servicio. Conecta una biblioteca de formas a tus proyectos Smithy para compartir formas entre ellos, en lugar de duplicar las definiciones en cada uno.

Consejo

Si deseas una API con una implementación, usa el generador ts#api en su lugar. Crea un proyecto de modelo Smithy y un servidor TypeScript que lo implementa.

Uso

Generar un Proyecto Smithy

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - smithy#project
5. Complete los parámetros requeridos
   • name: my-shapes
6. Haga clic en 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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	string	-	Nombre del proyecto Smithy
type	service | shapes	service	El tipo de proyecto Smithy a crear. Elija entre service (un modelo con una forma de servicio, listo para una implementación) y shapes (una biblioteca de formas reutilizables, compartida entre múltiples proyectos Smithy).
serviceName	string	-	El nombre de su servicio Smithy. Utiliza el nombre proporcionado por defecto. No aplicable a bibliotecas de formas.
namespace	string	-	El namespace para la API Smithy. Por defecto es el scope de tu monorepo
directory	string	packages	Directorio padre donde se coloca el proyecto Smithy.
subDirectory	string	-	El subdirectorio donde se coloca el proyecto Smithy. Por defecto es el nombre del proyecto.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establece en false para diferir la instalación cuando se ejecutan múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instala una vez al final.

Salida del Generador

type = shapes

Biblioteca de Formas

• Directoriomy-shapes

  • Directoriosrc

    • main.smithy Tus definiciones de formas compartidas
  • smithy-build.json Configuración de compilación de Smithy
  • build.Dockerfile Compila y valida el modelo
  • project.json Configuración del proyecto y objetivos de compilación

Una biblioteca de formas define formas y nada más:

$version: "2.0"

namespace com.example

structure Customer {
    @required
    id: String

    name: String
    email: String
}

Dado que una biblioteca de formas no tiene servicio, su smithy-build.json no configura generación de código — compilarla valida el modelo y lo ensambla en un único archivo de modelo JSON en dist/<my-shapes>/build/model/model.json.

type = service

Servicio

• Directoriomy-service

  • Directoriosrc

    • main.smithy Tu definición de servicio
    • Directoriooperations

      • echo.smithy Una operación de ejemplo
  • smithy-build.json Configuración de compilación de Smithy, incluyendo generación de código
  • build.Dockerfile Compila el modelo, especificación OpenAPI y TypeScript Server SDK
  • project.json Configuración del proyecto y objetivos de compilación

Un modelo de servicio define una forma de servicio y las operaciones que expone:

$version: "2.0"

namespace com.example

use aws.protocols#restJson1

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

Compilar un proyecto de servicio genera una especificación OpenAPI y un TypeScript Server SDK en dist/<my-service>/build/.

Compilación

Los proyectos Smithy se compilan usando Docker, que ejecuta el Smithy CLI para validar tu modelo:

pnpm

pnpm nx build my-shapes

yarn

yarn nx build my-shapes

npm

npx nx build my-shapes

bun

bunx nx build my-shapes

Dependiendo de una Biblioteca de Formas

Compilar una biblioteca de formas escribe un modelo ensamblado en dist/<my-shapes>/build/model/model.json. Este único archivo contiene cada forma que la biblioteca define, junto con cualquiera de la que dependa, por lo que un consumidor solo declara las bibliotecas que referencia directamente.

Para depender de una biblioteca de formas desde otro proyecto Smithy, realiza tres cambios en el proyecto consumidor:

1. Los proyectos Smithy se compilan dentro de un contenedor, y la compilación recibe la raíz del espacio de trabajo como un contexto de compilación nombrado. Agrega un COPY al build.Dockerfile del proyecto consumidor, junto a donde se copian sus propias fuentes:

   # 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. Agrega el archivo copiado a imports en el smithy-build.json del proyecto consumidor:

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

3. Agrega el objetivo build de la biblioteca como una dependencia del objetivo compile del proyecto consumidor en su project.json, para que el modelo exista antes de que el consumidor compile:

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

Tu modelo ahora puede referenciar las formas de la biblioteca con use:

$version: "2.0"

namespace com.example.api

use com.example.shared#Customer

structure GetCustomerOutput {
    @required
    customer: Customer
}

Las bibliotecas de formas pueden depender de otras bibliotecas de formas de la misma manera. Dado que el modelo compilado de cada biblioteca ya contiene sus propias dependencias, solo necesitas repetir estos pasos para las bibliotecas que referencias directamente. Una biblioteca alcanzada por más de una ruta se resuelve una vez — Smithy ignora definiciones de formas duplicadas pero equivalentes.