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

Referência da linguagem

O «quê» e o «como usar» do Aggrega. Sintaxe, invocação da CLI, catálogo de erros, exemplos trabalhados.

Os capítulos abaixo leem-se por ordem para uma primeira compreensão. Os subdiretórios de referência estão listados sob o respetivo capítulo — salte diretamente para eles quando procurar uma entidade, palavra-chave, provider, comando da CLI ou erro específico.

Antes de ler a sequência de capítulos, consulte Estado da linguagem para conhecer o estado atual de prontidão — que superfícies da linguagem estão disponíveis hoje, quais são aceites mas o compilador ainda não lhes dá seguimento, e quais estão planeadas para iterações futuras. Compatibilidade indica o que uma versão promete para os esquemas, a linha de comandos, as ferramentas do assistente, os códigos de erro e os kits de plugins.

Modelo de níveis de entidades

Os tipos de entidade de autoria do Aggrega estão organizados em três níveis que refletem a progressão da adoção (abaixo). Ao lado deles está o Workload detido pela plataforma, que não é um tipo de autoria próprio — é a forma que a entrada sintetizada de uma Recipe assume, exprimindo a forma de computação através do vocabulário form: (stateless, stateful, daemon, scheduled, task, reference). A divisão em níveis é um mecanismo de documentação e de integração, não uma restrição em tempo de execução: todos os tipos de entidade são cidadãos de primeira classe da linguagem; o compilador trata-os de forma uniforme; o Aggrega open source suporta todos os níveis sem licenciamento nem restrição de funcionalidades. Os marcadores de nível sinalizam «avançado; ignore se não precisar» para a navegação, e não capacidade.

NívelTipos de entidadeQuando adotar
Nível 1 — a superfície mínima viávelAggregate, Component, Recipe, Manifest, ReleaseDia 1 — fundadores individuais e equipas pequenas entregam software funcional apenas com o nível 1. O modelo mental: «Tenho uma aplicação; quero implementá-la; é assim que se faz.»
Nível 2 — separação de papéisFeature, FeatureRecipe, PluginDia 30 — equipas pequenas em que os papéis se separam (programador + Ops + por vezes Segurança). O nível 2 entra através de Plugins de renderização de provider (a equipa de Ops escolhe entre Helm, helm-chart, Compose, Terraform e CloudFormation), de Features (a equipa de Segurança gere as credenciais separadamente da configuração da aplicação) e de FeatureRecipes (personalização por provider no momento da associação).
Nível 3 — reutilização cross-ComponentSchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibraryDia 365 — catálogos maduros em que formas comuns se repetem em muitas entidades. O limiar é informal: quando uma forma (por exemplo, PodResources) aparece em 5 ou mais Components e coordenar as atualizações gera atrito, uma entrada de SchemaLibrary justifica-se por si.

Cada progressão é opcional. Um fundador individual nunca é obrigado a olhar para o nível 3; um catálogo empresarial tem acesso total ao nível 3 conforme necessário. O nível 1 é completo para o caso de uso do fundador individual — um programador pode entregar aplicações funcionais usando apenas entidades do nível 1. Esta é uma propriedade de desenho forte: o nível 1 não é um «subconjunto que compila»; é um «subconjunto que entrega software».

A superfície de cinco entidades do nível 1 tem um custo de entrada — Aggregate + Component + Recipe + Manifest + Release é mais cerimónia do que «largar um ficheiro YAML e obter um serviço em execução». O custo é o preço da separação de autoria em quatro domínios (intenção do programador / catálogo da plataforma / Platform Ops / encaminhamento) que distingue o Aggrega do Helm ou do Terraform puros. Os tutoriais do nível 1 percorrem explicitamente a configuração das cinco entidades.

No nível 3, o mecanismo spec.templates / $instantiate: (helpers paramétricos na SchemaLibrary) está documentado como uma subfuncionalidade ainda mais avançada. A maioria dos adotantes do nível 3 não recorre a spec.templates de início; o limiar é «quando a biblioteca tiver 6 ou mais esquemas que partilham estrutura parametrizada».

Ordem de leitura

  1. Como utilizar esta referência
  2. Convenções de nomenclatura
  3. Visão geral da referência de entidades
  4. Visão geral do vocabulário
  5. Visão geral dos templates
  6. Visão geral dos Providers
  7. Visão geral da CLI
  8. Visão geral dos erros
  9. Visão geral dos exemplos

Referência de autoria de Plugin

A superfície de plugins Wasm está ao lado da sequência de capítulos e não dentro dela: um autor de plugins lê-a independentemente do percurso de autoria de entidades. A página de entidade plugin aborda a superfície de autoria do catálogo; as páginas abaixo abordam os sockets, as cargas e o fluxo de trabalho do autor.

  • plugin-contract — os sockets a que um plugin se associa, a sua colocação no pipeline e as formas de entrada e de saída de cada socket.
  • plugin-developer-guide — o fluxo de trabalho do autor de ponta a ponta: describe(), declarações de capacidades, limites de tempo de execução, o ciclo de vida publish/pull/build, assinatura, versionamento.
  • policy-socket — o socket de governação em profundidade: os seus quatro papéis, as severidades dos veredictos, o canal de entrada do operador e a escrita de uma política para qualquer dos motores que vêm dentro do compilador.
  • governance-attachment-facts — os factos por associação que uma política de governação lê do grafo do build, incluindo as três unidades da marcação de sensibilidade e porque é que a ausência de marcação não é uma permissão.
  • when-to-use-a-pipeline-step — escolher entre um passo de pipeline e uma FeatureRecipe com templates.
  • embedded-plugins — os plugins incorporados no binário do compilador.
  • tagging-plugins — os dois plugins de governação integrados que escrevem etiquetas sem uma política, governance/label-injector e governance/selector-tagger: as suas definições e o que cada um escreve.
  • core-importers — os dez importadores do compilador, de Langflow, Flowise e n8n a Compose, MCP e às frameworks de agentes: o que cada um lê e esboça, as suas definições e a sua publicação com cada versão do compilador.
  • authoring-a-provider-walkthrough — um percurso guiado pela autoria de um guest de provider, desde um diretório vazio até um build que escreve os ficheiros que o provider renderizou.
  • writing-a-governance-plugin — escrever um plugin de governação próprio a partir do esqueleto de adaptador do kit de plugins: uma regra, o export de cada papel executado à mão, uma entidade Plugin no catálogo do workspace e um build que o plugin recusa.
  • compatibility — como os kits de plugins são versionados: o que uma versão de correção e uma versão menor de um kit podem alterar, e o que permite que um plugin já compilado continue a carregar.