深入解析設定檔案核心概念、優勢與應用場景

# 使用sed自動化替換設定引數
sed -i 's/debug_level=1/debug_level=3/' config.ini

# 使用jq修改JSON設定
jq '.database.max_connections = 100' config.json > config.json.new && mv config.json.new config.json

# 檢視設定檔案的變更歷史
git log -p config/database.yaml

# 比較不同版本的設定
git diff HEAD~5 HEAD config/database.yaml

# 回退到之前的設定版本
git checkout HEAD~3 config/database.yaml

# YAML設定範例
database:
  primary:
    host: db-master.example.com
    port: 5432
    credentials:
      username: app_user
      password: ${DB_PASSWORD}  # 環境變數參照
  replicas:
    - host: db-replica-1.example.com
      port: 5432
      read_only: true
    - host: db-replica-2.example.com
      port: 5432
      read_only: true

# 讀取設定檔案
import yaml

with open('config.yaml', 'r') as f:
    config = yaml.safe_load(f)

# 使用新增的設定引數
retry_limit = config.get('api', {}).get('retry_limit', 3)

database:
  host: db.example.com
  port: 5432
  username: app_user
  password: ${DB_PASSWORD}  # 最好使用環境變數或金鑰管理服務

api_services:
  payment_gateway:
    url: https://api.payment.example.com/v2
    api_key: ${PAYMENT_API_KEY}

features:
  new_ui: true
  beta_features: false
  payment_methods:
    credit_card: true
    crypto: false
    
debug:
  enabled: false
  level: info  # debug, info, warn, error
  
logging:
  file: /var/log/app.log
  rotation:
    max_size: 100MB
    max_files: 10

paths:
  data: /var/lib/app/data
  temp: /tmp/app
  
locale:
  timezone: Asia/Taipei
  language: zh_TW
  
executables:
  imagemagick: /usr/bin/convert
  ffmpeg: /usr/local/bin/ffmpeg

cache:
  provider: redis
  ttl: 3600
  max_size: 1000
  
queue:
  driver: rabbitmq
  prefetch: 10
  retry:
    attempts: 3
    delay: 5000

deployment:
  strategy: blue_green
  timeout: 300
  
scaling:
  min_instances: 2
  max_instances: 10
  cpu_threshold: 70

config/
├── config.base.yaml     # 共用基礎設定
├── config.dev.yaml      # 開發環境特定設定
├── config.test.yaml     # 測試環境特定設定
└── config.prod.yaml     # 生產環境特定設定

def validate_config(config):
    """驗證設定是否有效"""
    if 'database' not in config:
        raise ConfigError("Missing required 'database' section")
    
    db = config['database']
    required_fields = ['host', 'port', 'username', 'password']
    for field in required_fields:
        if field not in db:
            raise ConfigError(f"Missing required database field: {field}")
    
    # 驗證端

## 設定管理：應用程式的關鍵根本

在我多年的系統架構設計與開發經驗中，發現許多專案失敗的根源往往不是複雜的演算法或技術挑戰，而是看似簡單的設定管理問題。設定管理雖然看起來平凡無奇，但它實際上是軟體系統中最關鍵的基礎設施之一，直接影響系統的彈性、可維護性和安全性。

### 設定管理的關鍵類別

當我們談論應用程式設定時，實際上涵蓋了多種不同性質的設定：

#### 應用程式設定
這類別設定直接影回應用程式的行為邏輯：
- 功能開關（feature flags）
- 業務邏輯引數
- 各種臨界值與限制設定

#### 基礎設施設定
這些設定決定了應用程式與外部系統的互動方式：
- 資料函式庫引數
- 快取服務設定
- 訊息佇列設定
- API端點與服務發現設定

#### 佈署引數
與應用程式執行環境相關的設定：
- Docker及容器化引數
- 建置與佈署所需的金鑰與令牌（如GitHub Token、AWS存取金鑰等）

#### 使用者偏好設定
- 介面設定（主題、顏色、字型等）
- 個人化設定

#### 可變常數
這些是可能隨時間變化的值：
- 數值型常數（價格、加價係數等）
- 字串型常數（公司名稱、LLM提示詞等）

## 多層次設定檔案：靈活管理不同環境

多層次設定（Layered Configuration）是一種強大的設定管理模式，它允許多個設定檔案以層疊方式相互覆寫。每一層可以覆寫前一層的設定，最終合併成完整的設定。這種方法特別適合管理不同環境（開發、測試、生產）的設定差異。

