SuperAPI AI 工具集

convex

通用与其它

查看项目

更新于 10-16 06:16

技能介绍

用途:这是 Better Convex 的核心技能文档,面向已完成配置的 better-convex 应用,指导日常功能交付的常见路径(约 80% 场景),涵盖 cRPC + ORM + 认证 + React 的端到端开发。若缺少安装、环境、认证接线或项目结构,应先查阅 references/setup/index.md 及相关 setup 文件;高级或小众任务只加载对应功能参考。

主要能力范围:新增或更新 schema 表、索引、关系与触发器;实现 cRPC 过程(query、mutation、action、httpAction)并带运行时认证与限流;用 useCRPC() 与 TanStack Query 实现功能 UI;为认证、错误与副作用添加少量高价值测试。不包含全新项目搭建、插件深入(admin/organizations/polar)与包级一致性测试。

使用约定:优先用 ctx.orm 访问应用数据;列表/读取路径要有界且走索引;新功能用 cRPC builder 与中间件,避免裸 handler;预期失败用 CRPCError;跨行不变量优先用 schema 触发器,触发器不稳定时改为显式 mutation 辅助函数;认证与限流检查保持在服务端。模块间调用用 create<Module>Handler(ctx)(query/mutation,零开销)或 create<Module>Caller(ctx)(action/HTTP),从 ./generated/<module>.runtime 导入,不要直接调用 ctx.runQuery/ctx.runMutation/ctx.runAction。

关键差异:过程输入根必须是 z.object(...);无返回值 mutation 省略 .output(...) 而非 z.void();.paginated({ limit, item }) 需在 .query() 之前;元数据会 codegen 到 @convex/api 叶子,勿在 .meta(...) 放密钥;ctx.orm 强制约束与 RLS,ctx.db 绕过;非分页 findMany() 必须显式限定大小;谓词 where 需显式 .withIndex(...);无 where 的 update/delete 会抛错,除非 allowFullScan();count()、aggregate()、groupBy() 需要匹配的 aggregateIndex;cRPC React 查询默认实时(subscribe: true),不要对这些订阅路径用 queryClient.invalidateQueries。

典型文件与构建顺序:convex/functions/schema.ts、convex/functions/<feature>.ts、convex/lib/crpc.ts、src/lib/convex/crpc.tsx、src/** UI 文件、convex/functions/http.ts 或 convex/routers/**、convex/functions/crons.ts。默认顺序为 schema+索引+关系、触发器、带严格输入输出与认证限流的过程、React hooks、可选 HTTP 路由与调度、测试。

限制:本技能按目录限定,不应依赖 skills/convex/** 之外的文件;资料未提供具体安装命令、价格、平台支持与效果数据。