第4章配置文件设计

第四章：配置文件设计——YAML结构、环境变量与多环境方案

说到配置文件，我见过太多团队在这上面栽跟头了。有的把密码写死在代码里，有的开发环境和生产环境混用一套配置，还有的配置文件比业务代码还复杂。说白了，配置管理这件事，做得好能省下80%的运维烦恼，做不好就是一颗定时炸弹。

4.1 YAML配置文件结构设计

我个人习惯用YAML作为配置文件的格式。为什么？因为它比JSON更易读，比INI更灵活，比XML更简洁。你想想看，一个嵌套三层的JSON，光括号就能把人看晕，但YAML用缩进就搞定了。

先看一个基础的YAML配置结构：

# Alpha生成框架核心配置
app:
  name: "alpha-generator"
  version: "2.1.0"
  debug: false

server:
  host: "0.0.0.0"
  port: 8080
  workers: 4
  timeout: 30

database:
  driver: "postgresql"
  host: "localhost"
  port: 5432
  name: "alpha_db"
  pool:
    min: 2
    max: 10
    timeout: 5

logging:
  level: "info"
  format: "json"
  output: "stdout"
  file: "/var/log/alpha/app.log"

这里有个小细节——pool下面的timeout是连接池的超时，而server.timeout是请求超时。我曾经见过有人把这两个搞混，结果生产环境频繁断连，排查了整整两天。

我的习惯：YAML里用2个空格缩进，不用Tab。很多编辑器会把Tab和空格混用，一旦混了，解析器直接报错。这个坑我踩过不止一次。

4.2 环境变量管理

配置文件里最敏感的是什么？密码、密钥、Token。这些东西绝对不能硬编码在YAML里。我见过最离谱的一次，有人把AWS的Secret Key直接提交到了Git仓库，结果第二天账户就被盗刷了。

正确的做法是用环境变量来管理敏感信息。看这个例子：

database:
  host: "${DB_HOST}"
  port: "${DB_PORT}"
  user: "${DB_USER}"
  password: "${DB_PASSWORD}"
  ssl: true

redis:
  host: "${REDIS_HOST}"
  password: "${REDIS_PASSWORD}"
  db: 0

jwt:
  secret: "${JWT_SECRET}"
  expires_in: 3600

在代码里，我们会用类似这样的方式加载：

import os
import yaml
from string import Template

def load_config(path):
    with open(path, 'r') as f:
        raw = f.read()
    
    # 替换环境变量
    template = Template(raw)
    resolved = template.safe_substitute(os.environ)
    
    return yaml.safe_load(resolved)

嗯，这里要注意safe_substitute和substitute的区别。前者如果环境变量不存在，会保留原样；后者直接抛异常。我个人建议用safe_substitute，然后在启动时做校验，这样定位问题更方便。

我曾经踩过的坑：环境变量名不要用连字符（-），很多系统不支持。统一用下划线（_），比如DB_HOST而不是DB-HOST。另外，变量值里如果有特殊字符，记得用引号包起来。

4.3 多环境配置方案

一个项目通常有开发、测试、预发布、生产四个环境。每个环境的配置都不一样。怎么管理？我推荐两种方案：

方案一：文件分离法

按环境拆成多个文件：

config/
├── default.yaml        # 公共配置
├── development.yaml    # 开发环境
├── testing.yaml        # 测试环境
├── staging.yaml        # 预发布环境
└── production.yaml     # 生产环境

加载逻辑很简单：先加载default.yaml，再加载对应环境的文件，后者覆盖前者。这样公共配置只写一次，环境差异单独维护。

方案二：单文件分层法

把所有环境写在一个文件里，用层级区分：

default:
  app:
    name: "alpha-generator"
    version: "2.1.0"
  logging:
    level: "info"
    format: "json"

development:
  extends: default
  server:
    host: "127.0.0.1"
    port: 3000
  database:
    host: "localhost"
    name: "alpha_dev"

production:
  extends: default
  server:
    host: "0.0.0.0"
    port: 8080
    workers: 8
  database:
    host: "${DB_HOST}"
    name: "alpha_prod"
    pool:
      min: 5
      max: 20

我个人更倾向方案一。为什么？因为生产环境的配置通常需要严格权限控制，单独一个文件更容易做权限管理。而且，万一开发环境配置写错了，不会影响到生产。

  核心原则：
  公共配置放default，环境差异放各自文件
敏感信息必须用环境变量，不能写死在文件里
每个环境都要有独立的配置文件，不要用if-else在代码里判断
配置文件要纳入版本控制，但生产环境的敏感值不要提交

4.4 配置校验与最佳实践

配置加载完了，不代表就万事大吉。我见过太多因为配置写错导致的服务启动失败。所以，一定要做配置校验。

一个简单的校验示例：

def validate_config(config):
    required_fields = [
        'server.host',
        'server.port',
        'database.host',
        'database.port',
        'database.name',
    ]
    
    for field in required_fields:
        keys = field.split('.')
        value = config
        for key in keys:
            if key not in value:
                raise ConfigError(f"缺少必要配置: {field}")
            value = value[key]
    
    # 端口范围校验
    port = config['server']['port']
    if not (1024 <= port <= 65535):
        raise ConfigError(f"端口号不合法: {port}")
    
    # 数据库连接校验（可选）
    if config['database']['host'] == 'localhost' and config['app']['debug'] == False:
        print("警告：生产环境不建议使用localhost数据库")

最后，分享几个我多年总结的配置管理原则：

配置即代码：配置文件要像代码一样管理，有版本、有review、有测试
最小权限：每个服务只读取自己需要的配置，不要一股脑全加载
配置可追溯：每次配置变更都要有记录，谁改的、什么时候改的、为什么改
配置可回滚：出问题了能快速切回上一版配置

一个小技巧：在项目启动时，把加载后的配置（脱敏后）打印到日志里。这样出问题的时候，看一眼日志就知道当前用的是哪套配置，省去很多排查时间。

4.5 知识体系总览

下面这张图总结了本章的核心内容，你可以把它当作配置设计的检查清单：

配置管理这件事，说白了就是「把变化的东西和不变的东西分开」。不变的是业务逻辑，变化的是数据库地址、端口号、日志级别这些。你只要把变化的部分管好了，整个系统的稳定性就上了一个台阶。

📚 课程目录

第四章：配置文件设计——YAML结构、环境变量与多环境方案

4.1 YAML配置文件结构设计

4.2 环境变量管理

4.3 多环境配置方案

方案一：文件分离法

方案二：单文件分层法

4.4 配置校验与最佳实践

4.5 知识体系总览