Wrapper yang dipublikasikan, dilayani oleh Recipe milik basisnya
Contoh ini mengajarkan satu hal: Component yang melakukan extends terhadap Component lain mewarisi seluruh kontrak data basis tersebut, sehingga setiap Recipe yang ditulis untuk basis itu sudah
mengimplementasikan Component yang memperluasnya. Karena itu, memublikasikan varian khusus dari
komponen pustaka standar hanya memerlukan satu entitas katalog dan satu baris Manifest
— tanpa Recipe tersendiri, dan tanpa perubahan pada basis.
Wrapper di sini adalah example/gateway/nginx-reviewed. Wrapper ini dikirimkan dalam katalog
di samping core/gateway/nginx, komponen yang diperluasnya.
Apa yang ditambahkan wrapper, dan apa yang diwarisinya
Seluruh permukaan yang ditulis pada wrapper adalah metadata ditambah satu socket:
metadata: name: example/gateway/nginx-reviewed labels: component.aggrega.ai/type: server component.aggrega.ai/category: gateway gateway.example.com/audit-tier: reviewed # added gateway.example.com/data-zone: eu-west # added annotations: governance.example.com/review-board: platform-architecture # added governance.example.com/contact: platform-architecture@example.comspec: extends: core/gateway/nginx:1.0.0 schema: inherited usesSchema: reviewed_upstream: # added selector: "gateway.example.com/audit-tier=reviewed" inject: [env]schema: inherited adalah penanda literal yang ditulis Component yang memperluas sebagai pengganti
blok schema:. Penanda ini menyatakan bahwa tiga pilar data — values, infra
dan provides — adalah milik basis, persis seperti yang ditulis basis. Wrapper
tidak mendeklarasikan kunci pilar sendiri dan memang tidak dapat melakukannya: kontrak itu milik basis,
pada setiap kedalaman rantai.
Segala sesuatu yang tidak disebutkan wrapper akan diwarisinya. aggrega inspect example/gateway/nginx-reviewed --resolved menampilkan entitas hasil penggabungan, dan ada dua
hal di dalamnya yang layak dibaca dengan saksama:
- Tiga socket
uses, bukan satu:upstreamdanguard(milik basis, denganupstreammemilihcomponent.aggrega.ai/type=server) sertareviewed_upstream(milik wrapper). Perluasan menambahkan socket; perluasan tidak menggantikan himpunannya. - Tiga pilar basis, apa adanya —
values.upstream_path,infra.port/engine_version/compute/overrides, danprovides.host/port/protocol, masing-masing dengan deskripsi milik basis sendiri.
Apa yang ditulis Aggregate yang menggunakannya
aggregate-reviewed.yaml mendeklarasikan dua tingkat gateway sebagai wrapper, di depan
konsol basis data:
components: edge: type: example/gateway/nginx-reviewed values: upstream_path: /api/ # declared by the base; the wrapper never mentions it uses: reviewed_upstream: # the socket the wrapper ADDS internal: { target: internal, inject: { env: [ ... ] } } internal: type: example/gateway/nginx-reviewed values: upstream_path: / uses: upstream: # the socket the wrapper INHERITS console: { target: console, inject: { env: [ ... ] } } console: type: core/devtool/adminerupstream_path adalah kunci yang perlu diperhatikan. Kunci ini dideklarasikan dalam pilar
values milik core/gateway/nginx dan tidak muncul di mana pun dalam berkas wrapper, namun penulis
menuliskannya pada instans wrapper dan kunci itu sampai ke konfigurasi gateway
yang dirender. Itulah arti mewarisi pilar secara utuh dalam praktik.
Manifest adalah separuh lainnya, dan isinya satu baris per tipe:
mappings: components: type: example/gateway/nginx-reviewed:1.0.0: compose/nginx:1.0.0 core/gateway/nginx:1.0.0: compose/nginx:1.0.0 core/devtool/adminer:1.0.0: compose/adminer:1.0.0Kedua baris gateway menyebut Recipe yang sama. compose/nginx mendeklarasikan
implements: core/gateway/nginx:1.0.0, dan Recipe yang menyebut sebuah basis adalah
implementasi untuk setiap Component yang memperluas basis tersebut — sehingga wrapper
dilayani olehnya tanpa perubahan. Dua fakta berlaku sekaligus di sini, dan keduanya terpisah:
- Recipe cocok. Tidak ada Recipe yang mengimplementasikan tipe wrapper itu sendiri, dan memang tidak diperlukan.
- Pemetaan tetap diperlukan. Pemilihan Recipe dilakukan berdasarkan kunci pemetaan yang persis, sehingga
wrapper memerlukan entri
typesendiri; wrapper tidak mewarisi entri milik basis. Instans wrapper tanpa entri sendiri akan terhenti dengan diagnostik instans tak terpetakan meskipun basisnya sudah dipetakan.
Membuat contoh
Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.
Tulis contoh ke folder baru yang dinamai sesuai contoh itu:
aggrega scaffold --example extends-wrapperKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd extends-wrapperBuild
aggrega build --release release-reviewed.yaml --auto-pullKeluaran yang dirender dan lockfile dihasilkan, bukan dikirimkan: contoh ini
hanya meng-commit masukannya dan meregenerasi semua yang lain. --auto-pull me-resolve
lockfile selama build; menjalankan aggrega pull --release release-reviewed.yaml sekali
sebelumnya melakukan hal yang sama dan memungkinkan build berikutnya berjalan tanpa flag sama sekali.
Wrapper maupun basis yang diperluasnya berada di katalog bersama, yang di-resolve dari hub.aggrega.ai, registry bawaan yang dideklarasikan .aggrega-config.yaml. Perintah build tidak memerlukan flag --catalog, begitu pula aggrega inspect yang dijalankan dari direktori ini.
Pull mengambil core/gateway/nginx karena wrapper memperluasnya: sebuah basis merupakan dependensi dari segala yang memperluasnya, sehingga pull mengikuti extends: milik wrapper dan menyematkan basis itu di lockfile, baik Manifest menyebutnya maupun tidak. Manifest di sini memetakan basis karena alasan lain — rilis kontrol di bawah mendeklarasikan instans dari basis itu sendiri.
dist/compose/docker-compose.yaml yang dirender memuat buktinya:
edge: image: nginx:1.27.5-alpine entrypoint: - /bin/sh - -c - echo 'server { listen 8080; location /api/ { proxy_pass http://internal:8081; } }' > /etc/nginx/conf.d/default.conf && exec nginx -g 'daemon off;' [… omitted: the published port] labels: [… omitted: the other provenance labels every rendered document carries] aggrega.ai/recipe-uri: nginx:1.0.0 [… omitted: the service's network, its depends_on naming internal, and its healthcheck]Tiga pembacaan, diurutkan menurut apa yang dibuktikannya:
aggrega.ai/recipe-uri: nginx:1.0.0— Recipe milik basis membentuk layanan ini. Label provenans pada instans wrapper menyebut Recipe milik basis karena itulah Recipe yang merendernya.location /api/—values.upstream_path, kunci yang hanya dideklarasikan basis, ditulis pada instans wrapper dan dirender.proxy_pass http://internal:8081— edgereviewed_upstreamter-resolve.provides.hostdanprovides.portmilik target tiba di konteks injeksi di bawah kunci pengiriman yang dibaca Recipe milik basis, sehingga socket yang ditambahkan wrapper mengalir melalui Recipe yang tidak pernah mengenalnya.
Lockfile yang di-resolve oleh build mencatat fakta yang sama dari sisi resolver:
satu entri compose/nginx:1.0.0 pada satu digest, dirujuk dari kedua kunci
pemetaan — tipe milik basis dan tipe milik wrapper.
Label dan anotasi wrapper ikut terbawa bersama edge yang ter-resolve: konteks render
node konsumen memuat provides, labels dan anotasi setiap target,
sehingga konteks edge mengetahui bahwa upstream-nya adalah audit-tier=reviewed dan siapa yang
meninjaunya. Apakah semua itu muncul dalam artefak yang dirender adalah pilihan Recipe —
label dan anotasi ini adalah identitas komponen untuk dibaca selector dan kebijakan,
bukan keluaran yang dicap oleh compiler.
Dengan asisten AI
Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.
Gunakan hanya alat Aggrega, dan jangan membuat folder sendiri. Jika folder ruang kerja belum berisi folder `extends-wrapper`, panggil alat `scaffold` sekali dengan `example` diatur ke `extends-wrapper` dan tanpa `dir`: alat ini menulis contoh ke dalam folder `extends-wrapper` yang baru. Lalu panggil alat `build` dengan `workspace_root` diatur ke `extends-wrapper`, `release` diatur ke `release-reviewed.yaml`, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file mana yang ditulis oleh build; file tersebut berada di bawah `extends-wrapper/dist/`.Kontrol: untuk apa label yang ditambahkan
aggregate-unreviewed.yaml adalah aggregate-reviewed.yaml dengan satu perubahan — tingkat
internal dideklarasikan sebagai basis core/gateway/nginx polos alih-alih
wrapper — dan berkas ini diharapkan gagal:
aggrega build --release release-negative-unreviewed.yaml --auto-pull# [DEVELOPER_ERROR E0007] aggregate-unreviewed.yaml at .spec.components.edge.uses.reviewed_upstream.internal# selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.Penghentian itulah pelajarannya. Basis memenuhi socket upstream miliknya sendiri — basis itu
component.aggrega.ai/type=server, dan tingkat internal dihubungkan melalui socket
tersebut dengan cara yang persis sama — tetapi basis tidak membawa label audit-tier, sehingga
socket wrapper yang lebih ketat menolaknya. Label yang ditambahkan wrapper itulah yang membuat
instansnya dapat dipilih, dan selector adalah tempat hal itu terlihat.
Dua penghentian lain patut diketahui, dan keduanya adalah skema yang menjalankan tugasnya:
- Component yang mendeklarasikan
extendsdan menulis konten pilar di bawahschema:ditolak saat dokumen dimuat, dengan menyebut batasannya. Begitu pula Component yang menghilangkanschema:sepenuhnya.schema: inheritedadalah satu-satunya bentuk yang diterima, dan bentuk ini ditulis alih-alih tersirat agar pembaca tidak pernah tertukar antara blok pilar yang diwarisi dan blok yang terlupa. - Kunci
valuesyang tidak dideklarasikan basis ditolak pada instans wrapper, di jalur tempat kunci itu ditulis, karena kontrak yang ditegakkan adalah milik basis.
Mengapa ini berguna
Organisasi yang telah menetapkan bentuk yang sudah ditinjau untuk komponen pustaka standar
memerlukan tempat untuk menyimpannya. Jika disimpan dalam bentuk prosa, label, anotasi dan
socket harus dinyatakan ulang di setiap Aggregate yang memerlukannya, dan lama-kelamaan saling menyimpang.
Jika dipublikasikan sebagai Component yang memperluas basis, bentuk itu menjadi
entitas katalog berversi yang dapat ditinjau dan memiliki nama: tim yang menggunakannya menulis
type: example/gateway/nginx-reviewed dan satu baris Manifest, lalu mewarisi
seluruh kontrak basis beserta setiap Recipe yang sudah ditulis untuknya, pada
setiap target yang didukung basis.
Biaya wrapper itulah yang membuat ini berhasil: wrapper menambahkan struktur dan metadata dan tidak lebih. Karena wrapper tidak mendeklarasikan pilar, instans wrapper dan instans basis divalidasi terhadap satu kontrak, dan Recipe yang ditulis untuk basis tidak akan pernah dikejutkan oleh spesialisasinya.