人人都是架构师：2026年如何规划 Python项目

文章主旨：

对于准备认真迭代、会有测试且可能长期维护的 Python 项目，作者主张采用一套稳定的默认外层骨架（pyproject.toml、uv、src/、Ruff、mypy、pytest、Makefile/薄入口），把依赖、环境、质量命令和日常操作收口，减少重复决策，让结构退到背景。

关键要点：

1. 新项目优先固定外层边界与可复现流程，而不是提前设计业务目录；示例骨架包含 .python-version、src/myproject、tests、pyproject.toml、uv.lock、Makefile 等。
2. pyproject.toml 作为项目配置主入口，集中元数据、依赖和工具配置；开发依赖用 [dependency-groups]，不要与 [project.optional-dependencies] extras 混用。
3. uv 负责 Python 版本、环境、依赖、锁文件和命令执行；用 uv init --package、uv add、uv add --dev、uv run ... 缩短环境管理仪式并统一命令。
4. src/ 布局的核心价值是守住 import/打包边界，不是“更专业”；包内按真实职责生长，避免提前建 services/repositories/utils 等空层，utils 和 constants 不应成为垃圾场。
5. 质量工具固定一套能每天跑的：Ruff lint/format、mypy、pytest；pre-commit 只放快速确定检查，Makefile 提供 fmt/fix/lint/typecheck/test/check 统一入口，完整检查交给 make check 和 CI。

内容结构：

01 先看结果：我更愿意从这套外层骨架开始

先固定外层骨架和边界，不急着建 models/services/utils；示例骨架将项目配置放根目录、可安装包放 src/、测试单列、环境由 lockfile 重建、质量命令有固定入口。

02 pyproject.toml：把“这个项目是什么、依赖什么、工具怎么配”放到一个地方

pyproject.toml 逐渐成为项目配置主要入口，集中 [project] 元数据、运行依赖、开发依赖及 Ruff/mypy/pytest 配置；开发依赖应放 [dependency-groups]，区别于面向使用者的 optional-dependencies extras。配置集中减少“这个到底写在哪”的考古。

03 uv：别再把环境管理拆成一串仪式

uv 将 Python 版本、环境、依赖解析、锁文件和命令执行收拢；通过 uv init --package、uv add、uv add --dev 等建立项目，并用 uv run ... 统一运行工具，让团队成员不必关心虚拟环境是否激活。

04 src/ 布局：它解决的是 import 边界，不是“看起来更专业”

src/ 对可安装、被测试、被引用的包有价值，避免项目根目录天然成为包代码捷径；它减少开发环境掩盖导入问题的风险，但不等于测试最终 wheel 的字节级同一份内容，发布包可再加 build + 安装产物测试。

05 包内部怎么分：先按职责长，不要一上来搭三层架构

业务目录等职责真正出现第二、第三个文件时再拆；utils 能不建就先不建，helper 应靠近所服务的业务概念；config.py 值得早固定边界，用 pydantic-settings 集中环境变量读取、默认值和类型校验，.env 应进 .gitignore。

06 Ruff + mypy + pytest：质量工具别堆，固定一套能每天跑的

Ruff 合并 lint、import 排序、现代化检查和 formatter；mypy 可从 strict 开始或逐步收紧，目标是长期可运行；pytest 仍适合默认测试，测试目录可镜像源码职责但不必机械复制，mock 要留关键真实集成测试。

07 pre-commit：适合挡住低级问题，不要把整个 CI 塞进去

pre-commit 适合在 commit 前跑足够快、足够确定的检查，如 Ruff fix + format；完整 mypy、pytest、集成测试应交给统一检查命令和 CI，避免 commit 过慢导致 hook 被绕过。

08 Makefile：不是必须，但“统一入口”很值

薄 Makefile 把常见命令收口为 fmt、fix、format-check、lint、typecheck、test、check；检查不偷偷改文件，修复用 make fix，提交前或 CI 用 make check。重点不是 Make，而是日常操作有稳定入口。

09 十分钟搭完：一套更自洽的 bootstrap

初始化流程示例：uv init --package、uv add、uv add --dev、建 tests、安装 pre-commit，再补 pyproject.toml 工具配置、.pre-commit-config.yaml、Makefile、.gitignore；跑 make check 变绿，说明项目已有可复现、可检查、可继续生长的起点。

10 什么先别加：结构最容易死在“为以后准备”

不要提前建整套业务分层、不要 __init__.py 变总出口、不要 constants.py 垃圾场、不要把目录叠到路径难读、不要把“应该跑”当自动化；让结构跟着代码长，机制比提醒可靠。

11 几个最容易踩的坑

常见坑包括：把 optional dependencies 当 dev dependencies；为“现代”强上 src/；第一天就建 utils；一上来 strict 到项目跑不动；把 format 当 check；文档、CI、本地命令三套不一致。

12 写在最后

好的骨架应让人忘掉骨架；值得花脑子的应是业务拆分、数据流、边界、错误处理、测试价值，而不是每次重想 requirements 还是 pyproject、环境名、测试位置、Ruff/Black/isort 怎么拼。默认答案不是教条，脚本项目或已有稳定工具链无需推翻。

文章总结：

作者建议：对准备长期维护的 Python 项目采用稳定默认骨架，让 uv sync 和 make check 等命令可复现、可统一，把注意力还给真正要交付的内容；但默认不是禁令，简单脚本或已有工具链可按需例外。

数据STUDIO

查看原文：人人都是架构师：2026年如何规划 Python项目

文章来源：

数据STUDIO

扫码关注公众号