İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

Doğrulama yüzeyi

Aggrega, yazılan içeriği birbirinden ayrı dört şema katmanında doğrular. Her katman farklı bir kapsamı ele alır, derleme hattının farklı bir noktasında çalışır ve farklı biçimde hatalar üretir. Bir doğrulama hatasıyla karşılaşan yazarlar, girdiyi hangi katmanın reddettiğini bilmekten yarar sağlar: aynı alan birden fazla katman tarafından yönetilebilir ve neyin nerede düzeltileceğini tetiklenen katman belirler.

Bu sayfa dört katmanı, bunların derleme hattındaki yerini, her katmanın izlediği hata biçimi uzlaşımını ve aynı alana birden fazla katman uygulandığında katmanların nasıl etkileştiğini belgeler.

Dört katman

Katman 1 — JSON Schema zarfı

Kapsam. Her katalog YAML’ının yapısal biçimi: apiVersion, kind, metadata.{name, version, description, maintainers, license, ...}, üst düzey spec: bloğu ve şemanın bildirdiği varlığa özgü zorunlu alanlar. Her varlık türünün (Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) şema başvurusunda belgelenen kendi JSON Schema’sı vardır. Workload’un da orada bir şeması vardır ve bu kümede yazarın kendi başına bir katalog dosyası olarak değil, başka bir varlığın içinde yazdığı tek türdür: bir Recipe’nin ya da FeatureRecipe’nin workload: bloğu veya bir WorkloadLibrary girdisi. Nerede yazılırsa yazılsın aynı zarf denetimi onu yönetir ve aggrega validate bir Workload dosyasını doğrudan tek varlıklı bir hedef olarak kabul eder.

Doğrulamanın çalıştığı yer. Çözümleme sırasında (resolver / load), dosya başına. Her belge yüklendiğinde türünün JSON Schema’sına göre denetlenir; şemanın bildirdiği alanların dışındaki bir anahtar, başka herhangi bir doğrulama çalışmadan önce orada reddedilir.

Hata biçimi. Bir şema uyuşmazlığı, belge zarfı hatası olarak bildirilir. Başlığı, hatalı belgenin kategorisini taşır — bir katalog varlığı için [CATALOG_ERROR E0215], bir Aggregate için [DEVELOPER_ERROR E0215], bir Release için [OPS_ERROR E0215] — ve ileti türü, dosyayı, satırı ve sütunu, alan yolunu ve ihlal edilen kısıtlamayı adlandırır:

