跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

一个无人声明的 socket,交付真实的值

本示例讲授一句话,以及它的两个部分:

消费方可以自创连接,但只能消费生产方声明的内容。

一位 Aggregate 作者在自己的 component 上编写了一个 uses: 条目,所用的 socket 名称没有任何目录实体声明过。该边会被构建并且能够交付——值到达渲染产物的方式 与通过已声明 socket 完全相同。但 该边可以携带哪些键仍由目标声明:一旦指定了目标未声明的键,构建就会中止。

这里的一切都从标准库目录解析。该工作区 没有编写任何自己的 Component、Feature 或 Recipe。

技术栈

三个 component,其中一个以两种不同方式连接:

实例类型说明
dbcore/datastore/mariadb数据库
modelcore/ai-model/anthropic模型端点;引用形式的实现,因此不为其运行任何计算资源
webcore/devtool/adminer控制台,同时消费两者

core/devtool/adminer 只声明了一个 socket:

usesSchema:
databases:
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]

这就是其作者所预见的全部内容。位于数据库前端的控制台 是作者设想的连接;在环境变量中携带模型端点的控制台 则不是。

Aggregate 中写了什么

aggregate-delivers.yaml 在一个 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 没有出现在任何 usesSchema 中,无论是这个 Component 还是其他 Component。但它 仍然合法:目录对某个 socket 保持沉默,意味着该连接未被 预见,而不是被禁止;开发者拥有自己 应用的拓扑。

临时 socket 所放弃的,恰恰是缺失的 usesSchema 条目 本应携带的内容——没有 selector,因此没有任何东西约束该边可以到达哪个 component, 跨节点类型安全检查也无可评估;没有 inject: 允许列表;没有逐边的 valueSchema 或 infraSchema,因此逐边的 values: 和 infra: 没有可供检查的契约,也没有可继承的已声明 默认值。在此类 socket 上编写的逐边配置会被接受 并在未经检查的情况下传递,这正是每个在该支柱上没有契约的 socket 的行为——未编写 valueSchema 的已声明 socket 也处于 相同境地。

它没有放弃的,是该边可以携带的内容。endpoint 和 model 都是 core/ai-model/anthropic 在其 provides 支柱中声明的键。

生成示例

你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。

将示例写入一个以其命名的新文件夹:

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

然后它会打印接下来要运行的命令。第一条命令进入新文件夹:

Terminal window
cd adhoc-uses-socket

构建

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

渲染输出和锁文件是生成的,而非随附提供:本示例只提交输入,其余内容全部重新生成。--auto-pull 在构建期间解析锁文件;事先运行一次 aggrega pull --release release-delivers.yaml 效果相同,并且之后的构建无需任何标志即可运行。目录实体从 hub.aggrega.ai 解析,即 .aggrega-config.yaml 指定的默认注册表,因此构建和 aggrega inspect 都不需要 --catalog 标志。

借助 AI 助手

已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。

只使用 Aggrega 的工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `adhoc-uses-socket` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `adhoc-uses-socket`,且不提供 `dir`:它会把示例写入一个新的 `adhoc-uses-socket` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `adhoc-uses-socket`,`release` 设为 `release-delivers.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `adhoc-uses-socket/dist/` 下。

阅读输出

dist/compose/docker-compose.yaml 中的 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]

四个变量,其中三个通过边交付,而且输出并不 记录哪个 socket 是已声明的:

  • ADMINER_DEFAULT_SERVER: db 经由已声明的 socket databases 到达。其 值是数据库 Recipe 的 provides.host——一个 Compose 服务名。
  • ASSISTANT_ENDPOINT 和 ASSISTANT_MODEL 经由临时 socket assistant 到达,携带模型 Recipe 的 provides.endpoint 和 provides.model。

它们位于同一个映射中,按作者编写的顺序排列,彼此之间没有标记、没有注解,也没有 顺序差异。这正是关键所在:临时 socket 在声明上有所 不同,在交付上并无不同。只有一条 交付路径,两条边都走这条路径。

ASSISTANT_ENDPOINT 也值得作为一个预先编译(ahead-of-time)的事实来解读。 编译器并没有联系 Anthropic 来发现 https://api.anthropic.com; 是 Recipe 将其作为一个确定性的指针字符串发出,来源于模型 component 的 infra.endpoint,编译器只是路由该字符串而不 解释它。Adminer 本身并不读取任何 ASSISTANT_* 变量——这些 交付键由开发者选择,控制台的容器携带它们, 供容器中任何读取它们的程序使用。

即使渲染产物不记录这一区别,构建发出的图也会记录:每条边都带有一个 socket_declaration 字段,值为 declared 或 ad-hoc,因此如果某个组织希望每个连接都经过 其架构师声明的 socket,就应将其表达为治理策略, 而不是依赖编译器持有某种立场。参见 architecture/11-governance-and-compliance.md。

对照:消费方仍然不能自创的内容

aggregate-undeclared-key.yaml 是在 aggregate-delivers.yaml 基础上做了一处修改。该 临时边请求了第三个键:

- in: ASSISTANT_API_KEY
from: api_key

core/ai-model/anthropic 在其 provides 支柱中只声明了 endpoint 和 model。该构建预期会失败:

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")

中止本身就是要点,而值得注意的是它在何处触发: 出错路径指向临时 socket uses.assistant,并停在 连接层面,而不是其中的交付条目。在每条边上,from: 键都会 对照目标 Component 已声明的 provides 进行检查,socket 是否临时 对这一检查毫无影响。可以自创 socket 名称的作者,仍然不能在别人的 component 上自创输出键。

消息首先给出拒绝说明,然后是 Aggregate 以及编写该边的路径, 条目所在的机制和交付键,出错的键,解析时所依据的 component 类型,以及该类型已声明的键 (按排序顺序)——因此仅凭消息就能看出修复方法。完全未声明 provides 的目标 Component 同样会拒绝所有指向它的 from: 引用;只是没有已声明的键可列出,因此消息在 component 类型之后结束。

该写哪一种

在目录中声明 socket 仍是更好的做法,标准库目录也正是这样做的。已声明的 socket 带有一个 selector, 用于约束该边可以到达哪些 component,还带有 inject: 允许列表、 具有自身默认值的逐边契约,以及一段描述——这是对预期连接的一份可审查 陈述,并随提出它的实体一起进行版本管理。 临时 socket 不具备其中任何一项,该边的安全程度完全取决于 编写它的作者。

临时形式是一个逃生舱口,适用于本示例所展示的情形:目录作者 未预见、某一次部署需要的连接,而等待 目录变更就意味着推迟发布。使用它时要清楚它的代价。

有两项代价值得明确说明:

  • 拼错的 socket 名称是一个合法的临时 socket,而不是错误。在本应写 databases 的地方写成 databses,会得到一次成功的构建,但没有任何内容 经由预期的 socket 流动。对于与已声明 socket 名称只差一处编辑的名称,编译器会给出一条同时列出两种拼写的提示——参见 errors/warnings.md 中的“Uses-socket near-miss lint”—— 但这只是警告,绝不会改变构建的结果。
  • 有两个入口刻意不以这种方式开放。 Feature 挂载的 uses 只能指定所挂载 Feature 声明的 socket,Release 的 逐边 uses 只能指定消费方 Component 声明的 socket。 运维人员在架构之内进行配置和连接;他们并不编写架构。 因此 release-delivers.yaml 只携带 infra:,不涉及任何 socket—— assistant socket 属于 Aggregate 作者,且仅属于他们。

完整契约请参见 entities/component.md 中的“Topology Sockets: usesSchema”以及 architecture/07-dependency-resolution.md。