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

Convenções de nomenclatura

Este capítulo trata das regras de nomenclatura e de maiúsculas e minúsculas que se aplicam ao conteúdo criado em Aggrega: o padrão para nomes de instância criados pelo usuário, a disciplina de maiúsculas e minúsculas para nomes de campos na DSL, o formato que a plataforma usa para os identificadores que ela define, e não você, e a sintaxe de comentários usada na superfície de criação YAML.

Nomes de instância

Os nomes de instância escritos pelo usuário — as chaves que o desenvolvedor escreve para componentes, features, agregados, subsistemas, fronteiras, e sockets e aliases de uses — seguem todos um único padrão: ^[a-zA-Z0-9_-]+$. Tanto kebab-case (pii-filter, my-agent) quanto snake_case (openai_key, db_credentials) são válidos; as equipes podem adotar a convenção que preferirem.

Caracteres permitidos: alfanuméricos (a-z, A-Z, 0-9), hifens (-) e sublinhados (_). Nenhum outro caractere é permitido.

Exemplos:

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
PadrãoEscopoExemplos
^[a-zA-Z0-9_-]+$Todos os nomes de instância escritos pelo usuárioweb-server, openai_key, pii-filter

O padrão é aplicado na resolução por meio de patternProperties do JSON Schema.

Quanto custa o nome de um componente, e por que maiúsculas custam mais em alguns destinos

O padrão acima diz o que você pode escrever. Quanto um nome custa é outra questão, e a resposta depende do destino em que um componente é implantado — por isso vale a pena saber disso antes de escolher um nome, e não no momento em que um build recusa um.

O nome de um componente se torna a identidade com que cada recurso que ele emite é marcado, e cada destino deriva os próprios nomes dessa identidade: um instalador de charts deriva dela um nome de release, um orquestrador de contêineres deriva nomes de serviço. Um destino cujo alfabeto é mais restrito que o padrão não consegue conter um caractere que não admite, e o Aggrega não converte silenciosamente esse caractere em um semelhante — dois nomes que um autor consegue distinguir não podem virar um único nome em um cluster. Por isso, um caractere que o destino não admite é escrito como sequência de escape, e uma sequência de escape é mais longa que o caractere que substitui.

A consequência prática: uma letra maiúscula é gratuita em alguns destinos e cara em outros.

  • Em um destino cujos nomes admitem maiúsculas — um arquivo compose de orquestração de contêineres, por exemplo — PaymentsAPI é mantido exatamente como você o escreveu e custa onze caracteres.
  • Em um destino cujos nomes só admitem minúsculas — o nome de release de um instalador de charts — cada maiúscula passa por escape, e um nome de apenas seis maiúsculas já excede o que esse destino aceita.

Há um segundo efeito, e ele é o mais grave: uma sequência de escape começa com um hífen. Um destino que exige que um nome comece com uma letra minúscula ou um dígito vai, portanto, recusar um nome cujo primeiro caractere seja um que ele não admite, por mais curto que seja o restante — nenhum encurtamento resolve isso.

As recomendações decorrem dos dois efeitos. Prefira letras minúsculas e dígitos, com hifens entre as palavras, e comece um nome com uma letra minúscula. payments-api é mantido sem alterações por todos os destinos para os quais o Aggrega fornece um provider. payments_api é mantido por um arquivo compose, mas não pelo destino helm, cujos nomes de recurso não admitem sublinhado: os Services, workloads e a release a que ele dá o nome do componente são escritos payments-zuapi. PaymentsAPI custa ainda mais ali. Uma Recipe que publica o endereço de um recurso desses lê a grafia própria do destino em vez de prevê-la — veja templates/rendered-resource-names.md.

Um dígito inicial pode ser escrito legalmente e não custa nada em um arquivo compose, mas o destino helm o recusa. O nome de um Service do Kubernetes precisa começar com uma letra, e os Services que um chart ou um workload sintetizado emite recebem o nome do componente; assim, um componente chamado 1cache interrompe um build do helm — a recusa nomeia o componente e diz que o nome de um Service precisa começar com uma letra — em vez de gerar Services que o cluster recusaria.

Nada disso é uma regra que o compilador aplica por conta própria — ele não detém as regras de nomenclatura de nenhum destino e não inventa nenhum limite. O provider de cada destino responde pelos próprios nomes; assim, um nome só é recusado quando o destino em que um componente é de fato implantado diz que não pode usá-lo, e a recusa traz o motivo próprio desse destino e aponta para a chave spec.components que você escreveu. Um nome aceito em um destino e recusado em outro é o comportamento esperado, e não uma inconsistência.

