08.4 阶段 3:环境依赖与质量工具链
所属:全栈开发面试题库 / 学习路径 / 08 Python 全栈
本页目录
一、阶段定位
阶段 0 只用 venv 做了最简单的隔离,阶段 1、2 的代码还没有测试、没有 lint、没有类型门禁。本阶段把工程化工具链补齐:依赖从「全局 pip 装到哪算哪」升级为「锁文件可复现」;代码从「能跑」升级为「lint + 类型检查 + 测试全过」。阶段 4 写 FastAPI 时,这个工具链就是合并前的门禁;阶段 7 部署时,CI 流水线就是把这些命令串起来。
与前后阶段的衔接:因为阶段 2 已经写了类型注解,本阶段的 mypy 才有东西可查;因为阶段 1、2 的代码还没有测试,本阶段的 pytest 要回头补测试。跳过本阶段直接进 Web 开发,后面会出现「本地能跑、CI 红」「别人 clone 下来依赖装不上」「类型注解写了但没人检查」三类问题。
原有卡点及判断依据:
- 全局环境安装依赖导致项目间冲突:判断现象是
pip list里混着 requests、flask、pandas 等互不相关的包,且版本互相覆盖。本阶段用 uv 锁文件解决,见 5.1。 - 类型检查一上来拉满严格模式,报错过多直接放弃:判断现象是
mypy --strict后几百条错误,团队直接关掉。本阶段讲渐进式接入,见 5.4。 - mock 过度导致测试与真实行为脱节:判断现象是测试全绿,但线上调用真实 API 报错。本阶段讲 mock 的边界,见 5.6。
- 锁文件未纳入版本管理导致依赖不可复现:判断现象是别人 clone 后
uv sync装出不同版本。见 5.1。
二、阶段目标与投入
| 能力目标(可验证的行为) | 验证方式 |
|---|---|
能用 uv 创建工程并生成锁文件,在干净环境 uv sync 复现 |
删除 .venv 后 uv sync 结果与锁文件一致 |
能写标准 pyproject.toml,区分生产/开发/测试依赖分组 |
uv sync --group dev 与 uv sync 安装包集合不同 |
| 能用 ruff 检查与格式化代码,规则可配置 | ruff check . 与 ruff format . 无输出 |
| 能在 mypy 默认配置下通过,逐步引入严格选项 | mypy . 0 error |
| 能写 pytest fixture 并按作用域复用,用参数化驱动多组用例 | 测试隔离正确,fixture 复用次数符合预期 |
| 能配置 coverage 门禁,外部协作对象全部 mock | pytest --cov 覆盖率达阈值,CI 红即阻断 |
建议学时:
- 全职:2 周,约 60 小时。uv 与 pyproject 15 小时、ruff 5 小时、mypy 15 小时、pytest 20 小时、pre-commit 5 小时。
- 在职:5–6 周,约 70 小时。
学时分配建议:依赖管理与锁文件 20%、ruff 10%、mypy 20%、pytest 与 mock 35%、coverage 与 pre-commit 15%。
三、先修自检
| 先修项 | 合格标准 | 不合格时回到 |
|---|---|---|
| venv 基础 | 会创建与激活虚拟环境 | 08.1 阶段 0 |
| 函数与类 | 能写函数与类 | 08.2 阶段 1 |
| 类型注解 | 能为函数写注解 | 08.3 阶段 2 |
四、知识地图
| 模块 | 知识点 | 掌握程度 | 对应题库章节 |
|---|---|---|---|
| 依赖管理 | uv 安装/解析/锁文件、venv 隔离、版本管理 | 会用 | 06.1 通用后端工程 |
| pyproject.toml | PEP 621 字段、依赖分组、平台标记 | 会用 | 06.1 通用后端工程 |
| ruff | lint 规则集、自动修复、format、与 flake8/isort 关系 | 会用 | 06.1 通用后端工程 |
| mypy | 默认配置、--strict、渐进式接入、基线 |
会用 | 06.1 通用后端工程 |
| pytest | fixture 作用域、参数化、-k、--cov |
会用 | 06.1 通用后端工程 |
| mock | unittest.mock、monkeypatch、边界 |
会用 | 06.1 通用后端工程 |
| pre-commit | 钩子配置、本地与 CI 一致 | 会用 | 06.1 通用后端工程 |
进度管理建议:把工具链跑通后,所有阶段 1、2 的代码都要补测试。《知识点全清单》「环境依赖」「质量工具链」段是全量清单。
五、分模块精讲
5.1 venv、uv 与锁文件
为什么需要它:venv 只隔离目录,不锁定版本;pip freeze 导出的 requirements.txt 不记录传递依赖版本,安装结果可能漂移。uv 用一个锁文件固定完整依赖树,干净环境 uv sync 结果可复现。
核心机制:
- venv:复制/软链解释器,独立
site-packages;跨项目隔离。 - uv:Astral 出品的 Rust 实现,兼容 pip 生态,解析速度比 pip 快 10–100 倍;用
uv.lock锁文件记录每个包的精确版本与哈希。 uv init创建工程骨架;uv add requests加入依赖并写锁文件;uv sync在干净环境按锁文件安装。- uv 与 pip 的差异:pip 每次解析依赖树,uv 有缓存与锁;pip 的
requirements.txt是顶层声明,uv.lock 是完整闭包。
最小可运行示例:
# 安装 uv(一次性)
# macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# 创建工程
uv init myproj
cd myproj
# 加生产依赖
uv add requests fastapi
# 加开发依赖(分组)
uv add --dev pytest ruff mypy
# 干净环境复现
rm -rf .venv
uv sync # 按 uv.lock 安装,结果与同事一致
uv sync --group dev # 安装含 dev 组
# 锁定当前版本
uv lock
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
同事 clone 后 uv sync 装出不同版本 |
没提交 uv.lock |
把 uv.lock 提交进 Git |
uv add 报错找不到 Python |
本机没装对应版本 | uv python install 3.11 |
| 全局 pip 仍被使用 | 没激活 uv 管理的环境 | 用 uv run python ... 或在 .venv 里执行 |
面试考法:常问「锁文件解决什么问题」。答「固定完整依赖树的精确版本与哈希,保证干净环境安装可复现;避免『我这能跑』」。追问「uv 比 pip 快在哪」,答 Rust 实现、并行解析、全局缓存。
5.2 pyproject.toml 与依赖分组
为什么需要它:每个工具都有自己的配置文件(setup.cfg、tox.ini、.flake8、mypy.ini),分散难维护。PEP 621 统一到 pyproject.toml,所有工具按 [tool.xxx] 分节配置。
核心机制:
[project]:名称、版本、依赖、Python 版本要求。[project.optional-dependencies]或 uv 的[tool.uv] dev-dependencies:开发依赖分组。[tool.ruff]、[tool.mypy]、[tool.pytest.ini_options]:各工具配置。- 依赖分组:生产只装运行时依赖,开发组含测试、lint、类型检查工具。
最小可运行示例:
# pyproject.toml
[project]
name = "myproj"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
"fastapi>=0.110",
"uvicorn>=0.29",
]
[dependency-groups]
dev = [
"pytest>=8",
"ruff>=0.5",
"mypy>=1.10",
]
[tool.ruff]
line-length = 100
target-version = "py311"
[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP"]
[tool.mypy]
python_version = "3.11"
strict = false
warn_unused_ignores = true
[tool.pytest.ini_options]
addopts = "-v"
testpaths = ["tests"]
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 开发工具被装到生产镜像 | 依赖分组没分开 | 生产只 uv sync --no-dev,Docker 多阶段构建 |
| 配置改了工具不识别 | toml 字段名写错 | 查对应工具文档核对字段名 |
面试考法:常问「pyproject.toml 解决了什么」。答「统一项目元数据与工具配置,告别 setup.cfg、tox.ini、.flake8 多个文件」。
5.3 ruff:lint 与 format
为什么需要它:flake8、isort、black 是三个工具,各自规则、各自速度。ruff 一个工具覆盖 lint 与 format,速度是 flake8 的几十倍,配置在 pyproject.toml 里。
核心机制:
ruff check .:lint,规则集按select = ["E", "F", "I", "B", "UP"]选择(E=pycodestyle、F=pyflakes、I=isort、B=bugbear、UP=pyupgrade)。ruff check --fix .:自动修复可修复项。ruff format .:格式化,风格接近 black。- 在 CI 里跑
ruff check . && ruff format --check .,任何一项失败即阻断。
最小可运行示例:
# 检查
ruff check .
# 自动修复
ruff check --fix .
# 格式化
ruff format .
# CI 中只检查不修改
ruff format --check .
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 规则与团队风格冲突 | 选了太多规则 | 在 [tool.ruff.lint] ignore 里关掉 |
ruff format 与 black 输出不一致 |
二者风格略有差异 | 统一用 ruff,不用 black |
面试考法:常问「ruff 和 flake8、black 的关系」。答「ruff 是 Rust 实现的替代,lint 替代 flake8+isort+pyupgrade,format 替代 black;速度快几十倍,配置统一」。
5.4 mypy:渐进式接入严格模式
为什么需要它:阶段 2 写了类型注解,但没人检查等于白写。mypy 是最主流的静态类型检查器;一上来 --strict 会报几百个错,正确做法是渐进式接入。
核心机制:
mypy .默认配置:只检查有注解的函数,不强制所有参数。mypy --strict:开启全部严格选项,包括disallow_untyped_defs、warn_return_any等。- 渐进式策略:先默认配置 → 0 error;再逐步开启
warn_redundant_casts、disallow_untyped_defs;最后--strict。 - 对动态特性(ORM、第三方库)用
# type: ignore[attr-defined]或mypy --strict局部豁免。
最小可运行示例:
# 默认检查
mypy .
# 严格模式(新项目直接上)
mypy --strict .
# 只检查某个目录
mypy src/
# 生成基线(老项目)
mypy . --generate-baseline=mypy-baseline.txt
# 之后只报新增错误,存量错误逐步治理
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
--strict 后几百条错误 |
一上来拉满 | 先用默认配置清零,再逐步开严格选项 |
| ORM 模型属性报错 | ORM 动态注入字段 | 用官方 mypy 插件(如 [tool.django-stubs])或 # type: ignore |
# type: ignore 被滥用 |
报错就忽略 | 用 warn_unused_ignores = true 检查无效忽略 |
面试考法:常问「老项目怎么引入 mypy」。答「默认配置清零 → 开 warning 级选项 → 逐步 disallow_untyped_defs → 最后 --strict;用 baseline 隔离存量错误」。
5.5 pytest:fixture 作用域与参数化
为什么需要它:unittest 样板代码多、fixture 复用难。pytest 用 fixture 按作用域注入资源,用参数化驱动多组用例,测试代码简洁。
核心机制:
- fixture:
@pytest.fixture装饰的函数,测试函数参数名匹配时自动注入。 - 作用域:
function(默认,每个测试新建)、class、module、package、session。 - 参数化:
@pytest.mark.parametrize("a, b, expected", [(1,2,3), (2,3,5)])一次写多组用例。 - 常用命令:
pytest -k "login"按名字过滤;pytest --cov=src --cov-report=term-missing覆盖率。
最小可运行示例:
# tests/test_calc.py
import pytest
@pytest.fixture
def user():
return {"name": "Ann", "age": 30}
def test_user_name(user):
assert user["name"] == "Ann"
@pytest.mark.parametrize("a, b, expected", [
(1, 2, 3),
(0, 0, 0),
(-1, 1, 0),
])
def test_add(a, b, expected):
assert a + b == expected
# 跑全部
pytest
# 按名字过滤
pytest -k "login"
# 覆盖率
pytest --cov=src --cov-report=term-missing --cov-fail-under=80
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| fixture 每个测试都重建,慢 | 默认 function 作用域 | 复用开销大的 fixture 用 scope="module" 或 session |
| 测试间状态串扰 | 用了模块级全局变量 | 用 fixture 隔离,每个测试独立 |
| 覆盖率 100% 但线上有 bug | 为凑覆盖率写无效用例 | 关注分支覆盖与关键路径覆盖,不追求行覆盖数字 |
面试考法:常问「fixture 的作用域有哪些、怎么选」。答「function 默认隔离;module/session 用于连接池、数据库这类重资源」。追问「pytest 和 unittest 的区别」,答「fixture 注入、参数化、插件生态、断言更简洁」。
5.6 mock、monkeypatch 与覆盖率边界
为什么需要它:单元测试不能真的调用外部 API、数据库、时间——否则慢、不稳定、依赖外部环境。mock 把这些协作对象换成假对象,但 mock 过度会导致测试与真实行为脱节。
核心机制:
unittest.mock.Mock/MagicMock:模拟对象,记录调用。monkeypatchfixture:临时替换模块属性、环境变量,测试结束自动还原。- mock 构造器:
@patch("module.ClassName")替换类,返回 Mock 实例。 - 边界:mock 外部协作对象(API、DB、时间),不 mock 被测对象本身。
最小可运行示例:
# 被测代码:调用外部 API
import requests
def get_user_name(uid: int) -> str:
resp = requests.get(f"https://api.example.com/users/{uid}", timeout=5)
resp.raise_for_status()
return resp.json()["name"]
# 测试:mock requests.get
from unittest.mock import patch, MagicMock
@patch("myapp.user.requests.get")
def test_get_user_name(mock_get):
mock_resp = MagicMock()
mock_resp.json.return_value = {"name": "Ann"}
mock_resp.raise_for_status.return_value = None
mock_get.return_value = mock_resp
name = get_user_name(1)
assert name == "Ann"
mock_get.assert_called_once_with("https://api.example.com/users/1", timeout=5)
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| mock 了被测对象本身 | 把要测的类也 mock 了 | 只 mock 外部协作对象 |
| mock 设置太细,API 改了测试还绿 | mock 与真实行为脱节 | 保留契约测试(对真实 sandbox 跑一次) |
| monkeypatch 后环境变量没还原 | 没用 fixture | 用 pytest 的 monkeypatch fixture,自动还原 |
面试考法:常问「mock 适用于什么、边界在哪」。答「mock 外部依赖(网络、DB、时间),不 mock 被测对象;过度 mock 会让测试与真实行为脱节」。
5.7 pre-commit 与 CI 门禁
为什么需要它:本地跑过 lint 再提交,比 CI 报红再返工快。pre-commit 把 lint、format、类型检查挂到 git commit 钩子,不合规代码提交不了。
核心机制:
.pre-commit-config.yaml声明钩子,每个钩子是一个 repo 与 id。pre-commit install把钩子装到.git/hooks/。- 提交时自动跑钩子;失败则阻断 commit。
- CI 里跑同样的命令,保证本地与 CI 一致。
最小可运行示例:
# .pre-commit-config.yaml
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.5.0
hooks:
- id: ruff
args: [--fix]
- id: ruff-format
- repo: https://github.com/pre-commit/mirrors-mypy
rev: v1.10.0
hooks:
- id: mypy
pre-commit install
pre-commit run --all-files
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 钩子报错后没法提交 | 代码不合规 | 按提示修复后重新 add/commit |
| CI 红但本地没跑 | 钩子没装 | 新 clone 后先 pre-commit install |
面试考法:常问「pre-commit 解决什么」。答「把代码检查前移到本地,避免 CI 红返工;本地与 CI 规则保持一致」。
六、分层练习
6.1 复现型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| uv 创建工程 | uv init 建工程,加 requests 与 pytest |
uv sync 在删 .venv 后复现 |
1 小时 |
| ruff 检查与格式化 | 配 pyproject.toml,跑 ruff check --fix |
0 错误 | 0.5 小时 |
| mypy 默认检查 | 对阶段 2 的代码跑 mypy . |
0 error | 1 小时 |
| pytest fixture | 写一个带 fixture 的测试 | 测试隔离正确 | 1 小时 |
| coverage 门禁 | pytest --cov --cov-fail-under=80 |
覆盖率达阈值 | 1 小时 |
6.2 改造型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 引入 dev 依赖分组 | 把 pytest 从主依赖移到 dev 组 | 生产镜像不含 pytest | 0.5 小时 |
| mypy 渐进式 | 老项目用 baseline 隔离存量错误 | 新增代码 0 error | 1.5 小时 |
| mock 外部 API | 给一个调用 requests 的函数写测试 | mock 验证调用参数 | 1.5 小时 |
| pre-commit | 配 ruff + mypy 钩子 | commit 时自动跑 | 1 小时 |
6.3 设计型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 工程模板 | 为后续项目沉淀一个带工具链的模板 | 新工程复制即可用 | 3 小时 |
| 测试覆盖核心逻辑 | 给阶段 1 的两个 CLI 工具补测试 | 关键路径覆盖,分支可达 | 4 小时 |
| CI 配置草稿 | 写一个 GitHub Actions 或 GitLab CI 配置 | 跑 lint + mypy + pytest | 2 小时 |
七、排障表
| 现象 | 可能原因 | 排查步骤 | 解决办法 |
|---|---|---|---|
uv sync 装出与锁文件不同版本 |
没提交 uv.lock |
看 Git 状态 | 提交 uv.lock |
ruff check 大量规则报错 |
规则集选太多 | 看报错规则名 | 在 [tool.ruff.lint] ignore 关掉 |
mypy 报 ORM 动态属性 |
ORM 动态注入字段 | 看报错文件 | 用官方插件或 # type: ignore |
pytest 测试间状态串扰 |
模块级全局状态 | 看 fixture 作用域 | 用 fixture 隔离 |
coverage 100% 但线上有 bug |
为覆盖率写无效用例 | 看测试是否真的断言行为 | 关注关键路径与分支 |
pre-commit 钩子没跑 |
没 pre-commit install |
看 .git/hooks/ |
重新安装 |
ModuleNotFoundError 在 pytest 时 |
工程根目录不在 sys.path | 看运行目录 | 用 python -m pytest 或加 pyproject.toml 的 pythonpath |
| 依赖装到生产镜像 | dev 依赖没分组 | 看 Dockerfile 装包命令 | 生产 uv sync --no-dev |
八、出口条件
全部勾选后再进入 08.5 阶段 4:Web 框架主线。
- [ ] 能用 uv 创建工程、生成锁文件,在干净环境复现
- [ ] 能写标准
pyproject.toml,区分生产/开发/测试依赖 - [ ]
ruff check .与ruff format --check .0 错误 - [ ]
mypy .0 error,理解渐进式接入策略 - [ ] 能写 pytest fixture 按作用域复用,用参数化驱动多组用例
- [ ] 能 mock 外部协作对象,知道 mock 的边界
- [ ] coverage 门禁可配置,pre-commit 钩子可工作
自测题(先自己想,再看要点):
- 锁文件解决什么问题?
- 要点:固定完整依赖树的精确版本与哈希,干净环境
uv sync结果可复现。
- 要点:固定完整依赖树的精确版本与哈希,干净环境
- ruff 与 flake8、black 的关系?
- 要点:ruff 一个工具覆盖 lint(替代 flake8+isort+pyupgrade)与 format(替代 black),Rust 实现速度快。
- mypy
--strict为什么不适合老项目一上来就开?- 要点:会报几百条错误打击信心;正确做法是默认配置清零 → 逐步开严格选项。
- fixture 的作用域有哪些?怎么选?
- 要点:function/class/module/session;重资源(DB、连接池)用 module 或 session。
- mock 外部 API 时,边界在哪?
- 要点:只 mock 外部协作对象,不 mock 被测对象本身;过度 mock 会与真实行为脱节。
- 为什么
uv.lock必须提交进 Git?- 要点:否则同事 clone 后装出不同版本,依赖不可复现。
- pre-commit 与 CI 的关系?
- 要点:本地跑钩子提前发现问题,CI 跑同一套命令保证一致;两者规则不能冲突。