架构不变量
这八个不变量是 Aggrega 的基本规则。它们在各个版本之间始终成立,贯穿编译器核心、模式层、目录以及 Wasm 插件接口面。每一项设计决策、每一个功能、每一个编写的实体都遵守它们。
其他架构章节按编号引用这些不变量。当后面的章节说“根据不变量 2”或“按照 String Pipe 规则(不变量 3)”时,指的就是这里。
1. 编译器对内容保持中立、不预设立场,并且与用户意图无关
Aggrega 编译器是一个预先编译(Ahead-Of-Time,AOT)的文本路由器。它解析 YAML、遍历图、计算标签交集,并把字符串从源输送到汇。它不管控作者在 values、parameters、infra、provides 或 locals 中写入什么。它不强制执行命名约定、端口约定,也不强制执行 Architect 自创的语义标签。
许多听起来像编译器规则的规则——Zero-Port Contract、Naked-Base / Flavored-Edges 目录风格、为给定组件选择哪种运维原语——都是社会契约(Social Contracts):带有逃生舱口的最佳实践,由编写标准库目录的 Platform Architect 来维护。编译器不解释它们。
**本不变量关注的是编译器从你编写的内容中推断出什么,其范围仅限于此。**少数键属于 Aggrega 自身——它们是保留键,可接受的值写在已发布的模式中——模式检查它们的方式与检查任何其他已声明字段相同。component.aggrega.ai/type 就是其中之一:它的值集合是封闭的,携带集合之外值的文档会在加载时被拒绝。这是平台在声明它自己的键是什么含义,而不是编译器从你写的字符串中解读含义;你自己的每一个键仍然完全像本不变量所说的那样不受管控。一个按 Aggrega 未定义的维度对组件分类的目录会编写自己的标签键,模式接受它取任意字符串值,每个选择器接口面也都以相同方式读取它。
编译器真正强制执行的范围很窄:模式校验、YAML 解析、图构建、模板求值,以及 Injection Contract 的纯文本路由。其他一切都是约定,在目录编写时或在可选启用的 Wasm 治理插槽中执行。
编写自己内部目录的企业明确可以自由打破标准库约定。只要通过模式校验,编译器就接受它们写的任何内容。架构提倡最佳实践;它不建造牢笼。
2. AOT 纯粹性:编译器无法访问运行时信息
Aggrega 是一个预先编译(Ahead-Of-Time)编译器。在编译时:
- 它不向云 API 进行身份验证。
- 它不获取实时 IP 地址、DNS 名称或云生成的 URL。
- 它不把机密解析为明文——机密在整个中间表示(Intermediate Representation)中始终是元数据指针。
- 它不知道目标集群或服务的运行时状态。
- 它无法获取尚不存在的数据(预配后才有的端点、动态分配的端口、自动生成的资源名称)。
任何依赖运行时状态的内容都表示为一个确定性指针字符串——稳定的 DNS 名称、Terraform 插值字符串、CloudFormation 资源引用——由 Ops Recipe 提供。编译器原样传递该指针而不解析它。最终的物理数据由运行时环境(集群、IaC 状态管理器)解析。
这就是真正的控制反转(True Control Inversion):开发者在 Aggregate 中规定 Injection Contract,编译器预先连接确定性指针,运行时环境解析最终的物理数据。真正需要运行时解析的需求应放在 Ops Recipe 的 Wasm 管道中,而不是编译器核心中。
3. String Pipe:编译器无法推断含义
编译器不解释所传递值的含义。当 Component A 使用 Component B 时,编译器获取 Component B 的 Recipe 通过 provides 产生的标量——字符串、数字或布尔值——并将其传入 Component A 的 Recipe 上下文,在注入边界处以确定性方式转换为字符串。无论该值是 FQDN、本地主机名、IP 字面量、端口号,还是 Wasm 格式化的 DSN,都没有区别:编译器不验证可路由性、协议正确性或语义恰当性。
由此产生两个结果:
- 编译器不会根据名称猜测组件用途。名为
database-production的组件不会被识别为数据库。诸如component.aggrega.ai/type之类的语义类型标签(如果存在)是用于标签匹配的不透明元数据,而不是编译器的分支逻辑。 - 编译器不区分主机名、数据库名、端口号和任意不透明值。它们都是注入上下文中的标量条目,以字符串形式交付。
拓扑三元组——生产方 Recipe 上的 provides、消费方 Aggregate 上的 uses、边上的 inject——就是 Injection Contract。编译器计算标签并传递字符串;解释则是 Recipe 与 Component 之间的编写契约。
4. 无幽灵基础设施:编译器从不凭空创造计算资源或功能
编译器从不静默注入计算资源、Features、注解、路由代理,或任何作者未明确声明的其他资源。策略违规会产生响亮的护栏(Loud Guardrails)——构建停止,并给出具体错误,告诉作者在其编写的文档中应修正什么——而不是在调试时制造基础设施谜团的静默变更。
资源通过编写时的显式声明进入图:
- 开发者的 Aggregate(组件、
uses边、Feature 挂接)。 - Release 的 Feature 挂接(运维人员层面的添加)。
- 注解驱动的扩展(Manifest 声明注解 → Feature 的绑定;Component 或边界上的注解即为显式声明)。
- Recipe 层面的资源产出:Recipe 的
source渲染产生主制品;workload合成输出特定于提供方的部署形态(Pod 规约、Compose 服务等);artifacts:条目(内联或通过$import:加载)输出 Recipe 固有的辅助清单;FeatureRecipe 资源生成则在显式挂接 Feature 时,按每个 Feature 输出辅助资源。
Recipe 层面的路径是间隔一步的编写时声明:Recipe 作者针对 Component 契约编写 source / workload / artifacts / valuesMapping,开发者的 Aggregate 选择哪些 Components 参与。渲染输出中出现的任何资源,都可追溯到 Aggregate、Release 或注解绑定中的某个声明,或追溯到 Aggregate 的组件类型所选中的 Recipe 编写。
合成将作者声明的形态转换为特定于提供方的输出格式。以容器映射形式编写的 Workload 规约,可以渲染为 Kubernetes Pod 规约、Compose 服务块或 Terraform 模块——转换由提供方驱动,但资源可追溯到作者的 Workload 声明。
治理插槽为每次挂接携带一个角色,决定挂接可以对构建做什么的是角色,而不是插件的类型。以裁决角色挂接的治理插件——审查 IR 图(ir-verdict)或渲染后的制品(render-verdict)——可以拒绝构建,但不能更改它。如果这样的裁决希望添加某个资源,它会以附带修复指引的方式使构建失败,由作者自己添加该资源;宿主只把裁决的输出读作接受或拒绝,从不将其作为更改来应用,因此未经邀请地把图改写成合规状态——正是本不变量所禁止的幽灵基础设施——不可能来自裁决角色。以变换角色(label-transform 或 annotation-transform)挂接的治理插件是狭窄而明确的例外:挂接它的运维人员——可选启用,通过工作区的 plugins.governance 配置——已经声明了该变换,因此它所做的更改是显式声明,与注解驱动的扩展地位相同,而不是静默注入。区别在于邀请:未被请求的裁决不得改写构建,而显式挂接的变换可以,因为是运维人员要求的。由于变换会塑造渲染输出,它会像每个塑造输出的插件一样被固定在锁文件中——所应用的变换在拉取时即已确定,因此更改它意味着重新拉取,而不是在两次构建之间静默变化;裁决不塑造任何输出,因此不被固定。
5. Aggregate 是编写界面;Release 不能声明 values:
Release 模式机械地禁止 values: 块。运维人员不能从 Release 中为 Component 或 Feature 编写 values。这是 JSON Schema 层面的模式强制——不是社会契约,也不是约定——而且它是响亮的:每个实体文档在加载时都会依据其类型的模式进行校验,因此携带 values: 的 Release 会使构建停止,并给出指明文件和违规键的诊断,而不是被静默忽略。
这并不意味着各环境中的值完全相同。按环境变化的受支持途径是参数提升(Parameter Hoisting):
- 开发者在 Aggregate 中暴露一个带类型的
parameters.*字段。 - Component 的
values模板引用它:storage_size: "{{ .parameters.db_size }}"。 - Release 为该参数赋值:
parameters: { db_size: "100Gi" }。 - 渲染输出反映特定于环境的值。
对于哪些值对外暴露以供按环境变化(parameters 声明),以及它们如何流入组件的值(模板引用),Aggregate 仍是唯一可信来源。Release 负责赋值;它不覆盖。
另外两条约束保护同一条不变量:
- 当 Release 使用
extends时,模式禁止声明aggregate:指针。子 Release 必须部署与其父 Release 相同的开发者意图(Developer Intent)。 - Release 不能引入 Aggregate 未声明的计算资源,也不能重新指定开发者声明的边的目标。在 Architect 声明的插槽范围内,Release 可以在现有组件之间连接并配置边:它可以在开发者已连接的边上设置按边的
infra,或者把一条边从已声明但未绑定的插槽连接到某个现有组件。它不能声明按边的values(这些保留在 Aggregate 中),不能绑定 Component 的usesSchema未声明的插槽,也不能让边指向不存在的组件——任一情况都会使构建停止。请注意中间那一条所指的是哪个声明:插槽必须出现在目录 Component 的usesSchema中。Aggregate 作者可以命名其组件类型未声明的插槽,而 Release 界面有意没有以同样方式开放——运维人员在一个架构之内进行连接和配置,而不是发明一个架构。
按边的连接配置以消费方为作用域:边上携带的 values 和 infra 只出现在编写该边的节点的渲染上下文中,从不出现在目标的上下文中。因此,一个组件自身的渲染输出不随其他组件对它建立的连接而变化——连接或配置一条指向目标的边,绝不会扰动目标的 Recipe 渲染出的内容。这些连接唯一可见的地方是挂接到目标的 Feature:它的 FeatureRecipe 可以读取哪些组件使用该目标,因此它输出的资源——例如只准入已声明调用方的策略——会随连接而变,而目标自身的输出不会。即便在那里,按边的 values 和 infra 仍归属于消费方。
6. WebAssembly ABI 边界:领域特定的智能存在于 Wasm 中
Go 宿主二进制文件不包含任何特定于云或基础设施的逻辑。所有领域特定的智能、模板渲染和格式化都严格存在于由嵌入式 Wazero 运行时执行的 WebAssembly 插件中。Go 宿主编排管道,并以每个插槽所携带的编码,把有效载荷作为内存指针跨越 ABI 传递给 Wasm 客体。
由此产生两个推论:
- 特定于 Provider 的逻辑(特定于 Helm 的渲染、特定于 Terraform 的格式化、特定于 Compose 的合并)从不存在于 Go 编译器核心中。编译器把 Recipe 在
spec.capability中声明的提供方名称解析为为其服务的提供方渲染 Plugin,并把节点分派给该插件;翻译本身完全在 Wasm 客体中运行。对于标准提供方,宿主不包含任何按提供方编写的 Go 代码,因此进程内没有可回退的东西——一个解析不到任何服务 Plugin 的提供方名称会使构建停止,而不是渲染某个内置默认值。 - 策略逻辑(安全规则、合规检查、FinOps 计算)从不存在于 Go 编译器核心中。策略属于企业选择启用的 Wasm 治理插槽——以裁决角色(
ir-verdict/render-verdict)挂接以接受或拒绝构建的插件,或以变换角色(label-transform/annotation-transform)挂接以塑造标签或注解的插件。
ABI 边界使 Go 核心保持紧凑、可审计且与云无关。替换某个提供方的渲染逻辑只是替换一个 Wasm 制品,而不是重新编译 Aggrega 本身。
7. 关注点分离(四域划分)——指导,而非牢笼
Aggrega 的设计指导把编写工作分为四个领域:
- Developer Intent —— Aggregate。
- Platform Architect —— Component 和 Feature 目录实体。
- Platform Ops —— Recipe、FeatureRecipe、Plugin(包括提供方渲染 Plugin)。
- Platform Operator —— Manifest、Release。
典型的、运行良好的部署遵循这一划分:开发者编写应用意图,而不是物理基础设施;Ops 编写物理基础设施,而不是应用逻辑。Aggrega 就是为这样使用而设计的,官方文档、示例和标准库目录都按这一划分编写。
四域划分是指导和设计框架,而不是编译器强制。编译器(根据不变量 1)不预设立场。用户可以自由地:
- 合并角色(由一个人同时编写 Aggregates 和 Recipes)。
- 混合关注点(当企业目录有要求时,Architect 直接在
core/*Components 上硬编码合规标签)。 - 跨越领域边界(当遗留代码有要求时,开发者使用参数提升把基础设施关注点注入 Aggregate)。
编译器接受任何通过模式校验的编写模式。架构提倡最佳实践;模式层面的约束(例如不变量 5 中禁止在 Release 中使用 values:)是编译器真正拒绝的唯一跨域行为。其他一切分离都是社会契约,由目录作者维护,在企业选择启用时还由 Wasm 治理插槽维护。
8. 确定性输出
给定相同的输入,编译器产生逐字节相同的输出。针对同一目录对同一 Aggregate + Release + Manifest 进行两次编译,得到的渲染制品逐字节相等。
这是 GitOps 工具和基于差异的评审流程所依赖的契约。未改变输入的拉取请求不应在渲染输出中产生任何差异。改变了输入的拉取请求应只显示该改变所蕴含的差异——没有多余的重新排序,没有时间戳变动,也没有映射迭代带来的杂乱结果。
确定性输出通过三项准则来维持:
- 按作者顺序排列的映射:任何迭代顺序可能影响渲染输出的映射都使用有序映射容器,使迭代遵循作者的声明顺序而非哈希顺序。
- 渲染制品中不包含挂钟时间或随机内容,除非作者通过模板输入显式注入。
- 渲染是纯的:以相同输入调用同一个 Wasm 客体,会产生相同的输出。
编译器的 --trace 标志(参见 language-reference/cli/aggrega-build.md)为作者和运维人员提供了验证本不变量的手段。在启用 --trace 的情况下对同一输入进行两次编译,会产生逐字节相同的跟踪转储;任何一轮处理中的差异都能定位一次回归。确定性不只是发布时的属性——通过按节点的跟踪布局,它在编译器的每个中间状态都可观察。
确定性输出这一契约,使 Aggrega 可以安全地用作 GitOps 循环中的可信来源。
跨解析层级的不变性范围
逐字节相同输出的保证适用于锁文件中固定的制品——即通过注册表制品解析、其摘要记录在锁文件中的实体(三层实体解析模型中的注册表层)。当构建读取 Release 按路径指定的文件(以 ./ 或 ../ 开头的本地路径)或工作区目录目录中的实体(catalog_dirs:,属于工作区与缓存层)时,不变性取决于这些文件在两次构建之间保持不变。锁文件通过实体文档及其声明的文件的摘要来记录工作区目录目录中的实体,因此对于自拉取以来发生变化的实体,构建会停止而不是渲染它——只有一个例外:如果 Manifest 用某个引用来命名 Recipe 或 FeatureRecipe,而该引用同时也是某个 Component 或 Feature 的名称,那么它会以该 Component 或 Feature 的身份记录在该引用下,因此它的输入只由锁中与其相邻的固定项约束,对其自身文档的编辑不会被发现。保持文件原样是源代码控制系统(通常是 Git)的责任。
如果某个本地路径引用的底层文件在两次编译之间发生变化,即使编译器的输入形态未变,也会在渲染输出中产生合理的差异——确定性输出的保证依然成立(相同的字节输入 → 相同的字节输出),只是由于本地文件改变,输入不同了。需要对每个来源都保持跨构建不变性的目录,会把制品从注册表拉取到由锁文件固定的缓存中,而不是从本地路径或工作区目录读取它们;锁文件是字节一致性的锚点。