fix(tooling): 修复 pyright 解释器配置与类型守卫,补齐 ruff 门禁与两处历史 bug

- pyrightconfig.json 钉死 Python 3.12 虚拟环境,消除由于查找系统 Python 3.9 带来的假性报错
- 修复 huya/login.py 引用不存在函数的问题并补充单元测试
- 修复 browser_harvest.py 对 set 下标访问的错误并提升报错信息质量
- 虎牙 6 个子路由显式导入依赖,消除 import * 带来的未定义变量报警
- 规范化 Pydantic Field(default=...) 默认值声明
- 完善 solver.py / app_login.py 等核心路径类型守卫与 @overload 重载
- 在 pyproject.toml 中显式锁定 ruff lint 规则集 (E4, E7, E9, F, B, I, BLE)
- 门禁脚本同步增加 ruff check 检查并在 AGENTS.md 补齐实践经验总结
This commit is contained in:
yml2213
2026-10-08 12:33:39 +08:00
parent ec07e4fc06
commit a3c3a46b9c
31 changed files with 599 additions and 96 deletions
+9 -4
View File
@@ -35,11 +35,14 @@
关键是**反向验证** —— 把 bug 注入回去,确认用例真的会变红,再还原。
「跑了一下没报错」不算验证。
- **提交/推送会跑钩子**,所以本地必须按同样标准自查:
- `pre-commit`:`ruff format --check`(**只跑 `ruff check` 不够**,格式不对会直接拦下提交)
- `pre-commit`:`ruff format --check` **和** `ruff check`(两个都要跑,见坑 #8)
+ 前端 `tsc -b`;
- `pre-push`:上面这些 + **全量 pytest**。
- `pre-push`:上面这些 + **全量 pytest**(`TYPECHECK=1` 时额外跑 Pyright)。
- **断言要看 `model_dump()`(序列化结果)**,只看属性会假绿(原因见坑 #2)。
- **别信「测试通过」** —— 用例可能是假绿的(原因见坑 #3)。
- **Pyright 只查 `core`/`utils`/`web`,`tests` 有意排除**(原因和重新打开的方法都写在
`pyrightconfig.json` 的注释里)。别为了让它闭嘴去给 FastAPI 路由补返回值注解 ——
那等于加了 `response_model`,会真的裁剪响应体。
## 4. 数据库与迁移
@@ -100,8 +103,10 @@ docker compose up -d douyu-login
| 5 | **`docker compose run` 默认读 stdin**:用 `ssh 'bash -s' < 脚本` 喂进去时,它会把脚本剩下的行吃掉 | 用 `docker compose run -T --rm ... </dev/null` |
| 6 | **镜像同步脚本会白等 15 分钟**:`pgrep -f 'mysqldump.*douyu_login'` 匹配到了自己所在的 shell,等待循环永不提前退出 | 判定远端进程存活别用会自匹配的 `pgrep -f` 模式 |
| 7 | **`set -e` + 输出过滤(管道接 `grep -v`)会半途静默中止**:过滤把输出全吃掉时 grep 返回 1,被 `set -e` 当成失败(曾在「已删库、还没导入」处中止,镜像库一度是空的) | 过滤输出后别让 `set -e` 接管退出码;关键步骤显式检查成功 |
| 8 | **`ruff check` 通过 ≠ 能提交**:钩子查的是 `ruff format` | 提交前本地跑一遍 `.githooks/pre-commit` |
| 8 | **格式检查和 lint 检查,只跑一个都会漏**:`ruff format --check` 对「未使用导入 / 未排序导入 / 宽 except」全部放过(实测同一个文件、同一处未使用 `import json`:format 退出码 0,check 退出码 1),而 `ruff check` 又完全不管格式 | 钩子现在两条都跑;本地自查也两条都跑(`./dev.sh format-check` + `./dev.sh lint-check`) |
| 9 | **偷换概念把「账号级状态」当成「全局字段」**:斗鱼商城 `storehome` 的 `count`(库存)确实是全局的,但 **`status` 字段是强账号维度的!`status=1` 就是「已达兑换上限」(限量 1 件已满/已兑换)**。曾把两者混为一谈,误以为商品列表全不可信,跑去依赖早已被官方清空的 `exchangeList`,导致已兑换的账号被错误打上「两个都可兑换」绿标 | 判定高价值资产准入:**以 `storehome.status==1` 为最高裁判**;`exchangeList` 仅做历史展示兜底,绝不可当作否定已拥有的依据 |
| 10 | **Pyright 的报错数量取决于「它怎么找到解释器」**:`pyrightconfig.json` 原本没钉解释器,直接跑 `.venv/bin/pyright` 时它会去 PATH 摸 `/usr/bin/python3`(macOS 自带 3.9),进而读用户级 `~/Library/Python/3.9/site-packages` 里的 **SQLAlchemy 1.4.54** 和 3.9 语义 → 全仓报 **2926** 条(`Mapped[int]` 说「不是泛型」、`int \| None` 说「需要 3.10+」、`UTC` 说不认识),而同一个仓库 `uv run pyright` 只有 **273** 条。**90% 的「错误」是环境假象** | 必须在配置里显式写 `venvPath`/`venv`/`pythonVersion`;IDE 里出现成片这类报错先查解释器。自查命令:`pyright --verbose` 看 `Assuming Python version` 和 Search paths 里有不有 3.9 |
| 11 | **Pyright 不认 `Field()` 的位置参数默认值**:`x: int = Field(3, ge=1, le=10)` 会被判成「必填」,凡是不传该参数的调用点全报 `Arguments missing for parameters`;`Field(default=3, ...)` 才认。运行期 pydantic 两边等价(否则测试早红了),纯静态判定差异 | schema 里一律写 `Field(default=..., ...)`;排查手法是写最小复现(一个 pydantic 模型 + 一次构造)确认到底是哪边的问题 |
## 8. 仓库事实(速查)
@@ -112,6 +117,6 @@ docker compose up -d douyu-login
| 本地服务 | `./dev.sh`(8800 端口,`--reload`);**启动时会自动跑迁移** |
| 本地 MySQL | 容器 `live-hub-py-mysql-1`,端口 3307;库见 §4 |
| 生产镜像库 | `douyu_login_prod`(`scripts/refresh_local_prod_mirror.sh` 同步,只读用) |
| 迁移 head | `main` = `20261004_0051`;`dev` = `20261007_0052`(**两侧不一致,切分支前先对齐库**) |
| 迁移 head | `main` = `20261008_0052`;`dev` = `20261008_0053`(**两侧不一致,切分支前先对齐库**)。这行会过期,动手前用 `git ls-tree -r --name-only <ref> web/backend/migrations/versions/` 自己算一遍 head(没被任何 `down_revision` 引用的那个) |
| 前端 | `tsc -b` 开了 `noUnusedLocals`,死代码/未用导入直接报 TS6133;镜像构建时会 `npm run build` |
| 测试 | `pytest tests/ -q`(用 `douyu_login_test`);`ruff format` + `ruff check` |