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

Funciones y helpers de Sprig

El motor de plantillas de Aggrega conecta la biblioteca de funciones Sprig v3 más los helpers propios de Aggrega (optional y capitalizedWords) en cada plantilla Go que evalúa el renderizador, y sustituye la función index de Go por una que se detiene ante una clave que el mapa no contiene. Los autores que escriben el valuesMapping: de una Recipe, el injectMapping: de una FeatureRecipe o cualquier otra superficie de plantilla que evalúa el renderizador tienen disponible el conjunto completo de helpers de Sprig junto con las funciones integradas de text/template de Go y los campos del contexto de ejecución documentados en template-context-contract.md.

🔴 Lee «que evalúa el renderizador» como el alcance que es, porque una superficie de autoría queda fuera de él. Una coordenada source: estructurada se resuelve para que el artefacto que nombra pueda fijarse, y esa resolución no es una pasada de renderizado: registra los helpers propios de Aggrega y nada más, así que una llamada de Sprig en un campo source:, o en una entrada locals: que este lee, detiene el pull. Una entrada que ningún campo source: lee la evalúa solo el renderizado, con el conjunto completo. Resolver una coordenada determina lo que se fija en lugar de producir un artefacto, y por eso su conjunto de funciones es deliberadamente más reducido — consulta errors/fatal-halts.md «Resolving a source: coordinate registers a narrower function set (La resolución de una coordenada source registra un conjunto de funciones más reducido)» para la detención y la forma portable que usar en su lugar.

El conjunto de Sprig se registra por sí solo para la interpolación de parámetros, y junto con los helpers propios de Aggrega en las superficies de plantilla de valor del renderizador.

Qué está conectado

Sprig v3 expone toda su superficie de helpers — unas 200 funciones repartidas en las categorías siguientes. Esta página esboza las categorías con los helpers comunes de cada una; la referencia canónica por función es la documentación upstream de Sprig.

  • Cadenas — upper, lower, title, trim, trimAll, trimPrefix, trimSuffix, replace, contains, hasPrefix, hasSuffix, substr, quote, squote, cat, indent, nindent, repeat, helpers de estilo de nombre (snakecase, camelcase, kebabcase), helpers de abreviatura (abbrev, abbrevboth, trunc), helpers de suma de comprobación (sha1sum, sha256sum, sha512sum, adler32sum), toString.
  • Listas — list, tuple, first, last, rest, initial, append/push, prepend, concat, reverse, uniq, without, has, slice, chunk, join, splitList, split, splitn, sortAlpha, compact.
  • Diccionarios — dict, get, set, unset, hasKey, keys, values, pick, omit, pluck, merge, mergeOverwrite, dig, deepCopy.
  • Matemáticas — add, sub, mul, div, mod, add1, min, max, ceil, floor, round, más las variantes decimales con el sufijo f (addf, subf, mulf, divf, minf, maxf).
  • Conversión — int, int64, float64, atoi, toString, toDecimal, seq, until, untilStep.
  • Codificación — b64enc, b64dec, b32enc, b32dec, toJson, toPrettyJson, toRawJson, fromJson, más las variantes JSON con el prefijo must que exponen los errores de decodificación en lugar de poner a cero en silencio.
  • Comprobaciones de tipo — typeOf, typeIs, typeIsLike, kindOf, kindIs, deepEqual, empty.
  • Valores predeterminados y flujo — default, coalesce, all, any, ternary, fail (lanza un error de plantilla con un mensaje personalizado — la forma canónica de abortar un renderizado con un mensaje de guarda).
  • Regex — regexMatch, regexFind, regexFindAll, regexReplaceAll, regexReplaceAllLiteral, regexSplit, regexQuoteMeta, más las variantes estrictas con el prefijo must.
  • Rutas — base, dir, clean, ext, isAbs (estilo Unix); osBase, osClean, osDir, osExt, osIsAbs (según el sistema operativo).
  • SemVer — semver, semverCompare.
  • URL — urlParse, urlJoin.
  • Fechas — ago, date, dateInZone, dateModify, duration, durationRound, htmlDate, htmlDateInZone, now, toDate, unixEpoch.

