Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Convenciones de nomenclatura

Este capítulo trata las reglas de nomenclatura y de uso de mayúsculas y minúsculas que se aplican al contenido redactado de Aggrega: el patrón de los nombres de instancia redactados por el usuario, la disciplina de mayúsculas y minúsculas de los nombres de campo en el DSL, el formato que usa la plataforma para los identificadores que define ella y no tú, y la sintaxis de comentarios usada en la superficie de redacción YAML.

Nombres de instancia

Los nombres de instancia escritos por el usuario — las claves que el desarrollador escribe para componentes, features, agregados, subsistemas, límites, y sockets y alias de uses — siguen todos un único patrón: ^[a-zA-Z0-9_-]+$. Son válidos tanto kebab-case (pii-filter, my-agent) como snake_case (openai_key, db_credentials); los equipos pueden adoptar la convención que prefieran.

Caracteres permitidos: alfanuméricos (a-z, A-Z, 0-9), guiones (-) y guiones bajos (_). No se permite ningún otro carácter.

Ejemplos:

components:
web-server: # kebab-case
finance_worker: # snake_case
features:
pii-filter: # kebab-case
audit_logger: # snake_case
openai_key: # snake_case — natural for a credential attachment
db-password: # kebab-case — also valid
PatrónÁmbitoEjemplos
^[a-zA-Z0-9_-]+$Todos los nombres de instancia escritos por el usuarioweb-server, openai_key, pii-filter

El patrón se aplica durante la resolución mediante patternProperties de JSON Schema.

Lo que cuesta el nombre de un componente, y por qué las mayúsculas cuestan más con algunos destinos

El patrón anterior indica lo que puedes escribir. Lo que un nombre cuesta es una cuestión aparte, y depende del destino en el que se despliega un componente, así que conviene saberlo antes de elegir un nombre y no en el momento en que una build rechaza uno.

El nombre de un componente se convierte en la identidad con la que se marca cada recurso que emite, y cada destino deriva sus propios nombres de esa identidad: un instalador de charts deriva de ella un nombre de release, un orquestador de contenedores deriva nombres de servicio. Un destino cuyo alfabeto es más restringido que el patrón no puede contener un carácter que no admite, y Aggrega no convertirá silenciosamente ese carácter en otro parecido: dos nombres que un autor puede distinguir no deben convertirse en un solo nombre en un clúster. Por eso, un carácter que el destino no admite se escribe en su lugar como secuencia de escape, y una secuencia de escape es más larga que el carácter que sustituye.

La consecuencia práctica: una letra mayúscula es gratuita con algunos destinos y costosa con otros.

  • Con un destino cuyos nombres admiten mayúsculas — un archivo compose de orquestación de contenedores, por ejemplo — PaymentsAPI se conserva exactamente como lo escribiste y cuesta once caracteres.
  • Con un destino cuyos nombres solo admiten minúsculas — el nombre de release de un instalador de charts — cada mayúscula se escapa, y un nombre de solo seis mayúsculas ya supera lo que ese destino acepta.

Hay un segundo efecto, y es el más severo: una secuencia de escape empieza con un guion. Un destino que exige que un nombre empiece por una letra minúscula o un dígito rechazará, por tanto, un nombre cuyo primer carácter sea uno que no admite, por corto que sea el resto; ningún acortamiento lo remedia.

Las recomendaciones se derivan de los dos efectos. Prefiere letras minúsculas y dígitos, con guiones entre palabras, y empieza un nombre con una letra minúscula. payments-api se conserva sin cambios en todos los destinos para los que Aggrega incluye un provider. payments_api se conserva en un archivo compose, pero no en el destino helm, cuyos nombres de recurso no admiten el guion bajo: los Services, workloads y la release a los que da el nombre del componente se escriben payments-zuapi. PaymentsAPI cuesta aún más ahí. Una Recipe que publica la dirección de un recurso así lee la grafía propia del destino en lugar de predecirla: consulta templates/rendered-resource-names.md.

