SuperAPI AI 工具集

convex-backend

编程与开发

查看项目

更新于 10-23 02:19

技能介绍

用途

Convex Backend 技能用于借助 Convex 构建类型安全的后端逻辑,并实现实时数据同步。它适合以下场景:构建实时协作应用(聊天、仪表盘、多人游戏);需要无需管理基础设施的后端;希望使用带自动缓存的类型安全服务端函数;构建需要响应式数据(智能体状态、流式结果)的 AI 应用;使用托管数据库加函数进行快速原型开发。

主要能力

该技能覆盖 Convex 的核心开发要素:

  • Schema 定义:通过 defineSchema 和 defineTable 定义数据表、字段类型与索引,例如用户表、消息表、频道表,并支持 by_email、by_role、by_channel 等索引。
  • 查询(Queries):实时读取数据,支持索引查询、排序、限制数量,并可关联解析用户等关联数据。
  • 变更(Mutations):写入数据,包含认证身份检查、查找或创建用户、插入记录等逻辑。
  • 动作(Actions):调用外部 API(如 AI 接口),并通过 ctx.runMutation 将结果写回数据库。
  • 定时函数(Cron Jobs):使用 cronJobs 配置按间隔或按 cron 表达式运行的任务,如清理旧消息、生成每日报告。
  • 认证集成:通过 auth.config.ts 配置认证提供方,并在 React 客户端使用 ConvexProviderWithClerk 等集成。
  • React 客户端使用:使用 useQuery 和 useMutation 实现实时自动更新与数据写入。
  • 部署:使用 npx convex deploy 部署到生产环境,支持环境变量文件、设置与查看环境变量、查看日志、手动运行函数。
  • 文件存储:通过 ctx.storage.generateUploadUrl 生成上传 URL,通过 ctx.storage.getUrl 获取文件 URL。

使用方式

前置条件:Node.js 18+、npm 或 pnpm、Convex 账号(免费额度:每月 100 万次函数调用)。

快速开始:

在已有项目中初始化:

npm install convex
npx convex dev     # 启动本地开发(与云端同步)

在新项目中:

npm create convex@latest

部署到生产环境:

npx convex deploy
npx convex deploy --env-file .env.production

设置环境变量:

npx convex env set ANTHROPIC_API_KEY sk-ant-...
npx convex env list

查看日志与手动运行函数:

npx convex logs
npx convex logs --follow
npx convex run messages:listByChannel '{"channelId": "abc123"}'

适用场景

  • 实时协作应用:聊天、仪表盘、多人游戏。
  • 需要响应式数据的 AI 应用:智能体状态、流式结果。
  • 希望零基础设施管理的后端开发。
  • 需要类型安全服务端函数与自动缓存的场景。
  • 使用托管数据库加函数进行快速原型开发。

最佳实践

  • 在编写函数前先定义 schema 与校验。
  • 尽可能保持变更幂等。
  • 在每个特权查询/变更中检查认证身份。
  • 为高读取集合尽早添加索引。
  • 使用内部函数处理仅服务端逻辑(定时任务、webhook)。
  • 将密钥存储在 Convex 环境变量中,绝不写入代码。
  • 在 React 客户端使用乐观更新以获得即时 UI 反馈。

限制

  • 基础设施命令可能中断服务:在变更状态前确认目标主机/范围,并准备备份或快照。
  • 本技能为仅文档导入:上游脚本与模板未随附。
  • 动作有 10 分钟超时限制,需拆分为更小步骤。
  • 查询过慢时需添加匹配查询模式的数据库索引。
  • 类型错误时运行 npx convex dev 重新生成类型。
  • 认证不工作时检查 auth.config.ts 与提供方域名。
  • 部署失败时检查 npx convex logs 并确认环境变量已设置。

相关技能

  • firebase-app-platform:替代的托管后端。
  • vercel-deployments:前端托管。
  • agent-observability:为 AI 驱动的后端流程添加可观测性。