配置系统

HsxWorkFlow 基于 pydantic-settings 实现类型安全的配置管理，支持环境变量、.env 文件和代码内默认值。

概览

配置层次

AppConfig                              # 主配置（WORKFLOW_ 前缀）
├── debug: bool                        # 调试模式
├── environment: str                   # 运行环境
├── max_workers: int                   # 线程池大小
├── default_time_interval: float       # 执行间隔
├── database: DatabaseConfig           # 数据库配置（DB_ 前缀）
│   ├── host: str
│   ├── port: int
│   ├── user: str
│   ├── password: str
│   ├── database: str
│   ├── charset: str
│   └── url: str (property)
├── redis: RedisConfig                 # Redis 配置（REDIS_ 前缀）
│   ├── host: str
│   ├── port: int
│   ├── password: str
│   ├── db: int
│   ├── max_connections: int
│   └── url: str (property)
├── log: LogConfig                     # 日志配置（LOG_ 前缀）
│   ├── level: str
│   ├── dir: str
│   ├── format: str
│   ├── max_bytes: int
│   └── backup_count: int
├── quantity_detection: QuantityDetectionConfig  # 数量检测（QD_ 前缀）
│   ├── enabled: bool
│   ├── max_count: int
│   ├── slow_down_seconds: float
│   ├── break_on_limit: bool
│   └── redis_key_prefix: str
└── web: WebConfig                     # Web 配置（WEB_ 前缀）
    ├── host: str
    ├── port: int
    ├── debug: bool
    ├── cors_origins: list[str]
    └── docs_enabled: bool

.env 文件配置

创建 .env 文件：

# 基础配置
WORKFLOW_DEBUG=false
WORKFLOW_ENVIRONMENT=production
WORKFLOW_MAX_WORKERS=10
WORKFLOW_DEFAULT_TIME_INTERVAL=1.0

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=secret
DB_DATABASE=workflow_db
DB_CHARSET=utf8mb4

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
REDIS_MAX_CONNECTIONS=10

# Web 服务配置
WEB_HOST=0.0.0.0
WEB_PORT=5050
WEB_DEBUG=false
WEB_DOCS_ENABLED=true
WEB_CORS_ORIGINS=["*"]

# 日志配置
LOG_LEVEL=INFO
LOG_DIR=logs
LOG_MAX_BYTES=10485760
LOG_BACKUP_COUNT=7

# 数量检测配置
QD_ENABLED=false
QD_MAX_COUNT=1000
QD_SLOW_DOWN_SECONDS=1.0
QD_BREAK_ON_LIMIT=true
QD_REDIS_KEY_PREFIX=workflow_success

代码中访问配置

全局配置

from hsxworkflow import config, get_config

# 直接访问全局配置
print(config.debug)                    # False
print(config.environment)              # production
print(config.max_workers)              # 10
print(config.default_time_interval)    # 1.0

数据库配置

# 访问数据库配置
print(config.database.host)            # localhost
print(config.database.port)            # 3306
print(config.database.user)            # root
print(config.database.password)        # secret
print(config.database.database)        # workflow_db
print(config.database.charset)         # utf8mb4

# 获取完整连接 URL
print(config.database.url)             # mysql+aiomysql://root:secret@localhost:3306/workflow_db?charset=utf8mb4

Redis 配置

# 访问 Redis 配置
print(config.redis.host)               # localhost
print(config.redis.port)               # 6379
print(config.redis.password)           # None
print(config.redis.db)                 # 0
print(config.redis.max_connections)    # 10

# 获取完整连接 URL
print(config.redis.url)                # redis://localhost:6379/0

Web 配置

# 访问 Web 配置
print(config.web.host)                 # 0.0.0.0
print(config.web.port)                 # 5050
print(config.web.debug)                # False
print(config.web.docs_enabled)         # True
print(config.web.cors_origins)         # ["*"]

日志配置

# 访问日志配置
print(config.log.level)                # INFO
print(config.log.dir)                  # logs
print(config.log.max_bytes)            # 10485760
print(config.log.backup_count)         # 7

数量检测配置

# 访问数量检测配置
print(config.quantity_detection.enabled)           # False
print(config.quantity_detection.max_count)         # 1000
print(config.quantity_detection.slow_down_seconds) # 1.0
print(config.quantity_detection.break_on_limit)    # True
print(config.quantity_detection.redis_key_prefix)  # workflow_success

获取配置实例

# 获取配置实例（单例）
cfg = get_config()

# 使用配置实例
print(cfg.debug)
print(cfg.database.host)

环境变量优先级

配置加载优先级（从高到低）：

1. 环境变量
2. .env 文件
3. 代码默认值

示例

# 代码默认值
debug: bool = False

# .env 文件
WORKFLOW_DEBUG=true

# 环境变量
export WORKFLOW_DEBUG=false

# 最终值：false（环境变量优先级最高）

最佳实践

1. 敏感信息

# ✅ 使用环境变量存储敏感信息
DB_PASSWORD=${DB_PASSWORD}
REDIS_PASSWORD=${REDIS_PASSWORD}

# ❌ 不要在 .env 文件中硬编码敏感信息
DB_PASSWORD=secret123

2. 环境区分

# 开发环境
WORKFLOW_ENVIRONMENT=development
WORKFLOW_DEBUG=true
LOG_LEVEL=DEBUG

# 生产环境
WORKFLOW_ENVIRONMENT=production
WORKFLOW_DEBUG=false
LOG_LEVEL=INFO

3. 配置验证

from hsxworkflow import config

# 验证配置
if config.debug:
    print("运行在调试模式")

if config.environment == "production":
    print("运行在生产环境")

下一步

现在你已经了解了配置系统的使用方法，可以继续学习：

• 最佳实践 - 学习开发建议和常见问题