MappingLibrary
MappingLibrary 是一种目录实体,用于存放可复用的 Go 模板片段。共享整份 valuesMapping: 文档的 Recipes 和 FeatureRecipes(例如以同一 chart 为源的多个 Recipes 各自交给该 chart 的 values)只需在库中声明一次该文档,并在使用时通过 valuesMapping: { $import: ... } 指令引用它。该库实体属于第 3 层:供需要跨 Recipe 复用映射的目录选择启用。没有重复模板内容的目录无需包含任何 MappingLibrary。
MappingLibrary 的作用
平台架构师编写 MappingLibraries,用于集中管理在目录的 Recipes 和 FeatureRecipes 中反复出现的 Go 模板片段。库不是可部署的构建指令,而是一个定义命名空间。Recipe 和 FeatureRecipe 的作者通过 $import: 指令引用库条目:只需编写一次,凡是该导入能够解析之处都可使用。
“库”与“使用方”的划分是有意为之。Recipes 编码构建指令(source、valuesMapping、artifacts)。FeatureRecipes 编码行为附加。MappingLibraries 只编码模板片段,即其他实体在渲染时使用的 Go 模板内容。保持这三种角色相互独立,使每种实体类型都能按各自的节奏演进;不需要共享模板内容的作者永远不会接触到这种库实体。
实体信封
MappingLibrary 实体带有标准的目录信封。apiVersion: aggrega.ai/v1beta1 和 kind: MappingLibrary 标明实体种类;metadata.name 是一个 PascalCase 标识符;metadata.version 遵循严格的语义化版本。库的内容位于 spec.mappings 之下,这是一个必需的映射,必须至少声明一个条目。
apiVersion: aggrega.ai/v1beta1kind: MappingLibrarymetadata: name: BaseMappings version: 1.0.0spec: mappings: SimpleValues: 'image: {{ .values.image }}' Replicas: 'replicas: {{ optional .infra "replicas" 1 }}'条目由使用它的 Recipe 自身的模板引擎、依据该 Recipe 的渲染上下文求值,因此它读取的是 Recipe 自身的 valuesMapping: 所读取的小写支柱——.values、.infra、.context 等——并使用相同的函数,例如针对缺失键、能感知是否存在的 optional 辅助函数。.Values(Helm 对 chart values 的写法)不是该上下文所定义的根:读取它的条目会中止构建,并指出该引用。
编写映射条目
每个映射条目都是以 YAML 字符串形式编写的 Go 模板片段。该片段对实体信封而言是不透明的——编译器在加载 MappingLibrary 时原样存储该字符串,并在 Recipe 或 FeatureRecipe 通过 valuesMapping: { $import: ... } 导入该条目时,于使用阶段对其进行解析。导入会替换 Recipe 的整个 valuesMapping:——$import: 映射不携带其他任何键——因此一个条目是一份完整的 values 文档,而不是拼接进某份文档的一个片段。
较短的片段可以写在一行内:
spec: mappings: AppName: 'fullnameOverride: "{{ .context.rendered_name }}"'多行片段使用 YAML 的字面量风格标量(|),以便换行和缩进在往返过程中得以保留:
spec: mappings: ProbeBlock: | readinessProbe: httpGet: path: /healthz port: {{ .values.port }} livenessProbe: httpGet: path: /healthz port: {{ .values.port }}片段内可以使用 Go 模板的全部组合词汇:{{ define "name" }}...{{ end }} 在单个库内声明可复用的块;{{ template "name" . }} 调用这些块;管道和函数按照标准 Go text/template 包的规定提供支持。
单一编写模式
MappingLibrary 只提供一种编写模式:Go 模板。spec 不接受任何并行的编写界面,也没有库级别的表达能力逃生舱口。
原因在于使用界面的一致性。Recipes 和 FeatureRecipes 全部使用 Go 模板,它们自身的内容通过解析导入条目的同一个 Go 模板引擎求值,因此条目的读法与 Recipe 自身文本完全相同,作者只需学习一种求值模型。Go 模板的组合词汇——库内的 {{ define }} 和 {{ template }},以及使用时的 $import: 指令——提供了库所需的可复用块和参数化调用。
需要超出 Go 模板组合词汇所提供的表达能力的作者,应在更高层级进行组合——用 Components 或 Features 包装库条目,并加入它们自身的实质性变化——而不是在 MappingLibrary 内部升级到一种并行的编写语言。
命名约定
库名称和映射条目键遵循 PascalCase。实体信封的 JSON Schema 通过模式约束在两个位置强制执行该约定:
metadata.name匹配^[A-Z][A-Za-z0-9]*$。spec.mappings的映射键通过propertyNames匹配同一模式。
如果一个 MappingLibrary 在 spec.mappings 中含有非 PascalCase 的键,它会在工作区加载时无法通过信封校验。这一强制执行承担着实际作用:映射条目键出现在 #/mappings/<name> 引用片段中;非 PascalCase 的键会传播到每个导入该条目的使用方。
命名的统一使 #/mappings/<name> 片段易于阅读:#/mappings/ProbeBlock 一目了然。
引用库条目
Recipe 和 FeatureRecipe 的作者在 valuesMapping: { $import: ... } 块中通过映射条目的裸名称标识来引用它:
# Inside a Recipe's valuesMapping block:spec: valuesMapping: $import: "BaseMappings#/mappings/ProbeBlock"#/mappings/<name> 片段用于选择条目,并将映射引用与 SchemaLibrary 的 #/schemas/<name> 区分开来。该引用使用与 SchemaLibrary $ref: 相同的裸名称标识模型——<Library>#/mappings/<name>,不携带注册表主机。版本由每个 Release 的锁文件(名称 + 版本 + 内容摘要)提供;作者可以用 <Library>:<version>#/mappings/<name> 声明一个可选的最低版本下限(版本分隔符为 :,与 recipe/feature 映射及锁文件固定版本一致),物理位置则在解析时绑定。
跨库组合
MappingLibrary 条目可以是一个字段根 $import: 重定向:其主体的第一个标记是 $import: <Library>#/mappings/<entry>,它会用被引用条目的内容替换整个条目——这是按标识复用,而不是就地模板化。该重定向在使用时(Recipe 渲染时)解析,而不是在加载 MappingLibrary 时解析,并且是递归解析的——被导入的条目本身也可以是一个字段根 $import:。$import: 只作用于整个条目;它不是片段内部的模板函数。要在单个片段内部组合模板文本,请使用 Go 模板的 define / template。
# In library A — alias an entry to a shared entry in another library:spec: mappings: StandardProbe: | $import: MonitoringLibrary#/mappings/PrometheusAnnotations库之间可以自由地相互引用。回绕到自身的引用链会在使用它的 Recipe 渲染时中止,并给出指明循环中每一步的诊断。
层级定位
在实体层级文档模型中,MappingLibrary 属于第 3 层——供需要跨 Recipe 复用映射的目录按需选用。没有重复模板内容的目录无需包含任何 MappingLibrary 实体;层级标记表示“进阶内容;不需要时可跳过”,用于文档导航,而非表示能力。编译器对 MappingLibrary 的处理与其他目录实体类型一致:在加载工作区时执行相同的封装校验,在发布时使用相同的 OCI 发布流水线。
在目录层面,这一库类型与 SchemaLibrary 自然搭配——SchemaLibrary 存放可复用的 schema 定义;MappingLibrary 存放可复用的模板片段。两者都需要的目录就同时包含两者;两者都不需要的目录则都不包含。
MappingLibrary 不是什么
以下是几个值得提前澄清的常见误解:
-
不是内联
valuesMapping:的替代品。 大多数 Recipes 携带的是简单的valuesMapping:内容,适合以内联方式编写——这样 Recipe 保持自包含,作者可以在阅读 Recipe 其余部分的同时阅读映射内容。当同一个片段出现在许多 Recipes 中时,MappingLibrary 才有帮助;对于一次性的映射,内联编写才是正确的选择。 -
不是存放 schema 内容的地方。 Schema 定义(JSON Schema 2020-12)属于 SchemaLibrary;模板片段属于这里。各库类型按内容类型划分,而不是按复用模式划分。
-
不提供超出 Go 模板机制的参数化复用。 需要参数化变化的作者可以在库条目中使用 Go 模板的
{{ define }}+{{ template arg }}机制,或者组合 Components / Features,用它们自身的变化来包装库条目。该库实体本身不提供任何参数化辅助机制(没有类似于 SchemaLibrary 的spec.templates参数化辅助功能的templates块);Go 模板的组合词汇已覆盖相同的用例。