Một wrapper được phát hành, được phục vụ bởi Recipe của base
Ví dụ này dạy một điều: một Component extends một Component khác sẽ kế thừa
toàn bộ hợp đồng dữ liệu của base đó, nên mọi Recipe viết cho base đều đã
triển khai Component mở rộng. Vì vậy, phát hành một biến thể chuyên biệt của một
component thuộc thư viện chuẩn chỉ tốn một thực thể catalog và một dòng Manifest
— không cần Recipe riêng, và không thay đổi gì ở base.
Wrapper ở đây là example/gateway/nginx-reviewed. Nó được phân phối trong catalog
bên cạnh core/gateway/nginx, component mà nó mở rộng.
Wrapper thêm gì, và kế thừa gì
Toàn bộ phần được viết của wrapper là metadata cộng với một 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 là dấu hiệu nguyên văn mà một Component mở rộng viết thay cho
một khối schema:. Nó khẳng định rằng ba trụ cột dữ liệu — values, infra
và provides — là của base, đúng như base đã viết. Wrapper
không khai báo khóa trụ cột nào của riêng mình và cũng không thể: hợp đồng thuộc về base,
ở mọi độ sâu của một chuỗi.
Mọi thứ wrapper không nhắc đến, nó đều kế thừa. aggrega inspect example/gateway/nginx-reviewed --resolved hiển thị thực thể đã hợp nhất, và có hai
điều trong đó đáng đọc kỹ:
- Ba socket
uses, không phải một:upstreamvàguard(của base, trong đóupstreamchọncomponent.aggrega.ai/type=server) vàreviewed_upstream(của wrapper). Việc mở rộng thêm một socket; nó không thay thế cả tập hợp. - Ba trụ cột của base, nguyên văn —
values.upstream_path,infra.port/engine_version/compute/overrides, vàprovides.host/port/protocol, mỗi mục kèm mô tả riêng của base.
Một Aggregate sử dụng viết gì
aggregate-reviewed.yaml khai báo hai tầng gateway là wrapper, đứng trước một
console cơ sở dữ liệu:
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 là khóa cần chú ý. Nó được khai báo trong pillar values của core/gateway/nginx
và không xuất hiện ở đâu trong tệp của wrapper, vậy mà tác giả vẫn
viết nó trên một instance của wrapper và nó đi đến tận cấu hình gateway
được render. Đó là ý nghĩa thực tế của việc kế thừa trọn vẹn các pillar.
Manifest là nửa còn lại, và mỗi type là một dòng:
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.0Cả hai dòng gateway đều chỉ định cùng một Recipe. compose/nginx khai báo
implements: core/gateway/nginx:1.0.0, và một Recipe chỉ định một base là
phần triển khai cho mọi Component mở rộng base đó — nên wrapper được
nó phục vụ mà không cần thay đổi. Ở đây có hai sự thật cùng đúng, và chúng tách biệt:
- Recipe khớp. Không tồn tại Recipe nào triển khai type riêng của wrapper, và cũng không cần.
- Ánh xạ vẫn bắt buộc. Việc chọn Recipe dựa trên khóa ánh xạ chính xác, nên
wrapper cần mục
typeriêng; nó không kế thừa mục của base. Một instance của wrapper không có mục riêng sẽ dừng với chẩn đoán unmapped-instance ngay cả khi base của nó đã được ánh xạ.
Tạo ví dụ
Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.
Ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example extends-wrapperSau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:
cd extends-wrapperBuild
aggrega build --release release-reviewed.yaml --auto-pullĐầu ra được render và lockfile được sinh ra, không được phân phối kèm: ví dụ này
commit các đầu vào và sinh lại mọi thứ khác. --auto-pull phân giải
lockfile trong quá trình build; chạy aggrega pull --release release-reviewed.yaml một lần
trước đó cũng làm điều tương tự và cho phép các lần build sau chạy mà không cần flag nào.
Cả wrapper lẫn base mà nó mở rộng đều nằm trong catalog dùng chung, được phân giải từ hub.aggrega.ai, registry mặc định mà .aggrega-config.yaml khai báo. Lệnh build không cần flag --catalog, và aggrega inspect chạy từ thư mục này cũng vậy.
Thao tác pull tải về core/gateway/nginx vì wrapper mở rộng nó: một base là phụ thuộc của mọi thứ mở rộng nó, nên thao tác pull đi theo extends: của wrapper và ghim base vào lockfile, dù Manifest có nêu tên nó hay không. Manifest ở đây ánh xạ base vì một lý do khác — bản phát hành đối chứng bên dưới khai báo một instance của chính base đó.
Tệp dist/compose/docker-compose.yaml được render chứa bằng chứng:
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]Ba điểm cần đọc, theo thứ tự những gì chúng chứng minh:
aggrega.ai/recipe-uri: nginx:1.0.0— Recipe của base đã định hình service này. Nhãn nguồn gốc trên một instance của wrapper ghi tên Recipe của base vì đó là Recipe đã render nó.location /api/—values.upstream_path, một khóa chỉ base khai báo, được viết trên một instance của wrapper và được render.proxy_pass http://internal:8081— cạnhreviewed_upstreamđã được phân giải.provides.hostvàprovides.portcủa đích đến được đưa vào ngữ cảnh injection dưới các khóa phân phối mà Recipe của base đọc, nên một socket do wrapper thêm vào đi qua một Recipe chưa từng biết đến nó.
Lockfile mà quá trình build phân giải ghi nhận cùng sự thật đó từ phía resolver:
một mục compose/nginx:1.0.0 tại một digest, được tham chiếu từ cả hai khóa
ánh xạ — type của base và type của wrapper.
Các label và annotation của wrapper đi cùng cạnh đã phân giải: ngữ cảnh render của
một node sử dụng mang theo provides, labels và annotation của từng đích đến,
nên ngữ cảnh của edge biết upstream của nó là audit-tier=reviewed và ai đã review
nó. Việc những thông tin đó có xuất hiện trong artifact được render hay không là lựa chọn của Recipe —
các label và annotation này là danh tính component để selector và policy
đọc, không phải đầu ra mà compiler đóng dấu vào.
Với trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.
Chỉ sử dụng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục không gian làm việc chưa chứa thư mục `extends-wrapper`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `extends-wrapper` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `extends-wrapper` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `extends-wrapper`, `release` đặt thành `release-reviewed.yaml`, `auto_pull` đặt thành true và `write` đặt thành true. Hãy cho tôi biết lần build đã ghi những tệp nào; chúng nằm trong `extends-wrapper/dist/`.Đối chứng: label được thêm vào dùng để làm gì
aggregate-unreviewed.yaml là aggregate-reviewed.yaml với một chỉnh sửa — tầng
internal được khai báo là base core/gateway/nginx trần thay vì
wrapper — và nó được dự kiến sẽ thất bại:
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.Việc dừng lại chính là bài học. Base thỏa mãn socket upstream của chính nó — nó là
component.aggrega.ai/type=server, và tầng internal được nối qua socket đó
theo đúng cách như vậy — nhưng nó không mang label audit-tier, nên
socket chặt chẽ hơn của wrapper từ chối nó. Label mà wrapper thêm vào là thứ khiến
một instance của nó có thể được chọn, và selector là nơi điều đó thể hiện.
Còn hai trường hợp dừng nữa đáng biết, và cả hai đều là schema đang làm đúng việc của nó:
- Một Component khai báo
extendsvà viết nội dung trụ cột dướischema:bị từ chối khi tài liệu được tải, kèm tên ràng buộc. Một Component bỏ hẳnschema:cũng vậy.schema: inheritedlà dạng duy nhất được chấp nhận, và nó được viết ra thay vì ngầm hiểu để người đọc không bao giờ nhầm một khối trụ cột được kế thừa với một khối bị bỏ quên. - Một khóa
valuesmà base không khai báo sẽ bị từ chối trên một instance của wrapper, tại đường dẫn được viết, vì hợp đồng được thực thi là của base.
Vì sao điều này hữu ích
Một tổ chức đã thống nhất một hình dạng được review cho một component thuộc thư viện chuẩn
cần một nơi để lưu giữ nó. Nếu lưu bằng văn xuôi, các label, annotation và
socket bị viết lại trong mọi Aggregate cần đến chúng, và dần lệch nhau theo thời gian.
Nếu phát hành dưới dạng một Component mở rộng base, hình dạng đó trở thành một
thực thể catalog có phiên bản, có thể review và có tên: một nhóm sử dụng nó viết
type: example/gateway/nginx-reviewed và một dòng Manifest, rồi kế thừa
toàn bộ hợp đồng của base cùng mọi Recipe đã được viết cho nó, trên
mọi target mà base hỗ trợ.
Chi phí của wrapper chính là điều khiến cách này hoạt động: nó chỉ thêm cấu trúc và metadata và không gì khác. Vì nó không khai báo trụ cột nào, một instance của wrapper và một instance của base được kiểm tra theo cùng một hợp đồng, và một Recipe viết cho base không bao giờ bị bất ngờ bởi một biến thể chuyên biệt của nó.