convex-performance-audit

Convex 性能审计

一次诊断并修复 Convex 应用中的一类性能问题。

适用场景

• Convex 页面或功能运行缓慢或成本高昂
• npx convex insights --details 报告读取字节数、读取文档数或 OCC 冲突过高
• 低新鲜度读取路径使用了响应式机制，而按时间点读取即可满足需求
• 出现 OCC 冲突错误或突变重试过多
• 订阅数量过多或 UI 更新缓慢
• 函数即将达到执行或事务限制
• 需要在同级函数中修复相同的性能模式

不适用场景

• Convex 初始设置、身份验证设置或组件提取
• 没有性能目标的纯模式迁移
• 没有用户可见或部署可见问题的一次性微优化

防护原则

• 当规模较小、流量适中或可用信号较弱时，优先选择更简单的代码
• 除非有可衡量的信号、明显无界的路径或已知的高频读写路径，否则不要建议使用摘要表、拆分文档、更改获取策略或进行需要大量迁移的发布
• 在 Convex 中，小型表上的简单扫描通常可以接受。不要仅仅因为某种模式在大规模下不理想，就臆造结构性改造

第一步：收集信号

从最强的可用信号开始：

1. 如果用户或当前上下文已经提供部署 Health 洞察信息，请将其视为一手性能信号来源。
2. 如果可以使用 CLI 洞察信息，请运行 npx convex insights --details。必要时使用 --prod、--preview-name 或 --deployment-name。
   • 如果本地仓库中的 Convex CLI 版本过旧，不支持 insights，在放弃之前尝试运行 npx -y convex@latest insights --details。
3. 如果仓库已经使用 convex-doctor，可以将其发现作为参考。不要强制要求使用它，也不要将其视为事实来源。
4. 如果无法获取运行时信号，仍应根据代码进行审计，但要牢记上述防护原则。没有洞察信息并不能证明系统健康，但也不能证明需要进行大规模重构。

信号分类

收集信号后，确定问题类别并阅读对应的参考文件。

信号	参考文件
读取字节数或文档数过高、使用 JS 过滤、不必要的联接	references/hot-path-rules.md
OCC 冲突错误、写入竞争、突变重试	references/occ-conflicts.md
订阅数量过多、UI 更新缓慢、重新渲染过多	references/subscription-cost.md
函数超时、事务大小错误、负载过大	references/function-budget.md
泛泛地表示“运行缓慢”，但没有具体信号	从 references/hot-path-rules.md 开始

多种问题类别可能同时存在。先阅读最相关的参考文件，然后在症状仍然存在时检查其他文件。

升级处理较大改动

如果可能的修复涉及侵入性改动、影响范围广或需要大量迁移，请暂停并在编辑前提供选项。

例如：

• 在多个流程中引入摘要表或汇总表
• 拆分文档以隔离频繁更新的字段
• 在多个屏幕中重做分页或获取策略
• 切换到需要安全迁移发布的新索引或反规范化字段

如果正确性取决于在发布期间同时处理新旧状态，请查阅 convex-migration-helper 技能中的迁移工作流。

工作流

1. 界定问题范围

从实际项目中选取一个具体的用户流程。查看代码库、 客户端页面和 API 表面，找出与该症状相符的流程。

记录以下内容：

• 入口函数
• 使用 useQuery、usePaginatedQuery 或 useMutation 的客户端调用位置
• 读取的表
• 写入的表
• 该路径属于高读取、高写入，还是两者皆是

2. 追踪完整的读写集合

对于路径中的每个函数：

1. 追踪每一个 ctx.db.get() 和 ctx.db.query()
2. 追踪每一个 ctx.db.patch()、ctx.db.replace() 和 ctx.db.insert()
3. 记录外键查找、JS 侧过滤和完整文档读取
4. 找出所有会操作相同表的同级函数
5. 找出同一页面上呈现的响应式统计数据、聚合结果或小组件

在 Convex 中，每次额外读取都会增加事务开销，而每次写入都可能使响应式订阅失效。应将读取放大和失效放大视为首要问题。

3. 根据相关参考资料应用修复

阅读与问题类别匹配的参考文件。每份参考文件都包含具体模式、代码示例和建议的修复顺序。

不要只处理洞察中提到的单个函数。追踪操作相同表的同级读取函数和写入函数。

4. 一并修复同级函数

当操作某个表的一个函数存在性能问题时，也要检查同级函数是否存在相同模式。

发现问题后，检查操作同一表族的同级读取函数和写入函数是否存在相同问题，包括配套的摘要或汇总表。

示例：

• 如果一个列表查询从读取完整文档改为读取摘要表，请检查操作该表的其他列表查询
• 如果一个 mutation 将频繁更新的字段隔离出来，或拆分了热点文档，请检查对同一表进行写入的其他函数
• 如果一个读取路径需要对尚未回填的字段进行兼容迁移，请检查同级读取路径是否也存在相同的迁移风险

除非有明确的产品原因，否则不要修复一条路径，却让另一条路径继续使用旧模式。

5. 完成前验证

确认以下各项：

1. 结果与之前相同，没有记录丢失
2. 预期路径中已不再发生需要消除的读取或写入
3. 缺少反规范化字段或索引字段时，回退行为正常
4. 在需要时，已将频繁更新的字段与广泛读取的文档隔离
5. 已检查所有相关的同级读取函数和写入函数，而不只是最初的函数

参考文件

• references/hot-path-rules.md - 读取放大、失效、反规范化、索引、摘要表
• references/occ-conflicts.md - 写入争用、OCC 冲突解决、热点文档拆分
• references/subscription-cost.md - 响应式查询成本、订阅粒度、定点读取
• references/function-budget.md - 执行限制、事务大小、大型文档、负载大小

另请查看官方 Convex 最佳实践 页面，了解有关参数验证、访问控制和代码组织的其他模式，这些模式可能会在审查过程中显现。

检查清单

• 已从洞察、仪表板或代码审查中收集信号
• 已确定问题类别并阅读对应的参考资料
• 已界定一个具体的用户流程或函数路径
• 已追踪该路径中的每次读取和写入
• 已找出操作相同表的同级函数
• 已按照建议的修复顺序，根据参考资料应用修复
• 已一致地修复同级函数
• 已验证行为并确认没有回归