Advertencia sobre el determinismo

Aggrega garantiza una salida idéntica byte a byte para una entrada idéntica byte a byte. Un subconjunto de los helpers de Sprig lee el estado del entorno y rompe esa garantía cuando se invoca desde una plantilla. Los autores deberían evitar los siguientes helpers en las superficies de plantilla que contribuyen a los artefactos renderizados:

  • Lectores del reloj del sistema — now, date, dateInZone, dateModify, htmlDate, htmlDateInZone, ago cuando se llama sin una hora de referencia congelada.
  • Generadores aleatorios — randAlpha, randAlphaNum, randAscii, randNumeric, randBytes, randInt, uuidv4.
  • Lectores del entorno — env, expandenv (leen variables de entorno del proceso, que difieren entre las estaciones de trabajo de los operadores y los runners de CI).
  • Resolutores de red — getHostByName.

Estos helpers no los bloquea el motor; forman parte del conjunto de Sprig v3. La disciplina de evitarlos en las plantillas de la ruta de renderizado la sostienen los revisores y la garantía de salida determinista en la que confían los autores y el catálogo de la biblioteca estándar.

Números en una plantilla de valor

Un número que escribe un autor llega a una plantilla de valor como número. Un número sin parte decimal es un entero y se imprime entero: 1000000 imprime 1000000. Cualquier otro número se imprime en su forma decimal exacta más corta, nunca en notación exponencial: un 0.0000001 escrito por el autor imprime 0.0000001 y un 1e21 escrito por el autor imprime 1000000000000000000000, tanto si la plantilla escribe el valor directamente como si lo convierte en texto con toString, quote, printf "%v" o toJson. Un número que devuelve una función matemática — mulf, float64, round y similares — es el valor propio de esa función y se imprime en la forma propia de esa función, que es la notación exponencial para un valor muy pequeño o muy grande: {{ mulf .values.ratio 1 }} imprime 1e-07 para un 0.0000001 escrito por el autor.

Las comparaciones — eq, ne, lt, le, gt y ge — leen dos números por su valor, sea cual sea el tipo que lleve cada uno, de modo que un entero escrito por el autor se compara con un decimal escrito en la plantilla, y 3 es igual a 3.0:

{{ lt .values.replicas 1.5 }} # .values.replicas = 1 → true
{{ eq .values.replicas 3.0 }} # .values.replicas = 3 → true

Un número nunca se compara con un texto: cualquiera de las seis, al recibir un número y un texto entre comillas, detiene la compilación nombrando ambos tipos. Compara el número con un número escrito sin comillas, o conviértelo primero en texto:

{{ eq .values.port "8080" }} # halts: cannot compare a number with text
{{ eq .values.port 8080 }} # .values.port = 8080 → true
{{ eq (toString .values.port) "8080" }} # .values.port = 8080 → true

La detención es A value template failed while it ran (Una plantilla de valores falló durante su ejecución). Una aserción lee un número escrito por el autor de la misma manera; consulta Números en esta superficie.

Presencia y vacío — dos preguntas distintas

Una plantilla hace una de dos preguntas sobre un valor, y cada pregunta tiene sus propios helpers.

  • ¿Lo escribió el autor? hasKey y optional responden por presencia. Una clave que el autor escribió está presente contenga lo que contenga — 0, "" y false incluidos — y solo una clave que el autor omitió está ausente.
  • ¿Está vacío? default, with, if y empty responden por vacío. 0, "", false, una lista vacía, un mapa vacío y un valor ausente cuentan todos como vacíos ahí, como en Helm.
.values.replicashasKey .values "replicas"optional .values "replicas" 1.values.replicas | default 1if .values.replicas
ausentefalse11false
0true01false
3true33true

Un valor que legítimamente puede ser 0, "" o false — un número de réplicas de cero, un tiempo de espera de cero, un indicador desactivado — se comprueba con hasKey u optional, de modo que el 0 del autor llega a la salida como 0. default, with e if se ajustan a un valor cuya forma vacía no tiene un significado propio, donde «vacío» y «no escrito» pueden tratarse igual. Lee una clave dada de una sola manera por plantilla: una clave que la plantilla también lee como ruta con puntos cuenta como presente, como describe el límite de optional.

