Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

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:

instancekiểunó là gì
dbcore/datastore/mariadbcơ sở dữ liệu
modelcore/ai-model/anthropicmộ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ó
webcore/devtool/adminerconsole, 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: model

assistant 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ó:

Terminal window
aggrega scaffold --example adhoc-uses-socket

Sau đó 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:

Terminal window
cd adhoc-uses-socket

Build

Terminal window
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 qua databases, socket đã khai báo. Giá trị của nó là provides.host của Recipe cơ sở dữ liệu — một tên service Compose.
  • ASSISTANT_ENDPOINT và ASSISTANT_MODEL đến qua assistant, socket ad-hoc, mang provides.endpoint và provides.model củ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_key

core/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:

Terminal window
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 databses khi ý định là databases tạ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. uses của một Feature attachment chỉ được nêu một socket mà Feature được gắn khai báo, và uses theo 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ậy release-delivers.yaml mang infra: và không có gì về socket — socket assistant thuộ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.