Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Superficie di validazione

Aggrega valida il contenuto scritto dagli autori su quattro livelli di schema distinti. Ogni livello copre un ambito diverso, viene eseguito in un punto diverso della pipeline di compilazione e produce errori con una forma diversa. Gli autori che incontrano un errore di validazione traggono vantaggio dal sapere quale livello ha rifiutato l’input — lo stesso campo può essere regolato da più di un livello, e il livello che è intervenuto determina che cosa correggere e dove.

Questa pagina documenta i quattro livelli, la loro collocazione nella pipeline, la convenzione sulla forma degli errori che ciascun livello segue e il modo in cui i livelli interagiscono quando più di uno si applica allo stesso campo.

I quattro livelli

Livello 1 — Involucro JSON Schema

Ambito. La forma strutturale di ogni YAML del catalogo: apiVersion, kind, metadata.{name, version, description, maintainers, license, ...}, il blocco spec: di primo livello e i campi obbligatori per entità che lo schema dichiara. Ogni tipo di entità (Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) ha il proprio JSON Schema, documentato nel Riferimento degli schemi. Anche Workload ne ha uno lì, ed è l’unico tipo di quell’insieme che un autore scrive all’interno di un’altra entità — il blocco workload: di una Recipe o di una FeatureRecipe, oppure una voce di una WorkloadLibrary — anziché come file di catalogo a sé; lo stesso controllo dell’involucro lo governa ovunque sia scritto, e aggrega validate accetta direttamente un file Workload come destinazione a entità singola.

Esecuzione della validazione. Alla risoluzione (resolver / caricamento), per file. Ogni documento viene verificato rispetto al JSON Schema del suo tipo al momento del caricamento; una chiave al di fuori dei campi che lo schema dichiara viene rifiutata lì, prima che venga eseguita qualsiasi ulteriore validazione.

Forma dell’errore. Una discordanza con lo schema viene segnalata come errore dell’involucro del documento. La sua intestazione riporta la categoria del documento in errore — [CATALOG_ERROR E0215] per un’entità del catalogo, [DEVELOPER_ERROR E0215] per un Aggregate, [OPS_ERROR E0215] per una Release — e il messaggio indica il tipo, il file, la riga e la colonna, il percorso del campo e il vincolo violato:

[CATALOG_ERROR E0215] <path>
document envelope validation failed (Recipe, at <path>); 11:3: spec.foo: unexpected property: "foo". correct the document to match its kind's schema

Le omissioni di campi obbligatori e le discordanze di tipo emergono nella stessa forma — spec.capability: missing required property: capability, metadata.version: type: 1 has type "integer", want "string".

Livello 2 — Schemi dei pilastri (schema: / featuresSchema / usesSchema)

Ambito. I pilastri di dati che un’entità porta — values, infra, parameters, oltre al blocco di associazione features: i cui slot sono dichiarati da featuresSchema e al blocco uses: governato da usesSchema. Le entità del Dominio 2 (Component, Feature) incorporano dichiarazioni JSON Schema 2020-12 nel loro involucro YAML (spec.schema in linea — in forma compatta o completa — oppure un $ref: a una voce condivisa di una SchemaLibrary); le entità del Dominio 3 (Recipe, FeatureRecipe) consumano gli schemi risolti durante la propria fase di validazione.

Esecuzione della validazione. Alla risoluzione, dopo che l’involucro JSON Schema è stato superato. Il compilatore compone lo schema: scritto per l’entità con basi generate automaticamente, derivate dalle dichiarazioni usesSchema e featuresSchema; lo schema composto valida i blocchi values: / infra: / features: / uses: forniti dallo sviluppatore su ogni istanza di componente nell’Aggregate.

Forma dell’errore. Le violazioni dei vincoli emergono come messaggi che indicano l’entità, il percorso all’interno del pilastro e la regola che ha rifiutato il valore — per esempio uno sviluppatore che imposta una porta a 80 a fronte di una regola dello schema che richiede >=1024.

Una voce usesSchema o featuresSchema ridichiarata non produce alcun errore di composizione. Queste due superfici si sovrappongono per nome: la voce di un figlio sostituisce integralmente quella della base, schema e selettore insieme, quindi non c’è alcun conflitto da segnalare tra una voce della base e una del figlio.

Livello 3 — Capacità della modalità sintetizzata del Provider

Ambito. Governato dal controllo delle capacità della modalità sintetizzata del provider associato:

  • Il supporto alla modalità sintetizzata (workload:) dipende dalla capacità del provider associato, non dalla presenza di workloadSchema: una Recipe workload: associata a un provider che non può sintetizzare viene rifiutata qui. Il catalogo della libreria standard dichiara workloadSchema sui provider in grado di sintetizzare per convenzione — nello spec.provider.workloadSchema del Plugin di rendering dei provider — come contratto di traduzione documentato. Quel corpo di workloadSchema viene a sua volta compilato in JSON Schema 2020-12 quando il Plugin viene caricato, un controllo strutturale di accettazione che rifiuta uno schema malformato al caricamento anziché al rendering.