[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

Zorunlu alan eksiklikleri ve tür uyuşmazlıkları da aynı biçimde ortaya çıkar — spec.capability: missing required property: capability, metadata.version: type: 1 has type "integer", want "string".

Katman 2 — Sütun şemaları (schema: / featuresSchema / usesSchema)

Kapsam. Bir varlığın taşıdığı veri sütunları — values, infra, parameters, ayrıca yuvalarını featuresSchema’nın bildirdiği features: ekleme bloğu ve usesSchema’nın yönettiği uses: bloğu. Alan 2 varlıkları (Component, Feature), YAML zarflarına JSON Schema 2020-12 bildirimleri gömer (satır içi spec.schema — kısa ya da tam biçim — veya paylaşılan bir SchemaLibrary girdisine $ref:); Alan 3 varlıkları (Recipe, FeatureRecipe) çözümlenmiş şemaları kendi doğrulama geçişlerinde kullanır.

Doğrulamanın çalıştığı yer. Çözümleme sırasında, JSON Schema zarfı geçtikten sonra. Derleyici, varlığın yazılmış schema: alanını usesSchema ve featuresSchema bildirimlerinden türetilen otomatik oluşturulmuş tabanlarla birleştirir; birleşik şema, Aggregate’teki her bileşen örneğinde geliştiricinin sağladığı values: / infra: / features: / uses: bloklarını doğrular.

Hata biçimi. Kısıt ihlalleri; varlığı, sütun içindeki yolu ve değeri reddeden kuralı adlandıran iletiler olarak ortaya çıkar — örneğin bir geliştiricinin >=1024 gerektiren bir şema kuralına karşı bir bağlantı noktasını 80 olarak ayarlaması.

Yeniden bildirilen bir usesSchema ya da featuresSchema girdisi birleştirme hatası üretmez. Bu iki yüzey ada göre üst üste biner: alt girdi, şemasıyla ve seçicisiyle birlikte taban girdinin yerini tamamen alır; bu nedenle bir taban ile bir alt girdi arasında bildirilecek bir çakışma yoktur.

Katman 3 — Provider sentezlenmiş kip yeteneği

Kapsam. Bağlı sağlayıcının sentezlenmiş kip yetenek kapısı tarafından yönetilir:

  • Sentezlenmiş kip (workload:) desteği, workloadSchema’nın varlığına değil, bağlı sağlayıcının yeteneğine bağlıdır: sentezleme yapamayan bir sağlayıcıya bağlı bir workload: Recipe’si burada reddedilir. Standart kütüphane kataloğu, belgelenmiş çeviri sözleşmesi olarak, sentezleme yeteneğine sahip sağlayıcılarda workloadSchema’yı uzlaşım gereği bildirir — Provider-rendering Plugin’in spec.provider.workloadSchema alanında. Bu workloadSchema gövdesinin kendisi de Plugin yüklenirken JSON Schema 2020-12’ye derlenir; bu, hatalı biçimli bir şemayı render sırasında değil yükleme sırasında reddeden yapısal bir kabul kapısıdır.

Doğrulamanın çalıştığı yer. Taban render sırasında, Recipe’nin kendi valuesMapping’i çözümlendikten sonra. Katman 3, sentezlenmiş kip yönlendirmesini sağlayıcı yeteneğine bağlar.

Hata biçimi. Bir yetenek reddi katalog yazarlığı alanına atfedilir; bu nedenle raporu, bu kategoriyi ve hataya neden olan örneği taşıyan köşeli parantezli bir başlıkla açılır. İleti, koşulu belirten sabit cümleyle başlar, ardından düğümü, sağlayıcıyı ve o sağlayıcının desteklediği türleri adlandırır:

[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

[CATALOG_ERROR] başlığı, hatanın geliştiricinin Aggregate’inde değil katalog varlığında olduğunu belirtir. Terminalde başlık ayrıca koşulun kısa kodunu da taşır — bu koşul için tüm koşulların tablosunun çözümlediği E0265 — ve ileti girintili kendi satırına geçer; yukarıdaki tek satırlık biçim günlüğe ulaşan biçimdir. Açılış cümlesi her koşul için sabittir, bu nedenle metinden çalışırken eşleştirmeniz gereken kısım odur; ondan sonraki her şey hatalı düğüme göre değişir.

İlgili bir koruma, sağlayıcı yönlendirmesinin kendisini korur: aynı hedefe birden fazla Provider-rendering Plugin hizmet verdiğinde, çalışma alanı belirsizliği aggrega pull sırasında seçilen ve kilit dosyasına kaydedilen, .aggrega-config.yaml içindeki bir sağlayıcı bağlamasıyla çözer. Bağlama yoksa ve tam olarak bir aday Plugin varsa o aday kullanılır; bağlama yoksa ve birden fazla aday varsa derleme, aday eklentileri adlandırarak açıkça durur. Belirsizlik, katalog genelindeki bir benzersizlik kuralıyla değil, kullanım noktasında çalışma alanı başına çözülür.

Provider başına Workload içeriği doğrulaması. Provider işleyen bir Plugin’in spec.provider.workloadSchema alanı, provider’ın bir Workload’u nasıl çevirdiğini belgeler ve provider’ı bir Workload sentezleyebilir olarak işaretler; hiçbir şeyi doğrulamaz. Her Workload gövdesi, provider ne olursa olsun platformun Workload şemasına göre doğrulanır.

Katman 4 — Ek açıklama bağlaması değer doğrulaması

Kapsam. mappings.features.annotations.<key> altındaki bir Manifest bağlaması maps.infra ve/veya maps.values noktalı yol listeleri üzerinden yönlendirme bildirdiğinde, Release sınırlarında / sınır bileşenlerinde veya Aggregate alt sistemlerinde / bileşen örneklerinde yazılan ek açıklama değerleri. Bildirilen her yol, hedef Feature’ın spec.schema.<pillar> alanında bir yaprak özelliğe ilerler; ek açıklama değerinin o yapraktaki katkısı, Feature şemasının bildirdiği türe karşı doğrulanır. Doğrulama Feature’ın kendi JSON Schema 2020-12 bildirimi üzerinden akar — bağlamalar doğrulama parçaları değil, yalnızca yönlendirme bildirir.

Doğrulamanın çalıştığı yer. Çözümlemenin ek açıklama genişletme alt aşamasında, Manifest bağlama hedefi doğrulamasından (bildirilen her yolun başvurulan Feature şemasında var olduğunu doğrulayan katalog yükleme denetimi) sonra ve açık eklemeler üzerindeki Katman 2 şema doğrulamasıyla birlikte. Etkin her bileşen başına ek açıklama için: değer bir skaler, yapılandırılmış bir eşlem veya açık bir null olarak ayrıştırılır; taraf-sütun zorlamasıyla bağlamanın sütunlara göre gruplanmış maps bildirimi üzerinden alt anahtar başına yönlendirilir (Aggregate tarafı maps.values’u, Release tarafı maps.infra’yı tetikler); yaprak başına çalışma zamanı değeri, yönlendirilen sütunda Feature şemasının bildirdiği türe karşı doğrulanır. Birden çok alt anahtar hatası, durmadan önce toplanır ve tümü yayımlanır.

Hata biçimi. Bu katmandaki şema doğrulama hataları Katman 2 biçimini izler — varlık, yol (ek açıklama anahtarı ile alt anahtar rotası), kısıt ayrıntısı. Taraf-sütun bölümleme ihlalleri ve belirsiz yönlendirme hataları, ek açıklama değerinin yazıldığı belgeye atfedilir; bu nedenle bir Aggregate’in taşıdığı hata bir [DEVELOPER_ERROR] başlığı, bir Release’in taşıdığı hata ise bir [OPS_ERROR] başlığı açar ve ikisi de ek açıklama anahtarını, yönlendirilen sütunu, yazan tarafı ve kaynak konumunu adlandırır.

Katmanlar arasında tek bir hata biçimlendirme uzlaşımı

Dört katman gözlemlenebilir tek bir uzlaşımı paylaşır: Aggrega’ya atfedilebilen her doğrulama hatası, hatalı alanı ve onu reddeden kısıtı adlandıran yol artı gerekçe biçimini taşır.

  • Katman 1 (zarf) ve Katman 2 (sütun şemaları) hataları aynı köşeli parantezli başlıkla açılır — hatalı belgenin kategorisi ve koşulun kısa kodu; örneğin bir katalog varlığındaki zarf uyuşmazlığı için [CATALOG_ERROR E0215], bir sütun şemasının reddettiği bir Aggregate değeri için [DEVELOPER_ERROR E0168] — ardından alan yolu ve ihlal edilen şema kuralı gelir.
  • Katman 3 (Provider kaynağı / Workload) hataları tanım gereği katalog varlığına atfedilebilir: geliştiricinin girdisini reddeden şemayı Recipe + Provider çifti yazmıştır. Bu hatalar katalog yazımı alanına atfedilir ve bu atıf size iletiye yazılmış bir sözcük olarak değil, tanılamanın köşeli parantezli başlığında ulaşır: durduran bir rapor [CATALOG_ERROR E0nnn] ile açılır; burada kategori alanı, kısa kod ise durumu adlandırır. Eşleştirmeyi, bir kez verildikten sonra sabit kalan kısa kod üzerinden yapın.
  • Katman 4 (ek açıklama bağlama değeri doğrulaması) hataları Katman 2 biçimini izler: doğrulayan Feature şeması, başvurulan Feature’ın spec.schema alanında bulunur ve çalışma zamanı değerleri, yaprak başına tür denetimi için Manifest bağlamasının maps yönlendirmesi üzerinden bu şemaya akar.

Aggrega önekli sentinel’lerin ve bunları üreten yüzeylerin tam envanteri için bkz. errors/error-translation.md. Hata başına katalog ([CATALOG_ERROR] Recipe biçim kuralları, durum durum) için bkz. errors/fatal-halts.md.

Alanlar çakıştığında katmanların etkileşimi

Yazılan aynı alan birden fazla katman tarafından yönetilebilir. Bir Workload’un containers.<name>.ports.<port> alanı, Workload şemasının yapısal biçiminin bir parçası olarak Katman 1 tarafından denetlenir; Workload içeriği bir Component sütunu değil, Recipe’ye iç bir yapı olduğundan Katman 2 ona ulaşmaz; bir provider’ın workloadSchema alanı ise hiçbir şeyi denetlemez — bu nedenle 1024’ün altındaki bir portu reddetmek gibi bir kısıtlama, tetiklenen katmanın onu adlandıracağı Component şemasına veya bir onaylamaya aittir.

İşlem hattındaki yerleşim özeti

KatmanKapsamÇalıştığı aşamaHata öneki
1 — JSON Schema zarfıYapısal biçim (apiVersion, kind, metadata, üst düzey spec)Çözümleme (yükleme)belgenin kategorisi ile E0215 — bir katalog varlığı için [CATALOG_ERROR E0215]
2 — Sütun şemaları (schema: / featuresSchema / usesSchema)Sütun başına veri doğrulaması (values, infra, secrets, uses)Çözümleme (zarftan sonra)yazıldığı belgenin kategorisi ile koşulun kısa kodu — bir Aggregate değeri için [DEVELOPER_ERROR E0168]
3 — Provider yetenek kapısıSentezlenmiş mod desteği (provider yeteneği)Temel işleme[CATALOG_ERROR]
4 — Annotation bağlama değer doğrulamasıManifest bağlamasının maps yolları üzerinden hedef Feature’ın spec.schema alanına yönlendirilen annotation değeri katkılarıÇözümlemenin annotation genişletme alt aşaması, Katman 2 ile birlikteşema doğrulama hatası; taraf-sütun / belirsiz yönlendirme yüzeyleri, yazıldıkları belgenin kendi alanını açar — Aggregate’ten [DEVELOPER_ERROR], Release’ten [OPS_ERROR]

Çapraz başvurular

  • errors/error-translation.md — Aggrega önekli sentinel envanteri ve bunları üreten yüzeyler.
  • errors/fatal-halts.md — derleyicinin ürettiği her ölümcül durmanın hata bazında kataloğu.
  • vocabulary/data-pillars.md — Katman 2’nin doğruladığı veri sütunları (values, infra, parameters, locals, features:, uses: ve provides).
  • entities/component.md — schema: / featuresSchema / usesSchema için Component yazım yüzeyi.
  • entities/plugin.md — spec.provider.workloadSchema için provider işleyen Plugin yazım yüzeyi.
  • entities/manifest.md — Manifest’in features.annotations bağlama yüzeyi (Katman 4).
  • providers/well-known-annotations.md — Katman 4’ün doğruladığı annotation değeri ayrıştırma, yapılandırılmış değer alt anahtar yönlendirmesi, alt anahtar bazında null ile devre dışı bırakma ve taraflar arası birleştirme.