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

编写 provider:完整演练

本页完整演示编写一个 provider guest 的全过程,从一个空目录开始,直到构建写出由该 provider 渲染的文件。它是插件开发者指南的实践配套,该指南记录实体与生命周期;它也是插件契约的实践配套,该契约记录各个 socket。

这里构建的 provider 足够小,一次就能读完,同时又做实际的工作:它渲染环境文件。这个目标很适合作为第一个 provider,因为它的转换确实与格式相关——环境文件有自己的键语法、自己的引号规则,也没有可以存放构建来源信息的元数据块——因此 guest 必须做出大型 provider 要做的每一个决定,而又没有大量代码将这些决定掩盖起来。

**关于本页中的代码块。**每个显示输出的代码块都复制自按下文步骤顺序实际运行的结果,并遵循输出约定:一个代码块要么是完整的,要么是标明了省略行位置的摘录。这是一个需要你自己动手组装的演练,而不是一个可以克隆的工作区,因此源代码块是需要你创建的文件,而不是需要检出的文件。

你需要准备的内容

  • Go 工具链,它无需额外工具即可编译为 WebAssembly。
  • 插件开发套件的一份检出副本(插件开发者指南对其有介绍),以及该套件所基于的 ABI 包的检出副本:下面 guest 的 go.mod 指向这两者。
  • aggrega 二进制文件。

成品的形态

一个 provider 由两个制品组成:一个 .wasm guest,以及一个把它带入目录的 Plugin 实体。除此之外别无他物——无需修改宿主,无需注册,也无需重新构建编译器。添加一个 provider,就是把这两个文件放到构建能看到的位置。

本演练最终得到的工作区:

dotenv-walkthrough/
guest/ the Go module that compiles to the .wasm
go.mod
go.sum
main.go
catalog/ the Component and Recipe you author
component/example/compute/checkout/1.0.0/component.yaml
recipe/dotenv/checkout/1.0.0/recipe.yaml
dev-catalog/ the generated Plugin entity, with the .wasm beside it
plugin/provider/dotenv/0.1.0/plugin.yaml
plugin/provider/dotenv/0.1.0/provider--dotenv.wasm
dotenv.wasm the compiled guest
overlay.yaml the identity you supply to the entity generator
aggregate.yaml
manifest.yaml
release.yaml
.aggrega-config.yaml

1. guest 的自我报告

每个插件都导出 describe()。宿主在加载 guest 时调用它一次,并把返回结果视为 guest 对自身是什么的说明。对于 provider,该结果中有四个部分很重要。

创建 guest/main.go:

// A provider guest that renders environment-file artifacts.
package main
import (
"bytes"
"fmt"
"sort"
"strings"
pdk "github.com/extism/go-pdk"
"github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega"
)
func descriptor() aggrega.PluginDescriptor {
return aggrega.PluginDescriptor{
AbiVersion: aggrega.APIVersion,
PluginType: "provider",
Description: "Render artifact bodies into environment files, quoting and escaping each value as the format requires.",
Capabilities: []string{"dotenv"},
Exports: []aggrega.PluginExport{
{Name: "render_node"},
},
Metadata: &aggrega.PluginDescriptorMeta{License: "Apache-2.0"},
}
}
//go:wasmexport describe
func describe() int32 {
out, err := aggrega.MarshalDescriptor(descriptor())
if err != nil {
pdk.SetError(err)
return 1
}
pdk.Output(out)
return 0
}

PluginType 说明该 guest 服务于哪个插槽。Capabilities 是 Recipe 据以解析的列表:spec.capability 为 dotenv 的 Recipe 将被 路由到该 guest。Exports 列出宿主可以分派到的入口点;render_node 是每个 provider 都必须具备的入口点。

这个描述符是有意不完整的,就像初稿通常 那样。下面的第一次构建会暴露这一点。

2. 渲染节点

构建通过此 provider 渲染的每个 component 都会调用一次 render_node。它接收节点的身份标识、渲染上下文,以及所绑定的 Recipe 声明的预先求值的输入——此处是一个 artifact 集合,宿主已读取它并将其作为模板求值。

guest 的全部工作就是决定输出哪些字节。在 guest/main.go 中添加:

