用途:在 Convex 项目中构建数据模型与后端函数,覆盖 schema、query、mutation、action 及客户端调用,强调严格校验器与索引。
主要能力与规则:schema 必须在 convex/schema.ts 用 defineSchema/defineTable 定义全部表;_id 与 _creationTime 为系统字段自动添加;每个字段须用 v.* 校验器,尽量避免 v.any()。索引命名须包含全部字段,如 by_field1_and_field2;用 .index(name, [fields...]),字段顺序影响范围表达式,每索引最多 16 字段、每表最多 32 索引。函数须用带 args、returns、handler 的新语法,并校验参数与返回值(HTTP action 除外);读用 query、写用 mutation、外部或长任务用 action;action 不得访问 ctx.db,须用 ctx.runQuery/ctx.runMutation。同文件经 ctx.run* 调用时,接收变量须显式标注返回类型。
数据库操作:ctx.db.get/patch/replace/delete 须显式传表名;replace 为整体替换,patch 为浅合并,缺失均抛错;query 不支持 .delete(),须 .collect() 后遍历调用 ctx.db.delete(id);.unique() 匹配多条会抛错;生产查询禁用 filter,改用索引与 .withIndex。
性能与分页:大表优先 .withIndex;无范围时须搭配 take、first、unique 或 paginate;collect() 超过 1024 条会抛错,大结果集用 take(n)、paginate() 或 for await 迭代。分页须在 args 使用 paginationOptsValidator,.paginate() 返回 page、isDone、continueCursor,页面具响应性且大小可能变化,建议避免对完整结果对象使用严格 returns 校验器。
客户端与安全:使用 convex/_generated/api 的 api.* 引用;React 钩子为 useQuery、useMutation、useAction、usePaginatedQuery;不得在渲染期间调用 mutation 或 action。每个函数须做鉴权,通过 ctx.auth 检查身份;敏感逻辑不得暴露在公开函数,须用 internal 函数。
限制:资料未提供安装命令、收费、平台与具体使用步骤。