Un dígito inicial se puede escribir legalmente y no cuesta nada con un archivo compose, pero el destino helm lo rechaza. El nombre de un Service de Kubernetes debe empezar por una letra, y los Services que emite un chart o un workload sintetizado reciben el nombre del componente, de modo que un componente llamado 1cache detiene una build de helm — el rechazo nombra el componente e indica que el nombre de un Service debe empezar por una letra — en lugar de generar Services que el clúster rechazaría.

Nada de esto es una regla que el compilador aplique por su cuenta: no contiene las reglas de nomenclatura de ningún destino ni inventa ningún límite. El provider de cada destino responde de sus propios nombres, de modo que un nombre solo se rechaza cuando el destino en el que realmente se despliega un componente indica que no puede usarlo, y el rechazo incluye el motivo propio de ese destino y señala la clave spec.components que escribiste. Un nombre válido con un destino y rechazado con otro es el comportamiento esperado, no una incoherencia.

Los nombres que compone el propio Aggrega — la identidad de una feature adjunta en un límite, por ejemplo — se tratan al revés: se acortan para ajustarse al destino en lugar de rechazarse, porque se ensamblan a partir de partes escritas en varios lugares y ningún autor por sí solo puede ver la longitud que alcanzan. Solo se rechaza un nombre que hayas escrito tú.

El punto como separador de ruta reservado

El carácter punto (.) está excluido de todos los nombres de instancia escritos por el usuario. El punto cumple la función estructural de separador de ruta generado por el compilador para las referencias a componentes entre agregados.

Cuando un Aggregate raíz importa un subagregado llamado data-layer que contiene un componente llamado main-db, el compilador construye el ID absoluto aplanado data-layer.main-db uniendo con un punto el nombre de instancia del agregado y el nombre de instancia del componente. Esta ruta con puntos aparece en:

  • Destinos uses del desarrollador: target: data-layer.public_db — referencia a un componente exportado desde un agregado anidado.
  • Los propios diagnósticos de la build: una detención o una advertencia sobre ese componente lo nombra por su ruta con puntos, de modo que el nombre que lees es el que puedes buscar en tus documentos.

El separador no llega a un nombre

Una ruta con puntos es una dirección dentro de tus documentos, y no es un nombre que un destino de despliegue vaya a aceptar. El nombre de un Service de Kubernetes no admite ningún punto; peor aún, un punto dentro de una dirección de clúster es lo que separa un servicio del namespace en el que reside, de modo que un nombre con puntos entregado a un consumidor como host se resolvería en un servicio distinto en lugar de fallar.

Por eso el separador se reescribe en cada nombre y etiqueta que la build deriva de la identidad de un componente, y se reescribe en lugar de sustituirse: data-layer.main-db se convierte en data-layer-zdmain-db. Sustituirlo por un carácter que un destino sí acepte permitiría que dos componentes diferentes llegaran a un mismo nombre — data-layer.main-db y un componente que alguien escribió como data-layer-main-db — y un nombre al que llegan dos componentes no identifica a ninguno.

A qué llega eso, y a qué no:

  • Llega a los nombres y etiquetas derivados de la identidad — metadata.name en un recurso que Aggrega sintetiza, las etiquetas aggrega.ai/component-id y app.kubernetes.io/name, los selectores que coinciden con ellas, los nombres de archivo emitidos, {{ .context.instance_id }} y el nombre que un provider deriva para sí mismo, como el nombre de una release de helm. Cambian juntos, de modo que una dirección que una Recipe compone a partir de la clave que nombra un recurso — .context.instance_id donde el destino lo nombra según la identidad, .context.rendered_name donde el destino informa de un nombre propio — sigue nombrando el recurso que emite la build.
  • No llega a un nombre que hayas escrito tú. Un nombre de componente que no contiene ningún separador vuelve idéntico byte a byte, de modo que solo un componente aportado por un Aggregate importado se escribe de forma distinta en la salida que en el documento.
  • No llega a los nombres dentro de un chart o fragmento proporcionado por un autor. Pertenecen a quien los escribió, y un nombre que procede de un chart de terceros — un nombre de recurso personalizado de la forma <plural>.<group>, en el que el punto es legal — se emite exactamente como lo escribió ese chart.

