Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Funções e helpers Sprig

O motor de templates do Aggrega conecta a biblioteca de funções Sprig v3 mais os helpers próprios do Aggrega (optional e capitalizedWords) em todo template Go que o renderizador avalia, e substitui a função index do Go por uma que interrompe diante de uma chave que o mapa não contém. Os autores que escrevem o valuesMapping: de uma Recipe, o injectMapping: de uma FeatureRecipe ou qualquer outra superfície de template que o renderizador avalia têm à disposição o conjunto completo de helpers do Sprig junto com as funções nativas de text/template do Go e os campos do contexto de runtime documentados em template-context-contract.md.

🔴 Leia “que o renderizador avalia” como o escopo que é, porque uma superfície de autoria fica fora dele. Uma coordenada source: estruturada é resolvida para que o artefato que ela nomeia possa ser fixado, e essa resolução não é uma passagem de renderização: ela registra os helpers próprios do Aggrega e nada mais, então uma chamada Sprig em um campo source:, ou em uma entrada locals: que ele lê, interrompe o pull. Uma entrada que nenhum campo source: lê é avaliada apenas pela renderização, com o conjunto completo. Resolver uma coordenada determina o que é fixado em vez de produzir um artefato, e é por isso que seu conjunto de funções é deliberadamente mais restrito — veja errors/fatal-halts.md “Resolving a source: coordinate registers a narrower function set (A resolução de uma coordenada source registra um conjunto de funções mais restrito)” para a interrupção e a forma portável a usar em vez disso.

O conjunto do Sprig é registrado sozinho para a interpolação de parâmetros, e junto com os helpers próprios do Aggrega nas superfícies de template de valor do renderizador.

O que está conectado

