在开发生产级 Convex 应用时：用领域函数、索引查询…

在开发 Convex 后端应用时，按领域组织函数、用索引查询、为参数和返回值加校验、用 ConvexError 处理错误，并通过幂等 mutation 和 OCC 模式减少写冲突。

适用场景

解决思路

1. 安装 @convex-dev/eslint-plugin 作为开发依赖：运行 `npm i @convex-dev/eslint-plugin --save-dev`。
2. 在 `eslint.config.js` 中使用 `defineConfig` 并加入 `...convexPlugin.configs.recommended`，启用 Convex 推荐规则。
3. 确保代码满足 `no-old-registered-function-syntax` 规则：使用带 `handler` 的对象语法定义函数。
4. 确保代码满足 `require-argument-validators` 规则：所有函数都要有 `args: {}`。
5. 确保代码满足 `explicit-table-ids` 规则：所有 db 操作中显式写表名。
6. 确保代码满足 `import-wrong-runtime` 规则：不要在 Convex runtime 中导入 Node 模块。
7. 实现前不要假设，先获取最新文档：主文档 https://docs.convex.dev/understanding/best-practices/。
8. 实现前查阅错误处理文档：https://docs.convex.dev/functions/error-handling。
9. 实现前查阅写冲突文档：https://docs.convex.dev/error#1。
10. 需要更广上下文时查阅：https://docs.convex.dev/llms.txt。
11. 遵循 Zen of Convex：让 Convex 处理缓存、实时同步和一致性。
12. 遵循 Zen of Convex：把函数设计为应用的 API 接口。
13. 遵循 Zen of Convex：在 `schema.ts` 中显式定义数据模型，把 schema 当作真相。
14. 遵循 Zen of Convex：全面使用 TypeScript，利用端到端类型安全。
15. 遵循 Zen of Convex：把查询视为响应式订阅，而不是一次性请求。
16. 按领域组织 Convex 函数，例如把用户相关函数放在 `convex/users.ts`。
17. 函数定义从 `./_generated/server` 导入 `query`、`mutation`，从 `convex/values` 导入 `v`。
18. 定义查询函数时，用 `args: { userId: v.id('users') }` 声明参数，用 `returns` 声明返回类型，并在 `handler` 中用 `ctx.db.get('users', args.userId)` 获取文档。
19. 始终为函数参数和返回类型定义 validator。
20. 参数 validator 使用 `v.string()`、`v.optional()`、`v.union()`、`v.literal()` 等；返回 validator 使用 `v.id()`、`v.array()`、`v.object()` 等。
21. 创建 mutation 时返回 `v.id('tasks')`，插入数据时补全 `completed: false`、`createdAt: Date.now()` 等字段。
22. 查询过滤数据时使用索引而不是 `filter`：在 schema 中调用 `.index('by_user', ['userId'])`、`.index('by_user_and_status', ['userId', 'status'])`。
23. 查询时使用 `.withIndex('by_user', (q) => q.eq('userId', args.userId)).order('desc').collect()` 等基于索引的链式写法。
24. 面向用户的错误使用 `ConvexError`：从 `convex/values` 导入 `ConvexError`。
25. 抛出用户可见错误时使用对象，例如 `throw new ConvexError({ code: 'NOT_FOUND', message: 'Task not found' })`。
26. 更新前检查文档是否存在；不存在则抛 `ConvexError`，存在则用 `ctx.db.patch('tasks', args.taskId, { title: args.title })` 更新并返回 `null`。
27. 遵循 OCC 避免写冲突：让 mutation 幂等，以便重试时安全。
28. 幂等 mutation 示例：先 `ctx.db.get('tasks', args.taskId)`，若文档不存在或 `status === 'completed'` 则提前 `return null`，否则再 patch `status: 'completed'` 和 `completedAt: Date.now()`。
29. 尽可能不先读直接 patch：`ctx.db.patch('notes', args.id, { content: args.content })`，文档不存在时 patch 会抛错。
30. 对多个相互独立的更新使用 `Promise.all` 并行执行：先 map 生成 patch promise，再 `await Promise.all(updates)`。
31. TypeScript 中使用 `Id<'users'>` 表示文档引用。
32. TypeScript 中使用 `Doc<'users'>` 表示完整文档。
33. TypeScript 中正确使用 `Record<Id<'users'>, number>` 这类 Record 类型。
34. 区分 public 和 internal 函数：public 用 `query`、`mutation` 暴露给客户端；internal 用 `internalMutation` 等仅允许其他 Convex 函数调用。
35. 敏感操作使用 internal functions。
36. 完整 CRUD 模式：定义 `taskValidator`；`list` 用 `withIndex` 后 `collect`；`create` 插入并返回 id；`update` 过滤 undefined 后 patch；`remove` 用 `ctx.db.delete` 删除。
37. `update` mutation 中解构出 `taskId` 和 `updates`，用 `Object.fromEntries(Object.entries(updates).filter(([_, v]) => v !== undefined))` 清理 undefined；仅当清理后的对象非空才 patch。
38. 除非明确指示，不要运行 `npx convex deploy`。
39. 除非明确指示，不要运行任何 git 命令。
40. 始终为函数定义 returns validators。
41. 所有过滤数据的查询都使用索引。
42. 让 mutations 幂等以优雅处理重试。
43. 使用 `ConvexError` 作为面向用户的错误消息。
44. 按领域组织函数，例如 `users.ts`、`tasks.ts` 等。
45. 使用 internal functions 处理敏感操作。
46. 利用 TypeScript 的 `Id` 和 `Doc` 类型。
47. 避免常见错误：不要用 `filter` 代替 `withIndex`；始终定义索引并使用 `withIndex`。
48. 避免常见错误：不要缺少 return validators；始终指定 `returns` 字段。
49. 避免常见错误：不要写非幂等 mutations；更新前检查当前状态。
50. 避免常见错误：不要不必要地先读再 patch；尽可能直接 patch。
51. 避免常见错误：不要不处理 null 返回；文档 ID 可能不存在。
52. 需要时查阅 Convex Documentation：https://docs.convex.dev/。
53. 需要时查阅 Convex LLMs.txt：https://docs.convex.dev/llms.txt。
54. 需要时查阅 Best Practices：https://docs.convex.dev/understanding/best-practices/。
55. 需要时查阅 Error Handling：https://docs.convex.dev/functions/error-handling。
56. 需要时查阅 Write Conflicts：https://docs.convex.dev/error#1。

适用边界 · 注意事项

• 不适用于非 Convex 项目或未使用 Convex 后端的应用。
• 不适用于无法安装或使用 @convex-dev/eslint-plugin 与 Convex 平台的场景。
• 不适用于只需要普通 REST/GraphQL 后端且不需要 Convex 实时同步、OCC、端到端类型安全的场景。