《后端架构设计·架构基础与边界》11.2 配置、密钥与环境差异

// file: internal/platform/config/config.go
// tier: L1
// verify: go test ./internal/platform/config/
package config

import (
	"fmt"
	"net/url"
	"strconv"
	"strings"
)

type Env string

const (
	Dev     Env = "dev"
	Staging Env = "staging"
	Prod    Env = "prod"
)

// Config 是进程启动后唯一的配置来源。业务代码只接收这个结构，
// 不直接读 os.Getenv，环境差异才不会散落到各个包里。
type Config struct {
	Env                   Env
	HTTPAddr              string
	DatabaseURL           string
	PaymentBaseURL        string
	PaymentProvider       string
	PaymentAPIKey         string
	RequestTimeoutMS      int
	IdempotencyTTLMinutes int
	LogLevel              string
}

// Source 把两个非密来源分开：File 是随代码评审的配置文件，
// Env 是部署时注入的环境变量。密钥只允许出现在环境变量或密钥挂载里。
type Source struct {
	File map[string]string
	Env  map[string]string
}

type Issue struct {
	Code   string
	Key    string
	Detail string
}

func (i Issue) String() string {
	return fmt.Sprintf("%s %s: %s", i.Code, i.Key, i.Detail)
}

// allowed 是配置键的白名单。未知键通常意味着拼写错误或旧版本残留，
// 静默忽略会让进程带着一个“以为生效了”的值继续运行。
var allowed = map[string]bool{
	"APP_ENV": true, "HTTP_ADDR": true, "DATABASE_URL": true,
	"PAYMENT_BASE_URL": true, "PAYMENT_PROVIDER": true, "PAYMENT_API_KEY": true,
	"REQUEST_TIMEOUT_MS": true, "IDEMPOTENCY_TTL_MINUTES": true, "LOG_LEVEL": true,
}

// defaults 只放开发环境也安全的非密值。任何“生产忘了设置就危险”的值
// 都不在这里给默认，例如 APP_ENV 和支付渠道。
func defaults() map[string]string {
	return map[string]string{
		"HTTP_ADDR":               ":8080",
		"PAYMENT_PROVIDER":        "fake",
		"REQUEST_TIMEOUT_MS":      "2000",
		"IDEMPOTENCY_TTL_MINUTES": "30",
		"LOG_LEVEL":               "info",
	}
}

// Load 的优先级是 defaults < File < Env，后两者都只接受白名单键。
// 返回值同时包含 Config 和全部问题；调用方必须在有任何 Issue 时退出。
func Load(src Source) (Config, []Issue) {
	var issues []Issue
	add := func(code, key, detail string) {
		issues = append(issues, Issue{Code: code, Key: key, Detail: detail})
	}

	merged := defaults()
	for k, v := range src.File {
		merged[k] = v
		if !allowed[k] {
			add("UNKNOWN_KEY", k, "config file key is not in the allowlist")
		}
	}
	for k, v := range src.Env {
		merged[k] = v
		if !allowed[k] {
			add("UNKNOWN_KEY", k, "environment key is not in the allowlist")
		}
	}
	// 密钥出现在配置文件里就视为泄露风险，哪怕当前值是空的。
	if _, ok := src.File["PAYMENT_API_KEY"]; ok {
		add("SECRET_IN_FILE", "PAYMENT_API_KEY", "secrets must come from env or a secret mount")
	}

	env := Env(strings.TrimSpace(merged["APP_ENV"]))
	switch env {
	case Dev, Staging, Prod:
	default:
		add("INVALID_VALUE", "APP_ENV", fmt.Sprintf("want dev|staging|prod, got %q", env))
	}

	databaseURL := strings.TrimSpace(merged["DATABASE_URL"])
	if databaseURL == "" {
		add("MISSING_REQUIRED", "DATABASE_URL", "required in every environment")
	} else if u, err := url.Parse(databaseURL); err != nil || u.Scheme != "postgres" {
		add("INVALID_VALUE", "DATABASE_URL", "must be a postgres:// URL")
	}

	timeout := parseInt(merged["REQUEST_TIMEOUT_MS"], 1, 60000, "REQUEST_TIMEOUT_MS", add)
	ttl := parseInt(merged["IDEMPOTENCY_TTL_MINUTES"], 1, 10080, "IDEMPOTENCY_TTL_MINUTES", add)

	logLevel := strings.ToLower(strings.TrimSpace(merged["LOG_LEVEL"]))
	switch logLevel {
	case "debug", "info", "warn", "error":
	default:
		add("INVALID_VALUE", "LOG_LEVEL", fmt.Sprintf("unknown level %q", logLevel))
	}

	provider := strings.TrimSpace(merged["PAYMENT_PROVIDER"])
	apiKey := strings.TrimSpace(merged["PAYMENT_API_KEY"])
	baseURL := strings.TrimSpace(merged["PAYMENT_BASE_URL"])

	if env == Prod {
		// 开发默认值 fake 一旦被带进生产，订单会“支付成功”但钱没动。
		if provider == "fake" {
			add("DANGEROUS_DEFAULT", "PAYMENT_PROVIDER", "fake provider is dev-only; set the real provider")
		}
		if apiKey == "" {
			add("MISSING_SECRET", "PAYMENT_API_KEY", "required when APP_ENV=prod")
		}
		if baseURL == "" {
			add("MISSING_REQUIRED", "PAYMENT_BASE_URL", "required when APP_ENV=prod")
		} else {
			if !strings.HasPrefix(baseURL, "https://") {
				add("ENV_MISMATCH", "PAYMENT_BASE_URL", "prod must use https")
			}
			if strings.Contains(baseURL, "sandbox") || strings.Contains(baseURL, "localhost") {
				add("ENV_MISMATCH", "PAYMENT_BASE_URL", "sandbox or local endpoint in prod")
			}
		}
	} else if baseURL == "" {
		baseURL = "http://localhost:9090/fake"
	}

	return Config{
		Env:                   env,
		HTTPAddr:              merged["HTTP_ADDR"],
		DatabaseURL:           databaseURL,
		PaymentBaseURL:        baseURL,
		PaymentProvider:       provider,
		PaymentAPIKey:         apiKey,
		RequestTimeoutMS:      timeout,
		IdempotencyTTLMinutes: ttl,
		LogLevel:              logLevel,
	}, issues
}

