Poetry 依赖管理实战：从 pip 迁移的工程化升级

1. 为什么我三年内把 pip + requirements.txt 全换成了 Poetry

你有没有在凌晨两点对着终端里一串红色报错发呆？ImportError: cannot import name 'X' from 'Y'，查了半天发现是requests升级到了 2.32，而你项目里那个三年没动的urllib3被它悄悄拖到了不兼容版本；或者更经典的一幕：本地跑得好好的，CI 构建失败，日志里只有一行ERROR: No matching distribution found for some-package==1.2.3.post4+dev——你翻遍 PyPI 都找不到这个带+dev后缀的版本，最后发现是同事本地用pip install -e .装了个本地开发版，然后随手pip freeze > requirements.txt，把整个.egg-info目录里的临时构建信息都塞进去了。

这就是传统 Python 依赖管理的真实日常。不是“能不能装上”，而是“装上的到底是不是你真正想要的那个确定状态”。pip是个好工具，但它本质是个安装器，不是协调器；requirements.txt是个快照，但它是静态快照，没有语义、没有约束、没有可重现性保障。我带过的三个团队，平均每个季度都要花 1–2 个人日处理依赖冲突、环境漂移和 CI 失败——直到我们统一迁移到 Poetry。

Poetry 不是另一个“更好用的 pip”，它是从项目初始化那一刻起，就帮你建立一套可验证、可复现、可协作、可交付的依赖契约。它把pyproject.toml变成项目的“宪法”：里面写的不是“我当前装了什么”，而是“我明确需要什么版本范围、在什么环境下生效、哪些是开发专用、哪些必须打包进最终产物”。它用poetry.lock文件固化每一次解析结果，确保无论你在 macOS、Ubuntu 还是 Windows 上运行poetry install，得到的都是完全一致的依赖树——不是靠运气，是靠数学求解。

关键词“Code Improvement”在这里不是指写更炫的算法，而是指通过工程化手段，把原本靠人肉记忆、口头约定、经验踩坑维系的代码协作流程，变成一条有明确规则、自动校验、零歧义的流水线。Poetry 就是这条流水线上最关键的那台校准仪。它不改变你写 Python 的方式，但它彻底改变了你交付 Python 项目的方式。下面我会带你从零开始，用一个真实电商后台服务的迭代场景，手把手走完 Poetry 的完整生命周期——不是概念堆砌，是每一步都告诉你“为什么这么写”“不这么写会怎样”“别人踩过什么坑”。

2. Poetry 的核心设计哲学与底层机制拆解

2.1 它为什么能解决“依赖地狱”，而不是制造新问题？

很多开发者第一次接触 Poetry 时会困惑：“它和 pipenv 有什么区别？”“为什么不用 conda？”“我用 venv + pip install -r 已经很稳了啊。”这些疑问背后，是对“依赖管理”本质的误读。真正的痛点从来不是“装不上包”，而是“装上了，但不是我想要的那个精确组合”。

Poetry 的破局点，在于它把依赖解析（dependency resolution）从“尽力而为”升级为“约束满足（Constraint Satisfaction）”。这听起来很学术，但落地到操作层面，就是三件具体的事：

1. 声明式而非命令式：你在pyproject.toml里写的是requests = "^2.28.0"，这不是“请安装 2.28.0 版本”，而是“请安装满足>=2.28.0, <3.0.0的最新兼容版本”。Poetry 会基于这个约束，结合所有其他包的约束（比如django = "4.2.*"要求sqlparse >=0.2.2），用 SAT 求解器（具体是resolvelib库）计算出全局唯一最优解。它不会因为requests先装就优先满足它，再让django勉强适配；它会同时考虑所有约束，找到那个能让所有人握手言和的版本组合。

2. 锁定文件即契约：poetry.lock不是pip freeze的简单输出。它记录的不是“我当前环境里有哪些包”，而是“Poetry 在pyproject.toml约束下，经过完整求解后，确认的、可复现的、带完整哈希校验的依赖图谱”。里面包含每个包的 exact version、source（PyPI / git / local path）、checksum（SHA256）、以及它所依赖的子包列表。这意味着：

   • 你git commit了poetry.lock，就等于向团队承诺：“只要用 Poetry 安装，结果必然和我本地一致”；
   • CI 服务器poetry install时，会严格比对poetry.lock中的 checksum，任何篡改或网络污染都会被立即拦截；
   • 你删掉venv重来，只要poetry.lock不变，结果就绝对不变。

