后端前端AI 技能AI 插件搜索引擎【免费下载链接】clawhubSkill Plugin Registry for OpenClaw项目地址https://gitcode.com/gh_mirrors/mo/clawhub点击查看免费下载导读本文是 ClawHub 仓库中 Convex 性能审计技能.agents/skills/convex-performance-audit的核心参考规则hot-path-rules.md的完整展开。它回答了 Convex 应用中最常见的一类性能问题当顶层工作流指向读放大read amplification、反规范化denormalization、索引滚动index rollout、响应式查询成本或失效密集型写入invalidation-heavy writes时应该遵循哪些规则来修复。读完本文你将掌握五条热路径规则把过滤下推到存储层、最小化数据源、最小化行大小、隔离高频更新字段、按读模式匹配一致性并能在 ClawHub 这类大型 Skill/Plugin Registry 的真实源码中看到这些规则的具体落地形态从而可以直接用于你自己的 Convex 项目的性能审计。何时启用这些规则hot-path-rules.md并不是任何时候都要套用的通用规范它属于审计技能的分诊路由signal routing的一部分。根据 SKILL.md 中的信号路由表当出现以下信号时就应转向本规则npx convex insights --details报告高 bytes read、高 documents read或 OCC 冲突偏高代码中发现JS 侧.filter()过滤、不必要的外键 join、整表扫描顶层工作流明确指向读放大、反规范化、索引滚动、响应式查询成本或失效密集型写入没有明确具体信号、只是“感觉慢”的通用场景也默认从本规则开始排查。核心原则成本乘以并发规则的开头给出了整个审计的思维模型cost x calls_per_second x 86400即每一个被读取或被写入的字节都会与并发相乘。一个单次看起来微不足道的查询在每秒调用多次、一天运行 86400 秒之后就变成了可观的成本。在 Convex 中每一次写入还会额外扇出fan out为响应式失效reactive invalidation、复制replication工作和下游同步downstream sync。因此读放大与失效放大invalidation amplification都应被视为一等公民问题这正是 SKILL.md 工作流第 2 步“Trace the full read and write set”反复强调的点。一致性规则修复一个函数必须审计兄弟函数如果你在某个函数上修复了一个热路径模式就必须审计访问同一张表的兄弟函数sibling functions是否存在同样的模式。需要特别留意对同一张表的多个 list 查询对同一张表的多个写入方对同一批记录的公开浏览public browse与搜索查询被多个端点复用的辅助函数。ClawHub 中skillSearchDigest表就是一个典型例子在 convex/schema.ts 中它定义了数十个索引而在 convex/search.ts、convex/canonicalTrending.ts、convex/catalogTopics.ts 等多个模块都直接查询这张表。这意味着任何一个针对该表的读路径改造都必须横向检查所有这些兄弟调用点避免“只修好一条路径、另一条路径还停留在旧模式”。规则一把过滤下推到存储层Push Filters To Storage为什么.filter()不等于下推这是本规则最重要的一条认知JavaScript 的.filter()需要先把整个表读出来你已经在读数据时就付出了成本Convex 查询 API 的.filter()方法与在 JS 中过滤性能相同它同样不会把谓词下推到存储层真正能减少扫描文档数量的只有.withIndex()和.withSearchIndex()。因此优先选择withIndex(...)、文本搜索用.withSearchIndex(...)、更窄的表narrower tables、汇总表summary tables而不是接受“先扫描再过滤”的模式。// Bad: scans then filters in JavaScript export const listOpen query({ args: {}, handler: async (ctx) { const tasks await ctx.db.query(tasks).collect(); return tasks.filter((task) task.status open); }, });// Also bad: Convex .filter() does not push to storage either export const listOpen query({ args: {}, handler: async (ctx) { return await ctx.db .query(tasks) .filter((q) q.eq(q.field(status), open)) .collect(); }, });// Good: use an index so storage does the filtering export const listOpen query({ args: {}, handler: async (ctx) { return await ctx.db .query(tasks) .withIndex(by_status, (q) q.eq(status, open)) .collect(); }, });索引滚动的迁移规则Migration rule for indexes在部分回填partially backfilled的字段上新建索引会在滚动期间引入正确性 bug。这里有一个关键的 Convex 细节undefined ! false如果一份旧文档完全缺少某个字段它就不会命中一个期望该字段为false的复合索引条目。因此不要轻信旧注释里“该字段未回填 / 已回填”的说法必须亲自验证如果正确性依赖于滚动期间对旧状态和新状态都要正确处理不要在热路径里即兴编写部分回填的变通方案应当使用迁移安全的滚动方案并咨询convex-migration-helper技能。// Bad: optional booleans can miss older rows where the field is undefined const projects await ctx.db .query(projects) .withIndex(by_archived_and_updated, (q) q.eq(isArchived, false)) .order(desc) .take(20);// Good: switch hot-path reads only after the rollout is migration-safe // See the migration helper skill for dual-read / backfill / cutover patterns.ClawHub 中对这一点有直接注释佐证在 convex/schema.ts 的skillSearchDigest定义中publicVersion字段被明确标注为“Missing means the rollout backfill has not reached this row. New writes always store an explicit available or unavailable public-version state.”缺失即表示滚动回填尚未覆盖该行新写入总是存储显式的可用/不可用状态。这正是“旧行缺字段、新行有显式值”的迁移期双态dual-state场景热路径读取代码必须能同时处理这两种状态。检查冗余索引形如by_foo和by_foo_and_bar的两个索引通常是冗余的你只需要by_foo_and_bar因为可以用只带foo条件的查询来命中它、省略bar。多余的索引会在每次 insert、patch 和 delete 时增加存储成本与写开销。// Bad: two indexes where one would do defineTable({ team: v.id(teams), user: v.id(users) }) .index(by_team, [team]) .index(by_team_and_user, [team, user]);// Good: single compound index serves both query patterns defineTable({ team: v.id(teams), user: v.id(users) }).index( by_team_and_user, [team, user], );例外.index(by_foo, [foo])实际是按foo_creationTime排序而.index(by_foo_and_bar, [foo, bar])是按foobar_creationTime排序。如果你需要先按foo再按_creationTime排序的结果就必须保留单字段索引因为复合索引会先按bar排序。ClawHub 的skillSearchDigest表是一个更复杂的真实样例convex/schema.ts 中为每个查询模式都设计了带softDeletedAt前缀的复合索引如by_active_updated、by_active_name又为可疑过滤场景单独设计了一组by_nonsuspicious_*索引并使用.searchIndex(search_by_display_name, { searchField: displayName, filterFields: [softDeletedAt, isSuspicious] })见 convex/schema.ts把过滤字段放进搜索索引的filterFields——这正是“把过滤下推到存储层”的规模化实践。规则二最小化数据源Minimize Data Sources追踪每一次读取。如果一个函数只是为了一个很小的展示字段去解析外键而反规范化的副本已经存在那么在热路径上优先使用反规范化字段。何时反规范化当以下条件全部成立时才考虑反规范化该路径是热的被 join 的文档远大于你需要的字段大量读者正在反复为这次 join 买单。有用的思维模型join_cost rows_per_page x foreign_doc_size x pages_per_second小表 join 通常没问题在热 list 页面上为一个小字段去 join 大型文档通常不可取。回退规则Fallback rule反规范化数据是优化手段实时数据才是正确性路径。规则如果反规范化字段缺失或为 null回退到实时读取不要用占位符代替回退在查找映射lookup map中只包含完全填充的条目。// Bad: missing denormalized data becomes a placeholder and blocks correctness const ownerName project.ownerName ?? Unknown owner;// Good: denormalized data is an optimization, not the only source of truth const ownerName project.ownerName ?? (await ctx.db.get(project.ownerId))?.name ?? null;错误的查找映射模式——它让 map 声称“我有数据”从而阻断回退const ownersById { [project.ownerId]: { ownerName: null }, };正确的查找映射模式——只放入已填充的条目const ownersById project.ownerName ! undefined project.ownerName ! null ? { [project.ownerId]: { ownerName: project.ownerName } } : {};ClawHub 中一个真实的回退结构可见于 convex/lib/skillSearchDigest.ts 的digestToHydratableSkill它把 digest 行映射回完整的HydratableSkill形状并做了完全类型检查——若HydratableSkill新增了 digest 未携带的字段编译就会失败。这保证了“反规范化数据不完整时读取路径能安全地以主表数据为准”这一契约。尚无反规范化副本时优先给已有的summary、companion 或 digest 表加字段而不是把主热路径表撑大。如果需要引入新字段/新表并要求分阶段滚动、回填或新旧形状处理就使用迁移辅助技能制定滚动计划。推荐滚动顺序更新 schema更新写入路径回填backfill切换读取路径规则三最小化行大小Minimize Row Size热 list 页面应该读取刚好能满足 UI 的最小文档形状。当满足以下条件时优先用 summary / digest 表而不是全量源表list 页面只需要字段的一个子集源文档很大查询是高流量。一条 800 字节的 summary 行在热页面上比一条 3 KB 的完整文档便宜一个数量级。// Bad: list page reads source docs, then joins owner data per row const projects await ctx.db .query(projects) .withIndex(by_public, (q) q.eq(isPublic, true)) .collect();// Good: list page reads the smaller digest shape first const projects await ctx.db .query(projectDigests) .withIndex(by_public_and_updated, (q) q.eq(isPublic, true)) .order(desc) .take(20);但 digest 表是权衡取舍不是默认项值得做路径明显很热、源行远大于 UI 需要、或大量读者反复支付相同的 join 与 payload 成本可能不值得对源表的索引读取已经足够便宜、表还很小、或额外的写与迁移复杂度会压过收益。ClawHub 是这个模式的绝佳样本skillSearchDigest、curatedSkillSearchDigest、skillTopicSearchDigest见 convex/schema.ts以及packageSearchDigestconvex/schema.ts都是独立的 digest 表。skillSearchDigest只携带列表/卡片渲染所需的字段slug、displayName、summary、icon、owner 快照、badges、stats 等并把icon明确注释为“Kept on the digest so card/list hydration paths can render the icon without reading the full skill row”见 convex/schema.ts。查询侧则在 convex/canonicalTrending.ts 以by_skill索引 .unique()精确取单行、在 convex/lib/skillSearchDigest.ts 通过upsertSkillSearchDigest维护 digest——写入时还先做hasDigestChanged比对字段没变化就跳过写入skip no-op writes这正是规则四在写路径上的呼应。规则四隔离高频更新字段Isolate Frequently-Updated FieldsConvex 本身会对未变化的写入做 no-op不变写入不触发失效但真正的失效问题来自实际发生写入、却被大量查询订阅的文档。把lastSeen、计数器、presence、临时状态这类高频变更字段从被广泛读取的文档上移走——当大多数读者根本不需要这些字段时。这个改造同样要横向应用到兄弟写入方只拆分一个写路径没什么用如果另外三个 mutation 仍然更新同一个被广泛读取的文档的话。// Bad: every presence heartbeat invalidates subscribers to the whole profile await ctx.db.patch(user._id, { name: args.name, avatarUrl: args.avatarUrl, lastSeen: Date.now(), });// Good: keep profile reads stable, move heartbeat updates to a separate document await ctx.db.patch(user._id, { name: args.name, avatarUrl: args.avatarUrl, }); await ctx.db.patch(presence._id, { lastSeen: Date.now(), });注意这与 OCC 冲突见occ-conflicts.md写对写竞争是两回事。这里是写对订阅write-vs-subscription写入本身成功但它迫使成百上千个查询白白重跑。规则五让一致性匹配读模式Match Consistency To Read Patterns根据流量形态选择读取策略。高读低写High-read, low-write典型例子公开浏览页public browse pages搜索结果search results落地页landing pages目录列表directory listings优先在合适的地方使用 point-in-time reads点读取显式刷新explicit refresh分页使用本地状态在合适的地方缓存不要把订阅自动视为错误。只有当产品不需要实时新鲜度且响应式成本可观时才优先选择 point-in-time reads。更详细的模式见同目录的 subscription-cost.md——那里给出的subscriptions x invalidation_frequency x query_cost公式、skip跳过订阅、批量化查询N 个useQuery合并为 1 个、以及Date.now()会击穿查询缓存等模式都是本规则的直接延伸。高读高写High-read, high-write典型例子协作文档编辑器实时仪表盘presence 密集型视图响应式查询可能值得承担持续成本——此时订阅带来的实时性收益大于其失效开销。Convex 专项说明响应式查询Reactive queries每一个ctx.db.get()和ctx.db.query()都会加入该查询的失效集合invalidation set。在客户端useQuery创建一条实时订阅usePaginatedQuery为每一页创建一条实时订阅。对于低新鲜度流程只有当产品不需要自动推送更新时才考虑用 point-in-time read 替代实时订阅。Point-in-time reads框架辅助函数、服务端渲染抓取或一次性客户端读取可以在不需要实时更新时避免持续的订阅成本。适用场景聚合快照报表低变更率的列表显式刷新即可的页面触发器与扇出Triggers and fan-out触发器trigger在每次写入时都会触发包括那些并未实质改变文档的写入。当某个写入只是为了保持派生状态同步时写入前先 diff把昂贵的非阻塞工作移到ctx.scheduler.runAfter中在合适的场景下。聚合Aggregates响应式的全局计数相当于SELECT COUNT(*)在繁忙表上会频繁失效。优先一次性聚合抓取周期性重算预计算的 summary 行用于不需要每秒实时更新的全局统计。ClawHub 中globalStats、skillDailyStats、skillHourlyStats见 convex/schema.ts正是以预计算行而非实时COUNT的形式存在。回填Backfills较大的回填应使用基于游标cursor-based、自调度self-scheduling的internalMutation任务或 migrations 组件。先部署能同时处理两种状态的代码再运行回填。在空档期写入应填充新形状读取应安全回退。验证清单在关闭审计之前确认以下五点这也是 SKILL.md 工作流第 5 步的正式验收项结果与之前一致没有丢记录被移除的表或查找已不再出现在热路径的读取集合中测试或验证覆盖了回退行为——当反规范化字段或索引字段缺失时回退要可用在字段或索引未回填期间迁移安全性得到保持兄弟函数被一致地修复——不要留下一条路径已修复、另一条还停在旧模式。结语把规则放进 ClawHub 的审计流程本文的五条规则服务于一个更大的工作流先通过npx convex insights --details必要时加--prod、--preview-name或--deployment-nameCLI 过旧时可用npx -y convexlatest insights --details或部署健康面板收集信号再按信号路由表定位问题类别最后以本规则为基准逐函数修复并横向审计兄弟函数。ClawHub 仓库在skillSearchDigest系列 digest 表、by_active_*/by_nonsuspicious_*索引族、hasDigestChanged跳过写入、以及迁移期双态字段publicVersion缺失即未回填上的工程实践为本文每一条规则都提供了可以直接对照的源码级样例——这也是最值得读者在自己项目中复用的部分。补充说明本规则文档属于审计技能的参考文件完整的信号路由与工作流请继续阅读 SKILL.md同类问题订阅成本、OCC 冲突、函数预算分别见 subscription-cost.md、occ-conflicts.md 与 function-budget.md。赞分享后端前端AI 技能AI 插件搜索引擎【免费下载链接】clawhubSkill Plugin Registry for OpenClaw项目地址https://gitcode.com/gh_mirrors/mo/clawhub点击查看免费下载相关推荐Convex 热路径性能审计指南读放大、反规范化与索引下推的实战规则Convex 热路径性能审计指南读放大、反规范化与索引下推的实战规则 导读 本文档系统讲解 Convex 应用热路径Hot Path的性能优化规则聚焦读数据库后端Convex Backend 热路径性能优化指南读放大、反规范化与索引下推实战Convex Backend 热路径性能优化指南读放大、反规范化与索引下推实战 导读 本指南面向使用 Convex 构建高并发应用的开发者系统讲解热路径h数据库后端Convex 热路径优化指南读放大、反规范化、索引与失效成本的系统化治理Convex 热路径优化指南读放大、反规范化、索引与失效成本的系统化治理 本篇指南基于 convex backend 仓库中 convex performan数据库后端上一篇Chili3D撤销重做系统事务历史与状态管理最佳实践下一篇从70G到13.5G的镜像瘦身革命HeyGem.ai容器优化实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考