### 為何需要多層次設定？

#### 靈活覆寫特定設定
在玄貓參與的一個大型金融科技專案中，我們採用多層次設定來解決跨環境設定管理的痛點。基本原則是：
- 使用同一份核心設定檔案作為所有環境的基礎
- 各環境特有的設定存放在專屬設定檔案中
- 開發者可在本地設定檔案中進行個人化設定，無需修改分享設定

#### 環境隔離（開發、測試、預演、生產）
- 基礎設定檔案包含所有環境共用的設定
- 環境特設定檔案（如config.dev.yaml、config.prod.yaml）只包含差異部分
- 這大幅減少了設定檔案的重複內容，同時確保環境隔離

#### 開發與測試便利性
在一個微服務架構專案中，我發現多層次設定極大提升了開發效率：
- 開發者可以在不影響他人的情況下調整本地設定
- CI/CD流程可使用專屬設定層，與生產設定保持獨立
- 測試環境可輕鬆模擬各種設定場景

#### 避免設定重複
- 共用設定儲存在基礎層
- 特定引數僅在需要的層級中定義
- 顯著降低維護負擔和錯誤風險

### 何時使用多層次設定

多層次設定特別適合以下場景：

- **多環境佈署**：當應用需要在開發、測試、預演和生產等不同環境執行時
- **CI/CD管道**：區分建置、測試和佈署階段的設定
- **本地開發**：允許開發者建立個人化設定而不影響團隊分享設定
- **機密管理**：基礎設定不包含敏感資訊，而是透過額外的機密設定檔案加入
- **設定範本化**：使用基礎設定作為範本，再疊加環境特定值

## 多層次設定的實作原理

多層次設定的核心是層級覆寫機制。一般而言，它包含以下層級：

1. **基礎層**：通常是`config.yaml`，包含所有環境共用的預設值
2. **環境層**：如`config.dev.yaml`或`config.prod.yaml`，包含特定環境的設定
3. **本地層**：如`config.local.yaml`，包含開發者個人或特定伺服器的設定

### 多層次設定範例（YAML）

下面是一個實際的多層次設定範例，這種方法在玄貓負責的多個大型專案中證明非常有效：

**config.yaml（基礎設定）**：

