# 设计理念

这一页解释 better-commons **为什么这样设计**。它不教你「怎么用」，而是讲清楚每个
模块背后的取舍，帮助你判断何时使用、如何扩展。

## 整体原则

> **把重复的「基建」收敛成小而美的工具，配置驱动一切。**

better-commons 的每个模块都解决一类几乎每个业务项目都会遇到的基础问题：
配置、日志、外部 API、安全、可视化、性能度量。它们保持**零或极少的框架耦合**，
你可以只取其中一个模块用在自己的项目里。

## 配置：为什么是 XML + 环境变量覆盖

### Hadoop 风格 XML

配置采用 `<configurations><property><name>/<value>` 的格式，直接来自 Hadoop 生态。
选择它而不是 `.ini` / `.yaml`，是因为：

- **结构简单、可注释**：`<description>` 字段天然承载说明，适合当配置模板直接给团队评审；
- **多文件覆盖语义自然**：模板 + 私有覆盖文件的组合，与「三明治」配置实践一致；
- **已有生态心智**：服务端背景的开发者对这套格式零学习成本。

### 环境变量覆盖

配置键 `my.api.port` → 环境变量 `MY_API_PORT`，规则简单可预测：
大写 + 点转下划线。这带来一个关键能力——**同一份代码，本地用文件，生产用环境变量**，
密钥和差异配置永远不落盘。

## 加密：为什么是「明文 + 密文」双路径

`EncryptFile` 最核心的设计是**同时持有明文路径和密文路径**，而不是只持有密文：

```python
f = EncryptFile("plain.txt", "1234.dat", key)
```

- **开发期**：读写明文，改动即时可见，`git diff` 可读；
- **发布期**：删除明文只留密文，`read_text()` 仍透明工作；
- **同步判定**：用「明文 mtime 是否新于密文」做快路径，必要时再逐字节比对，
  避免每次读取都全量解密。

这个设计让「安全发布」和「开发体验」不再是二选一。密钥由调用方传入而非内置存储，
也避免了「钥匙和锁放在一起」的安全隐患。

## 大模型客户端：对齐 OpenAI 生态

`ChatClient` 没有自己发明协议，而是**对齐 OpenAI 兼容接口**（`/chat/completions`、
`/completions`），因此能无缝对接 vLLM、TGI、DeepSeek API 等主流服务：

- **续写 / 对话 / 多轮 / 转发**四类操作覆盖绝大多数场景；
- **结构化输出**通过透传 `response_format` 实现，不做私有封装；
- **响应缓存**：相同 URL + payload 命中 SQLite，批量任务省去重复计费；
- **错误分类**：`ChatError.error_type` 把超时 / 限流 / 敏感内容 / 未知四类错误
  结构化，业务方无需靠字符串匹配。

工厂函数 `create_chat_client` 遵循「配置驱动」原则，把连接参数全部放进 `Config`，
业务代码只关心 `ChatModel` 枚举。

## 日志：structlog 管线，异常自动兜底

日志模块的取舍是**「配置一次，到处舒心」**：

- 统一格式：`时间 - trace_id - 级别 - 文件:行 - 函数() - 消息`；
- **异常自动捕获**：`error` / `critical` 级别在异常上下文中自动带堆栈，
  省去每个调用点手写 `exc_info=True`；
- **trace_id 自动兜底**：没有显式传入也不输出难看的 `None`；
- 控制台彩色 + 文件纯文本，两套格式互不干扰。

## 计时：perf_counter + 多阶段累计

`Timer` 采用单调高精度时钟 `perf_counter`，不受系统时钟调整影响，适合度量耗时。
它继承 `ContextDecorator`，因此同时具备普通对象 / 上下文管理器 / 装饰器三种形态；
同一实例按阶段名累计，`Timer.timers` 类级字典提供全局聚合——「在哪儿慢」一目了然。

## 标注：协议驱动，可插拔

标注模块通过 `RegionLike` 协议定义「区域」的最小契约（`label` + `points`），
而不是绑定某个具体类。任何满足结构要求的对象都可以标注。协议属性声明为
**只读**（`@property`），使 `frozen` 数据类（如 `SimpleRegion`）也能满足协议——
这是「组合优于继承」在类型层面的体现。

## 文档为何按 Diátaxis 组织

本套文档遵循 **Diátaxis** 框架，把内容按「用户意图」而非「模块」划分：

- **教程**：按时间线跟着做，目标是学会（学习导向）；
- **操作指南**：按问题找答案，目标是解决（任务导向）；
- **API 参考**：完整签名，目标是精确（信息导向）；
- **解释**：背后的为什么，目标是理解（理解导向）。

这套组织方式是当前 Python 生态（FastAPI、Pydantic 等）的主流实践，也符合
「先会用、再查 API、最后懂原理」的阅读路径。