Esecuzione della validazione. Al rendering di base, dopo che il valuesMapping della Recipe stessa è stato risolto. Il Livello 3 subordina lo smistamento in modalità sintetizzata alla capacità del provider.

Forma dell’errore. Un rifiuto per capacità viene attribuito al dominio di authoring del catalogo, quindi la sua segnalazione si apre con un’intestazione tra parentesi quadre che riporta quella categoria e l’istanza in errore. Il messaggio si apre con la frase fissa che enuncia la condizione, poi indica il nodo, il provider e i tipi che quel provider supporta:

[CATALOG_ERROR] instance <node-id>: provider does not support the node's input kind (node "<node-id>"). provider "<provider-name>" does not support synthesized recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports synthesized

L’intestazione [CATALOG_ERROR] segnala che è in errore l’entità del catalogo, non l’Aggregate dello sviluppatore. In un terminale l’intestazione riporta anche il codice breve della condizione — E0265 per questa, che la tabella di tutte le condizioni risolve — e il messaggio si sposta su una propria riga rientrata; la forma su una riga qui sopra è quella che arriva in un log. La frase iniziale è fissa per ogni condizione, quindi è la parte su cui fare corrispondenza quando lavori a partire dal testo; tutto ciò che la segue varia con il nodo in errore.

Una protezione correlata tutela lo smistamento stesso verso i provider: quando più di un Plugin di rendering dei provider serve lo stesso target, il workspace risolve l’ambiguità tramite un’associazione del provider in .aggrega-config.yaml, scelta al momento di aggrega pull e registrata nel lockfile. Senza associazione e con esattamente un Plugin candidato, si usa quel candidato; senza associazione e con più di un candidato, la build si arresta in modo esplicito, indicando i plugin candidati. L’ambiguità si risolve per workspace nel punto d’uso, non con una regola di unicità valida per l’intero catalogo.

Validazione del contenuto del Workload per provider. Lo spec.provider.workloadSchema di un Plugin di rendering dei provider documenta come il provider traduce un Workload e contrassegna il provider come in grado di sintetizzarne uno; non valida nulla. Ogni corpo di Workload viene validato rispetto allo schema Workload della piattaforma, qualunque sia il provider.

Livello 4 — Validazione dei valori dei binding di annotazione

Ambito. I valori delle annotazioni scritti sui confini della Release / sui componenti di confine o sui sottosistemi / sulle istanze di componente dell’Aggregate, quando un binding del Manifest sotto mappings.features.annotations.<key> dichiara l’instradamento tramite liste di percorsi puntati maps.infra e/o maps.values. Ogni percorso dichiarato naviga lo spec.schema.<pillar> della Feature di destinazione fino a una proprietà foglia; il contributo del valore dell’annotazione su quella foglia viene validato rispetto al tipo dichiarato dallo schema della Feature. La validazione passa per la dichiarazione JSON Schema 2020-12 della Feature stessa — i binding dichiarano solo l’instradamento, non frammenti di validazione.

Esecuzione della validazione. La sottofase di espansione delle annotazioni della risoluzione, dopo la validazione delle destinazioni dei binding del Manifest (il controllo al caricamento del catalogo che conferma che ogni percorso dichiarato esiste nello schema della Feature referenziata) e accanto alla validazione degli schemi del Livello 2 sulle associazioni esplicite. Per ogni annotazione effettiva per componente: si analizza il valore come scalare, come mappa strutturata o come null esplicito; lo si instrada per sottochiave attraverso la dichiarazione maps del binding, raggruppata per pilastro, con l’imposizione lato-contro-pilastro (il lato Aggregate attiva maps.values; il lato Release attiva maps.infra); si valida il valore di runtime per foglia rispetto al tipo dichiarato dallo schema della Feature nel pilastro instradato. Più errori di sottochiave vengono raccolti ed emessi tutti prima dell’arresto.

Forma dell’errore. Gli errori di validazione dello schema a questo livello seguono la forma del Livello 2 — entità, percorso (chiave dell’annotazione più instradamento della sottochiave), dettaglio del vincolo. Le violazioni della partizione lato-contro-pilastro e gli errori di instradamento ambiguo sono attribuiti al documento in cui il valore dell’annotazione è stato scritto, quindi un errore portato da un Aggregate apre un’intestazione [DEVELOPER_ERROR] e uno portato da una Release apre un’intestazione [OPS_ERROR], ed entrambi indicano la chiave dell’annotazione, il pilastro instradato, il lato di authoring e la posizione nel sorgente.

