用途:在 Convex 项目中编写后端函数。每个导出函数使用对象形式,声明 args 与 returns 校验器;按处理逻辑选择类型:query 只读、mutation 读写、action 调用外部服务,internalQuery/internalMutation/internalAction 仅供其他 Convex 代码调用,httpAction 用于 HTTP 端点。
主要能力:读取用 ctx.db.get(id) 或 withIndex,禁止对表查询用 .filter();终止方法按预期数量选择 .unique()、.first()、.take(n)、.collect()、.paginate()。写入用 insert、patch、replace、delete,patch 直接合并字段并保证可重试。内部函数通过 ./_generated/api 的 api.* 与 internal.* 引用,定时任务与 cron 一律调度 internal.*。action 无 ctx.db,需通过 ctx.runQuery 与 ctx.runMutation 读写,每次调用是独立事务;默认运行时可用 fetch,需要 Node 内置模块或 Node 专用 SDK 时在文件首行加 "use node",且该文件只能导出 action。
错误处理:面向客户端的错误抛 ConvexError(来自 convex/values),普通 Error 在生产环境会被隐藏;预期缺失返回 null,真实失败才抛错。建议保持 handler 简短,把鉴权、校验与业务逻辑放入以 ctx 为首参的普通异步函数。
限制与常见错误:缺少 returns 校验器、表查询用 .filter()、在 action 中使用 ctx.db、在 query/mutation 中 fetch、调度 api.*、在含 query 的文件中使用 "use node"、在 query 中使用 Date.now()、一个 action 发起大量 runQuery、用普通 Error 传递用户消息、遗漏 await。文档见 https://docs.convex.dev/functions 等。