🔴 Este último punto tiene una consecuencia sobre lo que una Recipe debe publicar, y es lo más fácil de hacer mal en esta página. Las plantillas propias de un chart proporcionado nombran sus recursos según la identidad que les entrega la plataforma — un nombre de release, escrito en el alfabeto propio de esa plataforma y no en el descrito arriba — y el destino helm nombra los workloads que sintetiza según ese mismo nombre de release. Así, para la salida generada a partir de fuentes que tú proporcionaste, y para un workload sintetizado con un destino de ese tipo, {{ .context.instance_id }} no es el nombre que llevan esos recursos, y una dirección publicada a partir de él no nombra nada siempre que los dos alfabetos difieran. La clave que contiene el nombre de la plataforma, y qué providers informan de uno, se describen en templates/rendered-resource-names.md.

Reescribir el separador cuesta caracteres, y un nombre de longitud limitada puede quedarse sin ellos. El separador se sustituye por una secuencia de escape corta en lugar de por un único carácter, de modo que una identidad cualificada, una vez escrita, es algo más larga de lo que se lee en tus documentos. Eso solo importa donde el nombre resultante tiene una longitud limitada: el destino que genera un componente indica qué longitud de valor de etiqueta acepta, y donde la identidad escrita la superaría, la build se detiene en lugar de emitir un valor que el destino rechazaría. La detención indica la longitud en la que debe caber la propia identidad — la longitud antes de reescribirla, de modo que un nombre elegido dentro de ella funcione a la primera — y la solución es acortar las partes escritas por el autor: el nombre que el documento importador da al subagregado, o el nombre propio del componente dentro de él.

El separador es el motivo habitual por el que un nombre se escribe más largo de lo que se lee, pero no el único. Dos formas que un nombre escrito por el autor puede adoptar legalmente tampoco pueden conservarse tal cual, porque mantenerlas haría ambigua una secuencia de escape: un nombre que termina en guion, y un nombre en el que un guion va seguido inmediatamente de z. Cada una se reescribe de la misma manera, con el mismo coste. Cualquier otro nombre escrito por el autor vuelve idéntico byte a byte, de modo que a un nombre formado por letras, dígitos, guiones bajos y guiones entre palabras no le afecta nada de esto.

Un nombre de socket en el bloque uses propio de un componente coincide con una clave del usesSchema de la entidad de catálogo — un socket declarado — o bien nombra un socket ad hoc del propio desarrollador, que compila incluso en una entidad que no declara ningún usesSchema; un nombre que está a una sola edición de un socket declarado genera una advertencia que nombra ambas grafías. El uses por arista de una Release, y el de un adjunto de Feature, solo pueden nombrar un socket que la entidad declara, y cualquier otro nombre falla con un error de validación unknown-uses-socket.

Uso de mayúsculas y minúsculas en los campos

El DSL separa el YAML orientado al desarrollador (escrito por personas) de los contratos internos del compilador (consumidos por plantillas y herramientas):

  • YAML orientado al desarrollador (camelCase): los nombres de campo de varias palabras en los esquemas de Aggregate, Release, Component, Feature, Recipe, FeatureRecipe, Manifest y Plugin usan camelCase. Ejemplos: exportedComponents, syncWave, subDirectory, featuresSchema, usesSchema, valuesMapping, injectMapping, executionScope, appliesTo, appliesToAnyOf, conflictsWith. Sigue las convenciones de la API de Kubernetes.
  • Contratos internos (snake_case): los nombres de campo de varias palabras en el esquema del IR Graph y en el esquema del Template Context usan snake_case. Ejemplos visibles para el usuario con los que se encuentran los autores de Recipes: instance_id (en .context.instance_id — la identidad de la Recipe), inject_raw (en .inject_raw, un pilar de primer nivel junto a .inject en lugar de una clave bajo .context — el contrato de inyección sin modificar), attachment_name (en el contexto de una FeatureRecipe de adjunto — identifica el slot que el adjunto ocupa, o el nombre con el que se adjuntó). Sigue las convenciones de JSON API y se alinea con la generación de etiquetas de struct JSON de Go.
  • Campos de una sola palabra: en minúsculas independientemente del contexto. Ejemplos: values, infra, inject, provides, locals, features, labels, annotations, boundaries, components, subsystems, pipeline, source.

