提交 2d23fc4d authored 作者: zhangqianwei's avatar zhangqianwei

cfm_完成模块一 Python 工程化(第二版)

上级 2f1dd3a9
......@@ -1466,3 +1466,4368 @@ A:见 1.1.9 版本回退。一般做法:
[1] *Pro Git* 第 2.5 节 "远程仓库的使用"。
---
### 1.1.7 合并与冲突处理
> 用 1-2 句话说清:**把两个分支的改动合二为一**——但当 Git 不知道怎么合并时,就需要你亲自下场。
---
## 什么是合并与冲突?
### 一句话定义
`git merge` 把一个分支的改动**合并到当前分支**;当同一文件的同一位置被不同分支修改时,Git 无法自动合并,这就是**冲突(conflict)**。
### 为什么重要
团队协作的核心流程:**在 feature 分支开发 → 合并到 main**。合并时遇到冲突是家常便饭,能否正确解决冲突直接决定你的代码能否上线。
### 生活类比
你和队友同时在修改同一份文档:
- 你在第 5 行加了"欢迎语"
- 队友在第 5 行改了"标题颜色"
- Git 不知道谁的版本是对的 → **冲突** → 你们得商量一下用谁的
---
## 举个例子
### 输入
```bash
# 场景:feature/login 开发完成,合并到 main
# 1. 切到 main
git switch main
# 2. 拉取最新代码
git pull origin main
# 3. 合并 feature/login
git merge feature/login
```
### 输出(无冲突时)
```bash
$ git merge feature/login
Merge made by the 'ort' strategy.
README.md | 2 ++
1 file changed, 2 insertions(+)
```
### 输出(有冲突时)
```bash
$ git merge feature/login
Auto-merging README.md
CONFLICT (content): Merge conflict in README.md
Automatic merge failed; fix conflicts and then commit the result.
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 合并前 | 先切到目标分支并 pull 最新 | 直接在 feature 分支上合并 |
| 解决冲突 | 编辑文件 → 保留需要的部分 → add → commit | 直接 push 或删掉冲突标记就跑 |
| 放弃合并 | `git merge --abort` | 关掉编辑器假装没事发生 |
| 删除分支 | 合并完成后用 `-d` 删除 | 合并完还在原地留着 |
**冲突标记长这样**:
```markdown
<<<<<<< HEAD
这是 main 分支的内容
=======
这是 feature/login 分支的内容
>>>>>>> feature/login
```
---
## 原理深入:Fast-forward vs 三方合并
### Fast-forward(快进合并)
当 main 没有新提交时,Git 直接"指针移动",不产生新 commit:
```
合并前:
main: A ── B
└── feature: C ── D
合并后(fast-forward):
main: A ── B ── C ── D
└── feature (已合并)
```
### 三方合并(Recursive)
当 main 有新提交时,Git 需要"三方比较":
```
合并前:
main: A ── B ── M
\ \
feature: C ─────── D
Git 比较:A(共同祖先) vs B(main改动) vs C(feature改动)
结果:生成一个新 commit M 整合两者
```
---
## 实战代码
### 1. 标准合并流程
```bash
# 1. 确保在 main 分支
git switch main
# 2. 确保 main 是最新的
git pull origin main
# 3. 执行合并
git merge feature/login
# 4. 如果有冲突,解决后:
git add <冲突文件>
git commit -m "Merge branch 'feature/login' into main"
# 5. 合并完成后删除 feature 分支
git branch -d feature/login
```
### 2. 解决冲突的完整步骤
```bash
# 冲突时 Git 会列出冲突文件
$ git status
Unmerged paths:
(use "git add <file>..." to mark resolution)
both modified: README.md
# 打开文件,冲突标记长这样:
<<<<<<< HEAD
main 分支的代码
=======
feature 分支的代码
>>>>>>> feature/login
# 编辑后保留你需要的版本:
正确的代码
# 标记为已解决
git add README.md
# 完成合并提交
git commit -m "Merge branch 'feature/login' into main"
```
### 3. Abort 放弃合并
```bash
# 冲突太复杂,想放弃重来
git merge --abort
```
### 4. Squash Merge(压缩合并)
把 feature 分支的多个 commit 合并成一个:
```bash
git merge --squash feature/login
git commit -m "feat: 完成登录功能"
# 所有 feature 分支的改动被压缩成一个 commit
```
---
## 常见问题
**Q:合并时提示 `fatal: refusing to merge unrelated histories`?**
A:两个分支没有共同的祖先。解决方案:
```bash
git pull origin main --allow-unrelated-histories
# ⚠️ 谨慎使用,确认两个仓库确实应该合并
```
**Q:冲突文件太多,一个一个改太慢?**
A:可以用合并工具:
```bash
# 图形化工具
git mergetool
# 或者用 VS Code 的 Merge Editor
code --wait --merge <file1> <file2> <base> <local> <remote>
```
**Q:合并后想撤销?**
A:
```bash
# 还没 push
git reset --hard HEAD~1
# 已经 push
git revert HEAD # 创建一个新 commit 撤销之前的合并
```
---
## 验收标准
```
☐ 能用 git merge 合并分支
☐ 能识别冲突标记(<<<<<<< HEAD ... ======= ... >>>>>>>)
☐ 能手动解决简单冲突
☐ 能用 git merge --abort 放弃合并
☐ 能用 git branch -d 删除已合并分支
☐ 能区分 fast-forward 和三方合并
☐ 知道合并冲突后必须 add + commit 才能完成
```
## 官方来源
- `git-merge` 手册页:[https://git-scm.com/docs/git-merge](https://git-scm.com/docs/git-merge)
- Git Book - 合并:[https://git-scm.com/book/zh/v2/Git-分支-分支的衍合](https://git-scm.com/book/zh/v2/Git-%E5%88%86%E6%94%AF-%E5%88%86%E6%94%AF%E7%9A%84%E8%A1%8D%E5%90%88)
## 参考文献
[1] Scott Chacon & Ben Straub. *Pro Git (2nd Edition)*. Apress, 2014. 第 3.2 节 "分支的合并"。
---
### 1.1.8 查看历史与差异
> 用 1-2 句话说清:**翻 Git 的"账本"**——看看过去改了什么、谁改的、每次改动的差异。
---
## 什么是查看历史与差异?
### 一句话定义
- `git log` = 查看提交历史
- `git diff` = 查看两个版本之间的差异
- `git blame` = 查看某行代码是谁写的、什么时候改的
### 为什么重要
当代码出问题、想知道某行代码是谁写的、或要对比两个版本的差异时,这些命令就是你的"侦探工具"。
### 生活类比
- `git log` = 翻阅**微信聊天记录**,看谁发了什么消息
- `git diff` = 看**修改前后的对比截图**,哪些地方变了
- `git blame` = 查**"这是谁干的"**,追溯责任人
---
## 举个例子
### git log 查看历史
```bash
# 基本日志
git log
# 精简版(每行一个 commit)
git log --oneline
# 图形化展示分支
git log --oneline --graph --all
# 最近 5 条
git log -5
# 只看某个文件的修改历史
git log -- README.md
```
### git diff 查看差异
```bash
# 查看工作区 vs 暂存区
git diff
# 查看暂存区 vs 最新提交
git diff --cached
# 查看工作区 vs 某个 commit
git diff HEAD~3
# 查看两次 commit 之间的差异
git diff abc123..def456
# 只看某个文件的变化
git diff -- README.md
```
### git blame 追溯代码
```bash
# 查看某文件每行的最后修改者
git blame README.md
# 只看第 10-20 行
git blame -L 10,20 README.md
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 看全部历史 | `git log --oneline -20` | `git log` 刷屏找不到重点 |
| 看分支图 | `git log --graph --oneline --all` | 不知道有哪些分支 |
| 看单次改动 | `git show <commit-id>` | `git log` 一路翻 |
| 对比文件 | `git diff HEAD~1 -- file` | `cat` 手动对比 |
| 找 bug | `git blame` + `git bisect` | 盲目猜测 |
**git log 常用参数组合**:
```bash
# 实用的 log 命令
git log --oneline # 精简模式
git log --oneline --graph # 带分支图
git log --author="张三" # 只看某人的提交
git log --since="2024-01-01" # 只看某个时间段
git log --grep="登录" # 搜索 commit 消息
git log -p -- README.md # 看某个文件的详细变更
```
---
## 原理深入:diff 的三种视角
### 1. 工作区 vs 暂存区(`git diff`)
```
工作区:你正在改的
暂存区:git add 过的
```
### 2. 暂存区 vs HEAD(`git diff --cached`)
```
暂存区:即将提交的内容
HEAD:最后一次提交
```
### 3. 工作区 vs HEAD(`git diff HEAD`)
```
工作区:所有未提交的改动
HEAD:最后一次提交
```
### diff 输出解读
```bash
$ git diff
diff --git a/README.md b/README.md
index 1234567..89abcdef 100644
--- a/README.md ← 旧文件
+++ b/README.md ← 新文件
@@ -1,3 +1,4 @@ ← 影响第 1-3 行变成 1-4 行
# 项目
+新增加的这一行
这是原来的第二行
-删除的这一行
```
---
## 实战代码
### 1. 完整历史查询
```bash
# 按时间排序
git log --oneline --date=relative --pretty=format:"%h %s %ad %an"
# 输出:
# a1b2c3d feat: 新增登录功能 2 days ago Zhang San
# e4f5g6h fix: 修复注册 bug 5 days ago Li Si
# 查看某个 commit 的完整信息
git show a1b2c3d
```
### 2. 差异对比
```bash
# 比较两次提交
git diff abc123..def456
# 比较当前分支 vs main
git diff main..HEAD
# 只看改动的文件名
git diff --name-only
# 生成补丁文件
git diff > changes.patch
```
### 3. blame 追溯
```bash
# 查看某文件的每行代码来源
git blame README.md
# 输出示例:
^1234567 (Zhang San 2024-01-01 1) # 项目说明
ab8c9d2e (Li Si 2024-01-15 2) 新增使用方法
3f4g5h6i (Zhang San 2024-02-01 3) 修复错别字
# 只看特定行
git blame -L 10,20 README.md
```
### 4. 搜索历史
```bash
# 搜索 commit 消息
git log --grep="登录"
# 搜索改动内容
git log -S "def login()"
# 搜索某个文件的所有变更
git log --follow -p path/to/file.py
```
---
## 常见问题
**Q:`git diff` 输出太多,看不过来?**
A:
```bash
# 只看文件名
git diff --name-only
# 只看统计
git diff --stat
# 用工具看
git difftool
```
**Q:想撤回某次 commit 里的某个文件?**
A:
```bash
git checkout abc123^ -- path/to/file.py
# 这会把 abc123 之前的版本恢复到工作区
```
**Q:log 显示乱码?**
A:
```bash
git config --global log.decorate auto
git config --global i18n.logOutputEncoding utf-8
```
---
## 验收标准
```
☐ 能用 git log --oneline 查看精简历史
☐ 能用 git log --graph --oneline --all 查看分支图
☐ 能用 git diff 查看工作区与暂存区的差异
☐ 能用 git diff --cached 查看暂存区与最新提交的差异
☐ 能用 git show 查看某个 commit 的完整信息
☐ 能用 git blame 追溯某行代码的修改者
☐ 能用 git log -p 查看某个文件的历史变更
```
## 官方来源
- `git-log` 手册页:[https://git-scm.com/docs/git-log](https://git-scm.com/docs/git-log)
- `git-diff` 手册页:[https://git-scm.com/docs/git-diff](https://git-scm.com/docs/git-diff)
- `git-blame` 手册页:[https://git-scm.com/docs/git-blame](https://git-scm.com/docs/git-blame)
## 参考文献
[1] Scott Chacon & Ben Straub. *Pro Git (2nd Edition)*. Apress, 2014. 第 2.3 节 "查看提交历史"。
---
### 1.1.9 版本回退
> 用 1-2 句话说清:**后悔药**——写错了、删错了、push 错了,都能找回来。
---
## 什么是版本回退?
### 一句话定义
当代码出问题或需要回到历史版本时,使用 `git reset` / `git revert` / `git reflog` 三种方式回退。
### 为什么重要
Git 是"防删神器"——只要 commit 过,几乎没有真正丢失的数据。学会回退,你就拥有了"后悔药"。
### 生活类比
- **游戏存档**:打 boss 死了,读档重来
- **Ctrl+Z**:写错了,撤回
- **历史记录**:想回到上周的版本?轻松搞定
---
## 三种回退方式对比
| 命令 | 作用 | 是否改写历史 | 适用场景 |
| --- | --- | --- | --- |
| `git reset` | 移动 HEAD 指针 | ✅ 改写 | 撤销本地未 push 的 commit |
| `git revert` | 创建新 commit 撤销旧 commit | ❌ 不改写 | 撤销已 push 的 commit(安全) |
| `git reflog` | 恢复误删的 commit | ✅ 改写 | 恢复彻底消失的 commit |
---
## 举个例子
### 场景 1:撤销本地最后一个 commit(还没 push)
```bash
# 查看最近 3 个 commit
git log --oneline -3
# 回退到上一个版本(保留改动在工作区)
git reset --soft HEAD~1
# 回退到上一个版本(保留改动在暂存区)
git reset --mixed HEAD~1 # 默认
# 回退到上一个版本(丢弃所有改动)⚠️
git reset --hard HEAD~1
```
### 场景 2:撤销已 push 的 commit
```bash
# 创建新 commit 撤销指定 commit
git revert HEAD
# 推送撤销
git push origin main
```
### 场景 3:恢复误删的 commit
```bash
# 查看所有操作记录(包含被 reset 的)
git reflog
# 输出:
# a1b2c3d HEAD@{0}: reset: moving to HEAD~1
# e4f5g6h HEAD@{1}: commit: 新增功能
# 恢复到 e4f5g6h
git reset --hard e4f5g6h
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 撤销本地 commit | `git reset HEAD~1` | 删掉 .git 重来 |
| 撤销已 push 的 | `git revert HEAD` | `git reset --hard` 然后 `-f` 强推 |
| 想撤销多次 commit | `git revert HEAD~3..HEAD` | 多次 revert |
| 丢弃工作区改动 | `git checkout -- file` 或 `git restore` | 直接手动改回来 |
| 恢复误删 | `git reflog` 找到 commit | "完了,找不回来了" |
**⚠️ 危险警告**:
```bash
# 危险操作 --hard
git reset --hard HEAD~1
# 工作区的所有未提交改动都会丢失!
# 危险操作 强推
git push -f origin main
# 如果多人共用这个分支,会删掉别人的 commit!
```
---
## 原理深入:三种 reset 模式
### --soft(软重置)
```
HEAD 移动,但:
- 暂存区:保持不变
- 工作区:保持不变
效果:撤销 commit,但代码还在暂存区
```
### --mixed(混合重置,默认)
```
HEAD 移动,但:
- 暂存区:被撤销到工作区
- 工作区:保持不变
效果:撤销 commit 和 add,但代码还在工作区
```
### --hard(硬重置)
```
HEAD 移动,但:
- 暂存区:被清空
- 工作区:被清空
效果:彻底回到那个版本 ⚠️
```
### revert vs reset 对比图
```
reset(改写历史):
A -> B -> C -> D (HEAD)
↓
A -> B -> D (HEAD) ← C 被删除了
revert(安全撤销):
A -> B -> C -> D -> E (HEAD)
↑
E = "撤销 C"
```
---
## 实战代码
### 1. 完整回退场景
```bash
# 场景:想回到 3 天前的版本
git log --oneline -10
# 找到目标 commit:abc1234
# 方法 1:reset(本地用)
git reset --hard abc1234
# 方法 2:revert(已 push 用)
git revert abc1234
# 会生成一个新 commit,撤销 abc1234 的改动
```
### 2. 只撤销某个文件的改动
```bash
# 回到该文件的上一个版本
git checkout HEAD -- path/to/file.py
# 或(新语法)
git restore path/to/file.py
```
### 3. 用 reflog 恢复误操作
```bash
# 查看完整操作历史
git reflog
# 输出:
# abc1234 HEAD@{0}: commit: 新增功能
# def5678 HEAD@{1}: reset: moving to HEAD~1
# ghi9012 HEAD@{2}: commit: 修复 bug
# 恢复到 ghi9012
git reset --hard ghi9012
```
### 4. 撤销 merge
```bash
# 撤销合并
git revert -m 1 HEAD
# -m 1 表示保留 main 那边的改动,撤销 feature 的
# 撤销后推送
git push origin main
```
---
## 常见问题
**Q:已经 `git push -f` 强推了,能恢复吗?**
A:可以,但需要团队配合:
```bash
# 1. 找同事让他们把正确的分支 push 上来
# 2. 或者用 git reflog 找到被删的 commit,然后重新强推
# 3. 联系管理员从 GitHub 恢复
```
**Q:reset 后还能看到原来的 commit 吗?**
A:能,30 天内都能用 `git reflog` 找回:
```bash
git reflog --date=relative
```
**Q:想保留回退的记录,但不用 revert?**
A:只能 reset 到一个临时分支:
```bash
git checkout -b backup # 创建备份分支
git checkout main # 切回 main
git reset --hard abc123 # 回退
git push --force # ⚠️ 危险
```
---
## 验收标准
```
☐ 能区分 git reset --soft/--mixed/--hard 三种模式
☐ 能用 git reset 撤销本地未 push 的 commit
☐ 能用 git revert 安全撤销已 push 的 commit
☐ 能用 git reflog 恢复误删的 commit
☐ 能用 git restore 撤销某个文件的改动
☐ 知道强推(-f)的危险性,不会轻易在 main 上使用
☐ 理解 revert 不改写历史,适合公共分支
```
## 官方来源
- `git-reset` 手册页:[https://git-scm.com/docs/git-reset](https://git-scm.com/docs/git-reset)
- `git-revert` 手册页:[https://git-scm.com/docs/git-revert](https://git-scm.com/docs/git-revert)
- `git-reflog` 手册页:[https://git-scm.com/docs/git-reflog](https://git-scm.com/docs/git-reflog)
## 参考文献
[1] Scott Chacon & Ben Straub. *Pro Git (2nd Edition)*. Apress, 2014. 第 4.4 节 "重写历史"。
---
### 1.1.10 暂存工作
> 用 1-2 句话说清:**"我现在手头的工作还没写完,但又得切换分支去处理别的事"**——stash 就是把你的改动"锁进柜子"。
---
## 什么是暂存工作(stash)?
### 一句话定义
`git stash` 把工作区的**未提交改动**临时保存起来,之后可以恢复继续工作。
### 为什么重要
当你正在开发一半,突然要切到其他分支处理紧急 bug 时,stash 让你不用 commit 半成品就能切换分支。
### 生活类比
你在写报告,写到一半领导让你去开会:
- **不 stash**:把写了一半的报告(脏的)留在桌上 → 切换分支会冲突
- **stash**:把报告锁进抽屉 → 桌面干净,可以去做别的事 → 开完会再拿出来继续写
---
## 举个例子
### 输入
```bash
# 正在改代码,但还没写完
$ git status
Changes not staged for commit:
modified: app.py
# 突然要切到别的分支
git stash
# 切换分支处理紧急事务
git switch main
# ... 处理完回来 ...
# 恢复暂存的工作
git stash pop
```
### 输出
```bash
$ git stash
Saved working directory and index state WIP on main: a1b2c3d 初始版本
$ git status
On branch main
nothing to commit, working tree clean
$ git stash pop
On branch main
Changes not staged for commit:
modified: app.py
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 暂存前 | `git stash` 或 `git stash push` | 随便 commit 一个 "WIP" |
| 暂存时加说明 | `git stash push -m "未完成的登录功能"` | 没有任何描述 |
| 查看暂存列表 | `git stash list` | 忘了存了哪几个 |
| 恢复最新 stash | `git stash pop` | 手动复制粘贴代码 |
| 恢复指定 stash | `git stash apply stash@{2}` | 只 pop 最新 |
| 删除 stash | `git stash drop stash@{0}` | 不清理,越积越多 |
---
## 原理深入:stash 的存储结构
```
stash 实际创建了两个 commit:
1. commit 对象:存工作区的改动
2. commit 对象:存暂存区的改动
它们以特殊的 ref 存储:refs/stash
```
---
## 实战代码
### 1. 基本操作
```bash
# 暂存当前改动(简写)
git stash
# 暂存当前改动(带消息)
git stash push -m "未完成的登录功能"
# 只暂存某个文件
git stash push -m "wip" path/to/file.py
# 查看暂存列表
git stash list
# 输出:
# stash@{0}: On main: 未完成的登录功能
# stash@{1}: WIP on main: a1b2c3d 初始版本
# 恢复最新 stash 并删除
git stash pop
# 恢复最新 stash 但保留(不删除)
git stash apply
# 恢复指定 stash
git stash apply stash@{2}
# 删除最新 stash
git stash drop
# 删除所有 stash
git stash clear
```
### 2. 暂存包括未跟踪的文件
```bash
# 默认 stash 只会暂存已跟踪的文件
git stash -u # 包含未跟踪的新文件
git stash --include-untracked
```
### 3. 暂存指定路径
```bash
# 只暂存某个目录
git stash push -m "wip" src/components/
```
### 4. 从 stash 创建分支
```bash
# 从 stash 创建新分支继续工作(stash 内容和当前分支冲突时有用)
git stash branch new-branch stash@{0}
```
### 5. 常用工作流
```bash
# 场景:正在 feature/login 开发,main 出了 bug 要修
# 1. 暂存当前改动
git stash push -m "wip: feature/login"
# 2. 切到 main 修 bug
git switch main
git pull origin main
# ... 修复 bug ...
git commit -m "fix: 修复登录页崩溃"
git push origin main
# 3. 切回 feature 分支继续开发
git switch feature/login
git stash pop
```
---
## 常见问题
**Q:stash 和 commit 有什么区别?**
A:
| | stash | commit |
| --- | --- | --- |
| 目的 | 临时保存工作进度 | 永久存档 |
| 是否生成 commit | 生成特殊 commit | 生成普通 commit |
| 是否在 log 中可见 | `git stash list` | `git log` |
| 是否可以被 push | ❌ | ✅ |
**Q:stash 会不会丢?**
A:默认保留 30 天,但建议用完就 drop:
```bash
git stash drop stash@{0} # 删除指定 stash
git stash clear # 清空所有 stash
```
**Q:两个 stash 都想保留怎么办?**
A:给 stash 起名字:
```bash
git stash push -m "登录功能开发中"
git stash push -m "用户模块修改中"
git stash list
# stash@{0}: On main: 登录功能开发中
# stash@{1}: On main: 用户模块修改中
```
---
## 验收标准
```
☐ 能用 git stash 暂存未提交的改动
☐ 能用 git stash push -m "说明" 给 stash 起名字
☐ 能用 git stash list 查看暂存列表
☐ 能用 git stash pop 恢复并删除 stash
☐ 能用 git stash apply 恢复但保留 stash
☐ 能用 git stash drop 删除指定 stash
☐ 理解 stash 和 commit 的区别
☐ 能在紧急 bug 修复场景下使用 stash
```
## 官方来源
- `git-stash` 手册页:[https://git-scm.com/docs/git-stash](https://git-scm.com/docs/git-stash)
## 参考文献
[1] Scott Chacon & Ben Straub. *Pro Git (2nd Edition)*. Apress, 2014. 第 7.3 节 "暂存工作"。
---
### 1.1.11 Commit 规范与分支命名
> 用 1-2 句话说清:**让团队 review 不抓狂**——统一的 commit 规范和分支命名让代码历史可读、可追溯。
---
## 什么是 Commit 规范与分支命名?
### 一句话定义
规定 commit message 的格式(type: description)和分支的命名规则(如 feature/login)。
### 为什么重要
- 好的 commit 历史让 code review 和 bug 追踪事半功倍
- 混乱的 commit 信息("fix bug"、"update")让团队成员互相折磨
- 规范的分支命名让你一眼看出这个分支是干什么的
### 生活类比
学校成绩单的格式:`2024-01-15 数学 95 优`
vs
随手写的:`95`
---
## 常用 Commit 类型(type)
| type | 含义 | 示例 |
| --- | --- | --- |
| `feat` | 新功能 | `feat(login): 新增第三方登录` |
| `fix` | 修复 bug | `fix(cart): 修复结算金额错误` |
| `docs` | 文档 | `docs: 更新 README` |
| `style` | 代码格式(不影响功能) | `style: 统一缩进` |
| `refactor` | 重构(不修复问题不加功能) | `refactor: 抽取公共函数` |
| `perf` | 性能优化 | `perf: 优化列表查询速度` |
| `test` | 测试 | `test: 新增登录单元测试` |
| `chore` | 构建/工具 | `chore: 升级依赖版本` |
| `ci` | CI/CD | `ci: 添加 GitHub Actions` |
---
## 举个例子
### Commit Message 格式
```bash
# 格式
<type>(<scope>): <subject>
# 示例
feat(auth): 新增手机号登录功能
fix(order): 修复订单状态显示错误
docs(api): 更新接口文档
refactor(user): 重构用户模块代码结构
```
### Branch 命名格式
```bash
# 常用分支类型
feature/<功能名> # 新功能
bugfix/<问题描述> # 修复 bug
hotfix/<紧急问题> # 紧急修复
release/<版本号> # 发布分支
chore/<任务> # 杂项任务
# 示例
feature/user-auth # 用户认证功能
feature/shopping-cart # 购物车功能
bugfix/login-500-error # 修复登录 500 错误
hotfix/security-patch # 安全补丁
release/v1.2.0 # 发布版本
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| Commit 消息 | `feat(auth): 新增登录功能` | `update`、`fix bug`、`wip` |
| 消息语言 | 统一用英文(或统一用中文) | 混用中英文 |
| 消息长度 | subject ≤ 50 字 | 长篇大论写一坨 |
| 分支命名 | `feature/login-page` | `new`、`test`、`temp` |
| 作用域 | scope 写模块名 | 乱写作用域 |
---
## 原理深入:Angular 规范
目前最流行的 Commit 规范来自 Angular 团队:
```
<type>(<scope>): <subject>
<body>
<footer>
```
### Subject 规则
1. 以动词开头
2. 第一字母小写
3. 结尾不加句号
4. 不超过 50 字符
### Body 规则(可选)
- 解释 **what** 和 **why**,不解释 **how**
- 每行不超过 72 字符
### Footer 规则(可选)
- Breaking changes:`BREAKING CHANGE: xxx`
- 关联 issue:`Closes #123`
---
## 实战代码
### 1. 配置 commit 模板
```bash
# 创建 commit 模板
cat > ~/.gitmessage << 'EOF'
# <type>(<scope>): <subject>
#
# <body>
#
# Types: feat, fix, docs, style, refactor, perf, test, chore, ci
# Example: feat(auth): 新增第三方登录功能
# feat(auth): 新增短信验证码登录
# fix(cart): 修复结算金额显示错误
# docs: 更新 README 安装步骤
EOF
# 配置 Git 使用模板
git config --global commit.template ~/.gitmessage
```
### 2. commit-msg 钩子检查
```bash
# 项目根目录创建 .git/hooks/commit-msg
cat > .git/hooks/commit-msg << 'EOF'
#!/bin/bash
pattern="^(feat|fix|docs|style|refactor|perf|test|chore|ci)(\(.+\))?: .{1,50}"
if ! grep -qE "$pattern" "$1"; then
echo "Commit message 格式不正确"
echo "正确格式: <type>(<scope>): <description>"
exit 1
fi
EOF
chmod +x .git/hooks/commit-msg
```
### 3. 强制分支命名策略(GitHub)
在仓库 Settings → Branches → Branch protection rules 中:
- Require branches to be named before merge
- Pattern: `(feature|bugfix|hotfix|release)/.+`
### 4. Commitizen 工具
```bash
# 安装
npm install -g commitizen
# 使用交互式 commit
git cz
# 输出:
# ? Select the type of change that you're committing: feat
# ? What is the scope of this change? auth
# ? Write a short description: 新增手机号登录
# ? Provide additional context?
# ? Is this a BREAKING CHANGE? No
```
---
## 常见问题
**Q:已经 push 了才发现 commit 消息写错了?**
A:用 `git rebase` 交互式修改:
```bash
git log --oneline -5
# 找到要修改的 commit 的前一个
git rebase -i abc123^
# 把要修改的 commit 前的 pick 改成 edit
# 保存后修改
git commit --amend -m "正确的消息"
git rebase --continue
```
**Q:分支命名大小写敏感吗?**
A:敏感。建议全小写,用 `-` 分隔。
**Q:可以多人共用一个分支吗?**
A:可以,但建议每人一个分支:
```
feature/login/zhangsan # 张三的登录功能分支
feature/login/lisi # 李四的登录功能分支
```
---
## 验收标准
```
☐ 能写出符合规范的 commit message:type(scope): description
☐ 能区分 feat、fix、docs、refactor 等类型的适用场景
☐ 能给分支起有意义的名字:feature/bugfix/hotfix + 描述
☐ 知道 commit subject 不要超过 50 字符
☐ 知道已 push 的 commit 不要 amend
☐ 了解 Angular Commit Message 规范
☐ 能用 commit template 规范团队 commit
```
## 官方来源
- Conventional Commits 规范:[https://www.conventionalcommits.org/](https://www.conventionalcommits.org/)
- Git Book - 自定义 Git:[https://git-scm.com/book/zh/v2/Git-基础-自定义-Git](https://git-scm.com/book/zh/v2/Git-%E5%88%86%E5%88%86%E5%9C%B0%E5%8C%96-Git#_git_hooks)
## 参考文献
[1] Conventional Commits. *Conventional Commits Specification v1.0.0*. [https://www.conventionalcommits.org/](https://www.conventionalcommits.org/)
[2] Angular Team. *Angular Contributing Guide - Commit Message Format*. [https://github.com/angular/angular/blob/main/CONTRIBUTING.md](https://github.com/angular/angular/blob/main/CONTRIBUTING.md)
---
## 1.2 面向对象
> 本章导读:面向对象编程(OOP)是 Python 的核心范式。本章涵盖类定义、继承多态、特殊方法、访问控制、上下文管理器、迭代器和生成器、枚举类。掌握这些,你就能写出结构清晰、可复用的 Python 代码。
---
### 1.2.1 类定义与实例化
> 用 1-2 句话说清:**类是对象的蓝图,实例是根据蓝图创建的具体对象**。
---
## 什么是类?
### 一句话定义
类(Class)是创建对象的模板,定义了对象的属性(数据)和方法(行为)。
### 为什么重要
OOP 让代码更接近现实世界的事物,使大型项目的代码结构清晰、易于维护。
### 生活类比
- **类** = 汽车的图纸(定义所有汽车有什么:4个轮子、方向盘、发动机)
- **实例** = 根据图纸造出来的具体汽车(张三的红色轿车、李四的蓝色SUV)
---
## 举个例子
### 输入
```python
class Dog:
"""狗类"""
def __init__(self, name: str, age: int):
self.name = name # 实例属性
self.age = age
def bark(self) -> str:
return f"{self.name} 汪汪叫!"
def __str__(self) -> str:
return f"Dog(name={self.name}, age={self.age})"
# 创建实例
dog1 = Dog("旺财", 3)
dog2 = Dog("小白", 5)
# 调用方法
print(dog1.bark()) # 旺财 汪汪叫!
print(dog2) # Dog(name=小白, age=5)
```
### 输出
```
旺财 汪汪叫!
Dog(name=小白, age=5)
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| __init__ | 定义初始化逻辑 | 把所有属性都设默认值 |
| self | 第一个参数必须是 self | 忘记写 self 或写成其他名字 |
| 类属性 vs 实例属性 | 实例属性在 __init__ 中定义 | 把所有属性都定义为类属性 |
| 类型注解 | 给属性和方法加类型注解 | 完全没有类型 |
---
## 实战代码
### 1. 完整的类定义
```python
from dataclasses import dataclass
from typing import Optional
class User:
"""用户类"""
# 类属性(所有实例共享)
total_users = 0
def __init__(self, username: str, email: str, age: Optional[int] = None):
self.username = username # 实例属性
self.email = email
self.age = age
User.total_users += 1 # 更新类属性
def introduce(self) -> str:
age_info = f",今年 {self.age} 岁" if self.age else ""
return f"我叫 {self.username}{age_info}"
def __repr__(self) -> str:
return f"User(username={self.username!r}, email={self.email!r})"
# 使用
user1 = User("张三", "zhangsan@example.com", 25)
user2 = User("李四", "lisi@example.com")
print(user1.introduce()) # 我叫 张三,今年 25 岁
print(user2.introduce()) # 我叫 李四
print(User.total_users) # 2
```
### 2. 数据类(简化版)
```python
from dataclasses import dataclass
@dataclass
class Point:
x: float
y: float
color: str = "black" # 带默认值
def distance_to(self, other: 'Point') -> float:
return ((self.x - other.x)**2 + (self.y - other.y)**2) ** 0.5
p1 = Point(0, 0)
p2 = Point(3, 4)
print(p1.distance_to(p2)) # 5.0
```
---
## 常见问题
**Q:类属性和实例属性有什么区别?**
A:类属性所有实例共享,实例属性每个实例独有:
```python
class Dog:
species = "犬科" # 类属性:所有狗共享
def __init__(self, name):
self.name = name # 实例属性:每只狗不同
```
**Q:__init__ 是构造函数吗?**
A:Python 中 `__init__` 不是构造函数,是**初始化方法**。真正的构造函数是 `__new__`(很少用)。
---
## 验收标准
```
☐ 能定义类并创建实例
☐ 能区分类属性和实例属性
☐ 能在 __init__ 中初始化实例属性
☐ 能为类添加方法并通过 self 访问实例属性
☐ 能使用类型注解定义属性和方法参数
```
## 官方来源
- Python 官方文档 - 类:[https://docs.python.org/zh-cn/3/tutorial/classes.html](https://docs.python.org/zh-cn/3/tutorial/classes.html)
- dataclasses:[https://docs.python.org/zh-cn/3/library/dataclasses.html](https://docs.python.org/zh-cn/3/library/dataclasses.html)
## 参考文献
[1] Mark Lutz. *Learning Python (5th Edition)*. O'Reilly, 2013. Chapter 26-28.
---
### 1.2.2 继承与多态
> 用 1-2 句话说清:**继承让类拥有"父子关系",多态让不同对象用同一套接口做不同的事**。
---
## 什么是继承?
### 一句话定义
继承(Inheritance)允许一个新类复用另一个类的属性和方法,同时可以扩展或修改。
### 为什么重要
继承实现代码复用,避免重复定义相似的类。
### 生活类比
```
动物(父类)
├── 狗(子类):继承动物,有尾巴
│ └── 哈士奇(子子类):继承狗,会拆家
├── 猫(子类):继承动物,会爬树
└── 鸟(子类):继承动物,会飞
```
---
## 举个例子
### 输入
```python
class Animal:
def __init__(self, name: str):
self.name = name
def speak(self) -> str:
raise NotImplementedError("子类必须实现 speak 方法")
class Dog(Animal):
def speak(self) -> str:
return f"{self.name} 汪汪!"
class Cat(Animal):
def speak(self) -> str:
return f"{self.name} 喵~"
class Cat(Cat):
def speak(self) -> str:
return f"{self.name} 喵~"
# 多态:同一接口,不同实现
animals: list[Animal] = [Dog("旺财"), Cat("小白")]
for animal in animals:
print(animal.speak())
```
### 输出
```
旺财 汪汪!
小白 喵~
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 继承写法 | `class Child(Parent):` | `class Child extends Parent`(Java 写法) |
| 调用父类 | `super().__init__(name)` | 不调用,丢失父类初始化 |
| 方法覆盖 | 子类重写方法 | 完全重写不调用 super |
| 多继承 | `class C(A, B):` | 菱形继承搞不清 MRO |
---
## 实战代码
### 1. 单继承
```python
class Animal:
def __init__(self, name: str):
self.name = name
def eat(self):
return f"{self.name} 在吃饭"
class Dog(Animal):
def __init__(self, name: str, breed: str):
super().__init__(name) # 调用父类 __init__
self.breed = breed
def bark(self):
return f"{self.name} 汪汪叫!"
dog = Dog("旺财", "哈士奇")
print(dog.eat()) # 旺财 在吃饭(继承自 Animal)
print(dog.bark()) # 旺财 汪汪叫!
print(dog.breed) # 哈士奇
```
### 2. 多继承与 MRO
```python
class Flyable:
def fly(self):
return "我可以飞!"
class Swimmable:
def swim(self):
return "我可以游泳!"
class Duck(Animal, Flyable, Swimmable):
pass
duck = Duck("唐老鸭")
print(duck.fly()) # 我可以飞!
print(duck.swim()) # 我可以游泳!
# 查看方法解析顺序
print(Duck.__mro__)
# (<class 'Duck'>, <class 'Animal'>, <class 'Flyable'>, <class 'Swimmable'>, <class 'object'>)
```
### 3. 抽象基类
```python
from abc import ABC, abstractmethod
class Shape(ABC):
@abstractmethod
def area(self) -> float:
"""计算面积"""
pass
@abstractmethod
def perimeter(self) -> float:
"""计算周长"""
pass
class Rectangle(Shape):
def __init__(self, width: float, height: float):
self.width = width
self.height = height
def area(self) -> float:
return self.width * self.height
def perimeter(self) -> float:
return 2 * (self.width + self.height)
# shape = Shape() # 错误:不能实例化抽象类
rect = Rectangle(3, 4)
print(rect.area()) # 12.0
```
---
## 常见问题
**Q:Python 支持多重继承吗?**
A:支持,但要注意**方法解析顺序(MRO)**:
```python
class A:
def test(self):
print("A")
class B(A):
pass
class C(A):
def test(self):
print("C")
class D(B, C):
pass
D().test() # C(MRO: D -> B -> C -> A)
```
**Q:什么时候用继承?什么时候用组合?**
A:
- **继承**:是的关系("狗是动物")
- **组合**:有的关系("车有引擎")
```python
# 继承
class Dog(Animal): ...
# 组合
class Car:
def __init__(self):
self.engine = Engine() # 车有引擎
```
---
## 验收标准
```
☐ 能用 class Child(Parent) 实现继承
☐ 能在子类中调用 super() 访问父类方法
☐ 能实现方法重写(override)
☐ 能理解多态的概念并实际应用
☐ 能使用 ABC 定义抽象基类
☐ 能区分继承和组合的使用场景
```
## 官方来源
- Python 官方文档 - 继承:[https://docs.python.org/zh-cn/3/tutorial/classes.html#inheritance](https://docs.python.org/zh-cn/3/tutorial/classes.html#inheritance)
- abc 模块:[https://docs.python.org/zh-cn/3/library/abc.html](https://docs.python.org/zh-cn/3/library/abc.html)
## 参考文献
[1] David Goodger. *Python Patterns: Inheritance vs Composition*. [https://python-patterns.guide/](https://python-patterns.guide/)
---
### 1.2.3 特殊方法
> 用 1-2 句话说清:**双下划线方法(__xxx__)让自定义对象拥有 Python 内置行为**。
---
## 什么是特殊方法?
### 一句话定义
特殊方法(Magic Methods / Dunder Methods)是 Python 类预留的钩子,让对象支持 `len()`、`str()`、`+` 等内置操作。
### 为什么重要
让自定义对象"像原生类型一样"工作,代码更 Pythonic。
### 生活类比
"特殊方法"就像给对象装了"开关",打开后就能用 Python 的内置功能。
---
## 常用特殊方法速查
| 方法 | 作用 | 调用场景 |
| --- | --- | --- |
| `__init__` | 初始化 | `obj = Class()` |
| `__str__` | 人类可读字符串 | `print(obj)` |
| `__repr__` | 开发者可读字符串 | `repr(obj)`、调试 |
| `__len__` | 长度 | `len(obj)` |
| `__eq__` | 相等比较 | `obj1 == obj2` |
| `__lt__` | 小于比较 | `obj1 < obj2` |
| `__add__` | 加法 | `obj1 + obj2` |
| `__call__` | 可调用对象 | `obj()` |
---
## 举个例子
### 输入
```python
class Vector:
def __init__(self, x: float, y: float):
self.x = x
self.y = y
def __str__(self) -> str:
return f"Vector({self.x}, {self.y})"
def __repr__(self) -> str:
return f"Vector(x={self.x}, y={self.y})"
def __len__(self) -> int:
return 2 # 二维向量长度固定为 2
def __eq__(self, other: object) -> bool:
if not isinstance(other, Vector):
return NotImplemented
return self.x == other.x and self.y == other.y
def __add__(self, other: 'Vector') -> 'Vector':
return Vector(self.x + other.x, self.y + other.y)
def __abs__(self) -> float:
return (self.x ** 2 + self.y ** 2) ** 0.5
v1 = Vector(3, 4)
v2 = Vector(1, 2)
print(v1) # Vector(3, 4)
print(repr(v1)) # Vector(x=3, y=4)
print(len(v1)) # 2
print(v1 == v2) # False
print(v1 + v2) # Vector(4, 6)
print(abs(v1)) # 5.0
```
### 输出
```
Vector(3, 4)
Vector(x=3, y=4)
2
False
Vector(4, 6)
5.0
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| __str__ vs __repr__ | __str__ 给用户看,__repr__ 给开发者 | 只写一个 |
| 返回类型 | __str__ 返回 str,__len__ 返回 int | 返回值类型搞错 |
| 比较操作 | 用 NotImplemented 而不是 return False | 简单粗暴 return False |
| 数字操作 | 确保类型正确再运算 | 不检查类型 |
---
## 实战代码
### 完整示例:实现一个类似 list 的容器
```python
class Stack:
"""栈数据结构"""
def __init__(self):
self._items = []
def push(self, item):
self._items.append(item)
def pop(self):
if not self._items:
raise IndexError("Pop from empty stack")
return self._items.pop()
def __len__(self) -> int:
return len(self._items)
def __bool__(self) -> bool:
return len(self._items) > 0
def __str__(self) -> str:
return f"Stack({' -> '.join(map(str, self._items))})"
def __iter__(self):
return iter(self._items)
def __contains__(self, item) -> bool:
return item in self._items
# 使用
stack = Stack()
stack.push(1)
stack.push(2)
stack.push(3)
print(len(stack)) # 3
print(bool(stack)) # True
print(stack) # Stack(1 -> 2 -> 3)
print(2 in stack) # True
for item in stack: # 迭代
print(item, end=" ") # 1 2 3
```
---
## 常见问题
**Q:__str__ 和 __repr__ 有什么区别?**
A:
- `__repr__`:给开发者调试用,尽量包含所有信息
- `__str__`:给用户看,可读性好
```python
class Person:
def __repr__(self):
return f"Person(name={self.name!r}, age={self.age})"
def __str__(self):
return self.name
# repr: Person(name='张三', age=25)
# str: 张三
```
**Q:NotImplemented 和 NotImplementedError 有什么区别?**
A:
- `NotImplemented`:特殊值,告诉 Python "这个操作不支持此类型,试试其他的"
- `NotImplementedError`:异常,抛出表示"子类必须实现这个方法"
---
## 验收标准
```
☐ 能实现 __str__ 和 __repr__ 方法
☐ 能实现 __len__ 方法使对象支持 len()
☐ 能实现 __eq__ 和比较方法使对象可比较
☐ 能实现 __add__ 使对象支持 + 运算
☐ 能实现 __call__ 使对象可调用
☐ 知道 NotImplemented 和 NotImplementedError 的区别
```
## 官方来源
- Python 数据模型:[https://docs.python.org/zh-cn/3/reference/datamodel.html](https://docs.python.org/zh-cn/3/reference/datamodel.html)
## 参考文献
[1] Doug Hellmann. *Python Magic Methods*. [https://rszalski.github.io/magicmethods/](https://rszalski.github.io/magicmethods/)
---
### 1.2.4 访问控制
> 用 1-2 句话说清:**Python 的访问控制靠约定,而不是强制**——下划线前缀只是"请勿打扰"的标志。
---
## 什么是访问控制?
### 一句话定义
通过命名约定(单下划线、双下划线)控制属性和方法的访问权限。
### 为什么重要
封装(Encapsulation)是 OOP 的三大特性之一,保护数据不被随意修改。
### Python 的"假"封装
Python 没有真正的 private,用约定来模拟:
| 前缀 | 含义 | 说明 |
| --- | --- | --- |
| `name` | 公开 | 随意访问 |
| `_name` | 受保护 | 约定"请勿外部访问" |
| `__name` | 私有 | 名字被 mangling,不易直接访问 |
---
## 举个例子
### 输入
```python
class BankAccount:
def __init__(self, balance: float):
self.__balance = balance # 私有属性(名字被改成了 _BankAccount__balance)
def deposit(self, amount: float):
if amount <= 0:
raise ValueError("存款金额必须为正")
self.__balance += amount
def withdraw(self, amount: float):
if amount <= 0:
raise ValueError("取款金额必须为正")
if amount > self.__balance:
raise ValueError("余额不足")
self.__balance -= amount
@property
def balance(self):
"""只读属性"""
return self.__balance
# 使用
account = BankAccount(1000)
print(account.balance) # 1000
account.deposit(500) # 存款
print(account.balance) # 1500
account.withdraw(200) # 取款
print(account.balance) # 1300
# account.__balance # AttributeError!访问不到
account._BankAccount__balance # 能访问但不推荐
```
### 输出
```
1000
1500
1300
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 命名 | 私有用 `__name`,受保护用 `_name` | 全部公开 |
| 访问私有属性 | 通过公开方法(getter/setter)或 property | 直接访问 `__name` |
| property | 用 `@property` 装饰器 | 写 `get_name()` 方法 |
| setter | 用 `@name.setter` | 不提供 setter(单向 property) |
---
## 实战代码
### 完整的 property 使用
```python
class User:
def __init__(self, name: str):
self.name = name # 调用 setter
self._age = 0
@property
def age(self) -> int:
"""Getter"""
return self._age
@age.setter
def age(self, value: int):
"""Setter 带验证"""
if value < 0:
raise ValueError("年龄不能为负")
if value > 150:
raise ValueError("年龄不合理")
self._age = value
@age.deleter
def age(self):
"""Deleter"""
print("不允许删除年龄")
# del self._age # 真正删除
user = User("张三")
print(user.age) # 0
user.age = 25 # 调用 setter
print(user.age) # 25
user.age = -1 # ValueError: 年龄不能为负
```
---
## 常见问题
**Q:Python 真的有 private 吗?**
A:没有,但有 name mangling:
```python
class A:
def __init__(self):
self.__secret = 42 # 变成了 _A__secret
a = A()
print(a.__secret) # AttributeError
print(a._A__secret) # 42(能访问但不推荐)
```
**Q:什么时候用 property?**
A:当需要在访问/修改属性时做额外处理(验证、计算等)。
---
## 验收标准
```
☐ 能区分 _name(受保护)和 __name(私有)的使用场景
☐ 能用 @property 定义只读属性
☐ 能用 @name.setter 定义带验证的 setter
☐ 能用 @name.deleter 定义 del 行为
☐ 理解 Python 的封装是约定而非强制
```
## 官方来源
- Python 官方文档 - 标识符:[https://docs.python.org/zh-cn/3/reference/lexical_analysis.html#identifiers](https://docs.python.org/zh-cn/3/reference/lexical_analysis.html#identifiers)
## 参考文献
[1] Mark Lutz. *Learning Python (5th Edition)*. O'Reilly, 2013. Chapter 27.
---
### 1.2.5 上下文管理器
> 用 1-2 句话说清:**上下文管理器让你用 `with` 语句安全地管理资源**,如打开文件、数据库连接。
---
## 什么是上下文管理器?
### 一句话定义
实现 `__enter__` 和 `__exit__` 方法的对象,支持 `with` 语句,自动处理资源清理。
### 为什么重要
确保资源在使用后正确释放,即使发生异常也不会泄露。
### 生活类比
餐厅的"代客泊车":
- `__enter__` = 服务员把车开走
- `__exit__` = 用完餐后服务员把车开回来
- `with` = 整个停车过程
---
## 举个例子
### 输入
```python
# 文件操作 - 上下文管理器
with open("test.txt", "w") as f:
f.write("Hello, World!")
# 离开 with 块后,文件自动关闭
# 即使上面写代码出错,文件也会正确关闭
```
### 等价的代码
```python
f = open("test.txt", "w")
try:
f.write("Hello, World!")
finally:
f.close()
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 使用 | `with obj as f:` | 先 open 再手动 close |
| 自定义 | 用 `@contextmanager` 装饰器 | 每次都写完整类 |
| 异常处理 | contextmanager 会捕获异常 | 不处理异常导致资源泄露 |
---
## 实战代码
### 1. 类实现上下文管理器
```python
class DatabaseConnection:
def __init__(self, db_name: str):
self.db_name = db_name
self.connected = False
def __enter__(self):
print(f"连接数据库: {self.db_name}")
self.connected = True
return self
def __exit__(self, exc_type, exc_val, exc_tb):
print(f"关闭数据库: {self.db_name}")
self.connected = False
return False # 不处理异常,让它传播
def query(self, sql: str):
if not self.connected:
raise RuntimeError("未连接数据库")
return f"执行: {sql}"
# 使用
with DatabaseConnection("users.db") as db:
result = db.query("SELECT * FROM users")
print(result)
# 输出:
# 连接数据库: users.db
# 执行: SELECT * FROM users
# 关闭数据库: users.db
```
### 2. 装饰器实现(推荐)
```python
from contextlib import contextmanager
@contextmanager
def timer(name: str):
"""计时器上下文管理器"""
import time
start = time.time()
print(f"[{name}] 开始")
try:
yield # 关键:yield 之前的代码在 enter 执行,yield 之后在 exit 执行
finally:
end = time.time()
print(f"[{name}] 结束,耗时 {end - start:.2f}s")
# 使用
with timer("数据处理"):
import time
time.sleep(1)
print("处理中...")
# 输出:
# [数据处理] 开始
# 处理中...
# [数据处理] 结束,耗时 1.00s
```
### 3. 嵌套上下文管理器
```python
from contextlib import ExitStack
with ExitStack() as stack:
file1 = stack.enter_context(open("file1.txt", "w"))
file2 = stack.enter_context(open("file2.txt", "w"))
# 所有文件会在 with 块结束时自动关闭
```
---
## 常见问题
**Q:__exit__ 返回 True 会怎样?**
A:抑制异常,不让它传播(不推荐):
```python
def __exit__(self, exc_type, exc_val, exc_tb):
return True # 异常被吞掉了
```
**Q:contextmanager 的 yield 处发生异常会怎样?**
A:`finally` 块仍会执行:
```python
@contextmanager
def my_context():
try:
yield
finally:
print("cleanup") # 无论是否有异常都会执行
```
---
## 验收标准
```
☐ 能使用 with 语句操作文件、数据库等资源
☐ 能用类实现 __enter__ 和 __exit__
☐ 能用 @contextmanager 装饰器实现简单上下文管理器
☐ 理解 with 和 try/finally 的等价关系
☐ 知道 ExitStack 的使用场景
```
## 官方来源
- contextlib 模块:[https://docs.python.org/zh-cn/3/library/contextlib.html](https://docs.python.org/zh-cn/3/library/contextlib.html)
## 参考文献
[1] Python Packaging. *Context Managers and Python's with Statement*. [https://book.pythontips.com/en/latest/context_managers.html](https://book.pythontips.com/en/latest/context_managers.html)
---
### 1.2.6 迭代器与生成器
> 用 1-2 句话说清:**迭代器让你能遍历集合,生成器让你懒加载地产生数据**。
---
## 什么是迭代器?
### 一句话定义
迭代器是实现 `__iter__` 和 `__next__` 的对象,能逐个返回数据。
### 什么是生成器?
### 一句话定义
生成器是使用 `yield` 的特殊函数,按需产生数据,节省内存。
### 为什么重要
处理大数据或无限序列时,生成器只在需要时才计算,内存效率高。
### 生活类比
- **列表**:一次打印出所有菜名(占满桌子)
- **生成器**:服务员端一道吃一道(按需上菜)
---
## 举个例子
### 输入
```python
# 列表:一次性生成所有数据
squares = [x**2 for x in range(10)] # 内存占用大
# 生成器:按需生成
squares_gen = (x**2 for x in range(10)) # 只记录规则
print(next(squares_gen)) # 0
print(next(squares_gen)) # 1
```
### 自定义迭代器
```python
class Counter:
def __init__(self, start: int, end: int):
self.current = start
self.end = end
def __iter__(self):
return self
def __next__(self):
if self.current >= self.end:
raise StopIteration
result = self.current
self.current += 1
return result
for i in Counter(1, 4):
print(i, end=" ") # 1 2 3
```
### 自定义生成器
```python
def fibonacci(n: int):
"""斐波那契数列生成器"""
a, b = 0, 1
for _ in range(n):
yield a
a, b = b, a + b
for num in fibonacci(10):
print(num, end=" ") # 0 1 1 2 3 5 8 13 21 34
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 大数据处理 | 用生成器 | 用列表一次性加载 |
| yield 位置 | 在函数中用 yield | 把 yield 和 return 混用 |
| 迭代器复用 | 每次创建新实例 | 一个迭代器用完再遍历 |
---
## 实战代码
### 1. MyRange 实现
```python
def my_range(start: int, stop: int = None, step: int = 1):
"""实现类似 range() 的生成器"""
if stop is None:
start, stop = 0, start
while start < stop:
yield start
start += step
# 使用
for i in my_range(5):
print(i, end=" ") # 0 1 2 3 4
for i in my_range(1, 10, 2):
print(i, end=" ") # 1 3 5 7 9
```
### 2. 读取大文件
```python
def read_large_file(filepath: str, chunk_size: int = 1024):
"""分块读取大文件"""
with open(filepath, 'r', encoding='utf-8') as f:
while True:
chunk = f.read(chunk_size)
if not chunk:
break
yield chunk
# 使用:每次只读 1KB,不占用大量内存
for chunk in read_large_file("big_file.txt"):
print(chunk)
```
### 3. 无限序列
```python
def infinite_count(start: int = 0):
"""无限计数器"""
while True:
yield start
start += 1
# 使用时加限制
counter = infinite_count(1)
for _ in range(10):
print(next(counter), end=" ") # 1 2 3 4 5 6 7 8 9 10
```
---
## 常见问题
**Q:迭代器和生成器有什么区别?**
A:
- **迭代器**:实现 `__iter__` 和 `__next__` 的对象
- **生成器**:使用 `yield` 的函数,自动实现迭代器协议
```python
# 迭代器类
class MyIterator:
...
# 生成器函数(更简洁)
def my_generator():
yield 1
yield 2
```
**Q:生成器是一次性的吗?**
A:是,遍历完就空了:
```python
gen = (x for x in range(3))
print(list(gen)) # [0, 1, 2]
print(list(gen)) # [] 空了!
```
---
## 验收标准
```
☐ 能理解迭代器的 __iter__ 和 __next__ 协议
☐ 能自定义实现迭代器类
☐ 能用 yield 语法创建生成器函数
☐ 能用生成器表达式替代列表推导式
☐ 能手写 MyRange 例子
☐ 理解生成器省内存的场景
```
## 官方来源
- Python 官方文档 - 迭代器:[https://docs.python.org/zh-cn/3/library/stdtypes.html#iterator-types](https://docs.python.org/zh-cn/3/library/stdtypes.html#iterator-types)
- Python 官方文档 - 生成器:[https://docs.python.org/zh-cn/3/tutorial/classes.html#generators](https://docs.python.org/zh-cn/3/tutorial/classes.html#generators)
## 参考文献
[1] David Beazley & Brian K. Jones. *Python Cookbook (3rd Edition)*. O'Reilly, 2013. Chapter 4.
---
### 1.2.7 枚举类
> 用 1-2 句话说清:**枚举类用有意义的名称代替魔法数字/字符串**,让代码更易读。
---
## 什么是枚举类?
### 一句话定义
枚举(Enum)是一组命名的常量值,提高代码可读性和类型安全。
### 为什么重要
用 `Status.SUCCESS` 代替 `1`,用 `Color.RED` 代替 `"red"`,避免魔法值。
### 生活类比
- 不用枚举:`return 200`(200 是什么鬼?)
- 用枚举:`return HTTPStatus.OK`(一目了然)
---
## 举个例子
### 输入
```python
from enum import Enum
class Color(Enum):
RED = 1
GREEN = 2
BLUE = 3
# 使用
c = Color.RED
print(c) # Color.RED
print(c.name) # RED
print(c.value) # 1
print(c == Color.RED) # True
```
### 输出
```
Color.RED
RED
1
True
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 命名 | `class Status(Enum):` | 用字典或常量 |
| 访问 | `Status.SUCCESS` | `Status["SUCCESS"]`(需要异常处理) |
| 比较 | 用 `==` 或 `is` | 用 `>` `<`(除非继承 IntEnum) |
---
## 实战代码
### 1. 基本枚举
```python
from enum import Enum, auto
class Weekday(Enum):
MONDAY = 1
TUESDAY = 2
WEDNESDAY = 3
THURSDAY = 4
FRIDAY = 5
SATURDAY = 6
SUNDAY = 7
# 自动赋值
class Direction(Enum):
NORTH = auto()
SOUTH = auto()
EAST = auto()
WEST = auto()
print(Weekday.MONDAY.value) # 1
print(Direction.NORTH.value) # 1
```
### 2. IntEnum(可当整数用)
```python
from enum import IntEnum
class HTTPStatus(IntEnum):
OK = 200
NOT_FOUND = 404
INTERNAL_ERROR = 500
# 可以当整数用
print(HTTPStatus.OK + 1) # 201
print(HTTPStatus.OK == 200) # True
```
### 3. Flag(位枚举)
```python
from enum import Flag, auto
class Permission(Flag):
READ = auto()
WRITE = auto()
EXECUTE = auto()
# 组合权限
read_write = Permission.READ | Permission.WRITE
print(read_write) # Permission.READ|WRITE
# 检查权限
if Permission.READ in read_write:
print("有读权限")
```
### 4. 枚举遍历和成员检查
```python
class Status(Enum):
PENDING = 1
RUNNING = 2
SUCCESS = 3
FAILED = 4
# 遍历所有成员
for s in Status:
print(f"{s.name} = {s.value}")
# 成员检查
def check_status(status_value: int):
for s in Status:
if s.value == status_value:
return s
return None
status = check_status(2)
print(status) # Status.RUNNING
# 更优雅的方式
print(Status(2)) # Status.RUNNING
```
---
## 常见问题
**Q:Enum 和 IntEnum 有什么区别?**
A:
- `Enum`:值可以是任意类型,比较用 `==`
- `IntEnum`:值是整数,可以用 `<` `>` 比较
```python
from enum import Enum, IntEnum
class Color(Enum):
RED = 1
class HTTPStatus(IntEnum):
OK = 200
print(Color.RED == 1) # False
print(HTTPStatus.OK == 200) # True
print(HTTPStatus.OK > HTTPStatus.NOT_FOUND) # False(200 < 404)
```
**Q:枚举成员可以有方法吗?**
A:可以:
```python
class Operation(Enum):
ADD = '+'
SUB = '-'
MUL = '*'
DIV = '/'
def apply(self, x, y):
ops = {'+': lambda a, b: a + b, ...}
return ops[self.value](x, y)
print(Operation.ADD.apply(2, 3)) # 5
```
---
## 验收标准
```
☐ 能定义 enum.Enum 的枚举类
☐ 能用枚举成员 .name 和 .value 访问属性
☐ 能用 auto() 自动赋值
☐ 能区分 Enum 和 IntEnum
☐ 能在代码中用枚举替代魔法数字
☐ 能用 Flag 定义位枚举
```
## 官方来源
- enum 模块:[https://docs.python.org/zh-cn/3/library/enum.html](https://docs.python.org/zh-cn/3/library/enum.html)
## 参考文献
[1] Python Official Documentation. *Enum HOW TO*. [https://docs.python.org/zh-cn/3/howto/enum.html](https://docs.python.org/zh-cn/3/howto/enum.html)
---
## 1.3 装饰器
> 本章导读:装饰器是 Python 的高级特性,用于在不修改原函数的情况下增强功能。本章涵盖装饰器基础、带参数的装饰器、functools.wraps、常用内置装饰器、装饰器执行顺序。
---
### 1.3.1 装饰器基础
> 用 1-2 句话说清:**装饰器是一个返回函数的函数**,在不修改原函数的前提下给它添加新功能。
---
## 什么是装饰器?
### 一句话定义
装饰器是一个接收函数作为参数、返回新函数的函数。
### 为什么重要
装饰器实现"横切关注点"(日志、缓存、权限检查),避免代码重复。
### 生活类比
手机壳:
- 原函数 = 手机
- 装饰器 = 手机壳(套上去,不改变手机功能,但增加了保护)
---
## 举个例子
### 输入
```python
def timer(func):
"""计时装饰器"""
def wrapper(*args, **kwargs):
import time
start = time.time()
result = func(*args, **kwargs)
end = time.time()
print(f"{func.__name__} 执行耗时: {end - start:.2f}s")
return result
return wrapper
@timer
def slow_function():
import time
time.sleep(1)
return "完成"
# 等价于:slow_function = timer(slow_function)
slow_function()
```
### 输出
```
slow_function 执行耗时: 1.00s
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 语法 | `@decorator_name` | 不加 @ 手动赋值 |
| 包装函数 | `wrapper` 接收 `*args, **kwargs` | 不接受参数 |
| 返回值 | 返回 `result` | 忘记 return |
---
## 实战代码
### 1. 日志装饰器
```python
import functools
import logging
def log(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
logging.info(f"调用 {func.__name__}")
try:
result = func(*args, **kwargs)
logging.info(f"{func.__name__} 执行成功")
return result
except Exception as e:
logging.error(f"{func.__name__} 执行失败: {e}")
raise
return wrapper
@log
def divide(a, b):
return a / b
```
### 2. 类型检查装饰器
```python
def type_check(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
# 获取函数签名
import inspect
sig = inspect.signature(func)
bound = sig.bind(*args, **kwargs)
bound.apply_defaults()
for name, value in bound.arguments.items():
expected = sig.parameters[name].annotation
if expected != inspect.Parameter.empty and not isinstance(value, expected):
raise TypeError(f"{name} 期望 {expected.__name__},实际 {type(value).__name__}")
return func(*args, **kwargs)
return wrapper
@type_check
def add(a: int, b: int) -> int:
return a + b
print(add(1, 2)) # 3
# add(1, "2") # TypeError
```
---
## 验收标准
```
☐ 能理解装饰器是"接收函数、返回函数"的函数
☐ 能编写简单的装饰器
☐ 知道 wrapper 需要传递 *args 和 **kwargs
☐ 知道 @decorator 语法糖的等价写法
☐ 理解装饰器不修改原函数,只是包装它
```
## 官方来源
- Python 官方文档 - 装饰器:[https://docs.python.org/zh-cn/3/tutorial/controlflow.html#decorators](https://docs.python.org/zh-cn/3/tutorial/controlflow.html#decorators)
## 参考文献
[1] Bruce Eckel. *Python 3 Patterns, Recipes and Idioms*. [https://python-3-patterns-idioms-test.readthedocs.io/](https://python-3-patterns-idioms-test.readthedocs.io/)
---
### 1.3.2 带参数的装饰器
> 用 1-2 句话说清:**带参数的装饰器是一个返回装饰器的工厂函数**。
---
## 什么是带参数的装饰器?
### 一句话定义
装饰器工厂:外层函数接收参数,返回真正的装饰器。
### 结构
```
def decorator_factory(arg1, arg2): # 接收装饰器参数
def decorator(func): # 接收被装饰函数
def wrapper(*args, **kwargs): # 包装函数
# 用 arg1, arg2 做些什么
return func(*args, **kwargs)
return wrapper
return decorator
```
---
## 举个例子
### 输入
```python
def repeat(times: int):
"""重复执行函数的装饰器"""
def decorator(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
results = []
for _ in range(times):
result = func(*args, **kwargs)
results.append(result)
return results
return wrapper
return decorator
@repeat(3)
def greet(name: str):
return f"Hello, {name}!"
print(greet("World"))
```
### 输出
```
['Hello, World!', 'Hello, World!', 'Hello, World!']
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 结构 | `outer(params) -> decorator -> wrapper` | 直接装饰器带参数 |
| 参数传递 | 每层正确传递 | 参数丢失 |
---
## 实战代码
### 带日志级别的装饰器
```python
import functools
import logging
def log(level: str):
"""带日志级别的装饰器"""
levels = {
'DEBUG': logging.DEBUG,
'INFO': logging.INFO,
'WARNING': logging.WARNING,
'ERROR': logging.ERROR,
}
def decorator(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
logging.log(levels[level], f"调用 {func.__name__}")
return func(*args, **kwargs)
return wrapper
return decorator
@log('INFO')
def process():
pass
@log('DEBUG')
def debug_process():
pass
```
---
## 验收标准
```
☐ 能理解装饰器工厂的三层结构
☐ 能编写带参数的装饰器
☐ 能在装饰器参数中使用闭包变量
```
## 官方来源
- Python functools 模块:[https://docs.python.org/zh-cn/3/library/functools.html](https://docs.python.org/zh-cn/3/library/functools.html)
---
### 1.3.3 functools.wraps
> 用 1-2 句话说清:**@wraps 保留原函数的元信息**,让装饰后的函数看起来"还是原来的函数"。
---
## 什么是 functools.wraps?
### 一句话定义
`@functools.wraps(func)` 把被装饰函数的 `__name__`、`__doc__` 等元信息复制到 wrapper 函数。
### 为什么重要
没有 @wraps,`func.__name__` 会变成 `wrapper`,文档和类型检查会出错。
---
## 举个例子
### 输入
```python
def my_decorator(func):
def wrapper(*args, **kwargs):
return func(*args, **kwargs)
return wrapper
@my_decorator
def hello():
"""打招呼函数"""
return "Hello!"
print(hello.__name__) # 不加 @wraps: "wrapper",加了: "hello"
print(hello.__doc__) # 不加: None,加了: "打招呼函数"
```
### 加 @wraps 后
```python
import functools
def my_decorator(func):
@functools.wraps(func) # 放在 wrapper 前面
def wrapper(*args, **kwargs):
return func(*args, **kwargs)
return wrapper
@my_decorator
def hello():
"""打招呼函数"""
return "Hello!"
print(hello.__name__) # "hello"
print(hello.__doc__) # "打招呼函数"
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 位置 | `@functools.wraps(func)` 在 wrapper 定义内 | 放在外层 |
| 参数 | `@functools.wraps(func)` 传入被装饰函数 | 忘记传参 |
---
## 实战代码
### 需要 @wraps 的场景
```python
import functools
def debug(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
print(f"调用 {func.__name__}")
result = func(*args, **kwargs)
print(f"{func.__name__} 返回 {result}")
return result
return wrapper
@debug
def add(a: int, b: int) -> int:
"""返回两数之和"""
return a + b
# @wraps 让这些正常工作
print(add.__name__) # "add"(不是 "wrapper")
print(add.__doc__) # "返回两数之和"
print(add.__annotations__) # {'a': <class 'int'>, 'b': <class 'int'>, 'return': <class 'int'>}
# inspect 也能正常工作
import inspect
print(inspect.signature(add)) # (a: int, b: int) -> int
```
---
## 常见问题
**Q:不用 @wraps 会怎样?**
A:
```python
# 不加 @wraps
add.__name__ # "wrapper"
add.__doc__ # None
add.__annotations__ # {}(可能)
# 问题:
# 1. help(add) 显示的是 wrapper 的文档
# 2. 依赖 __name__ 的工具(如 Flask 路由)可能出错
# 3. 类型检查器会困惑
```
---
## 验收标准
```
☐ 知道 @functools.wraps 的作用
☐ 能在自定义装饰器中使用 @wraps
☐ 能解释 @wraps 保留哪些元信息
☐ 理解 @wraps 对调试和文档的重要性
```
---
### 1.3.4 常用内置装饰器
> 用 1-2 句话说清:**Python 内置了 @property、@staticmethod、@classmethod 等装饰器**,让类方法更灵活。
---
## 常用内置装饰器
| 装饰器 | 作用 | 特点 |
| --- | --- | --- |
| `@property` | 把方法变成属性 | 访问时不用加 `()` |
| `@staticmethod` | 静态方法 | 不需要 self/cls |
| `@classmethod` | 类方法 | 第一个参数是 cls |
---
## 举个例子
### 输入
```python
class Circle:
def __init__(self, radius: float):
self._radius = radius
@property
def radius(self) -> float:
"""半径(只读)"""
return self._radius
@property
def area(self) -> float:
"""面积(计算属性)"""
return 3.14 * self._radius ** 2
@staticmethod
def pi() -> float:
"""返回 π 值"""
return 3.14
@classmethod
def from_diameter(cls, diameter: float):
"""从直径创建圆"""
return cls(diameter / 2)
c = Circle(5)
print(c.radius) # 5(像属性一样访问)
print(c.area) # 78.5(自动计算)
print(Circle.pi()) # 3.14(不需要实例)
c2 = Circle.from_diameter(20) # 从直径创建
```
### 输出
```
5
78.5
3.14
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| @staticmethod | 不需要访问类或实例属性 | 用 self.xxx |
| @classmethod | 第一个参数是 cls | 第一个参数是 self |
| @property | 定义只读或计算属性 | 在 setter 外修改其他属性 |
---
## 实战代码
### @property 实现 getter/setter
```python
class Temperature:
def __init__(self, celsius: float):
self._celsius = celsius
@property
def celsius(self) -> float:
return self._celsius
@celsius.setter
def celsius(self, value: float):
if value < -273.15:
raise ValueError("温度不能低于绝对零度")
self._celsius = value
@property
def fahrenheit(self) -> float:
return self._celsius * 9/5 + 32
@fahrenheit.setter
def fahrenheit(self, value: float):
self._celsius = (value - 32) * 5/9
t = Temperature(25)
print(t.fahrenheit) # 77.0
t.fahrenheit = 32
print(t.celsius) # 0.0
```
---
## 验收标准
```
☐ 能区分 @staticmethod、@classmethod、@property 的使用场景
☐ 能用 @property 定义只读属性
☐ 能用 @xxx.setter 定义 setter
☐ 知道 @classmethod 常用于替代构造函数
```
---
### 1.3.5 装饰器执行顺序
> 用 1-2 句话说清:**多个装饰器从上到下执行,但 wrapper 函数从下到上执行**。
---
## 装饰器执行顺序
### 原则
```
多层装饰器的执行顺序:
1. 从下到上依次调用装饰器
2. wrapper 函数从内到外执行
```
### 执行图示
```
@decorator_a ← 上
@decorator_b ← 下
等价于:decorator_a(decorator_b(func))
执行顺序:
wrapper_a(wrapper_b(func))
↓
wrapper_b(func)
↓
func()
↓
wrapper_b 返回
↓
wrapper_a 返回
```
---
## 举个例子
### 输入
```python
import functools
def decorator_a(func):
print("装饰器 A")
@functools.wraps(func)
def wrapper(*args, **kwargs):
print("A 开始")
result = func(*args, **kwargs)
print("A 结束")
return result
return wrapper
def decorator_b(func):
print("装饰器 B")
@functools.wraps(func)
def wrapper(*args, **kwargs):
print("B 开始")
result = func(*args, **kwargs)
print("B 结束")
return result
return wrapper
@decorator_a
@decorator_b
def hello():
print("Hello!")
hello()
```
### 输出
```
装饰器 B ← 装饰器从下到上初始化
装饰器 A
--- 调用 hello() 时 ---
B 开始 ← wrapper 从内到外执行
Hello!
B 结束
A 开始
A 结束
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 顺序 | 装饰器初始化:下→上,wrapper 执行:内→外 | 混淆两个方向 |
| 调试 | 给每个 wrapper 打印日志 | 乱写顺序不验证 |
---
## 实战代码
### 典型场景:多个装饰器
```python
def log(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
print(f"[LOG] 调用 {func.__name__}")
return func(*args, **kwargs)
return wrapper
def timer(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
import time
start = time.time()
result = func(*args, **kwargs)
print(f"[TIMER] {func.__name__} 耗时 {time.time() - start:.2f}s")
return result
return wrapper
def retry(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
for attempt in range(3):
try:
return func(*args, **kwargs)
except Exception as e:
if attempt == 2:
raise
print(f"[RETRY] 重试 {attempt + 1}")
return func(*args, **kwargs) # unreachable but for clarity
return wrapper
@log
@timer
@retry
def fetch_data():
print("获取数据中...")
return "数据"
fetch_data()
```
---
## 验收标准
```
☐ 能画出多层装饰器的执行顺序图
☐ 能说出装饰器初始化顺序和 wrapper 执行顺序
☐ 能在实际代码中正确排列装饰器顺序
☐ 理解顺序对调试和错误处理的影响
```
## 官方来源
- Python 官方文档 - 装饰器定义:[https://docs.python.org/zh-cn/3/reference/compound_stmts.html#function](https://docs.python.org/zh-cn/3/reference/compound_stmts.html#function)
---
## 1.4 异步编程
> 本章导读:异步编程是现代 Python 并发的基础,让程序在等待 I/O 时可以做其他事。本章涵盖 async/await 语法、asyncio 基本使用、常见错误、异步 vs 同步对比。
---
### 1.4.1 async / await 语法
> 用 1-2 句话说清:**async/await 是 Python 异步编程的语法糖,让并发代码看起来像同步代码**。
---
## 什么是 async/await?
### 一句话定义
- `async def`:定义一个可以"暂停"的函数(协程)
- `await`:暂停当前协程,等待另一个协程完成
### 为什么重要
异步 I/O 比同步 I/O 高效 10-100 倍,尤其适合网络请求、文件操作。
### 生活类比
餐厅点菜:
- **同步**:等第一道菜上完才点第二道
- **异步**:把菜单给服务员,去做别的事,等叫号再去取
---
## 举个例子
### 输入
```python
import asyncio
async def fetch_user(user_id: int):
"""模拟获取用户数据"""
await asyncio.sleep(1) # 模拟网络请求
return {"id": user_id, "name": f"用户{user_id}"}
async def main():
# 创建协程(还没执行)
coro1 = fetch_user(1)
coro2 = fetch_user(2)
# 并发执行两个协程
results = await asyncio.gather(coro1, coro2)
print(results)
# 运行
asyncio.run(main())
```
### 输出
```
[{'id': 1, 'name': '用户1'}, {'id': 2, 'name': '用户2'}]
# 只用了 ~1 秒,而不是 2 秒
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 定义函数 | `async def func():` | `def func():` 然后 await |
| 调用协程 | `await func()` 或 `asyncio.run()` | 直接 `func()` |
| 返回值 | 普通 return | 不需要 await return |
---
## 实战代码
### 1. 基础语法
```python
import asyncio
# 定义异步函数
async def say_hello():
print("Hello")
await asyncio.sleep(1) # 暂停 1 秒(不阻塞其他代码)
print("World")
# 运行
asyncio.run(say_hello())
# async 函数返回的是协程对象
print(say_hello()) # <coroutine object say_hello at 0x...>
```
### 2. await 等待多个任务
```python
async def task(id: int):
await asyncio.sleep(1)
return f"Task {id}"
async def main():
# 方法 1:gather(并发执行)
results = await asyncio.gather(
task(1),
task(2),
task(3)
)
print(results)
# 方法 2:create_task(后台执行)
t1 = asyncio.create_task(task(1))
t2 = asyncio.create_task(task(2))
# 两个任务同时运行
r1 = await t1
r2 = await t2
asyncio.run(main())
```
---
## 验收标准
```
☐ 能用 async def 定义异步函数
☐ 能用 await 等待协程
☐ 能用 asyncio.run() 运行顶层协程
☐ 能区分普通函数和协程函数
☐ 能用 asyncio.gather 并发执行多个任务
```
## 官方来源
- asyncio 模块:[https://docs.python.org/zh-cn/3/library/asyncio.html](https://docs.python.org/zh-cn/3/library/asyncio.html)
## 参考文献
[1] Yifei Ding. *Python Asyncio Tutorial*. [https://docs.python.org/zh-cn/3/library/asyncioyncio.html](https://docs.python.org/zh-cn/3/library/asyncioyncio.html)
---
### 1.4.2 asyncio 基本使用
> 用 1-2 句话说清:**asyncio 是 Python 的异步 I/O 框架,提供事件循环、任务调度、协程管理**。
---
## asyncio 核心组件
| 组件 | 作用 |
| --- | --- |
| `asyncio.run()` | 运行顶层协程,创建事件循环 |
| `asyncio.create_task()` | 创建后台任务 |
| `asyncio.gather()` | 并发执行多个协程 |
| `asyncio.sleep()` | 异步睡眠(不阻塞) |
| `asyncio.wait()` | 等待多个任务完成 |
---
## 实战代码
### 1. 完整示例
```python
import asyncio
import time
async def fetch(url: str, delay: float):
"""模拟网络请求"""
print(f"开始请求: {url}")
await asyncio.sleep(delay)
print(f"完成请求: {url}")
return f"响应 from {url}"
async def main():
start = time.time()
# 并发请求(同时发出,同时等待)
results = await asyncio.gather(
fetch("https://api.example.com/users", 1.0),
fetch("https://api.example.com/posts", 0.5),
fetch("https://api.example.com/comments", 1.5),
)
elapsed = time.time() - start
print(f"总耗时: {elapsed:.2f}s") # ~1.5s(最长那个)
print(f"结果: {results}")
asyncio.run(main())
```
### 2. Task 的取消
```python
async def long_task():
try:
for i in range(10):
print(f"执行 {i}/10")
await asyncio.sleep(1)
except asyncio.CancelledError:
print("任务被取消")
raise
async def main():
task = asyncio.create_task(long_task())
await asyncio.sleep(3)
task.cancel() # 取消任务
try:
await task
except asyncio.CancelledError:
print("main: 任务已取消")
asyncio.run(main())
```
### 3. 超时控制
```python
async def slow_task():
await asyncio.sleep(5)
return "完成"
async def main():
try:
result = await asyncio.wait_for(slow_task(), timeout=2.0)
print(result)
except asyncio.TimeoutError:
print("任务超时!")
asyncio.run(main())
```
---
## 验收标准
```
☐ 能用 asyncio.run() 运行协程
☐ 能用 asyncio.create_task() 创建后台任务
☐ 能用 asyncio.gather() 并发执行
☐ 能用 asyncio.wait_for() 设置超时
☐ 能取消 asyncio 任务
```
---
### 1.4.3 常见错误
> 用 1-2 句话说清:**异步编程最常见的错误是忘记 await,导致协程对象被创建但从未执行**。
---
## 常见错误
### 错误 1:忘记 await
```python
async def fetch_data():
return {"data": "value"}
async def main():
result = fetch_data() # ❌ 错误!协程对象,没执行
print(result) # <coroutine object fetch_data...>
# 正确写法
result = await fetch_data() # ✅
print(result) # {'data': 'value'}
```
### 错误 2:在非异步函数中 await
```python
def sync_function():
result = await fetch_data() # ❌ 语法错误!
```
### 错误 3:混用同步和异步代码
```python
import time
async def slow_async():
await asyncio.sleep(1)
return "async"
def sync_slow():
time.sleep(1) # ❌ 这会阻塞整个事件循环!
return "sync"
```
---
## 错误表现与解决
### 忘记 await 的报错
```python
# 运行时没有任何报错,但结果不对
async def main():
result = fetch_data() # 忘记 await
print(result)
# 输出:<coroutine object fetch_data at 0x...>
# asyncio.run() 不会报错,只是协程没执行
```
### 正确做法
```python
# 始终确保 await
async def main():
result = await fetch_data()
print(result)
```
---
## 验收标准
```
☐ 能识别"忘记 await"导致的协程对象
☐ 能区分同步代码和异步代码的执行方式
☐ 知道在同步函数中不能使用 await
☐ 理解混用同步 sleep 和 asyncio 的后果
```
---
### 1.4.4 异步 vs 同步对比
> 用 1-2 句话说清:**异步比同步快,因为 I/O 等待期间可以做其他事**。
---
## 对比示例
### 同步版本
```python
import time
import requests
def fetch_all(urls: list[str]):
start = time.time()
results = []
for url in urls:
resp = requests.get(url) # 阻塞等待
results.append(resp.json())
elapsed = time.time() - start
print(f"同步耗时: {elapsed:.2f}s")
return results
# 10 个请求,每个 0.5 秒
# 总耗时:10 * 0.5 = 5 秒
```
### 异步版本
```python
import asyncio
import aiohttp
async def fetch_all_async(urls: list[str]):
start = time.time()
async def fetch_one(session, url):
async with session.get(url) as resp:
return await resp.json()
async with aiohttp.ClientSession() as session:
tasks = [fetch_one(session, url) for url in urls]
results = await asyncio.gather(*tasks)
elapsed = time.time() - start
print(f"异步耗时: {elapsed:.2f}s")
return results
# 10 个请求,每个 0.5 秒
# 总耗时:0.5 秒(并发执行)
```
### 性能对比
| 方式 | 10 个 0.5s 请求 | 100 个请求 |
| --- | --- | --- |
| 同步 | 5 秒 | 50 秒 |
| 异步 | 0.5 秒 | 0.5 秒 |
| 提升 | 10 倍 | 100 倍 |
---
## 实战代码
### 选择异步还是同步?
| 场景 | 推荐 |
| --- | --- |
| CPU 密集型(计算、加密) | 同步 + 多进程 |
| I/O 密集型(网络请求、文件读写) | 异步 |
| 简单的单次请求 | 同步(代码简单) |
| 大量并发请求 | 异步 |
| 混合场景 | 同步做 CPU 部分,异步做 I/O 部分 |
---
## 验收标准
```
☐ 能用 time.time() 对比同步和异步的执行时间
☐ 能区分 CPU 密集型和 I/O 密集型任务
☐ 能根据场景选择同步或异步
☐ 能说出异步的主要优势
```
## 官方来源
- aiohttp 文档:[https://docs.aiohttp.org/](https://docs.aiohttp.org/)
## 参考文献
[1] Yifei Ding. *Speed Up Your Python With Asyncio*. Real Python. [https://realpython.com/async-io-python/](https://realpython.com/async-io-python/)
---
## 1.5 Python 代码规范
> 本章导读:好的代码规范让代码更易读、易维护、易协作。本章涵盖 PEP8 规范、类型注解、虚拟环境、包结构规范。
---
### 1.5.1 PEP8 规范要点
> 用 1-2 句话说清:**PEP8 是 Python 的官方代码风格指南**,遵循它让你的代码更 Pythonic。
---
## 核心规则
### 1. 缩进
```python
# ✅ 正确:4 个空格
if True:
do_something()
# ❌ 错误:混合 tab 和空格
if True:
→ do_something()
```
### 2. 行长度
```python
# ✅ 每行不超过 79 字符(编辑器推荐 100-120)
def long_function_name(
arg1, arg2, arg3, arg4
):
pass
# 或使用括号
text = (
"这是一个很长的字符串,"
"它被拆成了多行"
)
```
### 3. 空行
```python
# 模块顶层函数之间:2 个空行
def func_a():
pass
def func_b():
pass
# 类方法之间:1 个空行
class MyClass:
def method_a(self):
pass
def method_b(self):
pass
```
### 4. Import
```python
# ✅ 标准库 → 第三方库 → 本地库的顺序
import os
import sys
import第三方库
import mymodule
# ✅ 每组 import 之间用空行分隔
# ✅ 避免 from xxx import *(除非明确知道导出了什么)
```
### 5. 空格
```python
# ✅ 正确
spam(ham[1], {eggs: 2})
i = i + 1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)
# ❌ 错误
spam( ham[1], {eggs: 2}) # 紧跟括号
i=i+1 # 操作符两侧无空格
x = x*2 - 1 # 优先级混乱
c = (a+b) * (a-b) # 同上
```
### 6. 命名
| 类型 | 命名规则 | 示例 |
| --- | --- | --- |
| 变量/函数 | 小写下划线 | `my_variable`, `my_function` |
| 类 | 大写开头驼峰 | `MyClass` |
| 常量 | 全大写下划线 | `MAX_SIZE`, `PI` |
| 私有属性 | 前置下划线 | `_private_var` |
| 特殊变量 | 双下划线开头/结尾 | `__init__`, `__all__` |
---
## 常用工具
### black(自动格式化)
```bash
pip install black
black myfile.py # 格式化文件
black . # 格式化整个目录
```
### flake8(代码检查)
```bash
pip install flake8
flake8 myfile.py # 检查代码
flake8 --max-line-length=120 . # 自定义行长度
```
### autopep8(自动修复)
```bash
pip install autopep8
autopep8 --in-place --aggressive myfile.py
```
---
## 验收标准
```
☐ 能说出 PEP8 的核心规则(缩进、空格、命名、空行)
☐ 能用 black 格式化代码
☐ 能用 flake8 检查代码风格
☐ 能区分变量、函数、类、常量的命名规则
```
## 官方来源
- PEP 8 官方文档:[https://peps.python.org/pep-0008/](https://peps.python.org/pep-0008/)
- PEP 8 中文翻译:[https://pep8.org/](https://pep8.org/)
---
### 1.5.2 类型注解
> 用 1-2 句话说清:**类型注解让函数和变量的类型"可见"**,IDE 能提示错误,代码更易维护。
---
## 基本语法
### 变量注解
```python
name: str = "张三"
age: int = 25
is_active: bool = True
score: float = 95.5
items: list = [] # 或 list[str](Python 3.9+)
```
### 函数注解
```python
def greet(name: str) -> str:
return f"Hello, {name}"
def add(a: int, b: int) -> int:
return a + b
```
---
## 常用类型
| 类型 | 说明 | 示例 |
| --- | --- | --- |
| `int`, `str`, `bool`, `float` | 基础类型 | `x: int = 1` |
| `list[T]`, `dict[K, V]`, `set[T]` | 泛型容器 | `list[int]`, `dict[str, int]` |
| `tuple[T, ...]` | 元组(固定/可变长度) | `tuple[int, str]` |
| `Optional[X]` | 可选类型(X 或 None) | `Optional[str]` |
| `Union[X, Y]` | 联合类型(X 或 Y) | `Union[int, str]` |
| `Callable[[Args], Return]` | 可调用对象 | `Callable[[int], str]` |
| `Any` | 任意类型 | `x: Any` |
---
## 实战代码
### 1. 基础注解
```python
from typing import List, Dict, Optional, Union, Callable
def process_user(
user_id: int,
name: str,
email: Optional[str] = None,
roles: List[str] = None,
metadata: Dict[str, Any] = None
) -> Dict[str, Any]:
if roles is None:
roles = []
if metadata is None:
metadata = {}
return {
"id": user_id,
"name": name,
"email": email,
"roles": roles,
"metadata": metadata
}
```
### 2. 复杂类型
```python
from typing import TypeVar, Generic, Protocol
# TypeVar(泛型变量)
T = TypeVar('T')
class Stack(Generic[T]):
def __init__(self) -> None:
self._items: List[T] = []
def push(self, item: T) -> None:
self._items.append(item)
def pop(self) -> T:
if not self._items:
raise IndexError("Stack is empty")
return self._items.pop()
def is_empty(self) -> bool:
return len(self._items) == 0
# 使用
stack: Stack[int] = Stack()
stack.push(1)
stack.push(2)
print(stack.pop()) # 2
```
### 3. Python 3.10+ 新语法
```python
# 使用 | 代替 Optional 和 Union
def func(x: int | str | None) -> int | str:
...
# match 语句
match x:
case int() as n if n > 0:
return "正整数"
case str() as s:
return s
case None:
return "无"
```
---
## 常见问题
**Q:加了类型注解会影响性能吗?**
A:不会。类型注解只在运行时用于类型检查,不影响执行性能。
**Q:mypy 是什么?**
A:静态类型检查器,在运行前检查类型错误:
```bash
pip install mypy
mypy myfile.py
```
---
## 验收标准
```
☐ 能为函数参数和返回值添加类型注解
☐ 能使用 Optional、Union、List、Dict 等常用类型
☐ 能在 Python 3.9+ 使用 list[int] 语法
☐ 知道类型注解不改变运行时行为
☐ 能用 mypy 进行静态类型检查
```
## 官方来源
- typing 模块:[https://docs.python.org/zh-cn/3/library/typing.html](https://docs.python.org/zh-cn/3/library/typing.html)
- mypy 文档:[https://mypy.readthedocs.io/](https://mypy.readthedocs.io/)
---
### 1.5.3 虚拟环境
> 用 1-2 句话说清:**虚拟环境让每个项目有独立的依赖**,避免版本冲突。
---
## 为什么需要虚拟环境?
```
项目 A 需要 Django 3.2
项目 B 需要 Django 4.0
↓
全局安装?冲突!
↓
虚拟环境:每个项目独立的 Python 环境
```
---
## venv(推荐,Python 3.3+ 内置)
### 创建和激活
```bash
# 创建虚拟环境
python -m venv myenv
# 激活(Linux/Mac)
source myenv/bin/activate
# 激活(Windows)
myenv\Scripts\activate
# 激活后提示符会变成 (myenv)
```
### 使用
```bash
# 安装依赖
pip install flask requests
# 生成依赖文件
pip freeze > requirements.txt
# 其他机器安装
pip install -r requirements.txt
# 退出虚拟环境
deactivate
```
---
## conda(Anaconda/Miniconda)
### 基本命令
```bash
# 创建环境
conda create -n myenv python=3.11
# 激活
conda activate myenv
# 安装包
conda install numpy pandas
# 导出环境
conda env export > environment.yml
# 从文件创建环境
conda env create -f environment.yml
```
### conda vs venv
| 维度 | venv | conda |
| --- | --- | --- |
| 适用场景 | 纯 Python 项目 | Python + 非 Python 依赖(C/C++) |
| 包管理 | pip | conda + pip |
| 体积 | 轻量 | 较大(含科学计算预装) |
---
## 实战代码
### 完整项目初始化流程
```bash
# 1. 创建项目目录
mkdir myproject && cd myproject
# 2. 创建虚拟环境
python -m venv .venv
# 3. 激活环境
source .venv/bin/activate # Linux/Mac
# 或 .venv\Scripts\activate # Windows
# 4. 升级 pip
pip install --upgrade pip
# 5. 安装依赖
pip install flask pytest black mypy
# 6. 生成 requirements.txt
pip freeze > requirements.txt
# 7. 提交代码(忽略虚拟环境)
# .gitignore 添加:.venv/
```
### .gitignore 示例
```
# 虚拟环境
.venv/
venv/
env/
# IDE
.vscode/
.idea/
# Python
__pycache__/
*.py[cod]
*.egg-info/
dist/
build/
# 测试
.pytest_cache/
.coverage
htmlcov/
# 环境变量
.env
```
---
## 验收标准
```
☐ 能用 python -m venv 创建虚拟环境
☐ 能激活和停用虚拟环境
☐ 能用 pip freeze 生成 requirements.txt
☐ 能用 pip install -r 安装依赖
☐ 知道 .gitignore 中需要忽略哪些文件
☐ 能区分 venv 和 conda 的适用场景
```
## 官方来源
- venv 模块:[https://docs.python.org/zh-cn/3/library/venv.html](https://docs.python.org/zh-cn/3/library/venv.html)
- conda 文档:[https://docs.conda.io/](https://docs.conda.io/)
---
### 1.5.4 包结构规范
> 用 1-2 句话说清:**良好的项目结构让代码可维护、可测试、可发布**。
---
## 标准项目布局
```
myproject/
├── .venv/ # 虚拟环境(可选)
├── src/ # 源代码
│ └── mypackage/ # 包目录
│ ├── __init__.py # 包初始化
│ ├── module1.py # 模块
│ ├── module2.py
│ └── subpackage/ # 子包
│ ├── __init__.py
│ └── module3.py
├── tests/ # 测试
│ ├── __init__.py
│ ├── test_module1.py
│ └── test_module2.py
├── docs/ # 文档
├── pyproject.toml # 项目配置(现代方式)
├── setup.py # 安装脚本(可选)
├── README.md # 项目说明
├── LICENSE # 许可证
├── .gitignore
└── requirements.txt # 依赖(可选)
```
---
## pyproject.toml 示例
```toml
[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "mypackage"
version = "0.1.0"
description = "我的 Python 包"
readme = "README.md"
requires-python = ">=3.9"
license = {text = "MIT"}
authors = [
{name = "Your Name", email = "you@example.com"}
]
dependencies = [
"requests>=2.28.0",
"click>=8.0.0",
]
[project.optional-dependencies]
dev = ["pytest>=7.0", "black>=22.0", "mypy>=0.950"]
[project.scripts]
mycmd = "mypackage.cli:main"
[tool.black]
line-length = 88
target-version = ['py39']
[tool.mypy]
python_version = "3.9"
warn_return_any = true
```
---
## 实战代码
### 1. src layout(推荐)
```bash
# 创建项目结构
mkdir -p src/mypackage/tests
touch src/mypackage/__init__.py
touch src/mypackage/module.py
touch tests/__init__.py
touch tests/test_module.py
# src/mypackage/module.py
def hello():
return "Hello, World!"
# tests/test_module.py
from mypackage import hello
def test_hello():
assert hello() == "Hello, World!"
```
### 2. 安装为可编辑模式
```bash
# 安装项目(开发模式)
pip install -e .
# 现在可以 import
python -c "from mypackage import hello; print(hello())"
```
---
## 常见问题
**Q:为什么推荐 src layout?**
A:
1. 避免导入时意外 import 项目的测试文件
2. 模拟真实用户安装后的环境
3. 更容易做可编辑安装(`pip install -e .`)
**Q:setup.py 和 pyproject.toml 用哪个?**
A:用 **pyproject.toml**(现代推荐)。setup.py 是旧方式,pyproject.toml 更简洁。
---
## 验收标准
```
☐ 能搭建标准的项目结构
☐ 能在 pyproject.toml 中定义项目元数据和依赖
☐ 能理解 src layout 的优势
☐ 能用 pip install -e . 安装开发模式
☐ 知道如何组织 tests 目录
☐ 能写好 README.md(安装、使用、许可证)
```
## 官方来源
- Python 打包指南:[https://packaging.python.org/](https://packaging.python.org/)
- pyproject.toml 规范:[https://packaging.python.org/en/latest/specifications/pyproject-toml/](https://packaging.python.org/en/latest/specifications/pyproject-toml/)
## 参考文献
[1] Hynek Schlawack. *Testing & Packaging*. [https://hynek.me/articles/testing-packaging/](https://hynek.me/articles/testing-packaging/)
---
## 附录:模块一总结
恭喜你完成了 **Python 工程化** 模块的全部内容!
### 学习成果检查
```
Git 使用(1.1)✅
├── 首次配置、克隆、分支、同步
├── 提交、推送、合并与冲突
├── 历史查看、版本回退、暂存
└── Commit 规范与分支命名
面向对象(1.2)✅
├── 类与实例、继承与多态
├── 特殊方法、访问控制
├── 上下文管理器、迭代器、枚举类
装饰器(1.3)✅
├── 装饰器基础、带参数装饰器
├── functools.wraps、内置装饰器
└── 装饰器执行顺序
异步编程(1.4)✅
├── async/await 语法
├── asyncio 基本使用
├── 常见错误、异步 vs 同步
代码规范(1.5)✅
├── PEP8 规范、类型注解
├── 虚拟环境、包结构规范
```
### 继续学习
- **模块二**:PyTorch 基础
- **模块六**:RAG 基础
- **模块七**:工程实操(FastAPI、PostgreSQL、Redis、Docker、pytest)
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑!
请 注册 或者 后发表评论