O Sprig v3 expõe toda a sua superfície de helpers — cerca de 200 funções nas categorias abaixo. Esta página esboça as categorias com os helpers comuns de cada uma; a referência canônica por função é a documentação upstream do Sprig.

  • Strings — upper, lower, title, trim, trimAll, trimPrefix, trimSuffix, replace, contains, hasPrefix, hasSuffix, substr, quote, squote, cat, indent, nindent, repeat, helpers de estilo de nome (snakecase, camelcase, kebabcase), helpers de abreviação (abbrev, abbrevboth, trunc), helpers de checksum (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.
  • Dicionários — dict, get, set, unset, hasKey, keys, values, pick, omit, pluck, merge, mergeOverwrite, dig, deepCopy.
  • Matemática — add, sub, mul, div, mod, add1, min, max, ceil, floor, round, mais as variantes decimais com o sufixo f (addf, subf, mulf, divf, minf, maxf).
  • Conversão — int, int64, float64, atoi, toString, toDecimal, seq, until, untilStep.
  • Codificação — b64enc, b64dec, b32enc, b32dec, toJson, toPrettyJson, toRawJson, fromJson, mais as variantes JSON com o prefixo must que expõem erros de decodificação em vez de zerar silenciosamente.
  • Verificações de tipo — typeOf, typeIs, typeIsLike, kindOf, kindIs, deepEqual, empty.
  • Valores padrão e fluxo — default, coalesce, all, any, ternary, fail (gera um erro de template com uma mensagem personalizada — a forma canônica de abortar uma renderização com uma mensagem de guarda).
  • Regex — regexMatch, regexFind, regexFindAll, regexReplaceAll, regexReplaceAllLiteral, regexSplit, regexQuoteMeta, mais as variantes estritas com o prefixo must.
  • Caminhos — base, dir, clean, ext, isAbs (estilo Unix); osBase, osClean, osDir, osExt, osIsAbs (conforme o sistema operacional).
  • SemVer — semver, semverCompare.
  • URL — urlParse, urlJoin.
  • Datas — ago, date, dateInZone, dateModify, duration, durationRound, htmlDate, htmlDateInZone, now, toDate, unixEpoch.

Ressalva sobre o determinismo

O Aggrega garante saída idêntica byte a byte para entrada idêntica byte a byte. Um subconjunto dos helpers do Sprig lê o estado do ambiente e quebra essa garantia quando invocado a partir de um template. Os autores devem evitar os seguintes helpers nas superfícies de template que contribuem para artefatos renderizados:

  • Leitores do relógio do sistema — now, date, dateInZone, dateModify, htmlDate, htmlDateInZone, ago quando chamado sem um horário de referência congelado.
  • Geradores aleatórios — randAlpha, randAlphaNum, randAscii, randNumeric, randBytes, randInt, uuidv4.
  • Leitores do ambiente — env, expandenv (leem variáveis de ambiente do processo, que diferem entre as estações de trabalho dos operadores e os runners de CI).
  • Resolvedores de rede — getHostByName.

Esses helpers não são bloqueados pelo motor; eles fazem parte do conjunto do Sprig v3. A disciplina de evitá-los em templates do caminho de renderização é mantida pelos revisores e pela garantia de saída determinística da qual dependem os autores e o catálogo da biblioteca padrão.

Números em um template de valor

Um número que um autor escreve chega a um template de valor como número. Um número sem parte decimal é um inteiro e é impresso inteiro: 1000000 imprime 1000000. Qualquer outro número é impresso em sua forma decimal exata mais curta, nunca em notação exponencial: um 0.0000001 escrito pelo autor imprime 0.0000001 e um 1e21 escrito pelo autor imprime 1000000000000000000000, quer o template escreva o valor diretamente, quer o converta em texto com toString, quote, printf "%v" ou toJson. Um número que uma função matemática retorna — mulf, float64, round e afins — é o valor próprio dessa função e é impresso na forma própria dessa função, que é a notação exponencial para um valor muito pequeno ou muito grande: {{ mulf .values.ratio 1 }} imprime 1e-07 para um 0.0000001 escrito pelo autor.

As comparações — eq, ne, lt, le, gt e ge — leem dois números pelo valor, seja qual for o tipo que carrega cada um, de modo que um inteiro escrito pelo autor se compara com um decimal escrito no template, e 3 é igual a 3.0:

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

Um número nunca é comparado com um texto: qualquer uma das seis, ao receber um número e um texto entre aspas, interrompe o build, nomeando os dois tipos. Compare o número com um número escrito sem aspas, ou converta-o primeiro em 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

A interrupção é A value template failed while it ran (Um template de valores falhou durante a execução). Uma asserção lê um número escrito pelo autor da mesma forma; veja Números nesta superfície.

Presença e vazio — duas perguntas diferentes

Um template faz uma de duas perguntas sobre um valor, e cada pergunta tem seus próprios helpers.

  • O autor o escreveu? hasKey e optional respondem pela presença. Uma chave que o autor escreveu está presente seja qual for seu conteúdo — 0, "" e false incluídos — e somente uma chave que o autor omitiu está ausente.
  • Está vazio? default, with, if e empty respondem pelo vazio. 0, "", false, uma lista vazia, um mapa vazio e um valor ausente contam todos como vazios ali, como no Helm.
.values.replicashasKey .values "replicas"optional .values "replicas" 1.values.replicas | default 1if .values.replicas
ausentefalse11false
0true01false
3true33true

Um valor que pode legitimamente ser 0, "" ou false — uma contagem de réplicas igual a zero, um timeout igual a zero, uma flag desativada — é testado com hasKey ou optional, para que o 0 do autor chegue à saída como 0. default, with e if servem para um valor cuja forma vazia não tem significado próprio, em que “vazio” e “não escrito” podem ser tratados da mesma forma. Leia uma determinada chave de uma única maneira por template: uma chave que o template também lê como caminho com pontos conta como presente, como descreve o limite de optional.

Helpers específicos do Aggrega

optional — valor alternativo sensível à presença

optional <map> <key> <fallback> retorna o valor em <key> dentro de <map> se a chave estiver presente; caso contrário, retorna <fallback>. Diferentemente do default do Sprig, optional distingue “chave ausente” de “chave presente com um valor zero, vazio ou falso”.

A assinatura recebe o mapa e a chave como argumentos separados porque um valor passado pelo operador | do template Go perdeu o acesso ao seu mapa pai. Sem o mapa pai no escopo, a presença não pode ser verificada.

Um limite à verificação de presença, e ele vem do template e não do helper: um template de valor lê uma chave ausente como nada, o que faz fornecendo um valor vazio em cada chave ausente que o template nomeia como caminho com pontos e lê como valor. Assim, um template que lê uma chave tanto por meio de optional quanto como esse caminho encontra essa chave presente e vazia, e obtém o valor vazio em vez do valor alternativo. Leia uma chave de uma única maneira por template e as duas respostas concordam.

# 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

O último caso é a distinção que o default do Sprig não consegue fazer. {{ .infra.replicas | default 1 }} retorna 1 quer replicas tenha sido escrito como 0, quer tenha sido omitido — a confusão que impede os padrões legítimos de scale-to-zero, sem novas tentativas, sem timeout e de flag falsa.

Convenção para as aspas das chaves: prefira crases. Os templates Go aceitam para o argumento de chave tanto literais de string entre aspas duplas ("replicas") quanto entre crases (`replicas`); ambos produzem a mesma string no momento da avaliação do template. Os exemplos do catálogo e da documentação usam uniformemente a forma com crases porque ela é segura para YAML em qualquer contexto de aspas. Uma chave entre aspas duplas dentro de um escalar YAML entre aspas duplas encerra a string YAML no meio do template:

# 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 }}"

Quando o template fica dentro de um escalar de bloco YAML (forma |) ou como um escalar de valor simples, ambas as formas são renderizadas corretamente. Quando o template está incorporado em um escalar YAML entre aspas duplas (o padrão field: "{{ ... }}" de valor de campo como template), as crases são obrigatórias. A convenção única (sempre crases) evita por completo a armadilha das aspas do YAML.

Quando preferir optional a default. Use optional quando o campo puder legitimamente ser zero, vazio ou falso e o autor do catálogo precisar distinguir “o autor não definiu isto” de “o autor definiu isto com um valor falsy”. Use default quando a confusão for aceitável (p. ex., campos de string em que vazio é inválido; campos numéricos em que zero é inválido).

Disponibilidade por superfície. optional está registrado em toda superfície que o renderizador avalia: as superfícies de template de valor (valuesMapping da Recipe, injectMapping da FeatureRecipe, provides, pipeline.with, o corpo do Workload), o avaliador de asserções e os templates de caminho (directory: / subDirectory: nas fronteiras da Release). O que difere na superfície de templates de caminho não é o conjunto de helpers, mas a política de chave ausente: um template de caminho trata uma chave ausente como erro e não como vazia, porque um segmento de caminho silenciosamente vazio produz um layout de sistema de arquivos quebrado que só é descoberto depois do build. optional lê uma chave sem que essa política estrita dispare primeiro, e é isso que o torna utilizável ali.

capitalizedWords — reduzir um nome a letras e dígitos

capitalizedWords <string> lê seu argumento como palavras separadas por sequências de qualquer caractere fora das letras e dígitos ASCII, coloca em maiúscula a primeira letra de cada palavra e as junta. Todo caractere do resultado é uma letra ou um dígito.

Ele existe porque alguns destinos aceitam apenas letras e dígitos nos nomes pelos quais endereçam recursos, enquanto um id de componente pode legitimamente conter um ponto, um hífen ou um sublinhado. Escrever essa conversão à mão em cada Recipe que precisa dela produz várias grafias de uma mesma ideia; um único helper dá a todo autor a mesma resposta.

# 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

🔴 O resultado não identifica o nome de onde veio. Todo separador é descartado, de modo que dois ids que diferem apenas na posição de seus separadores chegam ao mesmo resultado — payments-db e payments_db dão ambos PaymentsDb. O helper não consegue detectar isso, porque vê um nome de cada vez; capturá-lo cabe ao que endereça recursos pelo resultado. Um destino que faz isso rejeita a colisão em vez de emitir uma implantação em que falta um dos dois: no build para CloudFormation, dois componentes cujos ids se reduzem a um mesmo nome interrompem o build, e a mensagem nomeia cada id que chegou a ele. Escolha ids que difiram em mais do que a pontuação, e a questão não se coloca.

Disponibilidade por superfície. capitalizedWords está registrado onde quer que optional esteja: em toda superfície que o renderizador avalia e na resolução de uma coordenada source: estruturada. Não está disponível na interpolação de parâmetros do Aggregate, que oferece apenas o conjunto do Sprig.

index — uma chave que o mapa deve conter

index <collection> <key>... lê uma coleção por posição ou por chave, como faz o próprio index do Go — com uma diferença. Quando a coleção é um mapa e o mapa não contém a chave, index interrompe o build e nomeia a chave, enquanto o do Go responde com um valor vazio que é impresso como o 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")

É a leitura a usar onde a chave precisa estar presente — uma credencial lida sob o nome de variável que a Recipe calculou, uma chave que outro template publica — para que uma chave ausente pare o build em vez de chegar a um artefato como <no value>. Onde a chave pode legitimamente estar ausente, teste-a primeiro: {{ optional .values `replicas` 1 }} fornece um valor alternativo, o get do Sprig retorna uma string vazia e hasKey testa sem ler. Ler por meio de index e depois aplicar default não fornece um valor alternativo, porque a interrupção vem antes de default ser executado. Uma chave que está presente e contém null não está ausente: index a retorna, e ela é impressa como <no value>.

A interrupção é uma propriedade apenas de index, e é a mesma em toda superfície — os templates de valor, o avaliador de asserções, os templates de caminho, uma coordenada source: estruturada, a interpolação de parâmetros do Aggregate, o predicado validate: de um parâmetro e os predicados x-aggrega-when: / x-aggrega-validate: de um esquema. Uma leitura com ponto de uma chave não definida segue a política de chave ausente da própria superfície e não é afetada. A interrupção está documentada em errors/fatal-halts.md “A template indexes a map with a key the map does not hold (Um template indexa um mapa com uma chave que o mapa não contém)”.

Helpers comuns NÃO disponíveis

O Helm estende o text/template do Go com helpers de template de chart que costumam ser confundidos com helpers gerais do Sprig. Nenhum deles está registrado no renderizador do Aggrega. Os templates que o renderizador do Aggrega avalia (valuesMapping: da Recipe, injectMapping: da FeatureRecipe, provides, o corpo do Workload, o avaliador de asserções) não podem chamá-los:

  • include — a forma preferida do Helm para invocar um fragmento de template definido com uma saída de string encadeável por pipe. O renderizador do Aggrega não o registra. Use em vez disso {{ template "name" . }} do template Go padrão (a forma apenas com efeitos colaterais); para uma saída encadeável por pipe, componha usando fragmentos de MappingLibrary e diretivas $import:.
  • tpl — reavalia uma string como template aninhado em relação ao contexto atual. O Aggrega não o registra; a reavaliação aninhada não faz parte da superfície de templates. Autores que precisam de valores calculados devem compô-los com os helpers de string do Sprig e emitir o valor final diretamente.
  • required — faz a renderização do chart falhar com uma mensagem personalizada quando o valor nomeado está ausente. O Aggrega não o registra. A aplicação de campos obrigatórios no Aggrega fica na camada de contratos de parâmetros tipados (um slot parameters: de um Aggregate com required: true que a Release deixa sem preencher interrompe o build com E0165, nomeando o slot e o lugar onde o Aggregate o declara); as verificações de marcadores de obrigatoriedade por template usam o fail do Sprig para gerar um erro de template fatal que carrega a string fornecida.
  • warn — emite uma nota não fatal no terminal do operador. O Aggrega não o registra. Templates que precisam interromper a renderização com uma mensagem explicativa devem usar o fail do Sprig; templates que precisam recorrer a um valor alternativo sem interromper devem contar com as ramificações if/else padrão do Go.

Inventário de helpers entre motores (fundamental para autores de MappingLibrary)

Os fragmentos de MappingLibrary podem ter como destino um de dois locais de consumo:

  • Consumo do lado do Aggrega (valuesMapping: da Recipe, injectMapping: da FeatureRecipe etc., avaliados pelo renderizador do Aggrega). Os helpers disponíveis são: o Sprig v3 completo (default, coalesce, quote, nindent, indent, b64enc etc.) mais os próprios do Aggrega (optional, capitalizedWords), e index interrompe diante de uma chave que o mapa não contém. Os helpers de template de chart (include, tpl, required, warn) NÃO estão disponíveis.
  • Consumo interno ao chart do Helm (conteúdo de values.yaml do chart ou templates/*.yaml do chart renderizados a jusante pelo próprio motor de templates do Helm). Os helpers disponíveis são: o Sprig v3 completo mais os helpers de template de chart do Helm (include, tpl, required, warn). Os helpers próprios do Aggrega NÃO estão disponíveis, e index ali é o próprio do Go, que responde a uma chave ausente com um valor vazio em vez de interromper.

Os dois conjuntos de helpers compartilham a superfície do Sprig, mas divergem nas extensões específicas do motor. As entradas de MappingLibrary destinadas ao consumo interno ao chart do Helm usam as convenções do Helm (raiz .Values.<key> com V maiúsculo, | default, composição baseada em include); as entradas destinadas ao consumo do lado do Aggrega usam as convenções do Aggrega (.values.<key> em minúsculas, optional para o valor alternativo sensível à presença). A entidade de biblioteca armazena os fragmentos literalmente; a forma de autoria segue o local onde o fragmento se destina a ser renderizado.

Os helpers personalizados do Aggrega além do Sprig são optional e capitalizedWords, ambos documentados acima, e o seu index substitui o do Go, como documentado acima. O restante da superfície de helpers é exatamente o conjunto do Sprig v3.

Referências cruzadas