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

Convenções de nomenclatura

Este capítulo aborda as regras de nomenclatura e de capitalização que se aplicam ao conteúdo Aggrega escrito pelos autores: o padrão para os nomes de instância escritos pelo utilizador, a disciplina de capitalização para os nomes de campos na DSL, a capitalização que a plataforma usa para os identificadores que é ela, e não o utilizador, a definir, e a sintaxe de comentários usada na superfície de autoria YAML.

Nomes de instância

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

Caracteres permitidos: alfanuméricos (a-z, A-Z, 0-9), hífenes (-) e underscores (_). Nenhum outro carácter é 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ãoÂmbitoExemplos
^[a-zA-Z0-9_-]+$Todos os nomes de instância escritos pelo utilizadorweb-server, openai_key, pii-filter

O padrão é imposto na resolução através de patternProperties do JSON Schema.

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

O padrão acima diz o que se pode escrever. O que um nome custa é uma questão à parte, e varia consoante o destino em que um componente é implementado — por isso, vale a pena sabê-lo antes de escolher um nome e não no momento em que um build o recusa.

O nome de um componente torna-se a identidade com que é carimbado cada recurso que emite, e cada destino deriva os seus próprios nomes dessa identidade: um instalador de charts deriva um nome de release, um orquestrador de contentores deriva nomes de serviços. Um destino cujo alfabeto é mais restrito do que o padrão não consegue transportar um carácter que não admite, e o Aggrega não converte silenciosamente esse carácter num semelhante — dois nomes que um autor consegue distinguir não podem tornar-se um só nome num cluster. Assim, um carácter que o destino não admite é escrito como um escape, e um escape é mais longo do que o carácter que substitui.

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

  • Num destino cujos nomes admitem maiúsculas — um ficheiro compose de orquestração de contentores, por exemplo — PaymentsAPI é transportado exatamente como foi escrito e custa onze caracteres.
  • Num destino cujos nomes só admitem minúsculas — o nome de release de um instalador de charts — cada maiúscula é escapada, e um nome com seis maiúsculas, por si só, já excede o que esse destino aceita.

Há um segundo efeito, e é o mais incisivo: um escape começa por um hífen. Um destino que exija que um nome comece por uma letra minúscula ou um dígito recusará, portanto, um nome cujo primeiro carácter seja um que não admite, por mais curto que seja o resto — nenhum encurtamento resolve isso.

A orientação decorre dos dois efeitos. Prefira letras minúsculas e dígitos, com hífenes entre palavras, e comece um nome por uma letra minúscula. payments-api é transportado inalterado por todos os destinos para os quais o Aggrega disponibiliza um provider. payments_api é transportado por um ficheiro compose, mas não pelo destino helm, cujos nomes de recursos não admitem underscores: os Services, as cargas de trabalho e a release que nomeia a partir do componente escrevem-se payments-zuapi. PaymentsAPI custa ainda mais aí. Uma Recipe que publique o endereço de um desses recursos lê a grafia do próprio destino em vez de a prever — ver templates/rendered-resource-names.md.

Um dígito inicial é legal e não custa nada num ficheiro compose, mas o destino helm recusa-o. O nome de um Service do Kubernetes tem de começar por uma letra, e os Services que um chart ou uma carga de trabalho sintetizada emitem têm o nome do componente, pelo que um componente chamado 1cache interrompe um build helm — a recusa nomeia o componente e diz que o nome de um Service tem de começar por uma letra — em vez de renderizar Services que o cluster recusaria.

Nada disto é uma regra que o compilador aplique por iniciativa própria — não contém as regras de nomenclatura de nenhum destino e não inventa nenhum limite. O provider de cada destino responde pelos seus próprios nomes, pelo que um nome só é recusado quando o destino em que um componente é efetivamente implementado diz que não o pode usar, e a recusa apresenta a razão desse destino e aponta para a chave de spec.components que foi escrita. Um nome aceite num destino e recusado noutro é o comportamento esperado e não uma incoerência.

Os nomes que o próprio Aggrega compõe — a identidade de uma feature associada numa 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 sítios e nenhum autor isolado consegue ver o comprimento que atingem. Só é recusado um nome escrito pelo autor.

O ponto como separador de caminho reservado