// needsQuoting reports whether a value cannot be written bare in an
// environment file. A bare value ends at the first space, so anything
// carrying whitespace has to be quoted; the quote characters, the comment
// introducer and the expansion introducer would each be read as syntax.
func needsQuoting(v string) bool {
if v == "" {
return true
}
return strings.ContainsAny(v, " \t\n\r\"'#$\\")
}
// quote wraps a value in double quotes and escapes what the format reads as
// syntax inside them. Order matters: the backslash is escaped first, or the
// escapes introduced afterwards would be escaped a second time.
func quote(v string) string {
v = strings.ReplaceAll(v, `\`, `\\`)
v = strings.ReplaceAll(v, `"`, `\"`)
v = strings.ReplaceAll(v, "\n", `\n`)
v = strings.ReplaceAll(v, "\r", `\r`)
v = strings.ReplaceAll(v, "\t", `\t`)
return `"` + v + `"`
}
// normaliseKey maps an authored key into the environment-variable grammar:
// upper case, with the separators an author reaches for folded to
// underscores. It reports an error rather than correcting a key that still
// does not fit, because a silently-renamed variable is one the application
// never reads.
func normaliseKey(k string) (string, error) {
n := strings.ToUpper(k)
n = strings.NewReplacer("-", "_", ".", "_", "/", "_").Replace(n)
if n == "" {
return "", fmt.Errorf("empty key")
}
for i, r := range n {
switch {
case r >= 'A' && r <= 'Z', r == '_':
case r >= '0' && r <= '9' && i > 0:
default:
return "", fmt.Errorf("key %q maps to %q, which is not a valid environment-variable name", k, n)
}
}
return n, nil
}

该片段中的三个决定属于 provider 自身,其他任何层都无法做出。哪些字符需要强制加引号,是环境文件本身的事实。变量名语法也是如此;对于不符合语法的键选择拒绝而不是重命名,同样如此——被重命名的变量是应用程序会去查找却找不到的变量,这比构建中止更糟。

接下来是剩下的两部分:来源信息放在哪里,以及导出函数本身。

// provenanceComment renders the build-provenance key set the host computed as
// comment lines. An environment file has no metadata block, so a comment
// header is where provenance can go; the keys are emitted in sorted order so
// the bytes are identical across runs of identical input.
func provenanceComment(annotations map[string]string) []byte {
if len(annotations) == 0 {
return nil
}
keys := make([]string, 0, len(annotations))
for k := range annotations {
keys = append(keys, k)
}
sort.Strings(keys)
var out bytes.Buffer
for _, k := range keys {
fmt.Fprintf(&out, "# %s=%s\n", k, annotations[k])
}
out.WriteByte('\n')
return out.Bytes()
}
// renderBody translates one artifact body into environment-file lines. A
// blank line and a comment pass through untouched; every other line is
// KEY=value, and a line carrying no separator is a loud failure rather than a
// line the guest guesses at.
func renderBody(name string, body []byte) ([]byte, error) {
var out bytes.Buffer
for i, raw := range strings.Split(string(body), "\n") {
line := strings.TrimSpace(raw)
if line == "" || strings.HasPrefix(line, "#") {
continue
}
k, v, found := strings.Cut(line, "=")
if !found {
return nil, fmt.Errorf("%s line %d: %q declares no value; an entry is KEY=value", name, i+1, line)
}
key, err := normaliseKey(strings.TrimSpace(k))
if err != nil {
return nil, fmt.Errorf("%s line %d: %w", name, i+1, err)
}
val := strings.TrimSpace(v)
if needsQuoting(val) {
val = quote(val)
}
fmt.Fprintf(&out, "%s=%s\n", key, val)
}
return out.Bytes(), nil
}
//go:wasmexport render_node
func render_node() int32 {
var in aggrega.RenderNodeInput
if err := in.DecodeCBOR(pdk.Input()); err != nil {
pdk.SetError(fmt.Errorf("dotenv: decode RenderNodeInput: %w", err))
return 1
}
if in.ArtifactsProjection == nil || len(in.ArtifactsProjection.Entries) == 0 {
pdk.SetError(fmt.Errorf("dotenv: node %q supplied no artifacts to render", in.Node.ID))
return 1
}
var files []aggrega.RenderedFile
for _, e := range in.ArtifactsProjection.Entries {
body, err := renderBody(e.Name, e.Content)
if err != nil {
pdk.SetError(fmt.Errorf("dotenv: %w", err))
return 1
}
files = append(files, aggrega.RenderedFile{
Path: e.Name,
Content: append(provenanceComment(e.Annotations), body...),
Format: "text",
})
}
outputBytes, err := aggrega.RenderNodeOutput{Files: files}.EncodeCBOR()
if err != nil {
pdk.SetError(fmt.Errorf("dotenv: encode RenderNodeOutput: %w", err))
return 1
}
pdk.Output(outputBytes)
return 0
}
func main() {}

载荷以二进制编码传递,由 kit 负责读写。 宿主以规范 CBOR 形式将输入交给 render_node,并以相同编码读取应答,因此 guest 使用输入类型的 DecodeCBOR 解码,使用输出类型的 EncodeCBOR 编码——无需 CBOR 库,也无需手动解析。文件的 Content 是一个字节切片,guest 在其中填入要写入的确切字节;编码器将其作为原始字节传递,宿主原样写入。

宿主交给 guest 的是已求值的内容。 每个 artifact 条目的 Content 是编写的正文,其中的模板表达式已根据渲染上下文解析——guest 从不求值模板,也从不读取文件。正是这一点保持了编译器 ahead-of-time 边界的完整:guest 是从载荷到字节的纯函数。

确定性由 guest 负责。 在普通构建中,没有任何机制替你检查它。此处的确定性来自在输出前对来源信息的键进行排序,以及按载荷携带的顺序遍历 artifact 条目;本页末尾的检查会衡量其结果。

guest/go.mod 引用你本地检出的 kit:

module example.com/dotenv-provider
go 1.26.0
require (
github.com/aggrega-ai/aggrega-pdk/go v0.0.0
github.com/extism/go-pdk v1.1.3
)
require github.com/aggrega-ai/aggrega-abi/go v0.0.0 // indirect
replace github.com/aggrega-ai/aggrega-pdk/go => /path/to/aggrega-pdk/go
replace github.com/aggrega-ai/aggrega-abi/go => /path/to/aggrega-abi/go

3. 构建 guest

guest 就是一次选择了 WebAssembly 目标的普通 Go 构建:

Terminal window
cd guest
go mod tidy
GOWORK=off GOOS=wasip1 GOARCH=wasm go build -trimpath -buildvcs=false \
-ldflags "-X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Version=0.1.0 \
-X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Commit=walkthru" \
-buildmode=c-shared -o ../dotenv.wasm ./

go mod tidy 写入 go.sum,即依赖项的校验和,缺少它构建将拒绝运行。-trimpath 和 -buildvcs=false 让构建路径和版本控制标记不进入二进制文件,因此同一提交下的相同源码会产生相同的字节。两个 -ldflags 值把 guest 自身的版本写入其中,下一步会读取它。

继续之前,先确认导出项:

Terminal window
aggrega inspect --plugin dotenv.wasm
Plugin .wasm: dotenv.wasm
Exports:
render_node
hostFunctions (derived from binary, not yet recorded by aggrega plugin sync): (none)

这个 guest 不导入任何宿主函数,这是最小权限的默认做法:它既不需要文件系统,也不需要网络,因为它渲染的一切内容都随 payload 一起到达。

4. 生成 Plugin 实体

实体的契约字段不是手写的——它们从 guest 中读取,因此实体不可能承诺二进制文件没有做到的事情。你只需在一个小型 overlay 中提供身份信息。

overlay.yaml:

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: dotenv
Terminal window
aggrega plugin gen-catalog --plugin dotenv.wasm \
--overlay overlay.yaml --output-dir dev-catalog/plugin
generated dev-catalog/plugin/provider/dotenv/0.1.0/plugin.yaml

生成的实体:

# Generated from the plugin by `aggrega plugin gen-catalog`. You may narrow its capability lists; edit nothing else here.
apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: dotenv
version: 0.1.0
pluginType: provider
description: Render artifact bodies into environment files, quoting and escaping each value as the format requires.
spec:
abiVersion: v1beta1
exports:
- name: render_node
provider:
capabilities:
- dotenv

注意其中没有什么:任何指向 .wasm 的指针。插件的位置由其身份推导而来——即 pluginType/name 坐标加上所配置的注册表——因此没有需要编写的位置字段,也就不会写错。内容摘要在解析 Release 时记录在该 Release 的锁文件中,而不是记录在实体中。

5. 把 guest 放到构建会查找的位置

在开发 guest 期间,还没有已发布的内容可供获取,因此构建从一个目录目录中读取它:即紧挨着其实体放置、以 socket 和插件命名的 .wasm。

dev-catalog/plugin/provider/dotenv/0.1.0/plugin.yaml
dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasm
Terminal window
cp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasm

文件名同时包含 socket 和名称,是因为单独的插件名称只在其自身的 socket 内唯一——位于不同 socket、都叫 dotenv 的两个插件必须指向两个文件。

把构建好的文件复制到那里,而不是链接到它。该位置上的链接只有指向工作区内部某处时才会被跟随——或者,对于列在工作区之外的目录目录,只有指向该目录内部某处时才会被跟随;指向更外部位置的链接会使构建和拉取停止,并指出该链接,如工作区边界所述。

目录中的 provider 插件实体从不固定版本,pull 和 build 都不会获取它的 .wasm,因此在解析 Release 时该文件必须已经存在。pull 在写入 lockfile 之前会进行检查:如果它既没有在实体旁边、也没有在 build 读取插件的任何其他位置找到 .wasm,就会停止,并指出它所期望的文件和目录,如 A plugin’s .wasm is not on this machine(插件的 Wasm 文件不在本机上) 所述。

在 .aggrega-config.yaml 中让工作区指向这两个目录目录:

workspace:
catalog_dirs:
- catalog
- dev-catalog
auto_pull: true

auto_pull 让 aggrega build 在进程内解析 Release,因此首次构建不需要单独的解析步骤。

6. 以该 provider 为目标的文档

共四个文件。Component 声明作者可以设置什么;Recipe 绑定能力并编写制品;Aggregate 陈述意图;Release 对其进行放置。

catalog/component/example/compute/checkout/1.0.0/component.yaml:

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: example/compute/checkout
version: 1.0.0
description: An application whose configuration is delivered as an environment file.
labels:
component.aggrega.ai/type: server
component.aggrega.ai/category: compute
spec:
schema:
values:
service_name:
type: string
default: checkout
description: The name the application reports itself under.
log_level:
type: string
default: info
description: The application's log verbosity.
greeting:
type: string
default: hello
description: A value carrying characters the environment-file format must quote.
infra:
endpoint:
type: string
default: http://localhost:8080
description: The endpoint the operator points the application at.

catalog/recipe/dotenv/checkout/1.0.0/recipe.yaml:

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: checkout
version: 1.0.0
description: Renders the application's configuration as an environment file.
spec:
capability: dotenv
implements: example/compute/checkout:1.0.0
artifacts:
app.env: |
service-name = {{ .values.service_name }}
log.level = {{ .values.log_level }}
greeting = {{ .values.greeting }}
endpoint = {{ .infra.endpoint }}

spec.capability: dotenv 就是全部绑定。它指定的是一项能力,而不是一个插件:构建会将其解析为声明了该能力的那个 provider 插件。如果恰好只有一个插件声明了它(如本例),就不需要其他任何配置。

这里编写的键有意没有采用环境变量的形式。service-name 和 log.level 是作者自然会写出的拼写,对它们进行规范化是 provider 的工作。

aggregate.yaml:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: aggregate
version: "1.0.0"
description: One application whose configuration is an environment file.
spec:
components:
app:
type: example/compute/checkout
values:
service_name: checkout
log_level: debug
greeting: hello world

manifest.yaml:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: manifest
version: "1.0.0"
description: Binds the component type to the environment-file recipe.
spec:
mappings:
components:
type:
example/compute/checkout:1.0.0: checkout:1.0.0

release.yaml:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: walkthrough
environment: production
version: "1.0.0"
spec:
aggregate: aggregate
manifest: manifest
boundaries:
infra:
directory: infra
components:
app:
infra:
endpoint: "https://checkout.example.net"

7. 第一次构建,以及它拒绝了什么

Terminal window
aggrega build --release release.yaml --auto-pull
warning: plugin "provider/dotenv" resolved from local with no recorded digest to check it against, so it runs unverified; it is read from beside its Plugin entity in a catalog directory on every build, and a pull records its digest only for a plugin attached at a transform role; otherwise publish the plugin and reference the published entity to have its digest recorded
[… omitted: the notice saying the Release could not be rendered to discover its external inputs, carrying the error below beneath its first line]
Pull complete: release.lock (entities=5, source_artifacts=0, external_inputs=0)
[… omitted: a line saying again that external inputs were not fully discovered]
[CATALOG_ERROR E0265] instance app
provider does not support the node's input kind (node "app"). provider "dotenv" does not support artifacts-only recipes (this provider supports: none); declare one of the supported input kinds, or target a provider that supports artifacts-only

请分别阅读这两行,因为它们说的是不同的事情。

开发期间出现这条警告是预期之中的,而且它不会消失。 它表示该 guest 在运行时没有可供校验的已记录内容摘要,这正是一分钟前刚构建的 guest 的实际情况:没有任何东西发布过它,因此没有记录在案的摘要。它还说明了为什么重新解析该 Release 不会改变这一点——从 catalog 目录中其实体旁边读取的 guest 会被每次构建重新读取,而拉取操作只会为挂接在 transform 角色上的治理插件记录摘要,而这个 guest 不是这样的插件——以及什么才能改变这一点:发布该插件并引用已发布的实体。应将这条警告理解为构建正确地拒绝声称自己执行了并未执行的校验;只要 guest 仍在本地,就会一直看到它。

错误才是真正的发现,括号里的内容就是诊断。 该 provider 已被找到、加载,并被询问它渲染什么,而它回答了 none——this provider supports: none。开头编写的描述符指明了 socket、capability 和导出项,但从未说明该 guest 处理三种 Recipe 输入类型中的哪几种。宿主不会猜测:输入类型关卡读取 guest 声明的集合,并拒绝该 guest 从未声明的节点。

这就是大多数首个 provider 失败的样子。guest 本身没有问题;问题在于它的自我报告不完整。describe() 不是宿主容忍的一项形式——它是一个与格式无关的宿主决定将什么发送到哪里的全部依据。

8. 声明渲染行为契约

在 guest/main.go 的描述符中加入该契约:

Capabilities: []string{"dotenv"},
Contract: &aggrega.ProviderContract{
InputKinds: aggrega.InputKinds{
Sourced: false,
Synthesized: false,
ArtifactsStandalone: true,
},
BoundaryAssembly: "none",
},
Exports: []aggrega.PluginExport{

ArtifactsStandalone: true 正是关卡在寻找的声明。两个 false 值同样是声明,而明确写出它们正是关键所在:一个内嵌源码树的 Recipe,或一个声明了 workload 的 Recipe,现在会在任何渲染运行之前就被拒绝,并给出指明该 provider 的消息——而不是进入 render_node 后在其内部某处失败。

BoundaryAssembly: "none" 表示每个节点的输出都写到其落点,没有需要合并的内容。将多个 component 合并为一个文档的 provider 则声明 merge 或 nest,并导出 assemble_boundary 来完成合并。这是该 provider 接下来自然要添加的功能,其说明见插件契约。

重新构建 guest,重新生成实体,并将新的 .wasm 放回实体旁边:

Terminal window
cd guest
GOWORK=off GOOS=wasip1 GOARCH=wasm go build -trimpath -buildvcs=false \
-ldflags "-X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Version=0.1.0 \
-X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Commit=walkthru" \
-buildmode=c-shared -o ../dotenv.wasm ./
cd ..
aggrega plugin gen-catalog --plugin dotenv.wasm \
--overlay overlay.yaml --output-dir dev-catalog/plugin
cp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasm

重新生成的实体现在带有从二进制文件中读取的契约:

[… omitted: the header comments and the metadata block, unchanged from the first generation]
spec:
abiVersion: v1beta1
exports:
- name: render_node
provider:
capabilities:
- dotenv
contract:
inputKinds:
artifactsStandalone: true
boundaryAssembly: none

**每次重新构建 guest 后重新生成实体,是开发循环的一部分。**实体重述二进制文件所报告的内容,二者会在 guest 加载时交叉校验:实体声称而二进制文件未报告的导出或契约值是一种不匹配,构建会因此中止并指出该声明。实体省略的声明不受检查,因此在一次向二进制文件添加了内容的重新构建(如本步骤)之后遗留的实体仍能加载,只是不再描述该二进制文件。

9. 完成渲染的构建

Terminal window
aggrega build --release release.yaml --auto-pull
warning: plugin "provider/dotenv" resolved from local with no recorded digest to check it against, so it runs unverified; it is read from beside its Plugin entity in a catalog directory on every build, and a pull records its digest only for a plugin attached at a transform role; otherwise publish the plugin and reference the published entity to have its digest recorded
Pull complete: release.lock (entities=5, source_artifacts=0, external_inputs=0)
[… omitted: a line reporting total build time, which differs on every run]
Build completed: 1 file written to <workspace>/dist

最后一行给出输出目录的完整路径,其中 <workspace> 表示 工作区根目录。其下渲染出的目录树:

dist/infra/dotenv/app/app.env

以及该 provider 写出的文件全文:

1.0.0
# aggrega.ai/boundary-path=infra
SERVICE_NAME=checkout
LOG_LEVEL=debug
GREETING="hello world"
ENDPOINT=https://checkout.example.net

guest 所做的每一个决定都体现在这七行中。

  • service-name 和 log.level 按编写时的样子传入,输出为 SERVICE_NAME 和 LOG_LEVEL。作者从不需要编写目标格式的 语法。
  • GREETING 加了引号,其他三个没有。hello world 含有一个 空格,不加引号的话会在 hello 处截断;endpoint 不含任何 该格式视为语法的字符,加引号只会增加噪音。
  • 两个来源键是注释,因为环境文件没有 其他地方可以放置它们。若 provider 的输出有元数据块,则会把 同样的键放在那里。键由宿主计算;放置位置由 guest 决定。
  • 这些值来自两位不同的作者。service_name、log_level 和 greeting 是开发者意图,来自 Aggregate。endpoint 属于 运维人员,来自 Release。guest 看不到这两者的区别——它收到的 是一个已求值的主体。

10. 信任它之前值得检查的两件事

它是确定性的。 捕获输出,重新构建,然后比较:

Terminal window
cp -r dist ../capture && rm -rf dist
aggrega build --release release.yaml
diff -r ../capture dist

diff 不输出任何内容,就是你想要的结果。确定性是 guest 的 契约,而不是 host 的;一个在其输出路径中某处遍历 Go map 的 guest, 在单次构建中看起来完全正确,却无法通过这项检查。

它的拒绝是明确报出的。 破坏该 Recipe 的 artifact 中的一行,使其 不声明任何值:

artifacts:
app.env: |
service-name = {{ .values.service_name }}
this line declares no value
[… omitted: the unverified-plugin warning, and the pull's lines saying the Release could not be rendered to discover its external inputs]
[CATALOG_ERROR] instance app
rendering node "app"
caused by: wasm: plugin "provider/dotenv:0.1.0" call to render_node: dotenv: app.env line 2: "this line declares no value" declares no value; an entry is KEY=value

guest 自己的消息会完整地传达给作者,并附带它所来自的文件和行。 值得有意检查这一点,因为另一种失败方式——guest 悄悄跳过一行无法解析的内容——会产生一次 成功的构建和一个缺少变量的部署,而输出中没有任何内容 指出这一点。

11. 接下来可以添加什么

这里构建的 provider 是完整的,但只是最小实现。以下内容大致按需求频率排序:

  • assemble_boundary,用于将多个 component 的输出合并为一个 文档,通过 BoundaryAssembly 声明。

  • validate_node_input,用于在任何渲染运行之前对节点的输入进行结构检查, 使格式错误的输入在编写边界处报告, 而不是在渲染中途报告。

  • 渲染事实(Render facts),用于报告 guest 所写内容中只有 该 provider 对环境文件格式的了解才能看到的信息——在这里是 每个文件定义的变量名。一个事实由一个名称和一个列表组成,二者都是该 provider 自己的词汇,与文件一并返回——其值 始终是一个 JSON 数组,即使只有一项也是如此,否则构建会中止:

    // names lists the variables the files define, in the order they were written.
    value, err := json.Marshal(names)
    if err != nil {
    pdk.SetError(fmt.Errorf("dotenv: marshal render fact: %w", err))
    return 1
    }
    out := aggrega.RenderNodeOutput{
    Files: files,
    RenderFacts: []aggrega.RenderFact{{Name: "variable_names", Value: value}},
    }

    编译器按 guest 列出事实的顺序保存它们,只检查 每个值是否为列表,将这些列表交给读取它们的 Feature 模板, 并且无论是否报告事实,写出的文件都相同。请将每个事实的名称及其条目所含内容作为 provider 契约的一部分记录在文档中。

  • 省略条目(Omit entries),在 provider 渲染源之后适用。源渲染的 输入可以在其 SourceListing 旁携带 Omits,即指定要省略的渲染单元的条目; 支持它们的 provider 会从返回结果中省略每个匹配的单元, 在 Omitted 中为每个条目报告一个计数,并且 在其契约中声明 Omits: true。它们从不伴随 像本 provider 这样仅含 artifact 的渲染,因此只有在它 渲染带源的输入之后才会遇到它们。插件契约中的省略渲染单元 给出了完整结构。

  • 发布,将本地的 dev-catalog 布置转换为 一个经摘要固定、由 Release 解析并验证的 artifact。 插件开发者指南在发布、拉取和构建阶段下 介绍了这一生命周期。

每个 socket 的载荷和结果结构见 插件契约。