func parseInt(raw string, min, max int, key string, add func(string, string, string)) int {
	v, err := strconv.Atoi(strings.TrimSpace(raw))
	if err != nil || v < min || v > max {
		add("INVALID_VALUE", key, fmt.Sprintf("want %d..%d, got %q", min, max, raw))
		return 0
	}
	return v
}

// file: internal/platform/config/config_test.go
// tier: L1
// verify: go test ./internal/platform/config/
package config

import "testing"

func validProd() Source {
	return Source{
		File: map[string]string{"HTTP_ADDR": ":8443"},
		Env: map[string]string{
			"APP_ENV":          "prod",
			"DATABASE_URL":     "postgres://orders:secret@db.internal:5432/orders?sslmode=require",
			"PAYMENT_BASE_URL": "https://pay.example.com/v1",
			"PAYMENT_PROVIDER": "acme",
			"PAYMENT_API_KEY":  "sk_live_123",
		},
	}
}

func TestValidProductionConfig(t *testing.T) {
	cfg, issues := Load(validProd())
	if len(issues) != 0 {
		t.Fatalf("valid prod config should load, got %v", issues)
	}
	if cfg.Env != Prod || cfg.RequestTimeoutMS != 2000 || cfg.IdempotencyTTLMinutes != 30 {
		t.Fatalf("unexpected defaults: %+v", cfg)
	}
	t.Logf("env=%s provider=%s timeout=%dms ttl=%dmin issues=%d",
		cfg.Env, cfg.PaymentProvider, cfg.RequestTimeoutMS, cfg.IdempotencyTTLMinutes, len(issues))
}

func TestLoadRejectsBadConfig(t *testing.T) {
	cases := []struct {
		name   string
		mutate func(*Source)
		code   string
		key    string
	}{
		{"missing database url", func(s *Source) {
			delete(s.Env, "DATABASE_URL")
		}, "MISSING_REQUIRED", "DATABASE_URL"},
		{"invalid timeout", func(s *Source) {
			s.Env["REQUEST_TIMEOUT_MS"] = "0"
		}, "INVALID_VALUE", "REQUEST_TIMEOUT_MS"},
		{"dangerous default provider", func(s *Source) {
			delete(s.Env, "PAYMENT_PROVIDER")
		}, "DANGEROUS_DEFAULT", "PAYMENT_PROVIDER"},
		{"secret in config file", func(s *Source) {
			s.File["PAYMENT_API_KEY"] = "sk_live_123"
		}, "SECRET_IN_FILE", "PAYMENT_API_KEY"},
		{"sandbox endpoint in prod", func(s *Source) {
			s.Env["PAYMENT_BASE_URL"] = "https://sandbox.pay.example.com"
		}, "ENV_MISMATCH", "PAYMENT_BASE_URL"},
		{"unknown key typo", func(s *Source) {
			s.Env["DATABSE_URL"] = "postgres://typo"
		}, "UNKNOWN_KEY", "DATABSE_URL"},
	}
	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			src := validProd()
			tc.mutate(&src)
			_, issues := Load(src)
			if !hasIssue(issues, tc.code, tc.key) {
				t.Fatalf("want %s on %s, got %v", tc.code, tc.key, issues)
			}
		})
	}
}

func TestPrecedenceAndDevDefaults(t *testing.T) {
	src := validProd()
	src.File["REQUEST_TIMEOUT_MS"] = "500"
	cfg, issues := Load(src)
	if len(issues) != 0 || cfg.RequestTimeoutMS != 500 {
		t.Fatalf("file layer should win over default: %+v %v", cfg, issues)
	}
	src.Env["REQUEST_TIMEOUT_MS"] = "300"
	cfg, issues = Load(src)
	if len(issues) != 0 || cfg.RequestTimeoutMS != 300 {
		t.Fatalf("env layer should win over file: %+v %v", cfg, issues)
	}

	dev := Source{Env: map[string]string{
		"APP_ENV":      "dev",
		"DATABASE_URL": "postgres://localhost:5432/orders",
	}}
	cfg, issues = Load(dev)
	if len(issues) != 0 {
		t.Fatalf("dev defaults should load, got %v", issues)
	}
	if cfg.HTTPAddr != ":8080" || cfg.PaymentProvider != "fake" || cfg.PaymentBaseURL == "" {
		t.Fatalf("unexpected dev defaults: %+v", cfg)
	}
	t.Logf("dev addr=%s provider=%s payment_url=%s", cfg.HTTPAddr, cfg.PaymentProvider, cfg.PaymentBaseURL)
}

func hasIssue(issues []Issue, code, key string) bool {
	for _, issue := range issues {
		if issue.Code == code && issue.Key == key {
			return true
		}
	}
	return false
}

$ go test ./internal/platform/config/ -run TestValidProductionConfig -v
=== RUN   TestValidProductionConfig
    config_test.go:29: env=prod provider=acme timeout=2000ms ttl=30min issues=0
--- PASS: TestValidProductionConfig (0.00s)
PASS
ok  	archlab/internal/platform/config	0.239s