O carácter ponto (.) está reservado e excluído de todos os nomes de instância escritos pelo utilizador. O ponto tem 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 juntando o nome da instância do agregado e o nome da instância do componente com um ponto. Este caminho com pontos aparece em:

  • Alvos de uses do programador: 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 nomeia-o pelo seu caminho com pontos, para que o nome que se lê seja aquele que se pode procurar nos documentos.

O separador não chega a um nome

Um caminho com pontos é um endereço dentro dos documentos e não é um nome que um destino de implementação aceite. 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 vive, pelo que um nome com pontos entregue a um consumidor como host resolveria para um serviço diferente em vez de falhar.

Por isso, o separador é convertido num escape em todos os nomes e etiquetas que o build deriva da identidade de um componente, e é convertido num escape em vez de substituído: data-layer.main-db torna-se data-layer-zdmain-db. Substituí-lo por um carácter que um destino aceite permitiria que dois componentes diferentes chegassem a um mesmo nome — data-layer.main-db e um componente que alguém escreveu como data-layer-main-db — e um nome a que chegam dois componentes não identifica nenhum deles.

O que isso abrange, e o que não abrange:

  • Abrange os nomes e etiquetas derivados da identidade — metadata.name num recurso que o Aggrega sintetiza, as etiquetas aggrega.ai/component-id e app.kubernetes.io/name, os seletores que lhes correspondem, os nomes de ficheiro emitidos, {{ .context.instance_id }} e o nome que um provider deriva para si próprio, como o nome de uma release helm. Movem-se em conjunto, pelo que um endereço que uma Recipe compõe a partir da chave que nomeia um recurso — .context.instance_id quando o destino o nomeia a partir da identidade, .context.rendered_name quando o destino reporta um nome próprio — continua a nomear o recurso que o build emite.
  • Não abrange um nome escrito pelo autor. Um nome de componente sem separador volta byte a byte, pelo que só um componente com que um Aggregate importado contribui é escrito de forma diferente na saída e no documento.
  • Não abrange os nomes dentro de um chart ou fragmento fornecido por um autor. Esses pertencem a quem os escreveu, e um nome transportado de um chart de terceiros — o nome de um recurso personalizado da forma <plural>.<group>, onde um ponto é legal — é emitido exatamente como esse chart o escreveu.

🔴 Esse último ponto tem uma consequência para aquilo que uma Recipe deve publicar, e é o mais fácil de errar nesta página. Os próprios templates de um chart fornecido nomeiam os seus recursos a partir da identidade que a plataforma lhes entrega — um nome de release, escrito no alfabeto dessa plataforma e não no acima — e o destino helm nomeia as cargas de trabalho que sintetiza a partir desse mesmo nome de release. Assim, para saída renderizada a partir de uma source fornecida, e para uma carga de trabalho sintetizada nesse destino, {{ .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 transporta o nome da plataforma, e que providers reportam um, estão em templates/rendered-resource-names.md.

Converter o separador num escape custa caracteres, e um nome limitado pode ficar sem eles. O separador é substituído por um escape curto e não por um único carácter, pelo que uma identidade qualificada fica um pouco mais longa escrita do que se lê nos documentos. Isso só importa quando o nome em que se torna é limitado: o destino que renderiza um componente diz qual o comprimento de valor de etiqueta que aceita e, quando a identidade escrita o excederia, o build interrompe-se em vez de emitir um valor que o destino rejeitaria. A interrupção indica o comprimento em que a própria identidade tem de caber — o comprimento antes de ser convertida, para que um nome escolhido dentro dele funcione à primeira — e a correção é encurtar as partes escritas pelo autor: o nome que o documento importador dá ao subagregado, ou o próprio nome do componente dentro dele.

O separador é a razão habitual pela qual um nome fica mais longo escrito do que se lê, mas não é a única. Duas formas que um nome escrito pelo autor pode legalmente assumir também não podem ser transportadas tal como estão, porque deixá-las tornaria um escape ambíguo: um nome terminado em hífen e um nome em que um hífen é imediatamente seguido de z. Cada uma é convertida da mesma forma, com o mesmo custo. Todos os outros nomes escritos pelo autor voltam byte a byte, pelo que um nome construído com letras, dígitos, underscores e hífenes entre palavras não é afetado por nada disto.

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 programador, que compila mesmo numa 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 ambas as grafias. O uses por aresta de uma Release, e o de uma associação 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 para o programador (escrito por pessoas) dos contratos internos do compilador (consumidos por templates e ferramentas):

  • YAML voltado para o programador (camelCase): os nomes de campos com várias palavras nos esquemas 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): os nomes de campos com várias palavras no esquema do grafo IR e no esquema do Template Context usam snake_case. Exemplos voltados para o utilizador que os autores de Recipes 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 e não uma chave sob .context — o contrato de injeção não mutado), attachment_name (no contexto de uma FeatureRecipe de associação — identifica o slot que a associação preenche, ou o nome sob o qual foi associada). Segue as convenções das APIs JSON e alinha-se com a 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 programadores 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 esquema seguem estas convenções.