Los desarrolladores no se encuentran snake_case en el YAML que escriben, y los autores de plantillas no se encuentran camelCase en sus plantillas Go. Las ampliaciones del esquema siguen estas convenciones.

Tres estilos que se cruzan en una sola instrucción

La escritura de Recipes cruza habitualmente las tres convenciones de estilo en una sola instrucción: el campo DSL definido por el esquema usa camelCase, el nombre de instancia escrito por el usuario usa kebab-case o snake_case, y la referencia al contexto de la plantilla usa snake_case. Los autores que perciben esos cruces como convenciones separadas leen el YAML resultante sin dificultad; los que intentan explicar los estilos como una sola convención tienen problemas con los límites.

El ejemplo canónico: la plantilla valuesMapping: de una Recipe que hace referencia a la instancia de Component generada a través del contexto de la plantilla.

# Recipe authored against a Component the developer instantiated as "web-server"
# (kebab-case instance name) in their Aggregate.
spec:
valuesMapping: | # camelCase — schema-defined DSL field
name: "{{ .context.instance_id }}" # snake_case — template context
# internal contract
image: "{{ .values.image }}" # snake_case — template context
# internal contract

Tres estilos, una instrucción:

  • valuesMapping — camelCase. El nombre del campo DSL que el esquema define para la plantilla de mapeo de la Recipe. Camel porque el YAML del lenguaje orientado al desarrollador sigue las convenciones de la API de Kubernetes.
  • web-server (referenciado indirectamente a través del componente generado) — kebab-case. El nombre de instancia escrito por el usuario en el Aggregate; el desarrollador eligió la forma con guion. Podría ser igualmente web_server (snake_case); ambos son válidos según el patrón de nombres de instancia.
  • instance_id, image — snake_case. Nombres de campo dentro del contexto de la plantilla (.context.instance_id, .values.image). Snake porque el IR Graph y el contexto de la plantilla siguen las convenciones de JSON-API y se alinean con la generación de etiquetas de struct JSON de Go.

Los tres estilos no son intercambiables. Un autor de Recipes que escribe {{ .context.instanceId }} (camelCase) detiene la build: .context declara sus claves, e instanceId no es una de ellas, así que la referencia se rechaza antes de que se genere nada y el diagnóstico enumera las claves que .context sí define; consulta errors/fatal-halts.md «Template references a root the render context does not define (La plantilla hace referencia a una raíz que el contexto de renderizado no define)». Un desarrollador que escribe web.server (con un punto) se encuentra con el rechazo del patrón de nombres de instancia, porque el punto está reservado como separador de ruta. El objetivo de la disciplina: ten presentes las tres convenciones al leer o escribir; apóyate en los límites (dónde te encuentras en el YAML o en la plantilla) para saber qué estilo se aplica.

Identificadores definidos por la plataforma

Todo lo anterior rige los nombres en la superficie de escritura: un nombre de instancia que eliges, un campo de esquema que el lenguaje define para que lo completes, una clave del contexto de la plantilla que lees. Otros dos registros rigen los identificadores que define la propia plataforma y que tú solo relees o escribes. Están separados porque cumplen funciones distintas, y la función decide la forma.

El registro descriptivo: kebab-case, de forma uniforme. Un identificador de este registro dice con palabras lo que nombra, de modo que puedes leerlo y actuar en consecuencia sin consultar nada. Un flag de la CLI, el id de una regla de lint de publicación, el código de una clase de diagnóstico y el código con el que se registra una condición de detención pertenecen todos a él.

--no-unsupported-field-warnings # a CLI flag you type
category-matches-directory # a lint rule id, printed in `aggrega lint` output
unsupported-field # a diagnostic class code
artifact-provenance-skipped # another
parameter-contract-violation # the code a halting condition is registered under

