SuperAPI AI 工具集

function-creator

编程与开发

查看项目

更新于 10-16 16:04

技能介绍

用途

Convex Function Creator 用于在实现新的 API 端点时,创建符合最佳实践、安全且类型安全的 Convex 函数。根据资料,它适用于以下场景:创建新的查询函数(读取数据)、创建新的变更函数(写入数据)、创建新的动作函数(外部 API、长时间运行任务),以及向 Convex 后端添加 API 端点。

主要能力

该技能围绕 Convex 的三类函数展开,并给出各自的约束与示例:

  • 查询(Queries,只读):只能读取数据库,不能修改数据或调用外部 API,具备缓存与响应式特性,在事务中运行。
  • 变更(Mutations,事务性写入):可读写数据库,不能调用外部 API,在 ACID 事务中运行,冲突时自动重试。
  • 动作(Actions,外部调用 + 非事务):可调用外部 API(如 fetch、AI 等),可通过 ctx.runMutation 调用变更,不能直接访问数据库,没有自动重试;需要 Node.js API 时应添加 "use node" 指令。资料特别指出:带 "use node" 的文件只能包含 actions,不能包含 queries 或 mutations。

使用方式与必需组件

资料要求生成的函数包含以下要素:

  1. 参数校验:始终使用校验器定义 args,例如 v.id("tasks")、v.string()、v.number()、v.boolean()、v.array(v.string()) 以及 v.optional(v.object(...))。
  2. 返回类型校验:始终定义 returns,可为对象、数组或可空联合类型(如 v.union(v.object({...}), v.null()))。
  3. 身份认证检查:在公开函数中使用 ctx.auth.getUserIdentity() 并在未认证时抛出错误。
  4. 授权检查:验证所有权或权限,例如先获取资源,再比对 userId,不匹配时抛出未授权错误。

代码示例覆盖了带认证的安全查询、带校验的安全变更、调用外部 API 的动作,以及仅后端可调用的内部函数(如 internalMutation,无需认证)。资料还提到,需要 Node.js 专用 API(如 crypto、第三方 SDK)时,必须在文件顶部使用 "use node",且这类文件只能包含 actions;建议把需要 Node.js 的 actions 单独放在一个文件中,而把 queries 和 mutations 放在不使用 "use node" 的文件中。

适用场景

当你要向 Convex 后端新增读取、写入或对接外部服务的函数端点时使用。资料中的示例以任务(tasks)为例,涉及按用户查询任务、创建与更新任务、通过外部服务发送提醒等。

检查清单与限制

资料给出的检查清单包括:使用校验器定义 args;定义 returns 校验器;进行身份认证检查;进行授权检查;await 所有 promise;使用索引查询(不要在查询上使用 .filter());使用描述性错误信息;计划函数使用 internal.* 而非 api.*;如果使用 Node.js API,在文件顶部添加 "use node";如果文件带 "use node",则只能包含 actions;使用 "use node" 时,把 actions 与 queries/mutations 分开放在不同文件中。

资料未说明该技能的收费、价格、平台支持范围或实际使用效果,这些信息暂未提供。