用途:面向 TypeScript 开发者的 Convex 后端开发基础技能,覆盖核心心智模型、函数类型、分层架构与 HTTP 动作实现,适用于从零构建 Convex 应用、编写查询/变更/动作、理解函数类型差异、实现分层架构、配置 HTTP webhook 或从其他后端迁移。
主要能力:区分 query、mutation、action、httpAction 及对应 internal 私有变体;说明核心不变量——mutation 为 ACID 事务、query 具响应式、action 非事务且无 ctx.db、调度与 mutation 原子绑定。给出三层架构:客户端公开入口层、内部领域逻辑层、动作与调度编排层,以及模型层模式(业务逻辑抽为可复用函数,函数保持轻薄)。
必要用法:公开函数从 ./_generated/server 导入 query、mutation、action,私有用 internalQuery、internalMutation、internalAction,HTTP 用 httpAction 与 httpRouter;函数引用用 api.fileName.functionName 与 internal.fileName.functionName;动作内通过 ctx.runQuery、ctx.runMutation 读写,外部调用用 fetch;数据库读写用 ctx.db.get/query/withIndex/insert/patch/replace/delete。文件按 convex/ 目录路由,model/ 与 _lib/ 不参与路由。
限制与注意:代码库启用 @typescript-eslint/no-explicit-any,使用 any 会导致构建失败;mutation 必须确定性,不能调用 fetch,需调度 action;action 不能访问 ctx.db;查询应使用索引而非 filter;避免频繁写同一文档引发 OCC 错误;函数需提供 returns 校验器。具体安装命令与版本信息暂未提供。