Helpers específicos de Aggrega

optional — valor de respaldo sensible a la presencia

optional <map> <key> <fallback> devuelve el valor en <key> dentro de <map> si la clave está presente; en caso contrario, devuelve <fallback>. A diferencia del default de Sprig, optional distingue «clave ausente» de «clave presente con un valor cero, vacío o falso».

La firma recibe el mapa y la clave como argumentos separados porque un valor canalizado a través del operador | de las plantillas Go ha perdido el acceso a su mapa padre. Sin el mapa padre en el ámbito, la presencia no puede comprobarse.

Un límite a la comprobación de presencia, y proviene de la plantilla y no del helper: una plantilla de valor lee una clave ausente como nada, lo que hace proporcionando un valor vacío en cada clave ausente que la plantilla nombra como ruta con puntos y lee como valor. Así, una plantilla que lee una clave tanto a través de optional como mediante esa ruta encuentra esa clave presente y vacía, y obtiene el valor vacío en lugar del valor de respaldo. Lee una clave de una sola manera por plantilla y las dos respuestas coinciden.

# Present and non-zero: returns 3
{{ optional .infra `replicas` 1 }} # .infra.replicas = 3 → 3
# Absent: returns the fallback
{{ optional .infra `replicas` 1 }} # .infra.replicas unset → 1
# Present but authored zero: returns 0 (the discriminator)
{{ optional .infra `replicas` 1 }} # .infra.replicas = 0 → 0

El último caso es la distinción que el default de Sprig no puede hacer. {{ .infra.replicas | default 1 }} devuelve 1 tanto si replicas se escribió como 0 como si se omitió — la confusión que impide los patrones legítimos de escalado a cero, sin reintentos, sin tiempo de espera y de indicador en falso.

Convención para entrecomillar claves: preferir las comillas invertidas. Las plantillas Go aceptan para el argumento de clave tanto literales de cadena entre comillas dobles ("replicas") como entre comillas invertidas (`replicas`); ambos producen la misma cadena en el momento de la evaluación de la plantilla. Los ejemplos del catálogo y de la documentación usan uniformemente la forma con comillas invertidas porque es segura para YAML en cualquier contexto de entrecomillado. Una clave entre comillas dobles dentro de un escalar YAML entre comillas dobles termina la cadena YAML a mitad de la plantilla:

# BROKEN — the inner " closes the outer YAML string:
service_port: "{{ optional .infra "port" 8080 }}"
# WORKS — backticks are not a YAML escape character:
service_port: "{{ optional .infra `port` 8080 }}"

Cuando la plantilla está dentro de un escalar de bloque YAML (forma |) o como escalar de valor desnudo, ambas formas se renderizan correctamente. Cuando la plantilla está incrustada dentro de un escalar YAML entre comillas dobles (el patrón field: "{{ ... }}" de valor de campo como plantilla), las comillas invertidas son obligatorias. La convención única (siempre comillas invertidas) evita por completo la trampa del entrecomillado YAML.

Cuándo preferir optional a default. Usa optional cuando el campo puede ser legítimamente cero, vacío o falso y el autor del catálogo necesita distinguir «el autor no lo estableció» de «el autor lo estableció a un valor falsy». Usa default cuando la confusión es aceptable (p. ej., campos de cadena donde el vacío no es válido; campos numéricos donde el cero no es válido).

Disponibilidad por superficie. optional está registrado en cada superficie que evalúa el renderizador: las superficies de plantilla de valor (valuesMapping de la Recipe, injectMapping de la FeatureRecipe, provides, pipeline.with, el cuerpo del Workload), el evaluador de aserciones y las plantillas de ruta (directory: / subDirectory: en los límites de la Release). Lo que difiere en la superficie de plantillas de ruta no es el conjunto de helpers sino la política de claves ausentes: una plantilla de ruta trata una clave ausente como un error y no como vacía, porque un segmento de ruta silenciosamente vacío produce una estructura del sistema de archivos rota que solo se descubre después de la compilación. optional lee una clave sin que esa política estricta se dispare primero, y eso es lo que lo hace utilizable ahí.