3. 环境隔离与作用域分离：Poetry 默认为每个项目创建独立的虚拟环境（路径在~/.cache/pypoetry/virtualenvs/下，按项目哈希命名），且完全不依赖系统python或用户手动激活的venv。你执行poetry run python app.py，Poetry 会自动定位并激活该项目专属环境。更重要的是，它支持group机制：你可以定义[tool.poetry.group.dev.dependencies]和[tool.poetry.group.test.dependencies]，让poetry install默认只装生产依赖，而poetry install --with dev,test才装开发和测试依赖。这直接解决了requirements-dev.txt和requirements-prod.txt手动维护易出错的问题。

提示：很多人误以为 Poetry 的 lock 文件是“锁死所有版本”，这是误解。poetry.lock锁定的是求解结果，不是pyproject.toml的约束。当你修改pyproject.toml中的版本约束（如把^2.28.0改成^2.30.0），再运行poetry update，Poetry 会重新求解并生成新的poetry.lock。它保证的是“约束 → 结果”的确定性，而非“永远不动”。

2.2 与 pip + requirements.txt 的关键差异对比

这个表格不是为了贬低 pip，而是说明 Poetry 的定位：它是一个面向现代 Python 工程实践的集成工作流，把原本需要多个工具、多份配置、多套约定才能完成的事，收束到一个声明式文件和一组语义清晰的命令里。它的价值，不在单点功能更强，而在整体协作成本的断崖式下降。

2.3 为什么它值得你放弃“够用就好”的惯性？

我见过太多团队在“够用就好”的思维下付出隐性代价：

• 新人上手慢：新同事拿到项目，第一件事是pip install -r requirements.txt，结果报错，查半天发现要先pip install -r requirements-dev.txt，再pip install -e .，最后还要手动设置PYTHONPATH；
• CI/CD 不稳定：CI 脚本里写pip install -r requirements.txt，但某天 PyPI 上some-package的1.2.3版本被 yanked（撤回），CI 突然全挂，排查耗时半天；
• 安全审计难：pip list输出几百行，pip show package查依赖树，想确认django是否间接引入了有漏洞的jinja2，得手动一层层pip show，效率极低；
• 发布流程割裂：setup.py里写的install_requires和requirements.txt里写的版本经常不一致，导致打包后线上运行报ModuleNotFoundError。

Poetry 用一套机制同时解决这些问题：pyproject.toml是唯一真相源；poetry.lock是可验证的交付物；poetry install是确定性的环境重建；poetry audit（需插件）可直接扫描已知漏洞。它不增加复杂度，而是把原本分散在文档、Wiki、团队记忆里的“潜规则”，显性化、自动化、强制化。这正是“Code Improvement”最务实的体现——不是追求技术炫技，而是消灭重复劳动和人为失误。

3. 从零开始：一个电商后台服务的 Poetry 实战全流程

3.1 环境准备与 Poetry 安装（避开最常见陷阱）

Poetry 官方推荐用curl -sSL https://install.python-poetry.org | python3 -安装，但这是新手最容易栽跟头的第一步。原因有二：一是该脚本会尝试修改你的 shell 配置文件（如~/.bashrc），如果你用的是 zsh 或 fish，它可能失效；二是它默认安装到~/.local/bin，而该路径未必在你的$PATH中。

我建议采用更可控的方式：

# 1. 确保 Python 3.8+ 已安装（Poetry 1.4+ 要求 Python 3.8+） python3 --version # 应输出 3.8.x 或更高 # 2. 使用 pipx 安装（强烈推荐！pipx 是专为安装 Python CLI 工具设计的，隔离干净） pip install pipx pipx ensurepath # 这会把 pipx bin 目录加入 PATH，通常需要重启终端或 source ~/.bashrc pipx install poetry # 3. 验证安装 poetry --version # 应输出类似 Poetry (version 1.7.1)

注意：pipx是关键。它把 Poetry 安装在一个独立的虚拟环境中，完全不污染你的系统 Python 或项目环境。你以后升级 Poetry（pipx upgrade poetry）也不会影响任何项目。很多团队踩坑就是因为直接pip install poetry，结果 Poetry 的依赖和项目依赖冲突，导致poetry命令本身报错。

安装完成后，务必设置两个关键配置，否则你会在后续协作中遇到麻烦：