Os nomes que o próprio Aggrega compõe — a identidade de uma feature anexada em uma fronteira, por exemplo — são tratados ao contrário: são encurtados para caber no destino em vez de recusados, porque são montados a partir de partes escritas em vários lugares e nenhum autor sozinho consegue ver o comprimento que atingem. Só é recusado um nome que você escreveu.

O ponto como separador de caminho reservado

O caractere ponto (.) é excluído de todos os nomes de instância escritos pelo usuário. O ponto cumpre a função estrutural de separador de caminho gerado pelo compilador para referências a componentes entre agregados.

Quando um Aggregate raiz importa um subagregado chamado data-layer que contém um componente chamado main-db, o compilador constrói o ID absoluto achatado data-layer.main-db unindo com um ponto o nome de instância do agregado e o nome de instância do componente. Esse caminho com pontos aparece em:

  • Destinos uses do desenvolvedor: target: data-layer.public_db — referência a um componente exportado de um agregado aninhado.
  • Os próprios diagnósticos do build: uma interrupção ou um aviso sobre esse componente o nomeia pelo seu caminho com pontos, de modo que o nome que você lê é o que você pode procurar nos seus documentos.

O separador não chega a um nome

Um caminho com pontos é um endereço dentro dos seus documentos, e não é um nome que um destino de implantação vá aceitar. O nome de um Service do Kubernetes não admite nenhum ponto; pior, um ponto dentro de um endereço de cluster é o que separa um serviço do namespace em que ele está, de modo que um nome com pontos entregue a um consumidor como host seria resolvido para outro serviço em vez de falhar.

Por isso, o separador é reescrito em cada nome e label que o build deriva da identidade de um componente, e é reescrito em vez de substituído: data-layer.main-db se torna data-layer-zdmain-db. Substituí-lo por um caractere que um destino aceita permitiria que dois componentes diferentes chegassem a um único nome — data-layer.main-db e um componente que alguém escreveu como data-layer-main-db — e um nome a que dois componentes chegam não identifica nenhum deles.

O que isso alcança, e o que não alcança:

  • Alcança os nomes e labels derivados da identidade — metadata.name em um recurso que o Aggrega sintetiza, os labels aggrega.ai/component-id e app.kubernetes.io/name, os seletores que correspondem a eles, os nomes de arquivo emitidos, {{ .context.instance_id }} e o nome que um provider deriva para si, como o nome de uma release do helm. Eles mudam juntos, de modo que um endereço que uma Recipe compõe a partir da chave que nomeia um recurso — .context.instance_id onde o destino o nomeia segundo a identidade, .context.rendered_name onde o destino informa um nome próprio — continua nomeando o recurso que o build emite.
  • Não alcança um nome que você escreveu. Um nome de componente sem nenhum separador volta idêntico byte a byte, de modo que só um componente trazido por um Aggregate importado tem, na saída, uma grafia diferente da do documento.
  • Não alcança os nomes dentro de um chart ou fragmento fornecido por um autor. Eles pertencem a quem os escreveu, e um nome trazido de um chart de terceiros — um nome de recurso personalizado da forma <plural>.<group>, em que o ponto é legal — é emitido exatamente como esse chart o escreveu.

🔴 Esse último ponto tem uma consequência para o que uma Recipe deve publicar, e é a coisa mais fácil de errar nesta página. Os templates próprios de um chart fornecido nomeiam seus recursos segundo a identidade que a plataforma lhes entrega — um nome de release, escrito no alfabeto próprio dessa plataforma e não no descrito acima — e o destino helm nomeia os workloads que sintetiza segundo esse mesmo nome de release. Assim, para a saída gerada a partir de fontes que você forneceu, e para um workload sintetizado em um destino desse tipo, {{ .context.instance_id }} não é o nome que esses recursos têm, e um endereço publicado a partir dele não nomeia nada sempre que os dois alfabetos diferem. A chave que traz o nome da plataforma, e quais providers informam um, estão descritos em templates/rendered-resource-names.md.