capitalizedWords — reducir un nombre a letras y dígitos

capitalizedWords <string> lee su argumento como palabras separadas por secuencias de cualquier carácter fuera de las letras y dígitos ASCII, pone en mayúscula la primera letra de cada palabra y las une. Cada carácter del resultado es una letra o un dígito.

Existe porque algunos destinos solo aceptan letras y dígitos en los nombres con los que direccionan los recursos, mientras que un id de componente puede contener legítimamente un punto, un guion o un guion bajo. Escribir esa conversión a mano en cada Recipe que la necesita produce varias grafías de una misma idea; un único helper da a cada autor la misma respuesta.

# separators become word boundaries
{{ capitalizedWords `payments-db` }} # → PaymentsDb
{{ capitalizedWords `payments_db` }} # → PaymentsDb
{{ capitalizedWords `payments.db` }} # → PaymentsDb
# a run of separators is one boundary, and leading or trailing ones add nothing
{{ capitalizedWords `-payments--db-` }} # → PaymentsDb
# characters already inside a word keep the case they were authored with
{{ capitalizedWords `MY-app` }} # → MYApp
# a word beginning with a digit is carried as authored
{{ capitalizedWords `1st-app` }} # → 1stApp
# anything outside the alphabet is a boundary, including a non-ASCII letter
{{ capitalizedWords `café-app` }} # → CafApp

🔴 El resultado no identifica el nombre del que procede. Se descarta cada separador, de modo que dos ids que solo difieren en la posición de sus separadores llegan al mismo resultado — payments-db y payments_db dan ambos PaymentsDb. El helper no puede detectarlo, porque ve un nombre a la vez; detectarlo corresponde a lo que direcciona los recursos por el resultado. Un destino que lo hace rechaza la colisión en lugar de emitir un despliegue al que le falte uno de los dos: al compilar para CloudFormation, dos componentes cuyos ids se reducen a un mismo nombre detienen la compilación, y el mensaje nombra cada id que llegó a él. Elige ids que difieran en algo más que la puntuación, y la cuestión no se plantea.

Disponibilidad por superficie. capitalizedWords está registrado dondequiera que lo esté optional: cada superficie que evalúa el renderizador y la resolución de una coordenada source: estructurada. No está disponible en la interpolación de parámetros del Aggregate, que ofrece solo el conjunto de Sprig.

index — una clave que el mapa debe contener

index <collection> <key>... lee una colección por posición o por clave, como hace el propio index de Go — con una diferencia. Cuando la colección es un mapa y el mapa no contiene la clave, index detiene la compilación y nombra la clave, mientras que el de Go responde con un valor vacío que se imprime como el texto literal <no value>.

# Present: returns the value
{{ index .values `replicas` }} # .values.replicas = 3 → 3
# A position in a list, or in a string, reads as Go's does
{{ index .values.zones 0 }} # .values.zones = [a, b] → a
# Absent: halts, naming the key
{{ index .values `replicas` }} # .values.replicas unset → halts: (key "replicas")

Es la lectura que se usa donde la clave debe estar — una credencial leída bajo el nombre de variable que calculó la Recipe, una clave que publica otra plantilla — para que una clave ausente detenga la compilación en lugar de llegar a un artefacto como <no value>. Donde la clave puede estar legítimamente ausente, compruébala primero: {{ optional .values `replicas` 1 }} proporciona un valor de respaldo, el get de Sprig devuelve una cadena vacía y hasKey comprueba sin leer. Leer a través de index y luego aplicar default no proporciona un valor de respaldo, porque la detención llega antes de que se ejecute default. Una clave que está presente y contiene null no está ausente: index la devuelve, y se imprime como <no value>.

La detención es una propiedad de index por sí solo, y es la misma en cada superficie — las plantillas de valor, el evaluador de aserciones, las plantillas de ruta, una coordenada source: estructurada, la interpolación de parámetros del Aggregate, el predicado validate: de un parámetro y los predicados x-aggrega-when: / x-aggrega-validate: de un esquema. Una lectura con punto de una clave no establecida sigue la política de claves ausentes propia de su superficie y no se ve afectada. La detención está documentada en errors/fatal-halts.md «A template indexes a map with a key the map does not hold (Una plantilla indexa un mapa con una clave que el mapa no contiene)».