# 设置 Poetry 使用虚拟环境的存储位置（避免默认的 ~/.cache/pypoetry/virtualenvs/ 过于隐蔽） poetry config virtualenvs.path "$HOME/.venvs" # 设置 Poetry 默认使用项目目录下的虚拟环境（而非全局路径），便于 IDE 识别 poetry config virtualenvs.in-project true

这两行配置意味着：当你在项目根目录执行poetry init，Poetry 会自动在项目目录下创建.venv文件夹存放虚拟环境。这对 VS Code、PyCharm 等 IDE 极其友好——它们能自动检测到.venv并启用对应解释器，无需手动配置。

3.2 初始化项目：pyproject.toml的每一行都在说什么？

我们以一个真实的电商后台服务为例：ecommerce-api，它需要提供商品查询、订单创建、支付回调等接口，技术栈是 FastAPI + SQLAlchemy + Redis。

进入空目录，执行：

mkdir ecommerce-api && cd ecommerce-api poetry init

Poetry 会启动交互式向导，逐项询问：

• Package name：ecommerce-api（回车确认）
• Version：0.1.0（语义化版本，初始用 0.x 表示开发中）
• Description：A backend API for e-commerce services
• Author：Your Name <you@example.com>（按实际填写）
• License：MIT（回车确认）
• Compatible Python versions：^3.9（表示>=3.9.0, <4.0.0，我们项目要求 Python 3.9+）

最关键的是依赖部分：

• Would you like to define your main dependencies interactively?：输入y
• Search for a package：输入fastapi，Poetry 会搜索 PyPI 并列出匹配项
• Enter the version constraint：输入^0.110.0（FastAPI 0.110.x 是当前稳定版，^表示允许小版本更新）
• Search for a package：继续输入sqlalchemy，版本填^2.0.0
• Search for a package：输入redis，版本填^4.6.0
• Search for a package：输入pydantic，版本填^2.6.0（注意：FastAPI 0.110 要求 Pydantic 2.x）

全部添加完毕后，Poetry 会生成pyproject.toml。现在，打开它，我们逐段解读这个“项目宪法”：

[build-system] requires = ["poetry-core"] build-backend = "poetry.core.masonry.api" # 这是 PEP 517 标准要求，告诉 pip “用 poetry-core 来构建这个项目”

[tool.poetry] name = "ecommerce-api" version = "0.1.0" description = "A backend API for e-commerce services" authors = ["Your Name <you@example.com>"] license = "MIT" readme = "README.md" # 这些是项目元数据，会被打包进 wheel 中

[tool.poetry.dependencies] python = "^3.9" fastapi = "^0.110.0" sqlalchemy = "^2.0.0" redis = "^4.6.0" pydantic = "^2.6.0" # 这是核心！所有生产环境必需的依赖。注意 python 也在这里声明，Poetry 会据此选择合适的 Python 解释器

[tool.poetry.group.dev.dependencies] pytest = "^7.4.0" black = "^23.10.0" isort = "^5.12.0" # 这是开发组依赖。Poetry 会自动创建 [tool.poetry.group.dev] 区块。`poetry install` 默认不装它们。

[tool.poetry.scripts] start = "ecommerce_api.main:app" # 这是 CLI 脚本定义。运行 `poetry run start` 就等价于 `python -m ecommerce_api.main`，非常方便

现在，执行poetry install。Poetry 会：

1. 检查pyproject.toml中的python = "^3.9"，查找本地已有的 Python 3.9+ 解释器（如果没有，会提示你安装）；
2. 在项目根目录创建.venv文件夹（因为我们设置了virtualenvs.in-project true）；
3. 基于pyproject.toml中的依赖约束，调用求解器计算最优版本组合；
4. 下载并安装所有包（包括fastapi,sqlalchemy等）到.venv中；
5. 生成poetry.lock文件，记录所有包的精确版本和 checksum。

实操心得：poetry install后，立刻检查poetry.lock文件是否生成。如果没生成，说明求解失败（比如约束冲突），Poetry 会报错。此时不要慌，运行poetry show --tree查看当前已解析的依赖树，或poetry check验证pyproject.toml语法。最常见的错误是版本约束写得太死（如fastapi = "==0.110.0"），导致与其他包冲突。

3.3 日常开发：依赖增删、环境管理与脚本执行

添加新依赖（例如添加数据库迁移工具 Alembic）

业务需求：需要为 PostgreSQL 数据库添加自动迁移能力。