Reescrever o separador custa caracteres, e um nome de comprimento limitado pode ficar sem eles. O separador é substituído por uma sequência de escape curta em vez de um único caractere, de modo que uma identidade qualificada, depois de escrita, fica um pouco mais longa do que aparece nos seus documentos. Isso só importa onde o nome resultante tem comprimento limitado: o destino que gera um componente informa o comprimento de valor de label que aceita, e onde a identidade escrita o excederia, o build é interrompido em vez de emitir um valor que o destino rejeitaria. A interrupção informa o comprimento em que a própria identidade precisa caber — o comprimento antes da reescrita, de modo que um nome escolhido dentro dele funcione na primeira vez — e a correção é encurtar as partes escritas pelo autor: o nome que o documento importador dá ao subagregado, ou o nome do próprio componente dentro dele.

O separador é o motivo habitual pelo qual um nome é escrito mais longo do que se lê, mas não o único. Duas formas que um nome escrito pelo autor pode legalmente assumir também não podem ser mantidas como estão, porque deixá-las tornaria ambígua uma sequência de escape: um nome que termina em hífen, e um nome em que um hífen é seguido imediatamente por z. Cada uma é reescrita da mesma maneira, com o mesmo custo. Qualquer outro nome escrito pelo autor volta idêntico byte a byte, de modo que um nome formado por letras, dígitos, sublinhados e hifens entre palavras não é afetado por nada disso.

Um nome de socket no bloco uses próprio de um componente ou corresponde a uma chave no usesSchema da entidade de catálogo — um socket declarado — ou nomeia um socket ad hoc do próprio desenvolvedor, que é compilado mesmo em uma entidade que não declara nenhum usesSchema; um nome a uma única edição de distância de um socket declarado gera um aviso que nomeia as duas grafias. O uses por aresta de uma Release, e o de um anexo de Feature, só podem nomear um socket que a entidade declara, e qualquer outro nome falha com um erro de validação unknown-uses-socket.

Capitalização dos campos

A DSL separa o YAML voltado ao desenvolvedor (escrito por pessoas) dos contratos internos do compilador (consumidos por templates e ferramentas):

  • YAML voltado ao desenvolvedor (camelCase): nomes de campo com várias palavras nos schemas de Aggregate, Release, Component, Feature, Recipe, FeatureRecipe, Manifest e Plugin usam camelCase. Exemplos: exportedComponents, syncWave, subDirectory, featuresSchema, usesSchema, valuesMapping, injectMapping, executionScope, appliesTo, appliesToAnyOf, conflictsWith. Segue as convenções da API do Kubernetes.
  • Contratos internos (snake_case): nomes de campo com várias palavras no schema do IR Graph e no schema do Template Context usam snake_case. Exemplos visíveis ao usuário que os autores de Recipe encontram: instance_id (em .context.instance_id — a identidade da Recipe), inject_raw (em .inject_raw, um pilar de nível superior ao lado de .inject em vez de uma chave sob .context — o contrato de injeção não modificado), attachment_name (no contexto de uma FeatureRecipe de anexo — identifica o slot que o anexo preenche, ou o nome sob o qual foi anexado). Segue as convenções de JSON API e se alinha à geração de tags de struct JSON do Go.
  • Campos de uma só palavra: em minúsculas independentemente do contexto. Exemplos: values, infra, inject, provides, locals, features, labels, annotations, boundaries, components, subsystems, pipeline, source.

Os desenvolvedores não encontram snake_case no YAML que escrevem, e os autores de templates não encontram camelCase nos seus templates Go. As adições ao schema seguem essas convenções.

Três capitalizações que se cruzam em uma única instrução

A escrita de Recipes cruza rotineiramente as três convenções de capitalização em uma única instrução: o campo DSL definido pelo schema usa camelCase, o nome de instância escrito pelo usuário usa kebab-case ou snake_case, e a referência ao contexto do template usa snake_case. Os autores que percebem esses cruzamentos como convenções separadas leem o YAML resultante sem dificuldade; os que tentam explicar as capitalizações como uma única convenção se atrapalham com as fronteiras.

O exemplo canônico: o template valuesMapping: de uma Recipe que referencia a instância de Component gerada por meio do contexto do template.

# 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

Três capitalizações, uma instrução:

  • valuesMapping — camelCase. O nome do campo DSL que o schema define para o template de mapeamento da Recipe. Camel porque o YAML da linguagem voltado ao desenvolvedor segue as convenções da API do Kubernetes.
  • web-server (referenciado indiretamente por meio do componente gerado) — kebab-case. O nome de instância escrito pelo usuário no Aggregate; o desenvolvedor escolheu a forma com hífen. Poderia igualmente ser web_server (snake_case); ambos são válidos segundo o padrão de nomes de instância.
  • instance_id, image — snake_case. Nomes de campo dentro do contexto do template (.context.instance_id, .values.image). Snake porque o IR Graph e o contexto do template seguem as convenções de JSON-API e se alinham à geração de tags de struct JSON do Go.

