Convex 性能审计

诊断并修复 Convex 应用中的性能问题，一次解决一个问题类别。

何时使用

• 某个 Convex 页面或功能感觉缓慢或开销过大
• npx convex insights --details 报告高字节读取、高文档读取或 OCC 冲突
• 低新鲜度读取路径使用了响应式，而时间点读取本已足够
• 出现 OCC 冲突错误或过多的变更重试
• 订阅数量过高或 UI 更新缓慢
• 函数接近执行或事务限制
• 相同的性能模式需要在多个兄弟函数中修复

何时不使用

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

约束准则

• 当规模较小、流量适中或可用信号较弱时，优先采用更简单的代码
• 除非有测量到的信号、明确无界增长路径或已知的热读/热写路径，否则不建议使用摘要表、文档拆分、获取策略变更或迁移密集型的发布方案
• 在 Convex 中，对小表进行简单扫描通常是可接受的。不要仅仅因为某个模式在大规模下不理想就凭空构造结构性的工作

第一步：收集信号

从最强的可用信号开始：

1. 如果部署的健康洞察已从用户或当前上下文中获取，将其作为性能信号的一级来源对待。
2. 如果 CLI 洞察可用，运行 npx convex insights --details。需要时使用 --prod、--preview-name 或 --deployment-name。
   • 如果本地仓库的 Convex CLI 版本过旧不支持 insights，在放弃前尝试 npx -y convex@latest insights --details。
3. 如果仓库已使用 convex-doctor，可将其发现作为提示。不要求必须使用，也不将其视为唯一事实来源。
4. 如果运行时信号不可用，仍可从代码进行审计，但请牢记上述约束准则。缺乏洞察并不证明系统健康，但也不证明需要进行大规模重构。

信号路由

收集信号后，识别问题类别并阅读匹配的参考文件。

多个问题类别可能重叠。首先阅读最相关的参考文件，如果症状仍然存在，再检查其他文件。

升级较大修复方案

如果可能的修复方案具有侵入性、跨多个模块或涉及大量迁移，在编辑前暂停并先提供选项。

例如：

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

当正确性依赖于在发布过程中处理新旧状态时，请参考 skills/convex-migration-helper/SKILL.md 了解迁移工作流程。

工作流程

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. 一起修复兄弟函数

当访问某个表的一个函数存在性能问题时，审计兄弟函数是否存在相同模式。

发现一个问题后，检查同一表族的兄弟读取者和兄弟写入者，包括配套的摘要或汇总表。

例如：

• 如果一个列表查询从完整文档切换到摘要表，检查该表的其他列表查询
• 如果一个变更需要无操作写入保护，检查同一表的其他写入者
• 如果一个读取路径需要对未回填字段进行迁移安全发布，检查兄弟读取是否存在相同的发布风险

除非有明确的产品原因，否则不要修复一个路径而让另一个路径保留旧模式。

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 最佳实践页面，了解审计过程中可能涉及的有关参数验证、访问控制和代码组织的其他模式。

检查清单

• 从洞察、仪表盘或代码审计收集了信号
• 识别了问题类别并阅读了匹配的参考文件
• 界定了一个具体的用户流程或函数路径
• 追踪了该路径中的每次读取和写入
• 识别了访问相同表的兄弟函数
• 按照参考文件中的推荐修复顺序应用了修复
• 一致地修复了兄弟函数
• 验证了行为并确认无回归