Go generate 怎样把环境变量安全传给代码生成器

代码生成最容易留下两个隐患：把环境值直接塞进 //go:generate 指令，或者让生成器把机器路径、时间戳和密钥写进源码。更稳妥的边界是：指令只描述“运行哪个生成器”，自定义输入由执行 go generate 的父进程注入，生成器再用 os.LookupEnv 读取并校验。

推荐形态：GEN_TARGET=staging GEN_SCHEMA=./schema.json go generate ./...。环境变量负责输入，生成指令保持稳定，生成器只把允许的非敏感值写进结果。

先把环境变量放在生成命令外部

go generate 会显式扫描 //go:generate 指令，并在执行前展开其中的环境变量；它不会因为执行 go build 或 go test 就自动生成文件。自定义变量不必写进指令，可以让父进程提供给生成器。

package schema

// 这条指令只固定生成器入口，不把目标环境或密钥写进源码。
//go:generate go run ./cmd/schema-gen

// 该文件只负责承载 go:generate 指令，生成结果由 cmd/schema-gen 写出。

# 只把本次生成需要的非敏感输入注入父进程环境。
GEN_TARGET=staging GEN_SCHEMA=./schema.json go generate ./...

# CI 中同样调用这一入口，密钥只通过 CI 的受保护变量提供。
GEN_TARGET=production GEN_SCHEMA=./schema.json go generate ./...

这样做的好处是输入边界清楚：GEN_TARGET 和 GEN_SCHEMA 属于本次运行，指令文件仍可提交到仓库。若使用 go generate -x 排查问题，命令会被打印出来，因此不要把令牌直接写成指令参数。

让生成器用 LookupEnv 读取并设定默认值

生成器不要把环境变量拼到另一条 shell 命令中。先读取，再做空值处理和白名单限制；需要区分“没有设置”和“设置为空”时，使用 LookupEnv 比单独调用 Getenv 更直观。

package main

import (
    "fmt"
    "os"
    "path/filepath"
)

// envOrDefault 统一处理未设置和空字符串，避免生成结果依赖机器默认值。
func envOrDefault(name, fallback string) string {
    value, ok := os.LookupEnv(name)
    if !ok || value == "" {
        return fallback
    }
    return value
}

func main() {
    target := envOrDefault("GEN_TARGET", "local")
    if target != "local" && target != "staging" && target != "production" {
        panic(fmt.Sprintf("unsupported GEN_TARGET: %q", target))
    }

    schema := envOrDefault("GEN_SCHEMA", "./schema.json")
    // 这里只使用受控的输出路径，不把环境值当成输出文件名。
    output := filepath.Join("generated", "config.go")
    _ = schema // 实际项目中在这里读取并解析 schema。
    if err := os.WriteFile(output, []byte("// Code generated; DO NOT EDIT.\\n"), 0o644); err != nil {
        panic(err) // 生成失败必须返回错误，不能留下半成品却继续发布。
    }
    fmt.Println("generated target:", target)
}

示例中的 GEN_TARGET 只允许三个值，避免把任意文本带入生成逻辑。真实项目还应在写文件前创建确定的目录；示例为了突出环境边界省略了完整的 schema 解析。

用固定输入约束生成结果

“可复现”不是把所有环境变量都复制到生成文件，而是明确哪些变量属于生成输入。目标环境、schema 文件和工具版本可以成为输入；当前时间、用户名、绝对路径和令牌不应写入结果。

如果生成器必须访问私有服务，建议把令牌留在进程环境中，用完即止，并对日志做脱敏；生成文件只保存服务返回的、经过筛选的业务数据。不要为了“方便调试”把完整环境变量打印出来。

在本地与 CI 中复用同一套入口

本地和 CI 只需要替换环境注入方式，指令与生成器保持不变。可以把生成入口固定成一个脚本或 Make 目标，但脚本的职责仍然是组装明确的环境，而不是拼接一段包含用户输入的 shell 文本。

# 本地：显式给出输入，生成后只检查受影响文件。
GEN_TARGET=local GEN_SCHEMA=./schema.json go generate ./...
git diff --exit-code -- generated/

# CI：从受保护变量读取目标，不能把令牌回显到日志。
export GEN_TARGET="${CI_GEN_TARGET:-staging}"
export GEN_SCHEMA="./schema.json"
go generate ./...
git diff --exit-code -- generated/

出现结果不一致时，先对比 Go 工具链、GEN_TARGET、schema 内容和生成器版本，再检查是否有时间戳或绝对路径写入。不要先把问题归咎于 go generate 的变量展开；生成器自身的默认值和未固定输入通常才是差异来源。

最后可以记住四条边界：指令只保留生成器入口；环境值从父进程注入；生成器先读取、校验再使用；生成结果只包含稳定且允许公开的输入。

常见问题

环境变量为空时，应该让生成器失败吗？

如果它改变输出语义，例如目标环境，建议使用白名单并失败；如果只是可选的本地路径，可以提供明确的相对路径默认值，同时把默认行为写进文档。

可以直接在 go:generate 中写 $GEN_TARGET 吗？

可以展开，但不适合承载秘密或未经限制的用户输入。更稳的做法是让生成器读取父进程环境，并在程序内部校验和脱敏。