Fn 函数环境变量配置实战:用 func.yaml 声明必选与可选变量(Go 示例)
Fn 函数环境变量配置实战:用 func.yaml 声明必选与可选变量(Go 示例)
本教程围绕 Fn 开源无服务器平台中 func.yaml 的 expects.config 配置机制展开,通过 examples/inputs 目录下的 Go 函数示例,完整演示如何在本地与云端声明、注入必选(required)与可选环境变量,以及缺失时 Fn 的校验行为。读完本文,你将掌握 fn run 的本地调试流程、-e 传参方式、expects 配置写法,并能在自己的函数中复现这套"配置即契约"的开发模式。
场景速览:3 分钟跑通一个带输入的 Go 函数
examples/inputs 是 Fn 官方教程的第一课,主题只有一个:通过 func.yaml 中的 expects 段声明函数运行所需的环境变量,并区分必选与可选。整个示例包含四个文件:
- func.go:函数本体,读取 stdin 输入并回显两个环境变量的值
- func.yaml:函数声明文件,定义运行时、入口与期望的环境变量
- sample.payload.json:用于管道输入的样例 JSON
- test.json:函数测试用例定义
- README.md:本教程的操作说明
其中 func.go 的核心逻辑如下(已省略部分导入):
type person struct {
Name string
}
func main() {
p := &person{Name: "World"}
json.NewDecoder(os.Stdin).Decode(p)
mapD := map[string]string{"message": fmt.Sprintf("Hello %s", p.Name)}
mapD["SECRET_1"] = os.Getenv("SECRET_1")
mapD["SECRET_2"] = os.Getenv("SECRET_2")
mapB, _ := json.Marshal(mapD)
fmt.Println(string(mapB))
}
函数从标准输入读取 JSON,反序列化到 person 结构体(缺省时 Name 为 "World"),然后把 SECRET_1、SECRET_2 两个环境变量的值连同问候语一起以 JSON 输出。这是 Fn 函数标准的"stdin 进、stdout 出"模型——教程示例中明确指出输入经 stdin 进入(json.NewDecoder(os.Stdin).Decode(p)),输出写到 stdout,stderr 则进入服务器日志。
第一步:直接运行会怎样?必选变量的强制校验
在 examples/inputs 目录下直接执行:
fn run
会得到:
ERROR: required env var SECRET_1 not found, please set either set it in your environment or pass in `-e SECRET_1=X` flag.
这是 Fn 对 expects.config 中 required: true 字段的强制校验:运行函数前,Fn CLI 会先检查声明的必选环境变量是否已注入(无论是来自 shell 环境还是 -e 参数),缺失则直接报错、拒绝运行。注意提示语中的措辞——它明确给出了两种补救途径:
- 在 shell 环境中设置:
export SECRET_1=YOOO或直接写在命令前缀中 - 通过
-e参数传入:fn run -e SECRET_1=YOOO
这条错误信息本身即是"契约"的体现:函数作者声明了什么必须存在,调用方就必须提供什么,平台在运行前替你把关。
第二步:只提供必选变量
SECRET_1=YOOO fn run
输出:
info: optional env var SECRET_2 not found.
{"SECRET_1":"YOOO","SECRET_2":"","message":"Hello World"}
关键点:
- 必选变量缺失 → 硬错误,拒绝执行
- 可选变量缺失 → 仅打印一行 info 日志,函数照常运行
SECRET_2 在 func.yaml 中没有 required: true 标记,因此缺省时 Fn 只给出提示而不拦截,函数内 os.Getenv("SECRET_2") 返回空字符串 "",最终 JSON 中表现为空值。这说明可选变量适合用于"有默认行为兜底"的配置项。
第三步:同时提供必选与可选变量
SECRET_1=YOOO SECRET_2=DAWG fn run
输出:
{"SECRET_1":"YOOO","SECRET_2":"DAWG","message":"Hello World"}
两个变量都被注入,函数完整输出它们的值。至此,整个"必选/可选"对比闭环完成:同一条命令,通过是否设置 SECRET_2,即可观察可选变量缺省与注入两种行为。
配置拆解:func.yaml 的 expects 段
examples/inputs/func.yaml 全文如下:
version: 0.0.1
runtime: go
entrypoint: ./func
expects:
config:
- name: SECRET_1
required: true
- name: SECRET_2
逐字段解读:
| 字段 | 取值 | 含义 |
|---|---|---|
version |
0.0.1 |
函数清单格式版本号 |
runtime |
go |
运行时类型,Fn 据此选择构建/运行镜像 |
entrypoint |
./func |
容器内实际执行的可执行文件(Go 编译产物) |
expects.config |
列表 | 声明函数期望的环境变量契约 |
name |
SECRET_1 / SECRET_2 |
环境变量名 |
required |
true(仅 SECRET_1) |
是否必选;缺省为 false(可选) |
注意 SECRET_2 的写法:只写 name、不写 required,等价于 required: false,即"可选变量"。这是 YAML 中省略默认值的惯用写法。
对照仓库中其他 func.yaml,可以看到 version/runtime/entrypoint 是通用骨架,例如 tutorial/params/func.yaml 还有 path 字段(HTTP 触发路径),而 expects 段则是"配置契约"专属扩展。
从源码理解契约的执行链路
expects.config 的校验逻辑由 Fn CLI 在 fn run 时执行,本仓库中的服务端代码可从侧面印证这一机制的设计背景。在 api/agent/config.go 中:
// NewConfig returns a config set from env vars, plus defaults
func NewConfig() (*Config, error) {
注释明确指出 Fn 自身的配置体系是"环境变量 + 默认值"模式——这与函数级 expects.config 的设计同源:环境变量是 Fn 生态中传递配置的第一公民。相应地,在 api/agent/config_test.go 中可以看到针对 SetEnv 系列函数的单元测试(TestSetEnvUint、TestSetEnvUintPointer 等),覆盖了从环境变量解析配置的正常与异常路径,说明环境变量解析是整个平台核心路径的一部分。
再看函数运行时的环境变量注入:api/models/fn.go 中 Fn 结构体定义:
// Config is the configuration passed to a function at execution time.
Config Config `json:"config" db:"config"`
即函数在服务器端的 config 字段(键值对)会在执行时以环境变量形式传给函数容器。本地 fn run -e K=V 注入的变量,与云端通过 fn config 设置的变量,最终都会落到这个 Config 中,再以环境变量形态进入容器。这一点在 examples/apps/blog/README.md 中有完整的实操对照:
# 本地调试时逐个传入
fn run -e DB_USER=root -e DB_PASS=pass posts
# 部署后写入 app 级配置
fn config app blog DB_USER root
fn config app blog DB_PASS pass
对应地,blog 示例中的函数代码(func.rb)用 ENV['DB_USER'] 读取这些变量。可见:expects.config 解决的是"本地声明 + 本地校验",而 fn config 解决的是"云端持久化 + 云端注入",两者衔接起来才是完整的环境变量生命周期。
变量注入的三种方式(本地与云端)
综合本示例与仓库其他用法,Fn 函数环境变量的注入途径可归纳为:
| 方式 | 命令示例 | 适用场景 |
|---|---|---|
| 命令前缀 | SECRET_1=YOOO fn run |
单次本地调试,临时值 |
-e 参数 |
fn run -e SECRET_1=YOOO -e SECRET_2=DAWG |
多次传参、显式声明 |
| app 级配置 | fn config app myapp KEY VALUE |
部署到服务器后统一管理 |
其中 -e 参数在仓库中大量出现,例如 blog 示例的 fn run -e DB_USER=root -e DB_PASS=pass schema(examples/apps/blog/README.md),每个函数需要多个环境变量时可连续追加多个 -e。
进阶:函数内如何读取与使用这些变量
本示例在 Go 中通过标准库 os.Getenv 读取:
mapD["SECRET_1"] = os.Getenv("SECRET_1")
Go 的 os.Getenv 在变量不存在时返回空字符串,这正是示例中 SECRET_2 缺省输出 "" 的原因。开发者在函数内通常要做空值兜底或显式校验,例如:
secret := os.Getenv("SECRET_1")
if secret == "" {
// 可选:给出默认值或直接报错
}
除了自定义变量,Fn 平台本身也会向函数注入一组 FN_ 前缀的系统环境变量(如 FN_APP_NAME、FN_REQUEST_URL),examples/apps/hellos/func.go 中读取 FN_APP_NAME 用于拼装页面链接,examples/tutorial/params/func.go 中读取 FN_REQUEST_URL 解析 URL 参数。这类系统变量无需在 expects.config 中声明,但如果你在函数中依赖它们,同样建议做好缺省处理。
测试驱动:test.json 的输入/输出契约
examples/inputs/test.json 给出了本示例的测试用例:
{
"tests": [
{
"input": { "body": { "name": "Johnny" } },
"output": { "body": { "message": "Hello Johnny" } }
},
{
"input": { "body": "" },
"output": { "body": { "message": "Hello World" } }
}
]
}
它验证了两个关键行为:
- 传入
name=Johnny时,输出Hello Johnny - body 为空时,
person.Name保持默认值World,输出Hello World
与 sample.payload.json(内容为 {"name": "Johnny"})配合,构成了"管道输入 → stdin 解码 → JSON 输出"的完整测试闭环。注意测试只断言 message 字段,SECRET_* 变量不属于函数响应契约的一部分——它们属于环境契约,由 expects.config 单独管理。
完整运行闭环与后续进阶
回顾整条链路:
# 1. 本地直接运行 → 触发必选变量校验
fn run
# 2. 注入必选变量 → 可选变量缺省提示
SECRET_1=YOOO fn run
# 3. 全量注入 → 完整输出
SECRET_1=YOOO SECRET_2=DAWG fn run
# 4. 带 JSON 输入运行(管道方式)
cat sample.payload.json | fn run -e SECRET_1=YOOO
部署到 Fn 服务器后,环境变量改用 fn config 管理(见 README.md 中的 fn init / fn create app / fn deploy 流程),此时 expects.config 声明仍然有效,确保部署时不会遗漏必选配置。
这个示例是 Fn 教程体系的第一课,紧接着的进阶主题是输入参数处理(examples/tutorial/params 中通过 FN_REQUEST_URL 解析 URL 查询参数),以及多语言示例(examples/apps/hellos 的 Ruby/Node/Python/Go 全家桶)。理解环境变量契约之后,你便掌握了 Fn 函数配置注入的基石。