```yaml
database:
  host: "localhost"
  port: 5432
  username: "default_user"
  password: "default_pass"

logging:
  level: "info"
  file: "/var/log/app.log"

database:
  host: "prod-db.company.com"
  username: "prod_user"
  password: "secure_pass"

database:
  password: "local_pass"
  port: 5433

logging:
  level: "debug"

database:
  host: "prod-db.company.com" # 來自config.prod.yaml
  port: 5433                  # 來自config.local.yaml
  username: "prod_user"       # 來自config.prod.yaml
  password: "local_pass"      # 來自config.local.yaml

logging:
  level: "debug"              # 來自config.local.yaml
  file: "/var/log/app.log"    # 來自config.yaml（未被覆寫）

from deepmerge import always_merger
from pprint import pprint

# 基礎設定
base = {
    'database': { 'host': 'localhost', 'port': 5432, 'username': 'admin' },
    'logging': { 'file': 'app.log', 'level': 'info'}
}

# 覆寫設定
override = {
    'database': { 'port': 3306, 'username': 'dev_user', 'password': 'secret' },
    'logging': { 'level': 'debug' }
}

# 使用always_merger合併設定
merged_config = always_merger.merge(base, override)
pprint(merged_config)

# const.py
API_ID = '21186447'
API_HASH = '1507e2222222221dc6a847dc95b294f36a'

msg_basedir = '/opt/local/var/www/tgmedia/'
tgresources_dir = '/opt/local/var/www/tgresources'
watermarks_samples_dir = os.path.join(tgresources_dir, 'samples')

advertisement_block_patterns = [
    "#廣告", "瞭解更多", "關於廣告主",
    r"/\+886[( ]?(?:9|800)/", r"/0800/",
]

# myapp.py
import const
print(const.API_ID)

# 或者
from const import *
print(API_ID)  # '21186447'

# const.py（基礎設定）
API_ID = '21186448'
API_HASH = '2507edddddd...'

# 嘗試匯入覆寫設定
try:
    from myconst import *
except ImportError:
    pass

# myconst.py（覆寫設定）
API_ID = '21186448'
API_HASH = '2507e3333333...'

# myapp.py（應用程式）
import const
from const import API_HASH
print(const.API_ID)  # '21186448'
print(API_HASH)      # '2507e3333333...'

# 資料函式庫
database:
  host: localhost
  port: 5432 # PostgreSQL 預設埠
  username: admin
  password: "admin123"

logging:
  level: info
  file: app.log

modules:
  data_processor:
    batch_size: 100
    retry_attempts: 3
  machine_learning:
    model: "xgboost"
    learning_rate: 0.01

ids: [1, 2, 3, 4, 5]
users:
  - { name: Alice, role: admin }
  - { name: Bob, role: editor }
  - { name: Charlie, role: viewer }

import yaml

with open("config.yaml", "r", encoding='utf-8') as file:
    config = yaml.safe_load(file)

print(config["database"]["host"])

database:
  host: localhost
  port: 5432
  username: admin
logging:
  level: info

database:
  port: 3306
  username: dev_user
  password: secret
logging:
  level: debug

from ruamel.yaml import YAML

# 深度合併字典的函式
def merge_dicts(base, override):
    for key, value in override.items():
        if isinstance(value, dict) and key in base:
            base[key] = merge_dicts(base[key], value)
        else:
            base[key] = value
    return base

# 載入 YAML 的函式
def load_yaml(file_path):
    yaml = YAML(typ="safe")
    with open(file_path, 'r') as file:
        return yaml.load(file)

# 載入基礎和本地設定
base_config = load_yaml("config.yaml")
local_config = load_yaml("config_local.yaml")
# 合併設定
final_config = merge_dicts(base_config, local_config)
# 輸出結果
print("最終設定:")
print(final_config)

{'database':
    {'host': 'localhost',
      'password': 'dev_secret',
      'port': 3306,
      'username': 'dev_user'},
 'logging':
    {'file': 'app.log',
     'level': 'debug'}
}

{
  "logs": {
    "actions": "/var/log/myservice/action.log",
    "errors": "/var/log/myservice/error.log"
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "username": "user",
    "password": "pass"
  },
  "array": [1, 2, 3, 4, 5]
}

import json

# 從檔案讀取設定
with open('config.json', 'r') as file:
    config = json.load(file)

# 輸出設定
print(config)

; 這是一個註解
[logs]
actions = /var/log/myservice/action.log
errors = /var/log/myservice/error.log
[database]
host = localhost
port = 5432
username = user
password = pass

import configparser

# 讀取 INI 檔案的函式
def load_ini_config(file_path):
    config = configparser.ConfigParser()
    config.read(file_path)
    return config

# 載入設定
config = load_ini_config("config.ini")

# 輸出設定
print(config)

# 資料函式庫
database:
  host: localhost
  port: 5432
  credentials:
    username: admin
    password: secret

# 日誌設定
logging:
  level: info
  file: app.log

# 伺服器列表
servers:
  - name: server1
    ip: 192.168.1.1
  - name: server2
    ip: 192.168.1.2

import yaml

# 讀取YAML設定檔案
def load_yaml_config(file_path):
    with open(file_path, 'r') as file:
        return yaml.safe_load(file)

# 使用範例
config = load_yaml_config('config.yaml')
print(config)

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "credentials": {
      "username": "admin",
      "password": "secret"
    }
  },
  "logging": {
    "level": "info",
    "file": "app.log"
  },
  "servers": [
    {
      "name": "server1",
      "ip": "192.168.1.1"
    },
    {
      "name": "server2",
      "ip": "192.168.1.2"
    }
  ]
}

import json

# 讀取JSON設定檔案
def load_json_config(file_path):
    with open(file_path, 'r') as file:
        return json.load(file)

# 使用範例
config = load_json_config('config.json')
print(config)

; 資料函式庫
[database]
host = localhost
port = 5432
username = admin
password = secret

; 日誌設定
[logging]
level = info
file = app.log

import configparser

# 讀取INI設定檔案
def load_ini_config(file_path):
    config = configparser.ConfigParser()
    config.read(file_path)
    return config

# 使用範例
config = load_ini_config('config.ini')

# 存取設定專案
db_host = config['database']['host']
print(db_host)

# 資料函式庫
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=admin
DATABASE_PASSWORD=secret

# 日誌設定
LOG_LEVEL=info
LOG_FILE=app.log

import os
from dotenv import load_dotenv

# 載入.env檔案（如果存在）
load_dotenv()

# 直接存取環境變數
db_host = os.getenv('DATABASE_HOST', 'default_host')
db_port = int(os.getenv('DATABASE_PORT', '5432'))

print(f"連線到資料函式庫{db_host}:{db_port}")

version = 1.2   # 數字
debug = true    # 布林值
date = 2023-08-18T12:34:56Z  # 日期時間

[database]
host = "localhost"

[database.credentials]
username = "admin"
password = "secret"

[database]
host = "localhost"
port = 5432
credentials.username = "admin"
credentials.password = "secret"

# 註解
[database]
host = "localhost"
port = 5432

[database.credentials]
username = "admin"
password = "secret"

[logging]
level = "info"
file = "app.log"

import tomllib  # Python 3.11+內建
# import toml  # Python 3.11以下版本需使用此套件

# 讀取TOML設定檔案
def load_toml_config(file_path):
    # 必須以二進位模式開啟
    with open(file_path, "rb") as file:
        return tomllib.load(file)

# 使用範例
config = load_toml_config("config.toml")
print(config)

CREATE TABLE configurations (
    user_id INTEGER,
    key VARCHAR(32) NOT NULL,
    value TEXT NOT NULL,
    PRIMARY KEY (user_id, key)
);

# 使用Pydantic進行設定驗證的範例
from pydantic import BaseModel, validator, Field
from typing import Optional, List

class DatabaseConfig(BaseModel):
    host: str
    port: int = Field(..., ge=1024, le=65535)
    username: str
    password: Optional[str]
    
    @validator('host')
    def validate_host(cls, v):
        if not v:
            raise ValueError('資料函式庫不能為空')
        return v

class LoggingConfig(BaseModel):
    level: str
    file: Optional[str]
    
    @validator('level')
    def validate_level(cls, v):
        allowed = ['debug', 'info', 'warning', 'error']
        if v.lower() not in allowed:
            raise ValueError(f'日誌級別必須是以下之一: {", ".join(allowed)}')
        return v.lower()

class AppConfig(BaseModel):
    database: DatabaseConfig
    logging: LoggingConfig

import yaml
from pathlib import Path

def load_config(env: str = "dev"):
    config_path = Path(f"config.{env}.yaml")
    if not config_path.exists():
        raise FileNotFoundError(f"找不到設定檔案: {config_path}")
    
    with open(config_path, 'r') as f:
        config_data = yaml.safe_load(f)
    
    # 使用Pydantic模型驗證設定
    return AppConfig(**config_data)

# 應用程式啟動時
try:
    config = load_config("prod")
    # 設定驗證透過，繼續啟動應用程式
except Exception as e:
    print(f"設定驗證失敗: {e}")
    # 終止啟動或使用備用設定

{
  "type": "object",
  "properties": {
    "database": {
      "type": "object",
      "properties": {
        "host": {"type": "string"},
        "port": {"type": "integer", "minimum": 1024, "maximum": 65535},
        "username": {"type": "string"},
        "password": {"type": "string"}
      },
      "required": ["host", "port"]
    },
    "logging": {
      "type": "object",
      "properties": {
        "level": {"type": "string", "enum": ["debug", "info", "warning", "error"]},
        "file": {"type": "string"}
      }
    }
  },
  "required": ["database", "logging"]
}

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="config">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="database">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="host" type="xs:string"/>
              <xs:element name="port" type="xs:integer"/>
              <xs:element name="username" type="xs:string"/>
              <xs:element name="password" type="xs:string"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="logging">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="level" type="xs:string"/>
              <xs:element name="file" type="xs:string"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

# 安裝 AJV
npm install ajv

# 使用 CLI 驗證 JSON 檔案
npx ajv validate -s schema.json -d config.json

# 安裝 jsonschema
pip install jsonschema

# 驗證 JSON 檔案
jsonschema -i config.json schema.json

# 安裝 yamllint
pip install yamllint

# 檢查 YAML 檔案
yamllint config.yaml

# 安裝 yamale
pip install yamale

# 使用 schema 驗證 YAML 檔案
yamale --schema schema.yaml config.yaml

# 使用 XSD schema 驗證 XML
xmllint --schema schema.xsd --noout config.xml

# 安裝 xmlstarlet
apt-get install xmlstarlet  # Debian/Ubuntu
brew install xmlstarlet  # macOS

# 驗證 XML 檔案
xmlstarlet val --xsd schema.xsd config.xml

# 安裝 toml-validator
npm install -g toml-validator

# 驗證 TOML 檔案
toml-validator config.toml

# 使用 Python 驗證 TOML 語法
python3 -c "import tomllib; tomllib.load(open('config.toml', 'rb'))"

# 驗證 Terraform 設定
terraform validate

# 安裝 hcl2 工具
pip install python-hcl2

# 驗證 HCL 檔案
hcl2-lint config.hcl

from pydantic import BaseModel, Field

class DatabaseConfig(BaseModel):
    host: str
    port: int = Field(..., ge=1024, le=65535)  # 連線埠限制在 1024-65535
    username: str
    password: str

class LoggingConfig(BaseModel):
    level: str
    file: str

class Config(BaseModel):
    database: DatabaseConfig
    logging: LoggingConfig

from pydantic import BaseModel, Field, ValidationError

class DatabaseConfig(BaseModel):
    host: str = Field(..., description="資料函式庫名稱，必填欄位")
    port: int = Field(..., ge=1024, le=65535, description="連線埠號碼 (1024-65535)")
    username: str = Field(..., description="資料函式庫者名稱")
    password: str = Field(..., min_length=8, description="資料函式庫，最少 8 個字元")

class LoggingConfig(BaseModel):
    level: str = Field(..., regex='^(debug|info|warning|error)$', description="日誌等級 (debug, info, warning, error)")
    file: str

class Config(BaseModel):
    database: DatabaseConfig
    logging: LoggingConfig

from pydantic import ValidationError

try:
    # 嘗試驗證包含錯誤的資料
    config = Config(**data_with_errors)
except ValidationError as e:
    # 輸出錯誤詳情
    print("❌ 設定檔驗證錯誤:")
    print(e.json(indent=4))

❌ 設定檔驗證錯誤:
[
    {
        "loc": ["database", "port"],
        "msg": "value is not a valid integer (must be between 1024 and 65535)",
        "type": "value_error.number.not_in_range",
        "ctx": {"limit_value": 1024}
    },
    {
        "loc": ["database", "password"],
        "msg": "ensure this value has at least 8 characters",
        "type": "value_error.any_str.min_length",
        "ctx": {"limit_value": 8}
    },
    {
        "loc": ["logging", "level"],
        "msg": "string does not match regex '^(debug|info|warning|error)$'",
        "type": "value_error.str.regex",
        "ctx": {"pattern": "^(debug|info|warning|error)$"}
    }
]

try:
    config = Config(**data_with_errors)
except ValidationError as e:
    print("❌ 驗證錯誤:")
    for error in e.errors():
        loc = " → ".join(str(l) for l in error['loc'])
        msg = error['msg']
        print(f"欄位: {loc}\n錯誤: {msg}\n")

❌ 驗證錯誤:
欄位: database → port
錯誤: value is not a valid integer (must be between 1024 and 65535)

欄位: database → password
錯誤: ensure this value has at least 8 characters

欄位: logging → level
錯誤: string does not match regex '^(debug|info|warning|error)$'

from voluptuous import Schema, Required, All, Length, Range

# 設定檔結構定義
schema = Schema({
    'database': {
        'host': str,
        'port': All(int, Range(min=1024, max=65535)),
        'username': str,
        'password': str
    },
    'logging': {
        'level': All(str, Length(min=3, max=10)),
        'file': str
    }
})

# 範例設定
config = {
    'database': {
        'host': 'localhost',
        'port': 543222,  # 超出有效範圍
        'username': 'admin',
        'password': 'thetopsecret'
    },
    'logging': {'level': 'info', 'file': '/var/log/app.log'}
}

# 驗證設定
try:
    validated_data = schema(config)
    print("✅ 設定檔驗證透過!", validated_data)
except Exception as e:
    print(f"❌ 錯誤: {e}")

from pydantic import BaseModel, validator

class UserModel(BaseModel):
    id: int
    name: str
    email: str
    age: int = None
    
    @validator('email')
    def validate_email(cls, value):
        if '@' not in value:
            raise ValueError('無效的電子郵件格式')
        return value

from voluptuous import Schema, Required, All, Length, Email

user_schema = Schema({
    Required('id'): int,
    Required('name'): All(str, Length(min=1)),
    Required('email'): Email(),
    'age': int
})

# config/base.py - 基礎設定
DATABASE_ENGINE = 'postgresql'

# config/development.py - 開發環境
from config.base import *
DATABASE_HOST = 'localhost'
DEBUG = True

# config/production.py - 生產環境
from config.base import *
DATABASE_HOST = 'db.production.example.com'
DEBUG = False