设计与架构¶

本页面介绍 zerodep 的架构思路：仓库为什么采用当前结构、模块如何按复杂度分层、以及重构工作的整体进展。

关于项目的核心价值观（零依赖、单文件、正确性优先），参见设计理念。关于具体的跨模块实现模式，参见内部约定。

重构理念¶

zerodep 不是传统意义上的 Python 包。它不提供统一的运行时，不强制共享 import 树，也不追求单一的 pip install 入口。模块被设计为可以复制到其他项目中独立使用。

因此，这个仓库不需要、也不应该追求传统包的重构方式：抽取共享核心、构建内部工具层、或强制使用公共基类。

仓库真正需要的是仓库级的规范化。现有代码并不"烂"——真正的问题在于，许多模块在解决相同问题（sibling import、子进程执行、颜色检测、资源清理）时采用了略有不同的写法。重构的目标不是消灭这些重复——在单文件架构下，适度重复是健康的——而是让重复的模式变得可预测。

核心原则¶

以下四条原则指导 zerodep 的所有重构和架构决策。

1. 保持单文件契约¶

任何模块都不应要求从共享内部包中导入。以下做法被明确排除：

• 创建 zerodep/_core 或共享工具层
• 将模块改造为基于公共库的薄包装
• 任何导致复制出来的单文件无法独立运行的变更

2. 先标准化写法，再考虑抽象¶

最高优先级的工作不是"消灭重复代码"，而是"让重复代码采用相同的约定"。具体来说：

• 相同问题用相同结构解决
• 相同能力用相同命名
• 相同的 fallback 路径产出相同的错误语义

这样可以显著降低维护成本，同时不破坏单文件设计。

3. 大模块先做内部整形，再考虑跨模块抽象¶

对于 httpclient、runner、scheduler 这类子系统级模块，最有价值的重构是内部的：

• 更清晰的阶段边界
• 更容易审计的状态机
• 更明显的 sync/async 对照关系
• 更可检查的 cleanup 路径

跨模块提取（共享 helper、公共基类）排在后面，甚至可能永远不做。

4. 把重复模式当作仓库资产维护¶

仓库明确维护一套规范模式——不是作为共享代码，而是作为共享约定：

• 可选 sibling import
• 子进程执行
• 终端颜色检测
• Sync/async API 镜像
• Cleanup 语义（三级分类）
• 错误类型设计
• 大模块内部分层

这些模式在内部约定中有详细描述，是所有贡献者的参考基线。

模块复杂度分层¶

并非所有 zerodep 模块都有相同的复杂度和维护负担。仓库将模块分为三个层级。

简单工具模块¶

小型、聚焦的模块，解决一个边界清晰的问题。通常只有一个入口，没有内部状态机，错误面很小。

中等功能模块¶

功能更丰富的模块，有多个入口或较复杂的解析逻辑。可能涉及内部数据结构，但不管理长生命周期状态或并发执行。

子系统模块¶

本质上是压缩后的子系统：管理生命周期、处理并发、维护连接池或协调多个内部阶段。这类模块对内部结构的要求更严格，审查也更谨慎。

这种分层有助于明确预期：对 dotenv 的修改和对 scheduler 的修改，审查标准是不同的。

重构路线图¶

重构工作按风险和影响分为三个层级。

Tier 1 -- 规范化（已完成）¶

低风险、高收益的规范化工作。此层级所有项目均已完成。

Tier 2 -- 核心模块内部重构（已完成）¶

对三个最大子系统模块进行内部结构改进。此层级所有项目均已完成。

Tier 3 -- 仓库级治理（已完成）¶

形式化贡献者规范，增加边界行为测试覆盖。此层级所有项目均已完成。

延伸阅读¶

• 内部约定 -- Tier 1 标准化产出的详细模式规范
• 设计理念 -- 项目核心价值观以及 zerodep 的适用与不适用场景