SuperAPI AI 工具集

convex-doctor

编程与开发

查看项目

更新于 10-16 06:09

技能介绍

概述

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 报告发现时,按以下顺序修复:

  1. 安全错误(最高优先级):为 HTTP 操作和公开端点添加认证;将 api.* 服务端到服务端调用转换为 internal.*;将公开 action 迁移为 mutation 调度的 internal action。
  2. 正确性错误:从查询中移除 Date.now()(会破坏缓存和响应性);仅在有索引强制唯一性时把 .first() 改为 .unique();修复先 collect 后 filter 的模式,改用索引查询。
  3. 性能警告:将无界的 .collect() 替换为 .take(n) 或分页;把顺序执行的 ctx.run* 调用合并为单个 internal 查询;消除 HTTP 和 RSS 端点中的 N+1 模式。
  4. Schema 警告:在存在查询模式时,为外键添加缺失的索引;按 by_field snake_case 约定重命名索引;移除冗余索引(复合索引的前缀)。
  5. 架构警告:从大型处理器中抽取辅助函数;将 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(队列任务模式示例)。