Três capitalizações que se cruzam numa só instrução

A autoria de Recipes cruza habitualmente as três convenções de capitalização numa única instrução: o campo da DSL definido pelo esquema usa camelCase, o nome de instância escrito pelo utilizador usa kebab-case ou snake_case, e a referência ao contexto de template usa snake_case. Os autores que reconhecem os cruzamentos como convenções separadas leem o YAML resultante com clareza; os autores que tentam racionalizar as capitalizações como uma única convenção têm dificuldade com as fronteiras.

O exemplo canónico: o template valuesMapping: de uma Recipe que referencia a instância de Component renderizada através do contexto de 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 de campo da DSL que o esquema define para o template de mapeamento da Recipe. Camel porque o YAML voltado para o programador da linguagem segue as convenções da API do Kubernetes.
  • web-server (referenciado indiretamente através do componente renderizado) — kebab-case. O nome de instância escrito pelo utilizador no Aggregate; o programador escolheu a forma com hífenes. 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 campos dentro do contexto de template (.context.instance_id, .values.image). Snake porque o grafo IR e o contexto de template seguem as convenções das APIs JSON e se alinham com a 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 escreva {{ .context.instanceId }} (camelCase) interrompe o build: .context declara as suas chaves, e instanceId não é uma delas, pelo que a referência é recusada antes de qualquer renderização e o diagnóstico lista as chaves que .context define — ver 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 programador que escreva web.server (com um ponto) é rejeitado pelo padrão de nomes de instância, porque o ponto está reservado como separador de caminho. O objetivo da disciplina: ter as três convenções em mente ao ler ou escrever; confiar nas fronteiras (onde se está no YAML ou no template) para saber que capitalização se aplica.

Identificadores definidos pela plataforma

Tudo o que está acima rege os nomes na superfície de autoria — um nome de instância que se escolhe, um campo de esquema que a linguagem define para ser preenchido, uma chave do contexto de template que se lê. Dois outros registos regem os identificadores que a própria plataforma define e que o utilizador apenas lê ou escreve. São separados porque fazem trabalhos diferentes, e é o trabalho que decide a forma.

O registo descritivo: kebab-case, uniformemente. Um identificador aqui diz por palavras o que nomeia, para que se 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 está registada 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 pela mesma ordem — unsupported-field é silenciado por --no-unsupported-field-warnings —, pelo que a classe a que se fez corresponder 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 ocorrência sem analisar o texto da mensagem; a redação da mensagem pode melhorar, o código não muda.

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

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

Um código descritivo não pode ir aí. O mais longo deles encheria sozinho um terminal estreito, antes da localização que indica onde procurar. Por isso, o início leva um identificador escolhido pela largura, e o compromisso é deliberado: quatro dígitos não dizem nada sobre uma condição, razão pela qual cada código curto é publicado ao lado da condição que nomeia e do texto que essa condição apresenta, na referência de sentinelas de erro. Cite um código curto num relatório, escreva-o numa pesquisa e resolva-o aí.

Ambos os registos nomeiam as mesmas condições a partir de duas direções, e nenhum substitui o outro. Use o código descritivo quando escrever uma ferramenta que se baseia numa condição; cite o código curto quando falar com uma pessoa sobre uma.

