Convex 后端函数编写实战:Query/Mutation 定义、参数校验与 React 集成全指南

原创2026-09-22 09:21:571,753 阅读
文章标签:数据库后端

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 后端落地流程可以归纳为:

  1. 建模:在 schema.ts 中用 defineSchema/defineTable 声明表结构、字段校验器与索引;
  2. 写函数:在 convex/ 下新建 .ts 文件,用 query/mutation/action 定义业务逻辑,用 v.string()、v.number()、v.id("表名")、v.optional(...)、v.array(...) 声明入参与返回值;
  3. 本地验证:运行 npx convex dev 实时推送,或写 convex/**/*.test.ts 用例配合 Vitest 与 convex-test 离线验证;
  4. 前端接入:通过 useQuery(api.xxx.yyy, args) 与 useMutation(api.xxx.yyy) 在 React 组件中调用,全程类型安全;
  5. 发布:用 CLI 将函数推送至云端部署,Query 的响应式订阅自动生效。

结语

convex/ 目录的 README 模板虽然篇幅简短,却浓缩了 Convex 函数体系的核心范式:校验器驱动的参数契约、读写分离的 Query/Mutation、以及前后端共享的类型安全。结合仓库内 convex-test demo 的真实实现——带 returns 校验的列表查询、抛出 ConvexError 的业务校验、internalMutation 内部函数、基于索引的鉴权查询、调度与 HTTP 路由,再到 convex-test + Vitest 的离线测试闭环,你可以直接从模板出发,按本文的路径写出结构规范、可测试、可上线的 Convex 后端函数。

登录后查看全文
convex-backend