用途
Convex Actions 是一份关于 Convex 平台中 Action、事务与调度的最佳实践指南。它面向需要在 Convex 应用中编写 Action 的开发者，帮助其正确处理外部 API 调用、数据库读写以及异步任务调度。
函数类型概览
Convex 提供三种函数类型，各自在数据库访问、外部 API 调用和缓存方面能力不同：
- Query：只读数据库，不能调用外部 API，支持响应式缓存，用于获取数据。
- Mutation：可读写数据库，不能调用外部 API，无缓存，用于修改数据。
- Action：通过 runQuery/runMutation 访问数据库，可以调用外部 API，无缓存，用于外部集成。
主要能力与使用方式
使用 Node.js 运行时
在需要使用 Node.js API 的文件顶部添加 "use node"; 指令。示例中展示了通过 action 调用 Resend 邮件 API 的写法，包括从 process.env 读取 API Key、使用 fetch 发送请求并返回结果。
调度函数
使用 ctx.scheduler.runAfter 调度函数。示例中在 mutation 内插入任务后，通过 ctx.scheduler.runAfter(0, internal.tasks.processTask, { taskId }) 调度内部函数处理任务，并强调调度时应始终使用 internal 函数。
仅在切换运行时时使用 runAction
除非需要切换运行时，否则应使用普通 TypeScript 函数替代 runAction，以减少不必要的开销。示例对比了 ctx.runAction 与直接导入并调用普通函数两种写法。
避免顺序调用 ctx.runMutation / ctx.runQuery
每次调用都在独立事务中运行。指南建议将多次读取合并为单次一致性查询，将循环插入合并为原子批量操作，以保证一致性。例外情况包括迁移、聚合，或调用之间存在副作用时。
在 Query/Mutation 中优先使用辅助函数
使用普通 TypeScript 辅助函数而非 ctx.runQuery/ctx.runMutation，以减少开销。例外是需要部分回滚时，可使用 ctx.runMutation 并在 catch 中记录失败。
始终 await 异步操作
所有异步操作都应 await，包括 ctx.scheduler.runAfter 和 ctx.db.patch。建议启用 ESLint 的 no-floating-promises 规则。
完整 Action 示例
指南提供了一个支付处理 Action 的完整示例：先通过 ctx.runQuery 读取订单，再调用 Stripe API，最后通过 ctx.runMutation 更新订单状态并返回结果。
适用场景
适用于在 Convex 中编写需要调用外部 API 的 Action，例如发送邮件、处理支付、抓取页面，以及需要调度后台任务或保证数据库操作一致性的场景。
限制
资料未提供关于收费、价格、平台支持范围或性能指标的具体信息。