SuperAPI AI 工具集

convex-best-practices

通用与其它

查看项目

更新于 10-16 07:22

技能介绍

用途:为 Convex 应用提供生产环境下的正确性与性能模式,并说明 @convex-dev/eslint-plugin 强制执行的规则。适用于审查 Convex 代码、判断某个模式是否合适、配置 ESLint,以及修复写冲突和慢查询。

核心规则:每个函数都写 args 与 returns,无返回值时用 returns: v.null();所有表读取都通过 withIndex 走 convex/schema.ts 中的索引,而非 .filter();变更保持幂等,文档已处于目标状态时提前返回;无需旧值时直接 ctx.db.patch(id, fields);独立写入用 Promise.all;定时任务与 ctx.scheduler 只调度 internal.*;鉴权与业务逻辑放在接收 ctx 的普通辅助函数中;客户端可读的错误用 ConvexError,普通 Error 在生产环境会被脱敏。索引按字段顺序命名,查询字段顺序保持一致。

OCC 与写冲突:Convex 变更在乐观并发控制下运行,会记录读取内容,若其他变更先提交了这些数据的改动则重试,重试过多后客户端看到写冲突错误。冲突来源包括:两个变更同时写同一文档(计数器、lastSeen、共享设置);变更读取范围过宽(如整表 .collect());客户端调用同一变更快于其提交速度。应对方式:幂等加提前返回、直接 patch、用事件行替代计数器字段、心跳等高频写入加去重窗口(如 10 秒)并配合客户端防抖(输入 300–500ms,心跳数秒),把 lastSeen 等热字段放入独立表。

分页与确定性:无界表上的 .collect() 会日益变慢并触及读取上限,用户可增长的数据应使用 .paginate(),客户端用 convex/react 的 usePaginatedQuery 驱动 loadMore。查询中不得使用 Date.now(),需由客户端传入时间或由定时变更更新状态字段;变更与 action 可以调用 Date.now()。

ESLint:安装 npm i --save-dev @convex-dev/eslint-plugin,并在 eslint.config.js 中引入 convexPlugin.configs.recommended,可在 lint 阶段捕获旧函数语法、缺失参数校验器、查询中的 .filter() 以及整点 cron 等问题。

常见错误与检查清单:表查询用 .filter()、无界表用 .collect()、先读再 patch 共享文档、按事件递增计数字段、变更缺少提前返回、独立写入串行 await、查询中用 Date.now()、调度 api.、用普通 Error 传用户消息、把业务逻辑写进 handler。检查项包括:每个函数有 args 与 returns;读取用 withIndex;索引按字段顺序命名;变更幂等提前返回;无需旧值时不先读;独立写入用 Promise.all;高频计数用事件行或计数器组件;无界列表用 .paginate();查询中无 Date.now();调度目标为 internal.;已安装 ESLint 插件且 lint 通过。

限制:资料未提供该技能的安装命令、版本、收费与平台支持信息,暂未提供。