Cuando una clase de diagnóstico tiene un flag de supresión, el código y el flag son las mismas palabras en el mismo orden — unsupported-field se silencia con --no-unsupported-field-warnings — de modo que la clase que has detectado te indica el flag que debes usar, sin nada que traducir. Un código de clase es el nombre estable con el que las herramientas reconocen un hallazgo sin analizar el texto de su mensaje; la redacción del mensaje puede mejorar, el código no cambia.

El registro de códigos cortos: la letra E y cuatro dígitos. Una condición de detención lleva también un código corto — E0007 — y es el único identificador definido por la plataforma que no está en kebab-case. El motivo es su posición: abre cada diagnóstico de detención, junto a la categoría, antes del archivo y la línea que vas a leer.

[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge

Un código descriptivo no puede ir ahí. El más largo de ellos llenaría por sí solo un terminal estrecho, antes de la ubicación que te dice dónde mirar. Por eso la cabecera lleva un identificador elegido por su anchura, y la compensación es deliberada: cuatro dígitos no dicen nada sobre una condición, y por eso cada código corto se publica junto a la condición que nombra y al texto con el que se presenta esa condición en la referencia de centinelas de error. Cita un código corto en un informe, escríbelo en una búsqueda y resuélvelo allí.

Ambos registros nombran las mismas condiciones desde dos direcciones, y ninguno sustituye al otro. Usa el código descriptivo cuando escribas una herramienta que se base en una condición; cita el código corto cuando hables de una condición con una persona.

Que kebab-case aparezca aquí y en los nombres de instancia no es una colisión. El patrón de nombres de instancia trata de lo que puedes escribir — allí son válidos tanto kebab-case como snake_case, y los equipos eligen uno. Este registro trata de lo que la plataforma escribe, donde no hay nada que elegir: nunca eliges la grafía del id de una regla de lint, y la plataforma nunca elige la grafía del nombre de tu componente.

Deja sin cambios los estilos de los campos. Los campos de esquema escritos por el autor siguen en camelCase y las claves del contexto de la plantilla siguen en snake_case. Ninguno de los identificadores de este registro es un campo en ninguna de las dos superficies — son nombres cortos y estables para un flag, una regla o una clase de hallazgo — de modo que el hecho de que un código de diagnóstico esté en kebab-case no dice nada sobre cómo se escribe un campo de esquema.

Disciplina de sufijos en los nombres de rutas de documento

Un subconjunto de campos del lenguaje contiene valores de ruta de documento: cadenas que apuntan a una posición dentro de otro documento (la sección volumes de un Workload generado, la entrada featuresSchema de un Component, el nivel mappings de un Manifest). Los valores siguen la sintaxis de RFC 6901 JSON Pointer: tokens separados por barras que identifican la ruta a través del documento de destino.

RFC 6901 es la gramática de rutas de referencia para cada superficie de ruta de documento en Aggrega. El contrato de plugins Wasm consume documentos JSON Patch RFC 6902 cuyas rutas son punteros RFC 6901 (según la salida JSONPatch del rol label-transform en plugins/plugin-contract.md); el inventario de cadenas de formato de la gramática de URI menciona RFC 6901 junto a la sintaxis de plantillas Go y los helpers de Sprig (según vocabulary/uri-grammar.md «Format-string inventory»); las exportaciones .locals de cada Recipe usan RFC 6901 para apuntar a posiciones del Workload sintetizado que los plugins Wasm Injector reciben en el pipeline de plugins a través del payload with de su paso. Una gramática, varias superficies que la consumen.

La disciplina de sufijos en los nombres distingue los dos lados de escritura de estos valores de ruta mediante una división deliberada de sufijos, alineada con la sección más amplia sobre el uso de mayúsculas y minúsculas en los campos que aparece arriba:

  • Los campos de esquema que contienen JSON Pointers RFC 6901 usan el sufijo camelCase *Path. Los campos forman parte del esquema YAML orientado al desarrollador, por lo que siguen la convención camelCase. Ningún esquema de entidad declara un campo así; las rutas de documento que escribe un autor son las claves de exportación .locals que siguen.
  • Las claves de exportación .locals que contienen JSON Pointers RFC 6901 usan el sufijo snake_case *_path. Las claves forman parte de la superficie de exportación interna de la Recipe — las leen las plantillas posteriores de la propia Recipe y un pipeline de plugins Wasm a través del payload pipeline[].with que hace referencia a .locals — por lo que siguen la convención snake_case. Ejemplos:
    • volumes_path — .locals.volumes_path: "/spec/template/spec/volumes" expone la posición del array volumes del Workload sintetizado.
    • containers_path — .locals.containers_path: "/spec/template/spec/containers" expone la posición del array containers.
    • resource_path — .locals.resource_path: "/resource/aws_s3_bucket/main" expone una ruta de recurso nativa de Terraform.
    • root_path — .locals.root_path: "/data" expone la ruta raíz que consume el pipe del renderizador.

Las dos convenciones de sufijo reflejan la convención de dos niveles de la sección sobre el uso de mayúsculas y minúsculas en los campos: los campos definidos por el esquema usan camelCase; los identificadores escritos por el usuario o privados de la Recipe usan snake_case (o kebab-case). La disciplina de sufijos *Path / *_path hace visible en el propio identificador que el valor es una ruta con su gramática: quien ve cualquiera de los dos sufijos sabe que el valor sigue la sintaxis RFC 6901 sin tener que inspeccionar el valor.

Ejemplo práctico: un Wasm Injector que consume las exportaciones *_path de una Recipe.

# Recipe (Domain 3) — declares .locals exports the Wasm Injector consumes
spec:
locals:
primary_compute: "worker-container"
containers_path: "/spec/template/spec/containers"
volumes_path: "/spec/template/spec/volumes"
# Credential FeatureRecipe (Domain 3) — attached to the component the Recipe
# above realizes. Its templates read `.locals`: an attachment sees the host
# Recipe's resolved locals merged with the attachment's own block.
spec:
pipeline:
- id: workload_injector
plugin: pipeline-step/k8s-workload-injector:2.0.0
function: inject_secret
with: |
target_container: "{{ .locals.primary_compute }}"
containers_path: "{{ .locals.containers_path }}"
volumes_path: "{{ .locals.volumes_path }}"

Las claves *_path son exportaciones privadas de la Recipe; los valores containers_path / volumes_path son cadenas JSON Pointer RFC 6901. El plugin Injector consume las cadenas para posicionar su salida JSONPatch respecto al AST del Workload generado. El attachment las alcanza en su propio pilar .locals — no existe ningún campo .context.uses[].locals, de modo que un consumidor no puede leer los locals de su destino a través de una arista uses; lo que cruza una arista es el provides del destino.

Para el inventario más amplio de cadenas de formato (sintaxis de plantillas Go, funciones Sprig, JSON Pointer junto a regex de SemVer y la gramática de selectores de etiquetas), consulta vocabulary/uri-grammar.md «Format-string inventory». Para la superficie del contrato de plugins Wasm que consume parches RFC 6902 direccionados mediante punteros RFC 6901, consulta plugins/plugin-contract.md.

Sintaxis de los comentarios

Los caracteres de comentario dependen del lenguaje que los rodea:

  • Contexto YAML (la superficie de escritura predeterminada para toda entidad de Aggrega): usa #
  • Contexto de plantillas Go (dentro de los escalares de bloque valuesMapping: de una Recipe, los escalares de bloque injectMapping: de una FeatureRecipe, las entradas de mapeo de una MappingLibrary y los cuerpos assertions: de los bloques de aserciones): usa {{/* ... */}} para los comentarios de plantilla que el motor de plantillas reconoce y elimina al renderizar, o # para comentarios a nivel de YAML fuera del cuerpo de la plantilla.

Los esquemas en forma compacta bajo schema:, usesSchema:, featuresSchema: y parameters: son YAML de principio a fin; la anotación description: de cada campo es la superficie documentada para la documentación en línea de los campos (port: { type: integer, description: "TCP listen port" }).