迁移至Python Monorepo：基于pyproject.toml的项目结构规划

1. pyproject.toml 配置选择与导入路径处理 #

全局 vs 子包单独配置 #

• 如果各子项目关联性强、依赖重叠度高，用全局pyproject.toml更高效，能统一管理公共依赖，减少重复配置。
• 如果子项目独立性高（比如需单独发布、依赖差异大），每个子包单独配置pyproject.toml更合适，能实现依赖隔离，灵活控制每个子包的版本和发布流程。

保留原导入路径的方法 #

全局配置时，要维持from foo import helper的导入方式，无需加src前缀，可在根目录的pyproject.toml中配置packages路径：

[tool.poetry]
name = "monorepo-root"
# 其他全局配置...

[tool.poetry.packages]
include = ["foo", "bar"]
from = "src"

这样Poetry会把src目录下的foo、bar识别为顶层包，导入时无需指定src前缀。

子包单独配置的可行性 #

完全可取，尤其适合子包需要独立迭代、发布的场景。配合Poetry 1.2+的Workspaces功能，根目录可保留一个全局pyproject.toml定义工作区，统一管理跨子包的操作（比如批量安装依赖），每个子包的pyproject.toml负责自身的依赖、版本等配置。

2. Dockerfile 与主脚本组织建议 #

目录结构规范 #

推荐采用“子项目独立目录+统一Docker管理”的结构：

monorepo/
├── pyproject.toml
├── src/
│   ├── foo/
│   │   ├── main.py       # foo项目的主脚本
│   │   └── pyproject.toml
│   └── bar/
│       ├── main.py       # bar项目的主脚本
│       └── pyproject.toml
└── docker/
    ├── foo/
    │   ├── Dockerfile
    │   └── Dockerfile.dev  # 开发环境镜像配置
    └── bar/
        └── Dockerfile

• 主脚本：不再堆在根目录，放到对应子项目的目录下，避免根目录混乱，方便定位。
• Dockerfile：按子项目分类存放在docker/的子文件夹中，多环境镜像可通过后缀区分（如Dockerfile.dev、Dockerfile.prod）。

可选优化 #

根目录可新增一个入口脚本（如start.py），通过命令行参数指定启动哪个子项目，方便统一调度：

import sys
import subprocess

if __name__ == "__main__":
    service = sys.argv[1]
    subprocess.run(["python", f"src/{service}/main.py"])

3. Poetry 构建多项目Monorepo最佳实践 #

• 用Workspaces统一管理：在根目录pyproject.toml中定义工作区，关联所有子包路径，支持批量安装依赖、统一运行脚本：

  [tool.poetry.workspaces]
  members = ["src/foo", "src/bar"]
  

• 统一公共依赖版本：在根目录pyproject.toml中定义公共依赖，子包通过^或>=引用统一版本，避免版本冲突：

  # 根目录配置
  [tool.poetry.dependencies]
  python = "^3.10"
  requests = "^2.31.0"
  
  # 子包配置
  [tool.poetry.dependencies]
  requests = { workspace = "^" }
  

• 单独发布子包：若需发布单个子包，执行poetry publish --directory src/foo即可，无需切换目录。
• 依赖隔离与虚拟环境：根目录的虚拟环境可包含所有子包依赖，也可为单个子包单独创建虚拟环境（poetry install --directory src/foo）。
• 避免循环依赖：将跨子包的公共代码提取为独立子包（如src/common），减少子包间的直接循环依赖。
• 规范脚本命令：在根目录或子包的pyproject.toml中定义常用脚本，方便快速执行任务：

  [tool.poetry.scripts]
  start-foo = "foo.main:run"
  start-bar = "bar.main:run"
  

内容的提问来源于stack exchange，提问作者richrliu