# 方式一：交互式添加（推荐给新手） poetry add alembic # 方式二：指定版本约束（更精确） poetry add alembic@^1.13.0 # 方式三：添加到特定 group（如只用于开发） poetry add pytest-cov --group dev

执行后，Poetry 会：

• 自动更新pyproject.toml，在[tool.poetry.dependencies]下添加alembic = "^1.13.0"；
• 重新运行求解器，确保alembic与现有依赖（如sqlalchemy）兼容；
• 更新poetry.lock，记录alembic及其所有传递依赖的精确版本。

注意：poetry add不会自动安装新包到当前环境！它只更新声明。你需要再执行一次poetry install（或poetry update）来同步环境。这是设计使然——声明和安装是两个明确分离的动作，避免意外变更。

删除依赖

# 删除 alembic（假设需求取消） poetry remove alembic # 删除后同样需要 install 来同步环境 poetry install

环境管理：何时用poetry shell，何时用poetry run？

• poetry shell：启动一个已激活 Poetry 环境的子 shell。适合长时间开发，你可以在其中自由运行python,pip,pytest等命令，所有操作都在项目虚拟环境中。退出时输入exit。
• poetry run <command>：在 Poetry 环境中运行单条命令。适合 CI 脚本或临时操作，例如：

  poetry run pytest tests/ # 运行测试 poetry run black src/ # 格式化代码 poetry run start # 启动服务（对应 [scripts] 中定义的 start）

实操心得：在 CI/CD 脚本中，永远用poetry run，不要用poetry shell。因为poetry shell启动的是交互式 shell，CI 环境通常是非交互式的，会导致脚本卡住。poetry run是原子性命令，完美适配自动化流程。

查看依赖状态

# 查看所有已安装包（含版本） poetry show # 查看依赖树（直观显示谁依赖谁） poetry show --tree # 查看某个包的详细信息（如许可证、作者、依赖） poetry show fastapi --tree # 检查依赖是否有已知安全漏洞（需先安装插件） poetry plugin add poetry-plugin-audit poetry audit

poetry show --tree是我每天必用的命令。当线上出现ImportError时，我第一反应不是查代码，而是poetry show --tree | grep xxx，快速定位是哪个包的版本不对，或者哪个传递依赖缺失。它比pipdeptree更准确，因为它是基于poetry.lock的实时解析，而非当前环境的pip list。

3.4 生产部署与打包：从代码到可交付物的闭环

Poetry 的终极价值，在于它让“开发完成”和“可部署”之间不再有鸿沟。

步骤一：构建可分发包

在项目根目录，执行：

poetry build

Poetry 会：

• 读取pyproject.toml中的元数据（name, version, authors...）；
• 根据tool.poetry.packages（如果定义了）或默认规则（src/目录下的包）收集源码；
• 生成标准的dist/ecommerce_api-0.1.0-py3-none-any.whl（wheel）和dist/ecommerce_api-0.1.0.tar.gz（sdist）；
• wheel 文件内部已嵌入poetry.lock的哈希摘要，确保安装时的完整性。

提示：如果你的项目结构不是标准的src/模式（比如代码直接放在项目根目录），需要在pyproject.toml中显式声明：

[tool.poetry.packages] [{include = "ecommerce_api"}] # 假设你的包名是 ecommerce_api

步骤二：在目标服务器上安装

在生产服务器上，你不需要 Poetry，只需要pip：

# 1. 上传 dist/ 下的 wheel 文件到服务器 scp dist/ecommerce_api-0.1.0-py3-none-any.whl user@prod-server:/tmp/ # 2. 创建干净的虚拟环境（可选，但推荐） python3 -m venv /opt/ecommerce-api/env source /opt/ecommerce-api/env/bin/activate # 3. 安装 wheel（pip 会自动解析其内部依赖） pip install /tmp/ecommerce_api-0.1.0-py3-none-any.whl # 4. 验证安装 pip list | grep ecommerce # 应输出 ecommerce-api 0.1.0

关键点：pip install一个 Poetry 构建的 wheel，会自动读取 wheel 内部的METADATA和RECORD文件，确保安装的依赖与poetry.lock完全一致。你不需要在生产服务器上装 Poetry，也不需要传poetry.lock，wheel 本身就是自包含的契约。

步骤三：容器化部署（Docker 最佳实践）

Dockerfile 示例：

