wehub-resource-sync
580 lines
24 KiB
Markdown
580 lines
24 KiB
Markdown
# 配置管理使用说明
|
||
|
||
MyBoot 使用 [Dynaconf](https://www.dynaconf.com/) 管理配置，支持 YAML 文件、多文件合并、环境变量覆盖与远程配置文件。实现见 `myboot/core/config.py`。
|
||
|
||
## 1. 快速开始
|
||
|
||
在项目根目录或 `conf/` 目录放置 `config.yaml`，应用启动时自动加载：
|
||
|
||
```yaml
|
||
# conf/config.yaml
|
||
app:
|
||
name: "MyBoot App"
|
||
version: "0.1.0"
|
||
|
||
server:
|
||
port: 8000
|
||
reload: false
|
||
|
||
logging:
|
||
level: "INFO"
|
||
```
|
||
|
||
代码中读取：
|
||
|
||
```python
|
||
from myboot.core.config import get_settings, get_config, get_config_bool
|
||
|
||
# 点号路径（推荐）
|
||
port = get_config("server.port", 8000)
|
||
debug = get_config_bool("app.debug", False)
|
||
|
||
# Dynaconf 对象
|
||
settings = get_settings()
|
||
name = settings.app.name # 属性访问
|
||
port = settings.get("server.port") # 与 get_config 等价
|
||
```
|
||
|
||
通过 `create_app` 创建应用时，配置挂在 `app.config` 上，与全局 `get_settings()` 为同一实例（首次初始化后）：
|
||
|
||
```python
|
||
from myboot import create_app
|
||
|
||
app = create_app(name="我的应用", config_file="conf/config.yaml")
|
||
port = app.config.get("server.port", 8000)
|
||
```
|
||
|
||
## 2. 配置文件位置与合并
|
||
|
||
### 2.1 自动发现的文件（按加载顺序）
|
||
|
||
Dynaconf **按列表顺序加载**，**后加载的文件覆盖先加载的同名字段**：
|
||
|
||
| 顺序 | 路径 | 说明 |
|
||
| ---- | -------------------------------------------------------------------------- | ------------------------ |
|
||
| 1 | `{项目根}/config.yaml` 或 `config.yml` | 基底配置 |
|
||
| 2 | `{项目根}/conf/config.yaml` 或 `conf/config.yml` | 覆盖根目录同名键 |
|
||
| 3 | `create_app(config_file=...)` / `get_settings(config_file=...)` 传入的路径 | 覆盖上述文件 |
|
||
| 4 | 环境变量 `CONFIG_FILE` 指向的路径或 URL | **文件来源中优先级最高** |
|
||
|
||
示例：根目录 `server.port: 8000`，`conf/config.yaml` 中 `server.port: 9000`，最终以 **9000** 为准（若未再被 `CONFIG_FILE` 或环境变量键覆盖）。
|
||
|
||
同一嵌套对象（如 `server.cors`）在多个文件中出现时，还会受全局 `merge_enabled` 与 `dynaconf_merge` 影响，见下文 **第 3 节**。
|
||
|
||
### 2.2 指定配置文件
|
||
|
||
```bash
|
||
# 本地文件
|
||
export CONFIG_FILE=/etc/myboot/production.yaml
|
||
|
||
# 远程 URL（会下载到系统临时目录缓存，失败时尝试使用缓存）
|
||
export CONFIG_FILE=https://example.com/config.yaml
|
||
```
|
||
|
||
```python
|
||
from myboot import create_app
|
||
|
||
app = create_app(config_file="conf/config.prod.yaml")
|
||
```
|
||
|
||
远程配置下载逻辑见 `_download_config`：网络失败且存在缓存时回退到缓存文件。
|
||
|
||
### 2.3 内置默认值
|
||
|
||
未在任何 YAML 或环境变量中声明时，使用 `config.py` 中 `default_settings`（节选）：
|
||
|
||
| 键 | 默认值 |
|
||
| -------------------------------- | -------------- |
|
||
| `app.name` | `"MyBoot App"` |
|
||
| `app.version` | `"0.1.0"` |
|
||
| `server.host` | `"0.0.0.0"` |
|
||
| `server.port` | `8000` |
|
||
| `server.reload` | `true` |
|
||
| `server.workers` | `1` |
|
||
| `server.response_format.enabled` | `true` |
|
||
| `logging.level` | `"INFO"` |
|
||
| `scheduler.enabled` | `true` |
|
||
| `scheduler.timezone` | `"UTC"` |
|
||
| `scheduler.max_workers` | `10` |
|
||
|
||
## 3. 字典/列表合并与 `dynaconf_merge`
|
||
|
||
MyBoot 在 `create_settings()` 中启用了 Dynaconf 全局合并：
|
||
|
||
```python
|
||
# myboot/core/config.py
|
||
merge_enabled=True,
|
||
```
|
||
|
||
因此，**多个配置文件**（或带 `@merge` 的环境变量）加载到**同一嵌套字典/列表**时，默认会**深合并**，而不是简单地把后一个文件里的整块 YAML 盖掉前一个。
|
||
|
||
### 3.1 默认合并行为（`merge_enabled=True`）
|
||
|
||
| 类型 | 后加载文件中的同路径值 | 结果 |
|
||
| --------------------------------- | ---------------------- | ---------------------------------------- |
|
||
| 标量（`str` / `int` / `bool` 等） | 新值 | **覆盖**旧值 |
|
||
| 字典 | 新键与旧键 | **递归合并**（保留旧文件中未出现的子键） |
|
||
| 列表 | 新元素 | **拼接合并**（可能产生重复项） |
|
||
|
||
**示例**：根目录与 `conf/` 均定义 `server.cors` 时，若后加载文件只改 `allow_origins`，未写 `allow_methods`，合并后仍会保留先前的 `allow_methods`、`allow_headers`。
|
||
|
||
```yaml
|
||
# config.yaml（先加载）
|
||
server:
|
||
cors:
|
||
allow_origins: ["*"]
|
||
allow_methods: ["*"]
|
||
allow_headers: ["*"]
|
||
|
||
# conf/config.yaml（后加载，未使用 dynaconf_merge: false）
|
||
server:
|
||
cors:
|
||
allow_origins: ["http://localhost:3000"]
|
||
```
|
||
|
||
合并结果等价于：
|
||
|
||
```yaml
|
||
server:
|
||
cors:
|
||
allow_origins: ["*", "http://localhost:3000"] # 列表被拼接
|
||
allow_methods: ["*"]
|
||
allow_headers: ["*"]
|
||
```
|
||
|
||
### 3.2 `dynaconf_merge: false` 的作用
|
||
|
||
在需要**整块替换**某个字典（或列表）而不是与旧值合并时，在该字典（或列表）内加上 **`dynaconf_merge: false`**。
|
||
该标记是 Dynaconf 的**合并控制元数据**，不会作为业务配置键出现在 `get_config()` 结果中。
|
||
|
||
| 写法 | 作用范围 |
|
||
| ----------------------------- | ---------------------------------------------------- |
|
||
| 写在某个 **dict / list 内部** | 仅该节点：后加载内容**整体替换**先加载的同级对象 |
|
||
| 写在 **YAML 文件顶层** | 整个后加载文件相对先前来源按「替换」策略处理（慎用） |
|
||
|
||
**示例：用 `false` 完全替换 `server.cors`**
|
||
|
||
```yaml
|
||
# config.yaml
|
||
server:
|
||
cors:
|
||
allow_origins: ["*"]
|
||
allow_methods: ["*"]
|
||
allow_headers: ["*"]
|
||
|
||
# conf/config.prod.yaml（后加载）
|
||
server:
|
||
cors:
|
||
allow_origins: ["https://api.example.com"]
|
||
allow_credentials: true
|
||
dynaconf_merge: false # 整块替换 cors，不保留 allow_methods / allow_headers
|
||
```
|
||
|
||
最终 `server.cors` 仅包含：
|
||
|
||
```yaml
|
||
allow_origins: ["https://api.example.com"]
|
||
allow_credentials: true
|
||
```
|
||
|
||
**对比**：若去掉 `dynaconf_merge: false`，后加载文件里未写的 `allow_methods`、`allow_headers` 会**继续保留**，且 `allow_origins` 可能与旧列表**拼接**。
|
||
|
||
### 3.3 `dynaconf_merge: true`
|
||
|
||
显式声明「与已有字典/列表合并」。在 `merge_enabled=True` 时，多数嵌套 dict/list **已默认合并**，一般仅在需要强调或配合 `@merge` 环境变量时使用：
|
||
|
||
```yaml
|
||
server:
|
||
cors:
|
||
allow_origins: ["http://localhost:3000"]
|
||
dynaconf_merge: true
|
||
```
|
||
|
||
环境变量也可使用 Dynaconf 的 `@merge` 标记（TOML/JSON 形式），例如：
|
||
|
||
```bash
|
||
export SERVER__CORS='@merge {"allow_origins": ["http://localhost:3000"]}'
|
||
```
|
||
|
||
### 3.4 何时用 `false`、何时用环境变量
|
||
|
||
| 场景 | 建议 |
|
||
| ------------------------------------------------------------ | ----------------------------------------------------------------------------- |
|
||
| 生产配置要**换一整段** `server.cors` / `logging.third_party` | 后加载 YAML 中对应该段加 `dynaconf_merge: false` |
|
||
| 只改**一两个嵌套字段** | 直接写子键，或 `SERVER__CORS__ALLOW_ORIGINS=...` |
|
||
| 列表不想与旧值拼接 | 对该 list 使用 `dynaconf_merge: false`，或写完整列表并 `false` |
|
||
| 不确定合并结果 | 用 `get_settings().server.cors` 或 `get_config("server.cors")` 在本地打印验证 |
|
||
|
||
### 3.5 注意
|
||
|
||
1. **`dynaconf_merge` 只影响合并策略**，不改变「后加载文件优先」的顺序（见第 2 节）。
|
||
2. **标量字段**始终是覆盖，与 `dynaconf_merge` 无关。
|
||
3. 对**深层嵌套**的精细控制，除 `dynaconf_merge: false` 外，也可用环境变量 `__` 逐键覆盖（见第 5 节环境变量）。
|
||
4. 更多语法见 [Dynaconf 合并文档](https://www.dynaconf.com/merging/)。
|
||
|
||
## 4. 优先级总览
|
||
|
||
从高到低（后者覆盖前者）：
|
||
|
||
```
|
||
环境变量键（如 SERVER__PORT） > CONFIG_FILE 指向的文件 > config_file 参数 > conf/config.yaml > 根目录 config.yaml > default_settings
|
||
```
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[default_settings] --> B[根目录 config.yaml]
|
||
B --> C[conf/config.yaml]
|
||
C --> D[config_file 参数]
|
||
D --> E[CONFIG_FILE]
|
||
E --> F[环境变量 SERVER__PORT 等]
|
||
```
|
||
|
||
## 5. 环境变量
|
||
|
||
### 5.1 规则
|
||
|
||
| 项 | 说明 |
|
||
| ------------ | ----------------------------------------------------------- |
|
||
| 前缀 | **无**（`envvar_prefix=False`），变量名即配置路径的大写形式 |
|
||
| 嵌套分隔符 | **双下划线 `__`**，对应 YAML 中的层级 |
|
||
| 单下划线 `_` | 仅作为**同一层键名**的一部分（如 `keep_alive_timeout`） |
|
||
| 类型 | `env_parse_values=True`，自动尝试解析布尔、数字等 |
|
||
| 未知变量 | `ignore_unknown_envvars=True`，**仅当该键已在配置树中存在时**才接受环境变量覆盖（见下） |
|
||
|
||
#### 已知键限制（`ignore_unknown_envvars=True`）
|
||
|
||
MyBoot 在 `config.py` 中启用了 `ignore_unknown_envvars=True`。环境变量（含 `.env` 加载进 `os.environ` 的项）**不会**凭空新增配置项，只能**覆盖**下列来源里**已经出现过**的键路径：
|
||
|
||
1. 已加载的 YAML（`config.yaml`、`conf/config.yaml`、`CONFIG_FILE` 等）
|
||
2. `config.py` 中 `default_settings` 内置项（如 `app.name`、`server.port`、`logging.level`、`scheduler.timezone` 等）
|
||
|
||
因此：
|
||
|
||
- ✅ `SERVER__PORT=9000` 有效（`server.port` 在默认配置或 YAML 中已有）
|
||
- ❌ `DATABASE__URL=...` **无效**，若 YAML / 默认配置里**没有** `database` 段——变量会进入 `os.environ`，但 **MyBoot 不会读入** `get_config("database.url")`
|
||
- ❌ 任意「只在 `.env` 里出现、YAML 从未声明」的键都会被**静默忽略**
|
||
|
||
**正确做法**：需要靠 `.env` 注入的新配置，先在 YAML 中**声明结构**（值可写占位符），再用环境变量覆盖：
|
||
|
||
```yaml
|
||
# conf/config.yaml — 先声明键结构
|
||
database:
|
||
url: "" # 占位，真实值放在 .env / .local.env
|
||
app:
|
||
secret_key: "" # 敏感项同理
|
||
jobs:
|
||
cleanup_task:
|
||
enabled: true
|
||
```
|
||
|
||
```bash
|
||
# .local.env — 再覆盖
|
||
DATABASE__URL=postgresql://user:pass@127.0.0.1:5432/mydb
|
||
APP__SECRET_KEY=your-local-secret-key
|
||
JOBS__CLEANUP_TASK__ENABLED=false
|
||
```
|
||
|
||
若希望环境变量**无需**在 YAML 预声明即可生效，需修改 `myboot/core/config.py` 将 `ignore_unknown_envvars` 设为 `False`（当前框架默认未开启）。
|
||
|
||
### 5.2 示例
|
||
|
||
| YAML 路径 | 环境变量 |
|
||
| --------------------------- | --------------------------------------------------------- |
|
||
| `app.name` | `APP__NAME=MyApp` |
|
||
| `server.port` | `SERVER__PORT=9000` |
|
||
| `logging.level` | `LOGGING__LEVEL=DEBUG` |
|
||
| `server.keep_alive_timeout` | `SERVER__KEEP_ALIVE_TIMEOUT=60` |
|
||
| `server.cors.allow_origins` | `SERVER__CORS__ALLOW_ORIGINS='["http://localhost:3000"]'` |
|
||
|
||
```bash
|
||
export APP__NAME="生产应用"
|
||
export SERVER__PORT=8080
|
||
export LOGGING__LEVEL=WARNING
|
||
export SCHEDULER__TIMEZONE=Asia/Shanghai
|
||
```
|
||
|
||
**不要**用单下划线表示嵌套层级，例如 `SERVER_PORT` **不会**映射到 `server.port`（除非你在 YAML 里真有名为 `server_port` 的顶层键）。
|
||
|
||
### 5.3 布尔值
|
||
|
||
`get_config_bool` 将字符串视为真：`true`、`1`、`yes`、`on`（不区分大小写）。
|
||
|
||
### 5.4 MyBoot 与 `.env` 的关系（0.2.0 起自动加载）
|
||
|
||
**0.2.0 起 MyBoot 自动加载项目根目录的 `.env` 文件**（通过 Dynaconf 的
|
||
`load_dotenv`），`main.py` 无需再手动调用 `load_dotenv()`。
|
||
|
||
加载语义：
|
||
|
||
- 路径：**项目根目录**（含 `pyproject.toml` 的目录）下的 `.env`；
|
||
- 优先级：**真实环境变量 > `.env` > YAML 配置 > 内置默认值**
|
||
（`dotenv_override=False`：`.env` 不覆盖已存在的真实环境变量，与容器部署习惯一致）；
|
||
- 仍受 **`ignore_unknown_envvars=True`** 约束：`.env` 里的变量名必须对应
|
||
**YAML 或内置默认配置中已声明过的键路径**，否则不会进入 `get_config()`
|
||
（见上文 **5.1 已知键限制**）。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[".env（项目根）"] -->|"框架自动加载"| C["os.environ"]
|
||
B["真实环境变量"] -->|"优先"| C
|
||
C --> D["Dynaconf / MyBoot"]
|
||
E["config.yaml"] --> D
|
||
```
|
||
|
||
**注意：**
|
||
|
||
| 事项 | 说明 |
|
||
| ------------------- | -------------------------------------------------------------------- |
|
||
| 修改 `.env` 后 | 需**重启进程**；不会热更新 |
|
||
| 版本控制 | `.env` 加入 `.gitignore`；可提交 `.env.example` 作模板 |
|
||
| 键必须已声明 | `.env` 中每一项都须在 YAML（或内置默认值）中有对应路径，见 5.1 |
|
||
| 多个 env 文件 | 框架只自动加载根目录 `.env`；需要 `.local.env` 分层时仍可在 main.py 顶部自行 `load_dotenv(..., override=True)` |
|
||
|
||
### 5.5 旧版本（≤0.1.x）手动加载方式
|
||
|
||
0.1.x 不自动加载 `.env`，需在 `create_app()` 之前手动调用：
|
||
|
||
```python
|
||
from pathlib import Path
|
||
from dotenv import load_dotenv
|
||
|
||
load_dotenv(Path(__file__).resolve().parent / ".env")
|
||
|
||
from myboot import create_app # 必须在 load_dotenv 之后
|
||
app = create_app(name="我的应用")
|
||
```
|
||
|
||
升级到 0.2.0 后这段代码可以删除（保留也无害——重复加载是幂等的）。
|
||
|
||
### 5.6 `.env` 文件如何书写
|
||
|
||
`.env` 使用 **dotenv 格式**（不是 YAML）：每行 `键=值`，`#` 开头为注释。**不要**写 `export`（那是 shell 脚本写法）。
|
||
|
||
> **重要**：`.env` 只用于**覆盖**已有配置键，不能代替 YAML 做「首次声明」。未在 YAML / `default_settings` 中出现的键（如仅写 `DATABASE__URL` 而 `config.yaml` 里没有 `database.url`）将被忽略。
|
||
|
||
#### 命名规则（与 MyBoot 一致）
|
||
|
||
- 嵌套配置用 **`__`（双下划线）** 对应 YAML 层级。
|
||
- 键名一般**大写**（与常见约定一致；写入环境后 Dynaconf 会映射到配置树）。
|
||
- 单下划线 `_` 只表示键名的一部分，例如 `KEEP_ALIVE_TIMEOUT`。
|
||
|
||
#### 示例 `.env`（非敏感、可提交 `.env.example`）
|
||
|
||
```bash
|
||
# 应用
|
||
APP__NAME=MyBoot App
|
||
APP__VERSION=0.1.0
|
||
APP__DEBUG=false
|
||
|
||
# 服务
|
||
SERVER__HOST=0.0.0.0
|
||
SERVER__PORT=8000
|
||
SERVER__RELOAD=true
|
||
|
||
# 日志
|
||
LOGGING__LEVEL=INFO
|
||
|
||
# 调度器
|
||
SCHEDULER__ENABLED=true
|
||
SCHEDULER__TIMEZONE=Asia/Shanghai
|
||
```
|
||
|
||
#### 示例 `.local.env`（敏感信息，勿提交 Git）
|
||
|
||
以下变量均要求 `conf/config.yaml`（或根目录 `config.yaml`）中**已有同名路径**；示例见上一节 YAML 占位声明。
|
||
|
||
```bash
|
||
# 覆盖 .env 中的端口（server.port 已在 YAML/默认配置中存在）
|
||
SERVER__PORT=9000
|
||
|
||
# 以下键须先在 YAML 中声明 database.url、app.secret_key
|
||
DATABASE__URL=postgresql://user:password@127.0.0.1:5432/mydb
|
||
APP__SECRET_KEY=your-local-secret-key
|
||
```
|
||
|
||
#### 与 YAML 的对应关系
|
||
|
||
| `.env` 中的写法 | 等价 YAML 路径 | 代码读取 |
|
||
| ------------------------------------- | --------------------------- | ----------------------------------------- |
|
||
| `SERVER__PORT=9000` | `server.port` | `get_config("server.port")` |
|
||
| `LOGGING__LEVEL=DEBUG` | `logging.level` | `get_config("logging.level")` |
|
||
| `DATABASE__URL=...` | `database.url`（**须先在 YAML 声明**） | `get_config("database.url")` |
|
||
| `SERVER__CORS__ALLOW_ORIGINS='["*"]'` | `server.cors.allow_origins` | `get_config("server.cors.allow_origins")` |
|
||
|
||
#### 值的书写建议
|
||
|
||
```bash
|
||
# 字符串含空格或特殊字符时用引号
|
||
APP__NAME="My Boot App"
|
||
|
||
# 布尔（会被 env_parse_values 解析）
|
||
APP__DEBUG=true
|
||
SERVER__RELOAD=false
|
||
|
||
# 数字
|
||
SERVER__PORT=8080
|
||
SCHEDULER__MAX_WORKERS=20
|
||
|
||
# 列表 / 字典建议用 JSON 字符串（尤其嵌套较深时）
|
||
SERVER__CORS__ALLOW_ORIGINS=["http://localhost:3000","http://127.0.0.1:3000"]
|
||
```
|
||
|
||
**错误示例（不会映射到预期配置）：**
|
||
|
||
```bash
|
||
# 错误：单下划线不能表示 server.port
|
||
SERVER_PORT=8000
|
||
|
||
# 错误：dotenv 行内不要用 export
|
||
export SERVER__PORT=8000
|
||
|
||
# 错误：YAML 缩进语法不能用在 .env
|
||
server:
|
||
port: 8000
|
||
|
||
# 错误：YAML 中未声明 database 段时，此行会被 ignore_unknown_envvars 忽略
|
||
DATABASE__URL=postgresql://...
|
||
```
|
||
|
||
**内置默认已存在、可直接用 `.env` 覆盖的键（无需 YAML）** 包括：`app.name`、`app.version`、`server.host`、`server.port`、`server.reload`、`server.workers`、`logging.level`、`scheduler.enabled`、`scheduler.timezone`、`scheduler.max_workers` 等，完整列表见 `myboot/core/config.py` 中 `default_settings`。
|
||
|
||
#### 验证是否加载成功
|
||
|
||
```python
|
||
# 在 load_dotenv 且 create_app 之后执行
|
||
from myboot.core.config import get_config
|
||
|
||
# server.port 在 YAML/默认配置中存在 → 能读到 .env 覆盖值
|
||
print(get_config("server.port"))
|
||
|
||
# database.url 仅当 YAML 中已声明 database.url 时才能读到 .env 值
|
||
print(get_config("database.url", "(YAML 未声明或 .env 未覆盖)"))
|
||
```
|
||
|
||
`echo $DATABASE__URL` 能看到 shell 环境变量，但 **`get_config` 仍可能取不到**——说明键未进入 MyBoot 配置树，请检查 YAML 是否已声明该路径。
|
||
|
||
或在 shell 中确认环境变量已写入（Windows Git Bash）：
|
||
|
||
```bash
|
||
echo $SERVER__PORT
|
||
```
|
||
|
||
## 6. 读取 API
|
||
|
||
| 函数 / 对象 | 用途 |
|
||
| ------------------------------------- | ---------------------------------------- |
|
||
| `get_settings(config_file=None)` | 获取全局 `Dynaconf` 单例 |
|
||
| `get_config(key, default=None)` | 按点号路径取值 |
|
||
| `get_config_str(key, default="")` | 转为字符串 |
|
||
| `get_config_int(key, default=0)` | 转为整数，失败返回 default |
|
||
| `get_config_bool(key, default=False)` | 转为布尔 |
|
||
| `reload_config()` | 清空单例，下次 `get_settings()` 重新加载 |
|
||
| `app.config` | 应用持有的同一配置对象 |
|
||
|
||
```python
|
||
# 运行时修改（仅当前进程内存，不写回文件）
|
||
app.config.set("server.port", 9001)
|
||
```
|
||
|
||
### 6.1 单例注意
|
||
|
||
`get_settings()` 使用模块级单例，**首次调用**时确定加载了哪些文件；之后传入不同的 `config_file` 不会生效，除非先调用 `reload_config()`。
|
||
|
||
```python
|
||
from myboot.core.config import get_settings, reload_config
|
||
|
||
settings = get_settings() # 已固定加载结果
|
||
reload_config()
|
||
settings = get_settings("other.yaml") # 重新加载
|
||
```
|
||
|
||
## 7. 常用配置项
|
||
|
||
与框架行为直接相关的键（完整示例可参考 `conf/config.yaml` 与 README）：
|
||
|
||
### 7.1 `app`
|
||
|
||
| 键 | 说明 |
|
||
| ------------- | -------------------- |
|
||
| `app.name` | 应用名称 |
|
||
| `app.version` | 版本号 |
|
||
| `app.debug` | 调试开关（按需使用） |
|
||
|
||
### 7.2 `server`
|
||
|
||
| 键 | 说明 |
|
||
| -------------------------------------- | ----------------------------------- |
|
||
| `server.host` | 监听地址 |
|
||
| `server.port` | 端口 |
|
||
| `server.reload` | 热重载 |
|
||
| `server.workers` | Worker 数量 |
|
||
| `server.keep_alive_timeout` | Keep-Alive 超时 |
|
||
| `server.graceful_timeout` | 优雅关闭超时 |
|
||
| `server.cors` | CORS 子对象，存在时启用 CORS 中间件 |
|
||
| `server.response_format.enabled` | 是否统一响应格式 |
|
||
| `server.response_format.exclude_paths` | 排除路径列表 |
|
||
|
||
### 7.3 `logging`
|
||
|
||
| 键 | 说明 |
|
||
| --------------------- | -------------------- |
|
||
| `logging.level` | 日志级别 |
|
||
| `logging.format` | 日志格式 |
|
||
| `logging.file` | 日志文件路径（可选） |
|
||
| `logging.third_party` | 第三方库日志级别映射 |
|
||
|
||
### 7.4 `scheduler`
|
||
|
||
| 键 | 说明 |
|
||
| -------------------------- | ---------------------------------- |
|
||
| `scheduler.enabled` | 是否启用调度器 |
|
||
| `scheduler.timezone` | 时区（建议安装 `pytz`） |
|
||
| `scheduler.max_workers` | 调度线程池大小 |
|
||
| `scheduler.on_all_workers` | 多进程时是否在每个 worker 运行调度 |
|
||
|
||
Cron 与任务装饰器详见 [scheduler.md](./scheduler.md)。
|
||
|
||
### 7.5 `jobs`（可选）
|
||
|
||
用于在 `@cron` / `@interval` / `@once` 的 `enabled` 参数中按任务开关：
|
||
|
||
```yaml
|
||
jobs:
|
||
cleanup_task:
|
||
enabled: false
|
||
```
|
||
|
||
```python
|
||
from myboot.core.config import get_config
|
||
|
||
@cron("0 2 * * *", enabled=get_config("jobs.cleanup_task.enabled", True))
|
||
def cleanup(self):
|
||
...
|
||
```
|
||
|
||
## 8. 配置与装饰器、组件
|
||
|
||
- **定时任务**：`enabled=get_config('jobs.xxx.enabled', True)` 在类定义时求值，修改环境变量后需**重启进程**才生效。
|
||
- **日志**：`Application` 构造时调用 `setup_logging(self.config)`，之后改 `logging.*` 需自行处理或重启。
|
||
- **依赖注入**：`get_config` 可在模块级或组件方法内使用；与 `@component` 无冲突。
|
||
|
||
## 9. 最佳实践
|
||
|
||
1. **开发**用 `conf/config.yaml`，**生产**用 `CONFIG_FILE` 或环境变量注入敏感项，避免密钥进仓库。
|
||
2. **嵌套键**统一用 `__` 环境变量，避免与 `snake_case` 字段混淆。
|
||
3. **显式设置** `logging.level`、`scheduler.timezone`，减少环境差异。
|
||
4. 列表、字典类配置在环境变量中优先使用 **JSON 字符串**（如 CORS origins）。
|
||
5. 需要切换配置源时调用 `reload_config()`，或保证在任意 `get_settings()` 之前设置好 `CONFIG_FILE`。
|
||
6. 多文件拆分时保持「基底 → 环境专用」的加载顺序意识：后加载覆盖先加载。
|
||
7. 多文件共用同一嵌套段（如 `server.cors`）且不想**拼接列表、保留旧子键**时，在后加载文件中对应该段添加 **`dynaconf_merge: false`**（见第 3 节）。
|
||
8. 本地敏感项用 **`.local.env`** + `main.py` 中 `load_dotenv`（见第 5.5、5.6 节）；敏感值放 `.env`，但**键名须先在 YAML 声明**（`ignore_unknown_envvars=True`），结构可进 `config.yaml`，秘密不进 Git。
|
||
|
||
## 10. 相关文档与代码
|
||
|
||
| 资源 | 说明 |
|
||
| ---------------------------------------------------- | ---------------------------- |
|
||
| `myboot/core/config.py` | 配置加载与便捷函数 |
|
||
| `conf/config.yaml` | 项目默认配置示例 |
|
||
| [scheduler.md](./scheduler.md) | 调度器配置与 Cron |
|
||
| [dependency-injection.md](./dependency-injection.md) | 组件与 `get_config` 结合示例 |
|