Convex Performance Audit 是一个面向 Convex 应用的性能审计技能,用于诊断和修复性能问题,每次聚焦一类问题。
用途
当 Convex 页面或功能感觉缓慢或开销过高时使用;当 npx convex insights --details 报告高字节读取、高文档读取或 OCC 冲突时使用;当低新鲜度读取路径在只需时间点读取的地方使用了响应式时使用;当出现 OCC 冲突错误或过多 mutation 重试时使用;当订阅数量过高或 UI 更新缓慢时使用;当函数接近执行或事务限制时使用;当同一性能模式需要在多个兄弟函数中修复时使用。
不适用于:初始 Convex 设置、认证设置或组件提取;没有性能目标的纯 schema 迁移;没有用户可见或部署可见问题的一次性微优化。
主要能力
技能围绕信号收集与问题分类展开。首先收集最强信号:如果用户或当前上下文已提供部署健康洞察,将其视为一等性能信号来源;如果 CLI insights 可用,运行 npx convex insights --details,必要时使用 --prod、--preview-name 或 --deployment-name;如果本地仓库的 Convex CLI 太旧不支持 insights,可尝试 npx -y convex@latest insights --details;如果仓库已使用 convex-doctor,可将其发现视为提示,但不要求使用,也不作为真相来源;如果运行时信号不可用,仍可从代码审计,但需牢记护栏。
收集信号后,识别问题类别并阅读匹配的参考文件:高字节或文档读取、JS 过滤、不必要 join 对应 references/hot-path-rules.md;OCC 冲突错误、写入争用、mutation 重试对应 references/occ-conflicts.md;高订阅数、UI 更新慢、过多重渲染对应 references/subscription-cost.md;函数超时、事务大小错误、大负载对应 references/function-budget.md;一般“慢”且无具体信号时从 references/hot-path-rules.md 开始。多个问题类别可能重叠,先读最相关的参考,若症状仍在再检查其他。
使用方式
工作流程分为五步。第一步,界定问题:从实际项目中选择一个具体用户流程,查看代码库、客户端页面和 API 表面,找到与症状匹配的流程,记录入口函数、使用 useQuery、usePaginatedQuery 或 useMutation 的客户端调用点、读取的表、写入的表,以及该路径是高读取、高写入还是两者兼有。
第二步,追踪完整读写集合:对路径中每个函数,追踪每个 ctx.db.get() 和 ctx.db.query(),追踪每个 ctx.db.patch()、ctx.db.replace() 和 ctx.db.insert(),注意外键查找、JS 侧过滤和全文档读取,识别所有触及相同表的兄弟函数,识别同一页面渲染的响应式统计、聚合或小部件。在 Convex 中,每次额外读取都会增加事务工作,每次写入都可能使响应式订阅者失效,因此将读取放大和失效放大视为一等问题。
第三步,应用相关参考中的修复:阅读匹配问题类别的参考文件,每个参考包含具体模式、代码示例和推荐修复顺序。不要只停留在 insight 指出的单个函数,要追踪触及相同表的兄弟读取者和写入者。
第四步,一起修复兄弟函数:当一个触及某表的函数存在性能 bug 时,审计兄弟函数是否有相同模式。发现一个问题后,检查同一表族的兄弟读取者和写入者,包括配套的摘要或汇总表。例如,如果一个列表查询从全文档切换到摘要表,检查该表的其他列表查询;如果一个 mutation 隔离了频繁更新的字段或拆分了热文档,检查同一表的其他写入者;如果一个读取路径需要为未回填字段进行迁移安全发布,检查兄弟读取是否有相同发布风险。除非有明确产品原因,不要留下一条路径已修复而另一条仍用旧模式。
第五步,完成前验证:确认结果与之前相同、无记录丢失;确认已消除的读取或写入不再出现在预期路径中;确认当反规范化或索引字段缺失时回退行为正常;确认频繁更新的字段在需要时与广泛读取的文档隔离;确认检查了每个相关兄弟读取者和写入者,而不仅是原始函数。
适用场景
适用于需要定位和修复 Convex 性能问题的开发场景,尤其是已有可测量信号(如 insights 报告、OCC 冲突、订阅成本、函数预算问题)时。也适用于同一性能模式需要在多个兄弟函数中一致修复的情况。
限制
技能设有护栏:当规模小、流量适中或可用信号弱时,优先更简单的代码;除非有实测信号、明确无界路径或已知热读写路径,否则不建议摘要表、文档拆分、获取策略变更或迁移繁重的发布;在 Convex 中,小表上的简单扫描通常可接受,不要仅因模式在大规模下不理想就发明结构性工作。如果可能的修复具有侵入性、跨领域或迁移繁重,应停止并在编辑前提出选项,例如跨多个流程引入摘要或汇总表、拆分文档以隔离频繁更新字段、在多个屏幕重做分页或获取策略、切换到需要迁移安全发布的新索引或反规范化字段。当正确性取决于发布期间处理新旧状态时,参考 convex-migration-helper 技能获取迁移工作流。
参考文件
references/hot-path-rules.md 涵盖读取放大、失效、反规范化、索引、摘要表;references/occ-conflicts.md 涵盖写入争用、OCC 解决、热文档拆分;references/subscription-cost.md 涵盖响应式查询成本、订阅粒度、时间点读取;references/function-budget.md 涵盖执行限制、事务大小、大文档、负载大小。还可查看官方 Convex Best Practices 页面,了解参数验证、访问控制和代码组织等可能在审计中出现的其他模式。
检查清单
已从 insights、仪表板或代码审计收集信号;已识别问题类别并阅读匹配参考;已界定一个具体用户流程或函数路径;已追踪该路径中每次读写;已识别触及相同表的兄弟函数;已按推荐修复顺序应用参考中的修复;已一致修复兄弟函数;已验证行为并确认无回归。