SuperAPI AI 工具集

convex-component-authoring

通用与其它

查看项目

更新于 10-16 07:21

技能介绍

用途:把某项功能(计数器、限流、审计日志、通知等)抽取为自包含的 Convex 组件,拥有自己的 convex.config.ts、schema、函数和供父应用调用的类型化客户端封装。核心规则:组件不能读取父应用的表、ctx.auth 或 process.env,所需数据一律由应用以参数传入。

主要能力:用 defineComponent("name") 定义组件;组件内 schema 与函数从组件自身的 _generated/server 导入;父应用在 convex.config.ts 中用 app.use(counter) 注册,可用 { name: "pageViews" } 注册第二个实例;运行 npx convex dev 生成 components.counter 引用,函数路径镜像文件名(如 components.counter.public.add)。组件函数在父应用中为内部引用,需通过 ctx.runQuery / ctx.runMutation 调用,客户端不能直接访问。客户端封装类先接收组件引用、再接收选项,可在应用环境读取 ctx.auth 与 process.env 后传参。

边界规则:组件内 v.id("users") 指向组件自己的表,父应用 id 需以 v.string() 传入;组件内 Id 在 ComponentApi 中变为 string;组件内无 ctx.auth,需在应用解析用户后传 userId;无应用 process.env,需在 defineComponent 中声明 env 并由 app.use 提供,或作为参数传入;.paginate() 不能跨边界,组件内用 convex-helpers 的 paginator;组件 http.ts 路由由应用以 httpPrefix 挂载且无 ctx.auth;回调应用需用 createFunctionHandle 以函数句柄传递。每个公开函数都应带 args 与 returns 校验器,否则父应用只能看到 any。

适用场景:功能需要独立表与 schema、独立事务、跨应用复用,或面向 Convex 组件目录发布。若只是应用自有表上的共享逻辑,用 convex/lib/ 下的普通 TypeScript 辅助函数更简单;仅需 React hook 或客户端工具则用 npm 库。

限制:本地组件可把内容放在 convex/components/<name>/ 并省略 client/ 与 package.json;发布到 npm 的导出映射、构建顺序、README 与版本管理见 references/publishing.md。常见错误包括未注册 app.use、从应用 _generated/server 导入 mutation、在 React 中直接调用 api.counter.add、组件内使用 v.id("users")、ctx.auth、process.env 或 .paginate(),以及公开函数缺少 returns。文档:https://docs.convex.dev/components/authoring 与 https://docs.convex.dev/components/using。