AI 应用后端工程化：从原型到可交付系统 · 第 15 篇 · 第四章 · 会话与安全
从 UTF-8 读取失败和依赖版本整理出发，说明边界问题为什么总在换环境、换文件、换版本时爆发。
有些故障没有宏大架构背景：Windows 上打开中文文本变成乱码，依赖升级后一个方法突然消失，开发机正常而容器启动失败。这类问题常被当作“小修”，却最容易在环境变化时阻塞整个系统。
兼容性债务来自未写明的假设。默认编码、浮动版本和供应商私有字段都在说“环境应该和我现在一样”。工程化就是把这些隐含假设逐步变成显式契约。
文本没有天然编码
文件只是一串字节。open(path) 使用的默认编码取决于系统和运行环境，同一文件在两台机器上可能得到不同结果。
flowchart LR
Bytes[文件字节] --> Detect{编码来源}
Detect -->|协议声明| Declared[明确编码]
Detect -->|BOM| Bom[BOM 检测]
Detect -->|无信息| Policy[产品策略]
Declared --> Decode[严格解码]
Bom --> Decode
Policy --> Decode
Decode --> Text[Unicode 文本]
Decode -->|失败| Error[可解释错误]
对自己生成的文本，统一使用 UTF-8 并明确声明。对用户上传内容，可以支持有限编码检测，但不要用 errors="ignore" 悄悄丢字符。错误位置和候选编码应进入处理报告，让用户能修复源文件。
from pathlib import Path
def read_utf8_text(path: Path) -> str:
try:
return path.read_text(encoding="utf-8")
except UnicodeDecodeError as exc:
raise ValueError(
f"文件不是有效 UTF-8，错误字节位置：{exc.start}"
) from exc
编码策略要贯穿读取、数据库连接、JSON 响应、日志和测试夹具。只修一个 Loader，其他边界仍可能重新损坏字符。
依赖版本是运行契约
只写 library>=1.0 意味着明天安装时可能得到行为不同的 2.0。完全锁死所有传递依赖又会让安全升级困难。常见做法是维护人类评审的直接依赖范围，再生成可复现的锁文件；升级通过专门变更和测试完成。
依赖列表还应区分运行、开发和可选功能。生产镜像不需要测试工具，基础安装也不应因为一个不使用的 PDF 解析器无法编译而失败。
大模型生态变化快，同一框架的模型类型、序列化方法和导入路径经常调整。适配代码集中在边界层，比在几十个 Service 中直接导入框架类型更容易升级。
“在我机器上正常”的三层原因
第一层是平台差异：路径分隔符、大小写、换行和编码。第二层是运行时差异：Python 版本、系统库、时区。第三层是外部服务差异：模型版本、数据库扩展和 API 响应。
CI 至少固定主运行环境，并对明确支持的平台跑关键测试。容器镜像应锁定基础版本，启动日志记录不敏感的运行时信息。遇到问题先比较环境清单，而不是立即修改业务逻辑。
兼容层不能永远增长
支持旧版与新版接口时，可以在一个适配函数中检测能力并归一化。但兼容层要有删除条件：最低版本提升到何时、哪些用户仍依赖旧路径、测试何时可以移除。否则每次升级都增加一个分支，几年后没人知道哪些分支还能发生。
def model_to_dict(value) -> dict:
if hasattr(value, "model_dump"):
return value.model_dump()
if hasattr(value, "dict"):
return value.dict()
raise TypeError(f"unsupported model type: {type(value).__name__}")
这种适配应集中并有两组测试。业务层只调用 model_to_dict，无需了解版本历史。
一个看似无害的失败
文本加载器在 Linux 测试数据上全部通过，生产用户上传 GBK 导出的日志后任务失败。Worker 自动重试五次，每次都重新下载文件和占用队列，最终只显示“处理超时”。根因不是性能，而是不可重试的编码错误没有被分类。
修复要同时覆盖明确解码、错误分类、用户提示和停止重试。只加一次 UTF-8 参数解决了当前样本，却不等于完整策略；至少要说明系统支持什么，不支持时如何失败。
扩展到 API 与数据格式
兼容性方法同样用于接口版本、数据库 Schema 和事件消息：明确版本、集中适配、保存回归样本、设定淘汰计划。练习可以在 Windows 与 Linux 容器分别读取包含中文和不同换行的文件，再模拟两个 Pydantic 版本的序列化接口，确认业务输出一致。
两次小提交背后的大问题
它们没有增加用户功能，却降低了环境变化带来的不确定性。长期维护中，这类提交与新功能同样重要。