项目审阅报告¶

整体质量很高，教学内容准确、结构清晰。以下按优先级汇总发现的问题。

高优先级（事实错误/误导读者）¶

#	位置	问题
1	`docs/09-stdlib.md:158`	JSON escape 示例输入输出相同 `"小明"→"小明"`，应展示 `"\u5c0f\u660e"`
2	`examples/02_functions.py:18`	可变默认参数注释错误：`print("bad:", add_bad("a"), add_bad("b"))` 注释写 `['a'] ['a','b']`，实际输出是 `['a','b'] ['a','b']`（print 参数求值后共享同一 list）
3	`examples/12_gotchas.py:26`	同上问题，同一反模式在不同文件重复出错

#	位置	问题
4	`bookmarks-api/Dockerfile`	未 COPY `uv.lock` 且用 `uv sync`（非 `--frozen`），构建不可复现
5	`bookmarks-api/pyproject.toml`	`sqlmodel>=0.0.22` 是未使用的依赖，代码实际用的是 SQLAlchemy `Mapped` 风格
6	`bookmarks-api/main.py:40-47`	`POST /users` 存在竞态：SELECT→INSERT 无事务，并发注册同用户名会 500
7	`bookmarks-api/Dockerfile`	容器以 root 运行，缺少 `USER` 指令
8	`project/`	CLI 零测试，`iter_entries`/`iter_all`/`format_summary` 无测试覆盖

#	位置	问题
9	`docs/14-roadmap.md:33`	`（ Transformers）` 多余空格
10	`docs/03-data-model.md:70`, `12-gotchas.md:12`	"PEP 8 禁止"用词过强，应为"推荐"
11	`examples/async/01_concurrency.py:1`	docstring `1/2 章` 应为 `1 章`
12	`examples/async/`	文件名与 docs 章节名不对应（`01_concurrency` ↔ `01-event-loop`）
13	`project/parser.py:31`	`KeyError` 不可达，`except (ValueError, KeyError)` 应只保留 `ValueError`
14	`bookmarks-api/schemas.py`	`username` 无字符约束，可接受空格/特殊字符
15	`bookmarks-api/README.md`	缺 Docker 使用说明和环境变量文档
16	各核心章节(2-13)	缺少"← 回首页"链接（1、14 章有）

模块	评分	说明
文档内容	A-	Java/Python 对照准确，4 步教学法一致，JSON escape 一处错误
代码示例	A-	全部可运行，2 处输出注释与实际不符
logstats 项目	B+	代码 Pythonic，但 CLI 无测试
bookmarks-api	B	FastAPI/Pydantic v2 用法正确，但 sqlmodel 死依赖、Docker 不可复现、POST 竞态

内容准确性

09-stdlib.md:158 — JSON escape 示例：dumps 默认 ensure_ascii=True 会把 "小明" 转为 "\u5c0f\u660e"，但文档两侧显示相同的中文字符，未体现转义效果
03-data-model.md:70、12-gotchas.md:12 — "PEP 8 禁止" x == None 用词过强，PEP 8 是推荐 is/is not，并非严格禁止
03-data-model.md:76-82 — 小整数缓存说明略简化，REPL 中 a is b 可能为 False，但模块级常量折叠常为 True，可接受但应注明
10-engineering.md:76 — Windows Git Bash 激活注释有误导，标准写法应为 .venv\Scripts\activate
09-stdlib.md:134 — r"raw string" ↔ Pattern.compile 对照语义不等价，有误导风险

4 步教学法一致性

核心教程第 1-11 章严格遵循 Java 对照 → 语义差异 → 为什么 → Pythonic 正解 模式。以下章节结构有合理偏离：

文件完整性

mkdocs.yml 中定义的所有 29 个章节文件均存在，无缺失章节。所有交叉引用链接均可解析。

语言规范

正文中文、代码与术语英文的一致性良好，无显著混用问题。

格式问题

全部 28 个 .py 文件语法检查通过，16 个示例文件和 10 个解答文件均可运行。

缺陷

文件映射问题

Java/Python 对照准确性

逐章抽查语法、数据模型、OOP、异常、Pythonic、类型提示、标准库、并发等章节，对照代码均准确无误。

代码质量 — 整体 Pythonic，良好示范了 dataclass、生成器、类型提示、argparse、pytest 等教学内容。

具体问题

parser.py:31 — except (ValueError, KeyError) 中 KeyError 不可达，re.search 命名组均为必需
cli.py — top-slow -n 0 返回空，-n -1 返回除最慢外所有条目，无参数校验
stats.py — summarize 返回未参数化的 dict，可用 TypedDict 更精确

测试覆盖缺口

README — 内容准确，uv run logstats stats sample.log 等命令均可正常工作。

FastAPI 实践 — 依赖注入、_get_owned 辅助函数、lifespan 上下文管理器、响应模型声明等均符合最佳实践。

问题详情

sqlmodel 死依赖 — pyproject.toml 声明了 sqlmodel>=0.0.22，但代码全部使用 sqlalchemy.orm.DeclarativeBase + Mapped，无任何 from sqlmodel import 调用
Docker 构建不可复现 — Dockerfile 未 COPY uv.lock，uv sync 不加 --frozen 会重新解析依赖，锁文件形同虚设
容器以 root 运行 — 缺少 USER 指令，不符合容器安全最佳实践
POST /users 竞态 — SELECT + INSERT 无事务保护，并发注册同用户名时 IntegrityError 未捕获，返回 500
HttpUrl 限制 — Pydantic v2 的 HttpUrl 拒绝 http://localhost 等无 TLD 的 URL，对书签应用是实际 UX 问题
username 无字符约束 — 可接受空格、控制字符等

测试覆盖

10 个测试覆盖了主要正向路径和部分反向用例（无效 URL→422、缺 key→401、权限隔离→404）。缺口：

安全 — API key 明文存储（代码注释已说明为教学简化），无 SQL 注入风险，CORS 默认仅限 localhost。