FROM python:3.9-slim # 创建非 root 用户（安全最佳实践） RUN adduser -u 1001 -U -m appuser USER appuser # 复制构建好的 wheel（假设已构建并复制到 context） COPY dist/ecommerce_api-0.1.0-py3-none-any.whl /tmp/ RUN pip install /tmp/ecommerce_api-0.1.0-py3-none-any.whl # 复制应用配置和静态文件 COPY --chown=appuser:appuser config/ /home/appuser/config/ COPY --chown=appuser:appuser static/ /home/appuser/static/ # 暴露端口 EXPOSE 8000 # 启动命令（使用 poetry scripts 定义的 start） CMD ["poetry", "run", "start"]

注意：这里CMD用了poetry run start，但前提是 Docker 镜像里装了 Poetry。更轻量的做法是直接调用模块：

CMD ["python", "-m", "ecommerce_api.main"]

因为 wheel 安装后，ecommerce_api包已可用，python -m会自动找到入口。

4. 常见问题与实战排障技巧实录

4.1 “poetry install 报错：SolverProblemError” —— 依赖冲突的黄金排查法

这是 Poetry 新手最常遇到的报错，形如：

Because ecommerce-api depends on both fastapi (^0.110.0) and sqlalchemy (^2.0.0), and sqlalchemy (2.0.23) depends on pydantic (>=2.5.0,<3.0.0), but fastapi (0.110.2) depends on pydantic (>=2.5.0,<2.6.0), version solving failed.

这不是 bug，是 Poetry 在保护你。它发现了fastapi和sqlalchemy对pydantic的版本要求有重叠但不完全一致（<2.6.0vs<3.0.0），求解器无法找到一个同时满足两者的版本。

黄金排查三步法：

1. 精确定位冲突包：报错信息里已经指出是pydantic。运行poetry show pydantic --tree，看谁在依赖它。
2. 检查版本约束合理性：打开pyproject.toml，看fastapi和sqlalchemy的约束。fastapi = "^0.110.0"是合理的，但sqlalchemy = "^2.0.0"可能太宽泛。查 SQLAlchemy 2.0.x 的 release notes，发现2.0.23引入了对pydantic>=2.5.0的要求，而fastapi 0.110.2锁定了pydantic<2.6.0。解决方案是收紧sqlalchemy的约束：

   sqlalchemy = "^2.0.22" # 2.0.22 不要求 pydantic>=2.5.0

3. 执行poetry update重新求解：修改pyproject.toml后，运行poetry update sqlalchemy（只更新 sqlalchemy 及其传递依赖），Poetry 会重新计算并生成新的poetry.lock。

实操心得：永远不要盲目poetry update全部依赖！这可能导致大量包升级，引入未知风险。精准更新（poetry update package-name）是安全演进的关键。我团队的规范是：poetry update必须附带 Git commit message，说明“为何更新”和“影响范围”。

4.2 “poetry run python app.py 报错：ModuleNotFoundError” —— 路径与包结构陷阱

现象：本地poetry run python src/main.py能跑，但poetry run python -m ecommerce_api.main报错找不到模块。

根本原因：Python 的模块导入机制。python -m要求模块名ecommerce_api.main能被 Python 的sys.path找到。而 Poetry 默认不会把项目根目录加到sys.path，除非你按标准结构组织代码。

标准结构（强烈推荐）：

ecommerce-api/ ├── pyproject.toml ├── README.md ├── src/ │ └── ecommerce_api/ # 包名，必须与 pyproject.toml 中的 name 一致（或小写转换） │ ├── __init__.py │ ├── main.py │ └── models.py └── tests/

并在pyproject.toml中声明：

[tool.poetry.packages] [{include = "ecommerce_api", from = "src"}]

这样，poetry install时会将src/ecommerce_api作为可安装包，python -m ecommerce_api.main就能正常工作。

提示：如果你坚持用src外平铺结构（不推荐），可以在pyproject.toml中用packages配置指向根目录，但会增加 IDE 配置复杂度。标准src结构是 Python 社区共识，Poetry 官方也默认支持。

4.3 “CI 构建慢，总是重新下载依赖” —— 缓存优化实战

Poetry 默认每次poetry install都会检查 PyPI，即使poetry.lock没变。在 CI 中，这会导致重复下载，拖慢构建。

解决方案：利用 CI 缓存 + Poetry 的离线模式

以 GitHub Actions 为例：

- name: Cache Poetry dependencies uses: actions/cache@v3 with: path: ~/.cache/pypoetry/artifacts key: ${{ runner.os }}-poetry-artifacts-${{ hashFiles('**/poetry.lock') }} - name: Install dependencies run: | # 如果缓存命中，poetry install 会优先用缓存的 artifacts poetry install --no-root # --no-root 跳过安装当前项目（只装依赖）