O kebab-case aparecer aqui e nos nomes de instância não é uma colisão. O padrão de nomes de instância diz respeito ao que é permitido escrever — kebab-case e snake_case são ambos válidos aí, e as equipas escolhem um. Este registo diz respeito ao que a plataforma escreve, onde não há nada a escolher: nunca se escolhe a grafia do ID de uma regra de lint, e a plataforma nunca escolhe a grafia do nome de um componente.

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

Disciplina de sufixos de nomenclatura para caminhos de documentos

Um subconjunto de campos em toda a linguagem transporta valores de caminho de documento — cadeias que apontam para uma posição dentro de outro documento (a secção de volumes de um Workload renderizado, a entrada featuresSchema de um Component, o nível de mappings de um Manifest). Os valores seguem a sintaxe RFC 6901 JSON Pointer — tokens separados por barras que identificam o caminho através do documento de destino.

O RFC 6901 é a base de gramática de caminhos para todas as superfícies de caminhos de documentos no Aggrega. O contrato de plugins Wasm consome documentos JSON Patch RFC 6902 cujos caminhos são ponteiros RFC 6901 (segundo a saída JSONPatch do papel label-transform em plugins/plugin-contract.md); o inventário de cadeias de formato da gramática de URIs nomeia o RFC 6901 ao lado da sintaxe de templates Go e dos helpers Sprig (segundo vocabulary/uri-grammar.md «Format-string inventory»); as exportações .locals por Recipe usam o RFC 6901 para apontar para posições do Workload sintetizado que os plugins Wasm Injector recebem no pipeline de plugins através da carga with do seu passo. Uma gramática, várias superfícies consumidoras.

A disciplina de sufixos de nomenclatura distingue os dois lados de autoria destes valores de caminho através de uma divisão deliberada de sufixos, alinhada com a secção Capitalização dos campos acima:

  • Os campos de esquema que transportam JSON Pointers RFC 6901 usam o sufixo camelCase *Path. Os campos fazem parte do esquema YAML voltado para o programador, pelo que seguem a convenção camelCase. Nenhum esquema de entidade declara um campo deste tipo; os caminhos de documentos que um autor escreve são as chaves de exportação .locals abaixo.
  • As chaves de exportação .locals que transportam 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 através da carga pipeline[].with que referencia .locals —, pelo que seguem a convenção snake_case. Exemplos:
    • volumes_path — .locals.volumes_path: "/spec/template/spec/volumes" expõe a posição do array de volumes do Workload sintetizado.
    • containers_path — .locals.containers_path: "/spec/template/spec/containers" expõe a posição do array de contentores.
    • 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 sufixos refletem a convenção de dois níveis da secção Capitalização dos campos: os campos definidos pelo esquema usam camelCase; os identificadores escritos pelo utilizador ou privados da Recipe usam snake_case (ou kebab-case). A disciplina de sufixos *Path / *_path torna visível ao nível do identificador a natureza de gramática de caminho do valor — quem lê qualquer um dos sufixos sabe que o valor segue a sintaxe RFC 6901 sem ter de inspecionar o próprio valor.

Exemplo trabalhado: 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 cadeias JSON Pointer RFC 6901. O plugin Injector consome as cadeias para posicionar a sua saída JSONPatch sobre a AST do Workload renderizado. A associação chega a elas através do seu próprio pilar .locals — não existe nenhum campo .context.uses[].locals, pelo que um consumidor não consegue ler os locals do seu alvo através de uma aresta uses; o que atravessa uma aresta são os provides do alvo.

Para o inventário mais amplo de cadeias de formato (sintaxe de templates Go, funções Sprig, JSON Pointer ao lado da regex SemVer e da gramática de seletores de etiquetas), ver 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, ver plugins/plugin-contract.md.

Sintaxe de comentários

Os caracteres de comentário dependem da linguagem envolvente:

  • Contexto YAML (a superfície de autoria predefinida para todas as entidades Aggrega): usar #
  • Contexto de template Go (dentro de block scalars valuesMapping: de uma Recipe, block scalars injectMapping: de uma FeatureRecipe, entradas de mapeamento de uma MappingLibrary, corpos assertions: de blocos de asserções): usar {{/* ... */}} para comentários de template que o motor de templates reconhece e remove no momento da renderização, ou # para comentários ao nível do YAML fora do corpo do template.

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