可运行的示例
首先,入门会安装 Aggrega,并一步一步地带你走完其中两个示例。
完整、可 fork 的工作区,可用 aggrega CLI 编译。每个都是一个自包含的目录——一个由 Developer 编写的 Aggregate,以及一对或多对 Release/Manifest——除其页面所列内容外无需任何设置即可构建。要按部署的产品或展示的内容查找示例,请使用按产品和能力分类的示例,其中列出了这里的每个示例。
示例分为两种模式——同一套课程的两端:
-
使用——工作区引用标准库目录实体, 只在本地编写其自身用于教学的内容。构建时无需
--catalog标志:Terminal window aggrega build --release release.yaml这些被引用的实体从何处读取取决于工作区。工作区根目录下的
catalog/目录无论是否被指定都会被读取,因此自行编写教学内容的工作区只需将其放在那里即可。带有.aggrega-config.yaml的工作区还会读取catalog_dirs下列出的每个目录,每一个都是它存放实体的目录。列出的目录先被搜索,catalog/最后,且该栈采用先匹配者胜出,因此较早搜索的目录中的实体会遮蔽较晚目录中同一标识的实体。任何本地目录都未声明的内容——即标准库实体——从配置以default_registry指定的注册表hub.aggrega.ai解析。不在本地编写任何内容的工作区无需本地条目;既没有catalog/目录也没有.aggrega-config.yaml的工作区完全通过已配置的注册表解析。将catalog_dirs写为空列表表示该工作区完全没有本地目录。catalog_dirs中的每个路径都指向工作区内的目录,因此将整个工作区复制到别处后即可原样构建。为每个目标分别保留一个目录的多目标工作区,会在
workspace.releases下列出每个目标的各个目录,以其 Release 文件为键,使每个 Release 都基于自己的目录构建。 -
编写——工作区在本地
catalog-*/目录中从零构建目录实体(Components、 Features、Recipes)。mariadb-adminer是完整的编写示例;它构建的实体 与使用类示例所使用的实体属于同一类。
使用 aggrega build --release <release file> 每次运行构建一个 release;每个示例的页面都给出了它自己的命令。工作区按上文所述提供其目录;对于工作区未指明的目录所在位置,请自行传入 --catalog,需要这样做的页面都有说明。
锁文件是生成的而非随附的,因此新克隆的仓库中没有锁文件,首次构建需要一个。aggrega build 默认是只读的:没有锁文件时它会停止并给出两种解决办法。首次构建时传入 --auto-pull——aggrega build --release release.yaml --auto-pull——以在构建期间解析锁文件;事先运行一次 aggrega pull --release <release file> 效果相同,且之后的每次构建都无需任何标志。
在文档仓库的检出中,大多数工作区还带有一个 build-release.sh 辅助脚本,仓库自身的检查通过它进行构建。它为一个 release 运行 aggrega build,先回显该命令,并报告它使用了哪个 aggrega 二进制文件以及该文件的来源;设置 AGGREGA_BIN 即可选择二进制文件。由 aggrega scaffold --example 写出的副本带有该辅助脚本,但没有它所调用的共享脚本,因此请直接用 aggrega build 构建这样的副本。
如果这里的某个示例提到标准库目录的检出,导入说明了从哪里获取。
这些示例是对示例概览中所述概念页面的补充:概念页面讲解一个概念并链接到展示它的工作区;此处的工作区则是可构建、阅读和改编的完整技术栈。
页面中打印构建产物的代码块均复制自真实运行, 便于你将自己的输出与之比对——省略的行都会 加以标记。阅读这些页面上的输出说明了该 约定及其所用的标记。
此处并非每个目录都是一个工作区。快速入门示例每个步骤一个工作区,导入示例则每个导入阶段一个工作区,如下一段所述。有一个目录根本不包含工作区:policy-in-ci 包含两个规则脚本,它们读取构建的输出目录,并在其违反规则时予以拒绝,每个脚本都附有相应的流水线步骤。它们可用于此处各工作区的输出,也可用于你的输出。
每个 import-* 示例——列在按产品和能力分类的示例中的 import 能力之下——都按 aggrega import 所接收的样子,保存一个以另一种格式编写的项目,分为两个文件夹:source/,即该项目、使其成为工作区的 .aggrega-config.yaml,以及导入从中读取任何源文件都无法包含的值的应答文件;以及 draft/,即导入写出的文件(未经修改),它是一个按原样即可构建的工作区,另有导入在标准输出(stdout.txt)和标准错误(import.txt)上打印的内容。它在导入下的演练讲解了每个阶段。它的 check.sh 会运行本仓库共享的 scripts/check-import-example.sh,该脚本会再次导入,将其写出和打印的内容与 draft/ 进行比较,将演练引用的代码块与示例的文件进行比较,然后校验并构建所起草的 Release。
教学顺序
此处的每个示例在唯一的教学顺序中都有一个位置,由其头部中的 tier 和 position 给出:按层级逐一排列,层级的顺序与层级列表给出的顺序一致,每个层级内由简到繁。按教学顺序以这种方式列出每个示例,侧边栏的示例部分也遵循相同的顺序。你可以从上到下阅读各个层级,也可以直接跳到与你正在做的事情相符的层级;如果想改为按示例部署的内容或展示的内容查找示例,同一页面还按产品和按能力列出了它们。
构建还可以对其渲染的内容运行插件——参见何时使用流水线步骤。
每个示例的头部
每个示例的 README 都以一个简短的头部开头,以 YAML front matter 编写,说明该示例是什么:它的级别、它在教学顺序中的位置、它部署的产品以及它展示的内容。按产品和能力分类的示例就是根据这些头部生成的。
---example: level: start tier: catalog-only position: 1 products: [core/datastore/mariadb, core/devtool/adminer] shows: [connections, credentials]---level 是以下级别之一:
start——“仅目录”级别:由目录实体组装而成,除 Aggregate、Manifest 和 Release 外不编写任何内容。authoring——“编写”级别:编写一个 Component、一个 Feature 或一个 Recipe,或展示其结构。advanced——“进阶”级别:边界、治理策略、由注解驱动的 Features 以及组装的云栈。
tier 是示例所属的教学顺序部分,取以下阶段之一,各阶段按此顺序讲授:
start-here— 从这里开始:“入门”指南一步步扩展的两个示例,然后是两个面向云的入门示例。catalog-only— 仅使用目录:由目录实体组装而成,除 Aggregate、Manifest 和 Release 之外不编写任何内容。authoring— 编写:编写自己的 Component、Feature 或 Recipe,或展示其结构。advanced— 进阶:边界、治理策略、由注解驱动的 Features 以及组装好的云栈,其中若干项组合在一次构建中。importers— 导入器:用另一种格式编写的项目,由aggrega import起草为 Aggrega 文件,然后经审阅并构建。
position 是示例在其阶段内的位置,一个该阶段其他示例都不占用的正整数;一个阶段按位置从低到高列出其示例,最简单的在前。
products 按目录条目所带的名称列出示例部署的每个目录 Component。通用计算组件(例如 core/compute/server)以及示例为自身声明的实体不会被列出,因此一个示例可以一个都不列。
shows 列出示例所演示的内容,每个条目都取自以下列表:
multi-target——一个 Aggregate 为两个或更多目标构建,或以两种或更多方式实现。recipe-selection——Manifest 选择由哪个 Recipe 实现组件,或由哪个 FeatureRecipe 实现附加项:按类型、按实例或按目标。modules——作为模块导入的目录 Aggregate。connections——通过uses插口连接的组件,值沿每条边传递。credentials——凭据附加项以及每个目标如何交付它们。parameters——提升为参数、由 Release 填充的值。features——为凭据以外的用途附加的 Features,例如路由、监控、预算、缓存或脱敏。boundaries——放置在边界中的组件或模块,以及跨越边界的内容。policy——在构建期间或针对其输出接受或拒绝构建的治理策略。guardrails——一个预期会停止的 Release,以及它停止时给出的消息。catalog-authoring——为该示例编写的 Component、Feature 或 Recipe,放在示例旁边或发布到目录中。cloud-infrastructure——针对托管云服务的 Terraform 或 CloudFormation 输出。external-sources——一个获取其渲染内容的 Recipe:上游 chart、git 仓库或模块。import— 以其他格式编写的项目,由aggrega import起草为 Aggrega 文件,然后经审阅并构建。
每个示例至少列出一个产品或一项能力,以便索引能够放置它。它的 README 还包含一个 ## Scaffold the example 章节,其第一个命令块中是 aggrega scaffold --example <name>,第二个命令块中是 cd <name>,紧接着是一个 ## Build 章节,其第一个命令块就是 aggrega scaffold --example 打印出的、在那条 cd 之后要运行的内容。从本仓库根目录运行的 scripts/gen-examples-index.sh --check 会根据这些列表检查每个头部,拒绝缺少其中任一章节的示例,以及既没有可执行的 check.sh 也没有 build-release.sh 的示例,并确认索引是最新的;不带 --check 运行它即可重新写出索引。