As três capitalizações não são intercambiáveis. Um autor de Recipe que escreve {{ .context.instanceId }} (camelCase) interrompe o build: .context declara suas chaves, e instanceId não é uma delas, então a referência é recusada antes que qualquer coisa seja gerada e o diagnóstico lista as chaves que .context define — veja errors/fatal-halts.md “Template references a root the render context does not define (O template referencia uma raiz que o contexto de renderização não define)”. Um desenvolvedor que escreve web.server (com ponto) esbarra na rejeição do padrão de nomes de instância, porque o ponto é reservado como separador de caminho. O objetivo da disciplina: tenha em mente as três convenções ao ler ou escrever; apoie-se nas fronteiras (onde você está no YAML ou no template) para saber qual capitalização se aplica.

Identificadores definidos pela plataforma

Tudo o que foi dito acima rege os nomes na superfície de escrita — um nome de instância que você escolhe, um campo de schema que a linguagem define para você preencher, uma chave do contexto do template que você lê. Outros dois registros regem os identificadores que a própria plataforma define e que você apenas relê ou digita. Eles são separados porque cumprem funções diferentes, e a função decide a forma.

O registro descritivo: kebab-case, de forma uniforme. Um identificador deste registro diz em palavras o que nomeia, para que você possa lê-lo e agir sem consultar nada. Uma flag da CLI, o id de uma regra de lint de publicação, o código de uma classe de diagnóstico e o código sob o qual uma condição de interrupção é registrada pertencem todos a ele.

--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

Quando uma classe de diagnóstico tem uma flag de supressão, o código e a flag são as mesmas palavras na mesma ordem — unsupported-field é silenciado por --no-unsupported-field-warnings — de modo que a classe que você identificou indica a flag a usar, sem nada a traduzir. Um código de classe é o nome estável que as ferramentas usam para reconhecer uma constatação sem analisar o texto da sua mensagem; a redação da mensagem pode melhorar, o código não muda.

O registro de códigos curtos: a letra E e quatro dígitos. Uma condição de interrupção também traz um código curto — E0007 — e ele é o único identificador definido pela plataforma que não está em kebab-case. O motivo é a posição: ele abre cada diagnóstico de interrupção, ao lado da categoria, antes do arquivo e da linha que você vai ler.

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

Um código descritivo não cabe ali. O mais longo deles preencheria sozinho um terminal estreito, antes da localização que diz onde olhar. Por isso o cabeçalho recebe um identificador escolhido pela largura, e a troca é deliberada: quatro dígitos não dizem nada sobre uma condição, e é por isso que cada código curto é publicado ao lado da condição que nomeia e do texto com que essa condição é exibida na referência de sentinelas de erro. Cite um código curto em um relatório, digite-o em uma busca e resolva-o ali.

Os dois registros nomeiam as mesmas condições a partir de duas direções, e nenhum substitui o outro. Use o código descritivo quando estiver escrevendo uma ferramenta que se baseia em uma condição; cite o código curto quando estiver falando com uma pessoa sobre uma condição.

O kebab-case que aparece aqui e nos nomes de instância não é uma colisão. O padrão de nomes de instância trata do que você tem permissão para escrever — ali, kebab-case e snake_case são ambos válidos, e as equipes escolhem um. Este registro trata do que a plataforma escreve, onde não há nada a escolher: você nunca escolhe a grafia do id de uma regra de lint, e a plataforma nunca escolhe a grafia do nome do seu componente.

Ele mantém as capitalizações dos campos inalteradas. Os campos de schema escritos pelo autor continuam em camelCase e as chaves do contexto do template continuam em snake_case. Nenhum dos identificadores deste registro é um campo em qualquer uma das duas superfícies — são nomes curtos e estáveis para uma flag, uma regra ou uma classe de constatações — de modo que um código de diagnóstico em kebab-case não diz nada sobre como se escreve um campo de schema.

Disciplina de sufixos na nomenclatura de caminhos de documento

Um subconjunto de campos da linguagem contém valores de caminho de documento — strings que apontam para uma posição dentro de outro documento (a seção volumes de um Workload gerado, a entrada featuresSchema de um Component, o nível mappings de um Manifest). Os valores seguem a sintaxe RFC 6901 JSON Pointer — tokens separados por barras que identificam o caminho pelo documento de destino.

