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

可运行的示例

首先,入门会安装 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 运行它即可重新写出索引。