Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

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.com
spec:
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: upstream dan guard (milik basis, dengan upstream memilih component.aggrega.ai/type=server) serta reviewed_upstream (milik wrapper). Perluasan menambahkan socket; perluasan tidak menggantikan himpunannya.
  • Tiga pilar basis, apa adanya — values.upstream_path, infra.port / engine_version / compute / overrides, dan provides.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/adminer

upstream_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.0

Kedua 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 type sendiri; 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:

Terminal window
aggrega scaffold --example extends-wrapper

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:

Terminal window
cd extends-wrapper

Build

Terminal window
aggrega build --release release-reviewed.yaml --auto-pull

Keluaran 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 — edge reviewed_upstream ter-resolve. provides.host dan provides.port milik 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:

Terminal window
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 extends dan menulis konten pilar di bawah schema: ditolak saat dokumen dimuat, dengan menyebut batasannya. Begitu pula Component yang menghilangkan schema: sepenuhnya. schema: inherited adalah 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 values yang 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.