Una convenzione di formattazione degli errori per tutti i livelli

I quattro livelli condividono una convenzione osservabile: ogni errore di validazione attribuibile ad Aggrega ha una forma percorso-più-motivazione che indica il campo in errore e il vincolo che lo ha rifiutato.

  • Gli errori del Livello 1 (involucro) e del Livello 2 (schemi dei pilastri) si aprono con la stessa intestazione tra parentesi quadre — la categoria del documento in errore e il codice breve della condizione, come [CATALOG_ERROR E0215] per una discordanza dell’involucro in un’entità del catalogo e [DEVELOPER_ERROR E0168] per un valore di un Aggregate che uno schema di pilastro rifiuta — seguita dal percorso del campo e dalla regola dello schema violata.
  • Gli errori del Livello 3 (sorgente del Provider / Workload) sono per definizione attribuibili alle entità del catalogo — la coppia Recipe + Provider ha scritto lo schema che ha rifiutato l’input dello sviluppatore. Sono attribuiti al dominio di authoring del catalogo, e l’attribuzione ti raggiunge nell’intestazione tra parentesi quadre della diagnostica anziché come una parola digitata nel messaggio: una segnalazione bloccante si apre con [CATALOG_ERROR E0nnn], dove la categoria indica il dominio e il codice breve indica la condizione. Fai corrispondenza sul codice breve, che è fisso una volta emesso.
  • Gli errori del Livello 4 (validazione dei valori dei binding di annotazione) seguono la forma del Livello 2 — lo schema della Feature che valida risiede nello spec.schema della Feature referenziata, e i valori di runtime passano attraverso l’instradamento maps del binding del Manifest in quello schema per il controllo dei tipi per foglia.

Per l’inventario completo delle sentinelle con prefisso Aggrega e delle superfici che le producono, vedi errors/error-translation.md. Per il catalogo per errore (le regole di forma della Recipe [CATALOG_ERROR], condizione per condizione), vedi errors/fatal-halts.md.

Interazione tra livelli quando i campi si sovrappongono

Lo stesso campo scritto può essere regolato da più di un livello. Il containers.<name>.ports.<port> di un Workload è verificato dal Livello 1 come parte della forma strutturale dello schema Workload; il Livello 2 non lo raggiunge, poiché il contenuto del Workload è una struttura interna alla Recipe e non un pilastro di Component; e il workloadSchema di un provider non verifica nulla — quindi un vincolo come il rifiuto di una porta inferiore a 1024 appartiene allo schema del Component o a un’asserzione, dove il livello che scatta lo indica.

Riepilogo della collocazione nella pipeline

LivelloAmbitoEseguito inPrefisso dell’errore
1 — Involucro JSON SchemaForma strutturale (apiVersion, kind, metadata, spec di primo livello)Risoluzione (caricamento)la categoria del documento con E0215 — [CATALOG_ERROR E0215] per un’entità del catalogo
2 — Schemi dei pilastri (schema: / featuresSchema / usesSchema)Validazione dei dati per pilastro (values, infra, secrets, uses)Risoluzione (dopo l’involucro)la categoria del documento di authoring con il codice breve della condizione — [DEVELOPER_ERROR E0168] per un valore di un Aggregate
3 — Controllo delle capacità del ProviderSupporto alla modalità sintetizzata (capacità del provider)Rendering di base[CATALOG_ERROR]
4 — Validazione dei valori dei binding di annotazioneContributi dei valori delle annotazioni instradati nello spec.schema della Feature di destinazione tramite i percorsi maps del binding del ManifestLa sottofase di espansione delle annotazioni della risoluzione, accanto al Livello 2errore di validazione dello schema; le superfici lato-contro-pilastro / di instradamento ambiguo aprono il dominio proprio del documento di authoring — [DEVELOPER_ERROR] da un Aggregate, [OPS_ERROR] da una Release

Riferimenti incrociati

  • errors/error-translation.md — inventario delle sentinelle con prefisso Aggrega e delle superfici che le producono.
  • errors/fatal-halts.md — catalogo per errore di ogni arresto fatale emesso dal compilatore.
  • vocabulary/data-pillars.md — i pilastri di dati (values, infra, parameters, locals, features:, uses: e provides) che il Livello 2 valida.
  • entities/component.md — superficie di authoring del Component per schema: / featuresSchema / usesSchema.
  • entities/plugin.md — superficie di authoring del Plugin di rendering dei provider per spec.provider.workloadSchema.
  • entities/manifest.md — superficie di binding features.annotations del Manifest (Livello 4).
  • providers/well-known-annotations.md — analisi dei valori delle annotazioni, instradamento delle sottochiavi dei valori strutturati, esclusione con null per sottochiave e composizione tra i lati che il Livello 4 valida.