Một socket không ai khai báo, vẫn chuyển giao giá trị thật
Ví dụ này dạy một điều, và cả hai vế của nó:
Bên tiêu thụ có thể tự tạo ra kết nối. Nó chỉ được tiêu thụ những gì bên cung cấp khai báo.
Tác giả Aggregate viết một mục uses: trên component của chính mình dưới một tên socket
mà không entity nào trong catalog khai báo. Cạnh được xây dựng và nó chuyển giao — giá trị
đến được artifact đã render đúng như khi đi qua một socket đã khai báo. Nhưng
các khóa mà cạnh đó có thể mang vẫn do đích khai báo: nêu một khóa mà
đích không khai báo, và bản build sẽ dừng.
Mọi thứ ở đây được phân giải từ catalog thư viện chuẩn. Workspace không tự viết Component, Feature hay Recipe nào.
Stack
Ba component, và một trong số đó được nối theo hai cách khác nhau:
| instance | kiểu | nó là gì |
|---|---|---|
db | core/datastore/mariadb | cơ sở dữ liệu |
model | core/ai-model/anthropic | một endpoint mô hình; một hiện thực dạng tham chiếu, nên không có tài nguyên tính toán nào chạy cho nó |
web | core/devtool/adminer | console, tiêu thụ cả hai |
core/devtool/adminer khai báo đúng một socket:
usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: [env]Đó là toàn bộ những gì tác giả của nó đã dự liệu. Một console đứng trước một cơ sở dữ liệu là kết nối họ nghĩ đến; một console mang một endpoint mô hình trong môi trường của nó thì không.
Những gì Aggregate viết
aggregate-delivers.yaml nối cả hai cạnh từ một khối uses::
web: type: core/devtool/adminer uses: databases: # DECLARED — the socket the Component's usesSchema names db: target: db inject: env: - in: ADMINER_DEFAULT_SERVER from: host
assistant: # AD-HOC — declared nowhere model: target: model inject: env: - in: ASSISTANT_ENDPOINT from: endpoint - in: ASSISTANT_MODEL from: modelassistant không xuất hiện trong usesSchema nào, trên Component này hay bất kỳ Component nào khác. Dù vậy
nó vẫn hợp lệ: việc catalog im lặng về một socket nghĩa là kết nối đó không được
dự liệu, không phải là nó bị cấm, và nhà phát triển làm chủ topology của
ứng dụng của chính mình.
Điều socket ad-hoc từ bỏ chính là những gì mục usesSchema còn thiếu
lẽ ra đã mang — không có selector, nên không gì ràng buộc component nào mà
cạnh có thể chạm tới và phép kiểm tra an toàn kiểu xuyên node không có gì để đánh giá; không có
danh sách cho phép inject:; không có valueSchema hay infraSchema theo từng cạnh, nên
values: và infra: theo từng cạnh không có hợp đồng nào để kiểm tra và không có giá trị mặc định
đã khai báo nào để kế thừa. Cấu hình theo từng cạnh viết trên một socket như vậy được chấp nhận
và đi qua mà không được kiểm tra, đó là cách mọi socket không có hợp đồng cho trụ cột đó
hoạt động — một socket đã khai báo mà không viết valueSchema cũng ở cùng
vị trí.
Điều nó không từ bỏ là những gì cạnh có thể mang. endpoint và model
đều là các khóa mà core/ai-model/anthropic khai báo trong trụ cột provides của nó.
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 adhoc-uses-socketSau đó 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 adhoc-uses-socketBuild
aggrega build --release release-delivers.yaml --auto-pullĐầu ra đã 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 lúc build; chạy aggrega pull --release release-delivers.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 cờ nào. Các entity của catalog được phân giải từ hub.aggrega.ai, registry mặc định mà .aggrega-config.yaml chỉ định, nên cả bản build lẫn aggrega inspect đều không cần cờ --catalog.
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ỉ 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 workspace chưa có thư mục `adhoc-uses-socket`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `adhoc-uses-socket` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `adhoc-uses-socket` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `adhoc-uses-socket`, `release` đặt thành `release-delivers.yaml`, `auto_pull` đặt thành true và `write` đặt thành true. Hãy cho tôi biết bản build đã ghi những tệp nào; chúng nằm trong `adhoc-uses-socket/dist/`.Đọc đầu ra
dist/compose/docker-compose.yaml, service web:
web: image: adminer:4 environment: ADMINER_DESIGN: pepa-linha-dark ADMINER_DEFAULT_SERVER: db ASSISTANT_ENDPOINT: https://api.anthropic.com ASSISTANT_MODEL: claude-sonnet-4-5 [… omitted: the service's ports, provenance labels, networks, depends_on and healthcheck]Bốn biến, ba trong số đó được chuyển giao qua các cạnh, và đầu ra không ghi lại socket nào đã được khai báo:
ADMINER_DEFAULT_SERVER: dbđến quadatabases, socket đã khai báo. Giá trị của nó làprovides.hostcủa Recipe cơ sở dữ liệu — một tên service Compose.ASSISTANT_ENDPOINTvàASSISTANT_MODELđến quaassistant, socket ad-hoc, mangprovides.endpointvàprovides.modelcủa Recipe mô hình.
Chúng nằm trong cùng một map, theo thứ tự tác giả viết, không có dấu đánh dấu, không chú thích và không có khác biệt thứ tự nào giữa chúng. Đó chính là điểm mấu chốt: một socket ad-hoc là một điều khác khi khai báo, không phải một điều khác khi chuyển giao. Chỉ có một đường chuyển giao và cả hai cạnh đều đi qua nó.
ASSISTANT_ENDPOINT cũng đáng đọc như một thực tế của biên dịch ahead-of-time.
Trình biên dịch không liên hệ Anthropic để tìm ra https://api.anthropic.com;
Recipe phát ra nó dưới dạng một chuỗi con trỏ tất định lấy từ infra.endpoint của
component mô hình, và trình biên dịch định tuyến chuỗi đó mà không
diễn giải nó. Bản thân Adminer không đọc biến ASSISTANT_* nào — nhà
phát triển đã chọn các khóa chuyển giao đó, và container của console mang chúng cho
bất cứ thứ gì đọc chúng ở đó.
Đồ thị mà bản build phát ra ghi lại sự phân biệt này dù artifact đã render
thì không: mọi cạnh mang một trường socket_declaration có giá trị
declared hoặc ad-hoc, nên một tổ chức muốn mọi kết nối đều đi
qua một socket mà các Architect của mình đã khai báo sẽ diễn đạt điều đó thành một chính sách quản trị
thay vì trông cậy vào việc trình biên dịch giữ một quan điểm. Xem
architecture/11-governance-and-compliance.md.
Đối chứng: những gì bên tiêu thụ vẫn không được tự tạo ra
aggregate-undeclared-key.yaml là aggregate-delivers.yaml với một chỉnh sửa. Cạnh
ad-hoc yêu cầu một khóa thứ ba:
- in: ASSISTANT_API_KEY from: api_keycore/ai-model/anthropic khai báo endpoint và model trong trụ cột provides
của nó, và không gì khác. Bản build được dự kiến sẽ thất bại:
aggrega build --release release-negative-undeclared-key.yaml --auto-pull# [… omitted: a refused: line carrying the message below]# [DEVELOPER_ERROR E0156] .spec.components.web.uses.assistant.model# invalid inject key: the from-key must name a provides key its source publishes# (Aggregate adhoc-uses-socket-undeclared-key,# at .spec.components.web.uses.assistant.model, "env", "ASSISTANT_API_KEY", "api_key",# "core/ai-model/anthropic", "endpoint", "model")Việc dừng lại chính là bài học, và nơi nó xảy ra là phần đáng chú ý:
đường dẫn vi phạm nêu tên socket ad-hoc, uses.assistant, và dừng ở
kết nối thay vì ở mục chuyển giao bên trong nó. Khóa from: được
kiểm tra đối chiếu với provides đã khai báo của Component đích trên mọi cạnh, và việc
socket là ad-hoc không thay đổi gì trong phép kiểm tra đó. Một tác giả có thể tự tạo ra một
tên socket vẫn không được tự tạo ra một khóa đầu ra trên component của người khác.
Lời từ chối đứng đầu, sau đó là Aggregate và đường dẫn nơi cạnh được viết,
cơ chế và khóa chuyển giao mà mục được viết dưới đó, khóa
gây lỗi, kiểu component mà nó được phân giải theo, và các khóa đã khai báo của kiểu đó
theo thứ tự đã sắp xếp — nên chỉ cần nhìn thông báo là thấy cách sửa. Một
Component đích không khai báo provides nào cũng từ chối mọi tham chiếu from: tới
nó y như vậy; chỉ đơn giản là không có khóa đã khai báo nào để liệt kê, nên thông báo kết thúc
sau kiểu component.
Nên viết cách nào
Khai báo socket trong catalog vẫn là con đường tốt hơn, và đó là điều
catalog thư viện chuẩn làm. Một socket đã khai báo mang một selector
ràng buộc những component mà cạnh có thể chạm tới, một danh sách cho phép inject:, một
hợp đồng theo từng cạnh với các giá trị mặc định riêng, và một mô tả — một tuyên bố
có thể review về một kết nối đã được dự liệu, được quản lý phiên bản cùng entity tạo ra nó.
Một socket ad-hoc không mang gì trong số đó, và cạnh chỉ an toàn ngang với tác giả
đã viết nó.
Dạng ad-hoc là một lối thoát, cho trường hợp mà ví dụ này cho thấy: một kết nối mà tác giả catalog không dự liệu, được một bản triển khai cần đến, khi việc chờ một thay đổi catalog đồng nghĩa với việc chờ để phát hành. Hãy dùng nó khi biết rõ cái giá của nó.
Có hai cái giá đáng nói rõ:
- Một tên socket viết sai chính tả là một socket ad-hoc hợp lệ, không phải một lỗi. Viết
databseskhi ý định làdatabasestạo ra một bản build thành công trong đó không có gì chảy qua socket dự định. Trình biên dịch báo một tên socket cách một lần chỉnh sửa so với một tên đã khai báo bằng một thông báo tư vấn nêu cả hai cách viết — xem errors/warnings.md “Uses-socket near-miss lint (Lint gần trùng uses-socket)” — nhưng đó là một cảnh báo và không bao giờ thay đổi kết quả của bản build. - Có hai bề mặt được cố ý không mở theo cách này.
usescủa một Feature attachment chỉ được nêu một socket mà Feature được gắn khai báo, vàusestheo từng cạnh của một Release chỉ được nêu một socket mà Component tiêu thụ khai báo. Một người vận hành cấu hình và nối dây bên trong một kiến trúc; họ không viết ra nó. Vì vậyrelease-delivers.yamlmanginfra:và không có gì về socket — socketassistantthuộc về tác giả Aggregate, và chỉ của họ.
Để biết toàn bộ hợp đồng, xem
entities/component.md “Topology Sockets: usesSchema” và
architecture/07-dependency-resolution.md.