概述
convex-doctor 是面向 Convex 后端的静态分析工具,会对代码库在安全、正确性、性能、Schema 和架构五个类别上评分,分数范围为 0 到 100。本技能封装了该工具在特定代码库中使用的完整修复工作流(据资料记录,经历 17 轮修复后从 42 分提升至 100 分)。
使用方式
运行命令:
npx convex-doctor@latest
项目根目录存在 convex-doctor.toml 配置文件,其中包含有意设置的抑制项。在处理报告发现前应先检查该文件。
当前抑制项及理由(来自资料)
| 规则 | 级别 | 理由 |
|---|---|---|
| correctness/generated-code-modified | off | 代码生成后工作区总是处于脏状态 |
| schema/optional-field-no-default-handling | off | 94 个可选字段是 markdown frontmatter 的设计需要 |
| correctness/missing-unique | off | 剩余的 .first() 调用是有意的有序选取 |
| schema/deep-nesting | off | 聊天附件需要 4 级校验器 |
| schema/array-relationships | off | 标记出现在函数参数上,而非表列上 |
| perf/missing-index-on-foreign-key | off | 剩余外键位于嵌套数组内(无法建立索引) |
| arch/duplicated-auth | off | 每个公开处理器有意做认证感知 |
| arch/monolithic-file | off | 文件按领域组织 |
| arch/large-handler | off | 邮件模板、同步、搜索本身是多步骤操作 |
忽略文件:convex/_generated/**(生成代码)、convex/authComponent.ts(轻量认证组件转发器)。
修复优先级
当 convex-doctor 报告发现时,按以下顺序修复:
- 安全错误(最高优先级):为 HTTP 操作和公开端点添加认证;将
api.*服务端到服务端调用转换为internal.*;将公开 action 迁移为 mutation 调度的 internal action。 - 正确性错误:从查询中移除
Date.now()(会破坏缓存和响应性);仅在有索引强制唯一性时把.first()改为.unique();修复先 collect 后 filter 的模式,改用索引查询。 - 性能警告:将无界的
.collect()替换为.take(n)或分页;把顺序执行的ctx.run*调用合并为单个 internal 查询;消除 HTTP 和 RSS 端点中的 N+1 模式。 - Schema 警告:在存在查询模式时,为外键添加缺失的索引;按
by_fieldsnake_case 约定重命名索引;移除冗余索引(复合索引的前缀)。 - 架构警告:从大型处理器中抽取辅助函数;将 provider 模块与编排逻辑拆分;在面向用户的处理器中用 ConvexError 替换
throw new Error(...)。
常见修复模式
将公开 action 转换为队列任务:不在浏览器中调用公开 action,而是创建 job 表并用 mutation 调度 internal action。步骤为:在 convex/schema.ts 中添加带 status、result、error 字段的 job 表;创建公开 mutation 插入 pending job 并调度 internal action;创建返回 job 状态的公开 query 供 UI 使用;将 action 改为 internalAction,在完成或失败时更新 job 记录;更新前端调用 mutation 并轮询 query。资料记录此模式曾用于 AI 图像生成、AI 聊天响应、URL 导入。
将 api. 转换为 internal.**:当 Convex 函数在服务端调用另一个 Convex 函数时,若只有公开版本则创建 internal 版本;在调用方用 internal.module.fn 替换 api.module.fn;若函数需要公开和内部两种访问,保留两者并让公开版本调用 internal 版本。
批处理顺序 ctx.run 调用*:当 action 为独立数据发起多个 ctx.runQuery 时,创建单个返回全部所需数据的 internal 查询,用一次 ctx.runQuery 替换顺序调用,以减少事务开销。
从查询中移除 Date.now():查询必须是确定性的。给查询添加 now: v.number() 参数,由前端或调用该查询的 action/mutation 传入 Date.now();对于响应式订阅,对时间戳取整(如 60 秒间隔)以保持响应性稳定。
认证组件辅助函数转换:当 components.auth.public.* 触发 direct-function-ref 警告时,在 convex/authComponent.ts 中创建调用组件 API 的辅助函数,直接导入辅助函数而非使用 ctx.runQuery(internal.authComponent.*),并将 convex/authComponent.ts 加入 convex-doctor.toml 的 [ignore] 部分。
验证清单
每次修复后:npx convex codegen 通过;npx tsc --noEmit 通过(或由 npx convex codegen 覆盖);npm run build 成功;npx convex-doctor@latest 显示分数提升或问题减少;现有功能仍正常(AI 聊天、搜索、仪表盘、RSS、统计)。
分数历史(来自资料)
| 轮次 | 分数 | 错误 | 警告 | 关键变更 |
|---|---|---|---|---|
| 初始 | 42/100 | 73 | 243 | 基线 |
| 1(修复) | ~55 | ~50 | ~221 | 安全:HTTP 认证、api 转 internal |
| 2 | ~60 | ~40 | ~200 | AI action 流程、HTTP 加固 |
| 3 | 68/100 | - | - | collect-then-filter、认证信号 |
| 10 | 80/100 | 1 | 68 | 导入 URL 队列任务、唯一性查找 |
| 15 | 91/100 | 0 | 43 | 新闻通讯批处理、认证转发器、toml 配置 |
| 16 | 92/100 | 0 | 39 | 语义搜索批处理、认证辅助函数 |
| 17 | 100/100 | 0 | 0 | 统计辅助函数、联系辅助函数、最终 toml 调优 |
何时抑制、何时修复
应修复的情况:发现指向真实 bug 或安全缺口;修复风险低且能提升代码质量;模式可在不影响产品行为的前提下修改。
应抑制的情况:发现是工具误报(如组件函数引用);模式是设计所需(如每个处理器各自做认证检查);修复带来的复杂度超过警告价值;生成代码触发该发现。
应始终在 convex-doctor.toml 中记录抑制理由。
相关资料
所有修复 PRD 位于 prds/convex-doctor/:包括 convex-doctor-remediation.md(初始计划,5 个阶段)以及从 convex-doctor-second-pass.md 到 convex-doctor-seventeenth-pass.md。
相关文件:convex-doctor.toml(抑制配置)、convex/schema.ts(索引与表定义)、convex/authComponent.ts(认证组件转发器)、convex/importJobs.ts(队列任务模式示例)、convex/aiImageJobs.ts(队列任务模式示例)、convex/semanticSearchJobs.ts(队列任务模式示例)。