python项目跟目录app or src

目录

• src/ 布局的核心机制
• 为什么 src/ 不出现在路径里？
• src/ 布局存在的意义
• 总结

app/ vs src/ 的区别
方案 典型场景 示例项目
app/ FastAPI / Flask 等 Web 应用，直接作为包名使用 FastAPI 官方模板、你们现有项目
src/ Python 库/SDK 发布场景，src/ 下再放真正的包名 src/mylib/ → pip install mylib 。 如果是SDK，业务代码引用SDK的时候，需要 加上 src包路径吗

不需要。src/ 不是包名，它不会出现在 import 路径中。

src/ 布局的核心机制

以一个 SDK 项目为例：

my-sdk/
├── src/
│   └── mylib/            ← 这才是真正的 Python 包
│       ├── __init__.py
│       ├── client.py
│       └── utils.py
├── pyproject.toml
└── tests/

安装后的 import 写法：

# 正确 ✅ —— 直接用包名
from mylib.client import MyClient

# 错误 ❌ —— src 不是包的一部分
from src.mylib.client import MyClient

为什么 src/ 不出现在路径里？

关键在于打包配置（pyproject.toml 或 setup.py）会告诉 Python 包管理工具："去 src/ 目录下找包"：

# pyproject.toml (setuptools 示例)
[tool.setuptools.packages.find]
where = ["src"]       # ← 告诉 setuptools 从 src/ 下发现包

或 setup.py 的写法：

setup(
    package_dir={"": "src"},    # ← 根包指向 src/
    packages=find_packages(where="src"),
)

执行 pip install . 或 pip install mylib 后，Python 只把 mylib 装进 site-packages/，src/ 这层目录完全被跳过。

src/ 布局存在的意义

它解决的是开发阶段的一个陷阱：

布局	风险
flat（无 src）	项目根目录直接包含包，python 在根目录运行时会自动把 . 加入 sys.path，即使没安装也能 import 成功，可能掩盖打包配置问题
src 布局	包在 src/ 下，必须先 pip install -e .（开发模式安装）才能 import，强制你验证打包配置是否正确

总结

问题	答案
业务代码引用 SDK 时要加 src 吗？	不需要，直接 from mylib import xxx
src/ 是什么角色？	只是源码的物理隔离目录，不参与 import 路径
谁来处理这个映射？	打包工具（setuptools/poetry/hatch）通过配置跳过 src/
你们的 Web 项目需要 src/ 吗？	不需要，app/ 布局更适合 FastAPI Web 应用，直接 from app.xxx import yyy