关键点：

• 缓存路径是~/.cache/pypoetry/artifacts，这是 Poetry 下载 wheel 的默认位置；
• key使用poetry.lock的 hash，确保 lock 文件不变时缓存有效；
• --no-root参数很重要：它告诉 Poetry “只装pyproject.toml中的dependencies，不要装当前项目本身（即跳过poetry install的develop模式）”，这在 CI 中更安全，避免因项目未构建完成导致失败。

实操心得：我们团队在 GitLab CI 中还额外启用了 Poetry 的--sync参数：poetry install --sync。它会移除poetry.lock中没有声明的包，确保 CI 环境绝对干净，杜绝“本地有、CI 没有”的幽灵依赖。

4.4 “poetry.lock 文件巨大，Git 提交困难” —— 精简与审查技巧

一个大型项目poetry.lock可能有 3000+ 行。直接git diff很难看出变化。

高效审查技巧：

1. 用poetry show --tree对比：在修改前和修改后，分别运行poetry show --tree > tree-before.txt和poetry show --tree > tree-after.txt，用diff tree-before.txt tree-after.txt查看依赖树变化。
2. 聚焦关键包：poetry show <package-name>查看单个包的版本和依赖，比扫lock文件高效得多。
3. 忽略无关字段：poetry.lock中的source、checksum字段变化是正常的（如 PyPI CDN 切换），真正关注的是version字段。可以用git diff --ignore-all-space减少噪音。

注意：poetry.lock必须提交到 Git！它是可重现性的基石。不要因为它大就.gitignore。Git 对文本文件的 diff 和压缩非常高效，3000 行的 lock 文件在 Git 中只占几 KB。

4.5 “如何迁移现有 pip + requirements.txt 项目？”

这是最常被问的问题。迁移不是一蹴而就，而是分三步走：

第一步：初始化 Poetry，但不删除旧文件

cd existing-project poetry init # 交互式，按提示填，依赖先跳过 # 手动编辑 pyproject.toml，将 requirements.txt 中的包，按格式添加到 [tool.poetry.dependencies] # 例如：requests==2.28.1 → requests = "==2.28.1" poetry install

第二步：验证并清理

• 运行所有测试：poetry run pytest
• 检查poetry show --tree是否与pipdeptree输出一致
• 确认无误后，删除requirements.txt、requirements-dev.txt等旧文件

第三步：更新 CI/CD 和团队文档

• 修改 CI 脚本，将pip install -r requirements.txt替换为poetry install
• 更新 README，将开发指南改为poetry install和poetry run ...
• 在团队 Wiki 中记录 Poetry 常用命令速查表

实操心得：迁移时，永远保留poetry.lock的首次提交。这样，如果后续发现回归问题，可以git revert到这个干净的 baseline，快速回滚。我们有个项目迁移后发现性能下降，就是靠 revert 到初始 lock 文件，确认是 Poetry 本身无问题，而是某个新版本包的 bug。

5. 进阶技巧与团队协作规范

5.1 使用pyproject.toml的高级特性提升工程健壮性

pyproject.toml不仅是依赖清单，更是项目配置中心。以下是我们团队强制使用的几项：

自动化代码质量检查

[tool.poetry.group.dev.dependencies] pytest = "^7.4.0" black = "^23.10.0" isort = "^5.12.0" mypy = "^1.8.0" flake8 = "^6.1.0" # 配置 black [tool.black] line-length = 88 skip-string-normalization = true # 配置 isort [tool.isort] profile = "black" line_length = 88 # 配置 mypy [tool.mypy] python_version = "3.9" disallow_untyped_defs = true disallow_incomplete_defs = true warn_return_any = true

现在，poetry run black src/和poetry run mypy src/就能直接使用这些配置，无需额外的pyproject.toml或mypy.ini。所有质量门禁都集中管理。

定义常用脚本，统一团队操作

[tool.poetry.scripts] # 开发服务器 dev = "uvicorn ecommerce_api.main:app --reload --host 0.0.0.0:8000" # 运行测试（带覆盖率） test = "pytest --cov=ecommerce_api --cov-report=html" # 一键格式化+类型检查+测试 ci-check = "poetry run black src/ && poetry run isort src/ && poetry run mypy src/ && poetry run pytest"

团队成员只需