Helpers comunes NO disponibles

Helm extiende el text/template de Go con helpers de plantillas de chart que a menudo se confunden con helpers generales de Sprig. Ninguno de ellos está registrado en el renderizador de Aggrega. Las plantillas que evalúa el renderizador de Aggrega (valuesMapping: de la Recipe, injectMapping: de la FeatureRecipe, provides, el cuerpo del Workload, el evaluador de aserciones) no pueden llamarlos:

  • include — la forma preferida de Helm para invocar un fragmento de plantilla definido con una salida de cadena encadenable por pipe. El renderizador de Aggrega no lo registra. Usa en su lugar {{ template "name" . }} de las plantillas Go estándar (la forma solo con efectos secundarios); para una salida encadenable por pipe, compón usando fragmentos de MappingLibrary y directivas $import:.
  • tpl — reevalúa una cadena como plantilla anidada contra el contexto actual. Aggrega no lo registra; la reevaluación anidada no forma parte de la superficie de plantillas. Los autores que necesiten valores calculados deberían componerlos con los helpers de cadenas de Sprig y emitir directamente el valor final.
  • required — hace fallar el renderizado del chart con un mensaje personalizado cuando falta el valor nombrado. Aggrega no lo registra. La aplicación de campos obligatorios en Aggrega reside en la capa de contratos de parámetros tipados (un slot parameters: de un Aggregate con required: true que la Release deja sin cubrir detiene la compilación con E0165, nombrando el slot y el lugar donde el Aggregate lo declara); las comprobaciones de marcadores de obligatoriedad por plantilla usan el fail de Sprig para lanzar un error de plantilla fatal que lleva la cadena proporcionada.
  • warn — emite una nota no fatal en el terminal del operador. Aggrega no lo registra. Las plantillas que necesiten detener el renderizado con un mensaje explicativo deberían usar el fail de Sprig; las plantillas que necesiten recurrir a un valor de respaldo sin detenerse deberían apoyarse en las ramas if/else estándar de Go.

Inventario de helpers entre motores (fundamental para los autores de MappingLibrary)

Los fragmentos de MappingLibrary pueden tener como destino uno de dos sitios de consumo:

  • Consumo del lado de Aggrega (valuesMapping: de la Recipe, injectMapping: de la FeatureRecipe, etc., evaluados por el renderizador de Aggrega). Los helpers disponibles son: Sprig v3 completo (default, coalesce, quote, nindent, indent, b64enc, etc.) más los propios de Aggrega (optional, capitalizedWords), y index se detiene ante una clave que el mapa no contiene. Los helpers de plantillas de chart (include, tpl, required, warn) NO están disponibles.
  • Consumo interno del chart de Helm (contenido de values.yaml del chart o templates/*.yaml del chart renderizados aguas abajo por el propio motor de plantillas de Helm). Los helpers disponibles son: Sprig v3 completo más los helpers de plantillas de chart de Helm (include, tpl, required, warn). Los helpers propios de Aggrega NO están disponibles, y index ahí es el propio de Go, que responde a una clave ausente con un valor vacío en lugar de detenerse.

Los dos conjuntos de helpers comparten la superficie de Sprig pero divergen en las extensiones específicas del motor. Las entradas de MappingLibrary destinadas al consumo interno del chart de Helm usan las convenciones de Helm (raíz .Values.<key> con V mayúscula, | default, composición basada en include); las entradas destinadas al consumo del lado de Aggrega usan las convenciones de Aggrega (.values.<key> en minúsculas, optional para el valor de respaldo sensible a la presencia). La entidad de biblioteca almacena los fragmentos literalmente; la forma de autoría sigue el lugar donde el fragmento debe renderizarse.

Los helpers personalizados de Aggrega por encima de Sprig son optional y capitalizedWords, ambos documentados arriba, y su index sustituye al de Go, como se documenta arriba. El resto de la superficie de helpers es exactamente el conjunto de Sprig v3.

Referencias cruzadas