Fn 函数环境变量配置实战:用 func.yaml 声明必选与可选变量(Go 示例)

原创2026-10-14 18:31:181,371 阅读
文章标签:云原生后端微服务

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 参数),缺失则直接报错、拒绝运行。注意提示语中的措辞——它明确给出了两种补救途径:

  1. 在 shell 环境中设置:export SECRET_1=YOOO 或直接写在命令前缀中
  2. 通过 -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" } }
        }
    ]
}

它验证了两个关键行为:

  1. 传入 name=Johnny 时,输出 Hello Johnny
  2. 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 函数配置注入的基石。

登录后查看全文
fn