A RFC 6901 é a gramática de caminhos de referência para toda superfície de caminho de documento no Aggrega. O contrato de plugins Wasm consome documentos JSON Patch RFC 6902 cujos caminhos são ponteiros RFC 6901 (conforme a saída JSONPatch do papel label-transform em plugins/plugin-contract.md); o inventário de strings de formato da gramática de URI cita a RFC 6901 ao lado da sintaxe de templates Go e dos helpers Sprig (conforme vocabulary/uri-grammar.md “Format-string inventory”); as exportações .locals de cada Recipe usam a RFC 6901 para apontar para posições do Workload sintetizado que os plugins Wasm Injector recebem no pipeline de plugins por meio do payload with da sua etapa. Uma gramática, várias superfícies que a consomem.

A disciplina de sufixos na nomenclatura distingue os dois lados de escrita desses valores de caminho por meio de uma divisão deliberada de sufixos, alinhada à seção mais ampla sobre a capitalização dos campos acima:

  • Os campos de schema que contêm JSON Pointers RFC 6901 usam o sufixo camelCase *Path. Os campos fazem parte do schema YAML voltado ao desenvolvedor, por isso seguem a convenção camelCase. Nenhum schema de entidade declara um campo assim; os caminhos de documento que um autor escreve são as chaves de exportação .locals abaixo.
  • As chaves de exportação .locals que contêm JSON Pointers RFC 6901 usam o sufixo snake_case *_path. As chaves fazem parte da superfície de exportação interna da Recipe — lidas pelos templates seguintes da própria Recipe e por um pipeline de plugins Wasm por meio do payload pipeline[].with que referencia .locals — por isso seguem a convenção snake_case. Exemplos:
    • volumes_path — .locals.volumes_path: "/spec/template/spec/volumes" expõe a posição do array volumes do Workload sintetizado.
    • containers_path — .locals.containers_path: "/spec/template/spec/containers" expõe a posição do array containers.
    • resource_path — .locals.resource_path: "/resource/aws_s3_bucket/main" expõe um caminho de recurso nativo do Terraform.
    • root_path — .locals.root_path: "/data" expõe o caminho raiz que o pipe do renderizador consome.

As duas convenções de sufixo refletem a convenção de dois níveis da seção sobre a capitalização dos campos: os campos definidos pelo schema usam camelCase; os identificadores escritos pelo usuário ou privados da Recipe usam snake_case (ou kebab-case). A disciplina de sufixos *Path / *_path torna visível no nível do identificador a natureza de gramática de caminho do valor — quem vê qualquer um dos sufixos sabe que o valor segue a sintaxe RFC 6901 sem precisar inspecionar o próprio valor.

Exemplo comentado: um Wasm Injector que consome as exportações *_path de uma 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 }}"

As chaves *_path são exportações privadas da Recipe; os valores containers_path / volumes_path são strings JSON Pointer RFC 6901. O plugin Injector consome as strings para posicionar sua saída JSONPatch em relação à AST do Workload gerado. O attachment as alcança no próprio pilar .locals — não existe um campo .context.uses[].locals, então um consumidor não consegue ler os locals do seu destino através de uma aresta uses; o que atravessa uma aresta é o provides do destino.

Para o inventário mais amplo de strings de formato (sintaxe de templates Go, funções Sprig, JSON Pointer ao lado de regex SemVer e da gramática de seletores de labels), veja vocabulary/uri-grammar.md “Format-string inventory”. Para a superfície do contrato de plugins Wasm que consome patches RFC 6902 endereçados por ponteiros RFC 6901, veja plugins/plugin-contract.md.

Sintaxe de comentários

Os caracteres de comentário dependem da linguagem ao redor:

  • Contexto YAML (a superfície de escrita padrão para toda entidade do Aggrega): use #
  • Contexto de template Go (dentro dos escalares de bloco valuesMapping: de uma Recipe, dos escalares de bloco injectMapping: de uma FeatureRecipe, das entradas de mapeamento de uma MappingLibrary e dos corpos assertions: dos blocos de asserções): use {{/* ... */}} para comentários de template que o mecanismo de templates reconhece e remove no momento da renderização, ou # para comentários no nível do YAML fora do corpo do template.

Os schemas em forma compacta sob schema:, usesSchema:, featuresSchema: e parameters: são YAML do começo ao fim; a anotação description: de cada campo é a superfície documentada para a documentação inline dos campos (port: { type: integer, description: "TCP listen port" }).