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:

Servicio (--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.
Biblioteca de formas (--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.

Uso

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

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

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

Instale el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - smithy#project
Complete los parámetros requeridos
- name: my-shapes
Haga clic en Generate

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

Biblioteca de Formas

Directoriomy-shapes
- Directoriosrc
  - main.smithy Your shared shape definitions
- smithy-build.json Smithy build configuration
- project.json Project configuration and build targets

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 — construirla valida el modelo y lo ensambla en un único archivo de modelo JSON en dist/<my-shapes>/build/model.json.

Servicio

Directoriomy-service
- Directoriosrc
  - main.smithy Your service definition
  - Directoriooperations
    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 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
    ]
}

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

Construcción

Los proyectos Smithy se construyen con el Smithy CLI, que valida tu modelo:

pnpm nx build my-shapes

yarn nx build my-shapes

npx nx build my-shapes

bunx nx build my-shapes

En macOS y Linux, el CLI se resuelve mediante mise, que la construcción obtiene bajo demanda, por lo que no hay nada que instalar — descarga y almacena en caché la versión fijada la primera vez que construyes. En Windows es un prerrequisito que instalas tú mismo — consulta Construcción en Windows.

Dependiendo de una Biblioteca de Formas

Construir una biblioteca de formas escribe un modelo ensamblado en dist/<my-shapes>/build/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 dos cambios en el proyecto consumidor:

Agrega el modelo construido de la biblioteca a imports en el smithy-build.json del proyecto consumidor. Las rutas son relativas a ese archivo, por lo que el número de segmentos ../ coincide con cuán profundamente está anidado el proyecto consumidor — tres para packages/my-api/model a continuación:
```
{
  "version": "1.0",
  "sources": ["src/"],
  "imports": ["../../../dist/packages/my-shapes/build/model.json"],
  ...
}
```
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 construya:
```
{
  "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 construido 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 las definiciones de formas duplicadas pero equivalentes.