Convex 后端函数编写实战:Query/Mutation 定义、参数校验与 React 集成全指南
Convex 后端函数编写实战:Query/Mutation 定义、参数校验与 React 集成全指南
导读
本文以 Convex 开源仓库中 convex/ 函数目录的标准 README 模板为主体,系统讲解 Convex 后端函数的编写规范:如何用 TypeScript 定义 Query(读取)与 Mutation(写入)函数、如何用 convex/values 的校验器(Validator)约束参数、如何通过 React Hooks 在前端调用这些函数,以及如何使用 Convex CLI 将函数推送至部署。文中所有示例均结合仓库内 convex-test demo 的真实函数实现与测试用例展开,读完即可照抄编写出第一个可运行的 Convex 后端函数。
1. 认识 convex/ 函数目录
在任何一个 Convex 项目中,后端代码都约定存放于项目根目录的 convex/ 文件夹内(仓库中的实际样例即 npm-packages/demos/convex-test/convex)。该目录中的每个 .ts 文件导出一个或多个 Convex 函数,模板 README(即本文对应的 README.md)开篇即指出:
Write your Convex functions here.
目录下还包含一个由 CLI 自动生成的 _generated/ 子目录(见 _generated),其中:
server.ts/server.js:导出query、mutation、action、internalMutation、httpAction等函数定义器;api.ts/api.js:导出api与internal命名空间,客户端与后端据此获得类型安全的函数引用;dataModel.ts:根据schema.ts生成的数据库表类型定义。
这些生成文件在运行 convex dev 或执行测试时会自动更新,开发者不应手改。
2. Query 函数:从数据库读取数据
2.1 函数定义骨架
README 给出了一个接收两个参数的 Query 函数标准模板:
// convex/myFunctions.ts
import { query } from "./_generated/server";
import { v } from "convex/values";
export const myQueryFunction = query({
// Validators for arguments.
args: {
first: v.number(),
second: v.string(),
},
// Function implementation.
handler: async (ctx, args) => {
// Read the database as many times as you need here.
const documents = await ctx.db.query("tablename").collect();
// Arguments passed from the client are properties of the args object.
console.log(args.first, args.second);
// Write arbitrary JavaScript here: filter, aggregate, build derived data,
// remove non-public properties, or create new objects.
return documents;
},
});
结构拆解如下:
| 组成 | 说明 |
|---|---|
query({...}) |
从 ./_generated/server 导入的函数定义器,声明这是一个只读函数 |
args |
参数校验器集合,客户端传入的每个参数都必须在此声明类型,否则调用会被拒绝 |
handler |
异步实现体,接收 ctx(执行上下文)与 args(已校验的参数对象) |
ctx.db |
数据库句柄,query("表名") 后接 .collect() 取回全部文档,.first() 取首条,.unique() 取唯一值 |
关键点在于 Query 内只能读、不能写,这保证了它可以在任意部署节点上安全重放,并天然支持订阅与缓存失效。README 还特别提示:handler 内可执行任意 JavaScript 逻辑,例如过滤、聚合、构建派生数据、剔除非公开字段或创建新对象,之后再把处理结果返回给客户端。
2.2 仓库中的真实 Query 实现
模板之外,demo 项目 posts.ts 展示了带排序与返回值校验的完整写法:
export const list = query({
args: {},
returns: v.array(
v.object({
_id: v.id("posts"),
_creationTime: v.number(),
title: v.string(),
content: v.string(),
author: v.string(),
}),
),
handler: async (ctx) => {
const posts = await ctx.db.query("posts").order("desc").collect();
return posts;
},
});
这里比模板多出两个实用细节:
order("desc"):对结果按_creationTime倒序排列,配合.collect()一次取回;returns:声明返回值的校验器(这里用v.array(v.object({...}))描述每篇帖子的形状),由框架在运行时校验返回值,防止意外的类型漂移。
此外 tasks.ts 展示了结合索引的查询方式 ctx.db.query("tasks").withIndex("by_author", (q) => q.eq("author", identity.name)).collect(),其中 by_author 索引定义在 schema.ts 中:
tasks: defineTable({
author: v.optional(v.string()),
text: v.optional(v.string()),
}).index("by_author", ["author"]),
3. 在 React 中调用 Query
README 给出前端调用模板,使用 convex/react 提供的 useQuery Hook:
const data = useQuery(api.myFunctions.myQueryFunction, {
first: 10,
second: "hello",
});
- 第一个参数是类型安全的函数引用
api.myFunctions.myQueryFunction(来自_generated/api); - 第二个参数是传给后端函数的参数对象,其键必须与
args中声明的校验器一一对应(此处first为数字、second为字符串); useQuery是响应式的:数据变化、查询失效时会自动重新请求并触发组件重渲染,无需手动管理请求状态。
在 demo 测试中也能看到等价的服务端调用形态(见 auth.test.ts):await asSarah.query(api.tasks.list) 直接以编程方式触发同一个 Query,便于在测试里断言返回值。
4. Mutation 函数:写入数据库
4.1 函数定义骨架
与 Query 相对,Mutation 负责插入、更新、删除数据。README 模板:
// convex/myFunctions.ts
import { mutation } from "./_generated/server";
import { v } from "convex/values";
export const myMutationFunction = mutation({
// Validators for arguments.
args: {
first: v.string(),
second: v.string(),
},
// Function implementation.
handler: async (ctx, args) => {
// Insert or modify documents in the database here.
// Mutations can also read from the database like queries.
const message = { body: args.first, author: args.second };
const id = await ctx.db.insert("messages", message);
// Optionally, return a value from your mutation.
return await ctx.db.get("messages", id);
},
});
mutation({...})声明这是一个可写函数;ctx.db.insert("messages", message)插入文档并返回其Id;ctx.db.get("messages", id)按主键读取,这里用作插入后的回读,演示 Mutation 同样可以读库;- Mutation 可选返回值,前端可以拿到该结果继续处理。
4.2 仓库中的真实 Mutation 实现
demo 项目 messages.ts 给出了带业务校验的真实写法:
export const send = mutation({
args: { body: v.string(), author: v.string() },
handler: async (ctx, { body, author }) => {
if (body === "") {
throw new ConvexError("Empty message body is not allowed");
}
await ctx.db.insert("messages", { body, author });
},
});
值得注意的两点:
- 这里直接以解构方式取用
args,与模板的args.first等价; - 业务校验失败时抛出
ConvexError(来自convex/values),它是 Convex 专门设计给客户端展示的错误类型,消息可以安全地传递给前端,而普通Error的堆栈与内部信息则会被隐藏。
demo 中还有 internalMutation 的用法(见 posts.ts):internalMutation 定义的函数不能从客户端直接调用,只能被服务端其他函数通过 internal 命名空间触发,适合作为内部工具函数(例如被 Action 调用的写库入口)。
5. 在 React 中调用 Mutation
README 给出了两种调用方式:
const mutation = useMutation(api.myFunctions.myMutationFunction);
function handleButtonPress() {
// fire and forget, the most common way to use mutations
mutation({ first: "Hello!", second: "me" });
// OR
// use the result once the mutation has completed
mutation({ first: "Hello!", second: "me" }).then((result) =>
console.log(result),
);
}
useMutation(api.myFunctions.myMutationFunction)返回一个触发函数;- “发射后不管”(fire and forget) 是最常见用法:
mutation({...})立即返回,后台执行写入; - 需要结果时,可以对返回的 Promise 调用
.then((result) => ...),result即 Mutation handler 的返回值(对应模板中的return await ctx.db.get("messages", id))。
6. 模板之外:Action、调度与 HTTP 路由
convex/ 目录不止有 Query 与 Mutation,demo 项目完整展示了另外三种函数形态,可作为模板的进阶补充:
6.1 Action:执行不可重放的外部副作用
export const sendAIMessage = action({
args: { prompt: v.string() },
handler: async (): Promise<string> => {
const response = await fetch("https://www.example.com/ai");
const text = await response.text();
return text;
},
});
见 messages.ts。Action 可以发起任意网络请求(如调用 AI 服务、第三方 API),因为它的执行不要求可重放,代价是不能直接使用 ctx.db(需经 runMutation/runQuery 间接访问)。
6.2 调度:ctx.scheduler.runAfter
return await ctx.scheduler.runAfter(delayMs, internal.scheduler.someAction);
见 scheduler.ts。runAfter 返回 Id<"_scheduled_functions">,可延迟执行另一个函数;示例中还演示了 Mutation 通过 api.scheduler.mutationSchedulingAction 递归调度自身,形成链式任务。
6.3 HTTP 路由:httpRouter
const http = httpRouter();
http.route({
path: "/some/path",
method: "POST",
handler: httpAction(async (_ctx, _request) => {
return new Response(`Hello, world!`);
}),
});
export default http;
见 http.ts。httpRouter 与 httpAction 让 Convex 函数暴露为标准的 HTTP 端点(支持 Web 标准 Request/Response),适合接入 Webhook 或自建 REST 接口。
7. 开发与测试工作流
7.1 用 CLI 推送与开发
README 明确给出两条 CLI 使用指引,均在项目根目录执行:
npx convex -h:查看 Convex CLI 的全部子命令;npx convex docs:在本地浏览器启动官方文档。
配合 demo 的 package.json 可以看到常用脚本:
"scripts": {
"dev": "convex dev",
"test": "vitest",
"test:once": "vitest run"
}
convex dev 会启动本地开发服务器,监控 convex/ 目录变更,自动把函数推送到本地部署并同步生成 _generated/ 代码——这就是"写函数、保存、立即生效"的开发循环。
7.2 用 convex-test 做无部署单元测试
本 demo 的名字即揭示其定位:配合 convex-test 包在 Vitest 中直接测试 Convex 函数,无需启动部署。测试配置见 vitest.config.ts,其中 convex 测试运行在 edge-runtime 环境以贴近真实运行沙箱。
auth.test.ts 是典型用例:
const t = convexTest(schema, modules);
const asSarah = t.withIdentity({ name: "Sarah" });
await asSarah.mutation(api.tasks.create, { text: "Add tests" });
const sarahsTasks = await asSarah.query(api.tasks.list);
convexTest(schema, modules)用内存数据库构建测试实例,modules由import.meta.glob("./**/*.ts")收集全部函数模块;t.withIdentity(...)模拟不同登录身份的调用者,从而验证 tasks.ts 中ctx.auth.getUserIdentity()的鉴权逻辑——Sarah 能读到自己的任务,而 Lee 的查询结果为空。
这一模式让"模板中的函数"可以像普通 TypeScript 模块一样被快速验证,也印证了模板中"Write arbitrary JavaScript here"的承诺:Convex 函数首先是普通 TypeScript 函数。
8. 从模板到线上:完整落地路径
综合模板 README 与 demo 源码,一个完整的 Convex 后端落地流程可以归纳为:
- 建模:在 schema.ts 中用
defineSchema/defineTable声明表结构、字段校验器与索引; - 写函数:在
convex/下新建.ts文件,用query/mutation/action定义业务逻辑,用v.string()、v.number()、v.id("表名")、v.optional(...)、v.array(...)声明入参与返回值; - 本地验证:运行
npx convex dev实时推送,或写convex/**/*.test.ts用例配合 Vitest 与convex-test离线验证; - 前端接入:通过
useQuery(api.xxx.yyy, args)与useMutation(api.xxx.yyy)在 React 组件中调用,全程类型安全; - 发布:用 CLI 将函数推送至云端部署,Query 的响应式订阅自动生效。
结语
convex/ 目录的 README 模板虽然篇幅简短,却浓缩了 Convex 函数体系的核心范式:校验器驱动的参数契约、读写分离的 Query/Mutation、以及前后端共享的类型安全。结合仓库内 convex-test demo 的真实实现——带 returns 校验的列表查询、抛出 ConvexError 的业务校验、internalMutation 内部函数、基于索引的鉴权查询、调度与 HTTP 路由,再到 convex-test + Vitest 的离线测试闭环,你可以直接从模板出发,按本文的路径写出结构规范、可测试、可上线的 Convex 后端函数。