MappingLibrary
MappingLibrary, yeniden kullanılabilir Go şablon parçalarını tutan bir katalog varlığıdır. Bütün bir valuesMapping: belgesini — aynı chart’ı kaynak alan birkaç Recipes’in her birinin ona verdiği değerleri — paylaşan Recipes ve FeatureRecipes, onu bir kütüphanede bir kez bildirir ve tüketim anında bir valuesMapping: { $import: ... } yönergesiyle ona başvurur. Kütüphane varlığı Katman 3’tür: Recipe’ler arası eşleme yeniden kullanımına ihtiyaç duyan kataloglar için isteğe bağlıdır. Yinelenen şablon içeriği olmayan kataloglar hiçbir MappingLibrary olmadan yayımlanır.
MappingLibrary’nin rolü
Platform mimarları, kataloğun Recipes ve FeatureRecipes genelinde tekrarlanan Go şablon parçalarını merkezîleştirmek için MappingLibraries yazar. Bir kütüphane, dağıtılabilir bir derleme talimatı değildir; bir tanımlar ad alanıdır. Recipe ve FeatureRecipe yazarları kütüphane girdilerine bir $import: yönergesiyle başvurur; bu yönerge bir kez yazılır ve içe aktarmanın çözümlendiği her yerde kullanılır.
“Kütüphane” ile “tüketici” arasındaki ayrım bilinçlidir. Recipes derleme talimatlarını (source, valuesMapping, artifacts) kodlar. FeatureRecipes davranışsal eklemeleri kodlar. MappingLibraries yalnızca şablon parçalarını kodlar: diğer varlıkların işleme zamanında kullandığı Go şablonu içeriğini. Üç rolü ayrı tutmak, her varlık türünün kendi hızında gelişmesini sağlar; paylaşılan şablon içeriğine ihtiyaç duymayan yazarlar kütüphane varlığıyla hiç karşılaşmaz.
Varlık zarfı
Bir MappingLibrary varlığı standart katalog zarfını taşır. apiVersion: aggrega.ai/v1beta1 ve kind: MappingLibrary varlık türünü belirtir; metadata.name bir PascalCase tanımlayıcıdır; metadata.version katı anlamsal sürümlemeye uyar. Kütüphanenin içeriği, en az bir girdi bildirmesi gereken zorunlu bir eşlem olan spec.mappings altında yer alır.
apiVersion: aggrega.ai/v1beta1kind: MappingLibrarymetadata: name: BaseMappings version: 1.0.0spec: mappings: SimpleValues: 'image: {{ .values.image }}' Replicas: 'replicas: {{ optional .infra "replicas" 1 }}'Bir girdi, onu tüketen Recipe’in kendi şablon motoru tarafından, Recipe’in işleme bağlamına karşı değerlendirilir; bu yüzden bir Recipe’in kendi valuesMapping: alanının okuduğu küçük harfli sütunları — .values, .infra, .context ve diğerlerini — okur ve aynı işlevleri, örneğin bulunmayan bir anahtar için varlığa duyarlı optional yardımcısını kullanır. Helm’in chart değerleri için kullandığı yazım olan .Values, bu bağlamın tanımladığı bir kök değildir: onu okuyan bir girdi, başvuruyu adlandırarak derlemeyi durdurur.
Eşleme girdilerinin yazılması
Her eşleme girdisi, YAML dizesi olarak yazılmış bir Go şablonu parçasıdır. Parça, varlık zarfı için opaktır: derleyici dizeyi MappingLibrary yüklenirken olduğu gibi saklar ve bir Recipe ya da FeatureRecipe girdiyi valuesMapping: { $import: ... } aracılığıyla içe aktardığında, tüketim anında ayrıştırır. İçe aktarma, Recipe’in valuesMapping: alanının tamamını değiştirir — $import: eşlemi başka hiçbir anahtar taşımaz — bu nedenle bir girdi, bir belgeye eklenen bir parça değil, eksiksiz bir değerler belgesidir.
Kısa parçalar tek bir satıra sığar:
spec: mappings: AppName: 'fullnameOverride: "{{ .context.rendered_name }}"'Çok satırlı parçalar, satır sonlarının ve girintinin gidiş-dönüşte korunması için YAML’ın literal biçimli skalerini (|) kullanır:
spec: mappings: ProbeBlock: | readinessProbe: httpGet: path: /healthz port: {{ .values.port }} livenessProbe: httpGet: path: /healthz port: {{ .values.port }}Go şablonunun tüm birleştirme sözcük dağarcığı parçaların içinde kullanılabilir: {{ define "name" }}...{{ end }} tek bir kütüphane içinde yeniden kullanılabilir bloklar bildirir; {{ template "name" . }} bunları çağırır; ardışık düzenler ve fonksiyonlar standart Go text/template paketine göre desteklenir.
Tek yazım modu
MappingLibrary tek bir yazım moduyla gelir: Go şablonları. spec paralel bir yazım yüzeyi kabul etmez ve kütüphane düzeyinde bir ifade gücü kaçış yolu yoktur.
Nedeni tüketim yüzeyinin tekdüzeliğidir. Recipes ve FeatureRecipes baştan sona Go şablonudur ve kendi içerikleri, içe aktarılan bir girdiyi çözümleyen aynı Go şablon motoru üzerinden değerlendirilir; böylece bir girdi tam olarak Recipe’in kendi metni gibi okunur ve yazarlar tek bir değerlendirme modeli öğrenir. Go şablonunun kompozisyon sözcük dağarcığı — bir kütüphane içinde {{ define }} ve {{ template }}, tüketim anında ise $import: yönergesi — bir kütüphanenin ihtiyaç duyduğu yeniden kullanılabilir blokları ve parametreli çağrıyı sağlar.
Go şablonunun birleştirme sözcük dağarcığının sunduğunun ötesinde ifade gücüne ihtiyaç duyan yazarlar, MappingLibrary’nin kendi içinde paralel bir yazım diline yükselmek yerine daha üst bir düzeyde birleştirme yapar: kütüphane girdilerini kendi esaslı varyasyonlarıyla saran Components ya da Features.
Adlandırma uzlaşımları
Kütüphane adları ve eşleme girdisi anahtarları PascalCase biçimini izler. Varlık zarfının JSON Schema’sı, bu uzlaşımı desen kısıtlamaları aracılığıyla iki konumda zorunlu kılar:
metadata.name,^[A-Z][A-Za-z0-9]*$ile eşleşir.spec.mappingseşlem anahtarları,propertyNamesaracılığıyla aynı desenle eşleşir.
spec.mappings içinde PascalCase olmayan bir anahtar bulunan bir MappingLibrary, çalışma alanı yüklenirken zarf doğrulamasında başarısız olur. Bu zorunluluk işlevsel bir rol taşır: eşleme girdisi anahtarları #/mappings/<name> başvuru parçasında yer alır; PascalCase olmayan anahtarlar, girdiyi içe aktaran her tüketiciye yayılırdı.
Adlandırmadaki tekdüzelik #/mappings/<name> parçasını okunaklı tutar: #/mappings/ProbeBlock bir bakışta okunur.
Kütüphane girdilerine başvurma
Recipe ve FeatureRecipe yazarları, bir valuesMapping: { $import: ... } bloğu içinde bir eşleme girdisine yalın ad kimliğiyle başvurur:
# Inside a Recipe's valuesMapping block:spec: valuesMapping: $import: "BaseMappings#/mappings/ProbeBlock"#/mappings/<name> parçası girdiyi seçer ve bir eşleme başvurusunu SchemaLibrary’nin #/schemas/<name> parçasından ayırır. Başvuru, SchemaLibrary $ref: ile aynı yalın ad kimlik modelini kullanır — <Library>#/mappings/<name>; kayıt defteri ana bilgisayarı taşımaz. Sürüm, Release başına kilit dosyası (ad + sürüm + içerik özeti) tarafından sağlanır; bir yazar isteğe bağlı bir minimum sürüm alt sınırını <Library>:<version>#/mappings/<name> biçiminde belirtebilir (sürüm ayırıcısı, recipe/feature eşlemeleri ve kilit dosyası sabitlemesiyle uyumlu olarak : karakteridir) ve fiziksel konum çözümleme anında bağlanır.
Kütüphaneler arası birleştirme
Bir MappingLibrary girdisi alan kökünde bir $import: yönlendirmesi olabilir: gövdesinin ilk belirteci $import: <Library>#/mappings/<entry> olur ve bu, girdinin tamamını başvurulan girdinin içeriğiyle değiştirir — yerinde şablonlama değil, kimlik yoluyla yeniden kullanım. Yönlendirme MappingLibrary yüklenirken değil, tüketim anında (Recipe işlenirken) ve özyinelemeli olarak çözümlenir — içe aktarılan bir girdinin kendisi de alan kökünde bir $import: olabilir. $import: yalnızca girdinin tamamına uygulanır; bir parçanın ortasında kullanılan bir şablon işlevi değildir. Şablon metnini tek bir parçanın içinde birleştirmek için Go şablonunun define / template yapılarını kullanın.
# In library A — alias an entry to a shared entry in another library:spec: mappings: StandardProbe: | $import: MonitoringLibrary#/mappings/PrometheusAnnotationsKütüphaneler birbirine serbestçe başvurabilir. Kendi üzerine geri dönen bir zincir, onu tüketen Recipe işlendiğinde, döngünün her adımını adlandıran bir tanılamayla durur.
Katman yerleşimi
MappingLibrary, entity katmanı dokümantasyon modelinde Katman 3’tür — Recipe’ler arası mapping yeniden kullanımına ihtiyaç duyan kataloglar için isteğe bağlıdır. Tekrarlanan şablon içeriği olmayan kataloglar hiçbir MappingLibrary entity’si olmadan yayımlanır; katman işareti, yetenek değil, dokümantasyonda gezinme için “ileri düzey; gerekmiyorsa atlayın” anlamını taşır. Derleyici MappingLibrary’yi diğer katalog entity türleriyle aynı şekilde ele alır: workspace yüklenirken aynı zarf doğrulaması, release zamanında aynı OCI yayımlama hattı.
Bu kütüphane türü, katalog düzeyinde SchemaLibrary ile doğal olarak eşleşir — SchemaLibrary yeniden kullanılabilir şema tanımlarını, MappingLibrary ise yeniden kullanılabilir şablon parçalarını barındırır. Her ikisine de ihtiyaç duyan kataloglar ikisini birden, hiçbirine ihtiyaç duymayanlar ise hiçbirini yayımlamaz.
MappingLibrary ne değildir
Önceden giderilmesi gereken birkaç yaygın yanılgı:
-
Satır içi
valuesMapping:yerine geçmez. Çoğu Recipe, satır içinde yazılmasından fayda gören basitvaluesMapping:içeriği taşır: Recipe kendi kendine yeterli kalır ve yazar eşleme içeriğini Recipe’in geri kalanıyla birlikte okur. MappingLibrary, AYNI parça birçok Recipes genelinde göründüğünde işe yarar; tek seferlik eşlemeler için doğru seçim satır içi yazımdır. -
Şema içeriğinin yeri değildir. Şema tanımları (JSON Schema 2020-12) SchemaLibrary’ye aittir; şablon parçaları buraya aittir. Kütüphane türleri, yeniden kullanım örüntüsüne göre değil, içerik türüne göre ayrılır.
-
Go template mekanizmalarının ötesinde parametrik yeniden kullanım sağlamaz. Parametrik varyasyona ihtiyaç duyan yazarlar, kütüphane girdilerinin içinde Go template’in
{{ define }}+{{ template arg }}mekaniklerini kullanır ya da kütüphane girdilerini kendi varyasyonlarıyla saran Components / Features oluşturur. Kütüphane varlığının kendisi parametrik yardımcı mekanizması içermez (SchemaLibrary’ninspec.templatesparametrik yardımcılarına benzer birtemplatesbloğu yoktur); Go template’in kompozisyon sözcük dağarcığı aynı kullanım durumunu karşılar.