convex-backend 函数目录入门:从 README 引导到 Query/Mutation 与分页实战

原创2026-10-13 22:09:38249 阅读
文章标签:数据库后端

convex-backend 函数目录入门:从 README 引导到 Query/Mutation 与分页实战

导读

本文围绕 npm-packages/private-demos/pagination-visualization/convex/README.md 展开,它是 Convex 项目中每个 convex/ 函数目录的标准引导文档:告诉你如何编写带参数校验的 query 查询函数与 mutation 变更函数、如何把函数引用到 React 组件中使用,以及如何用 Convex CLI 推送函数到部署环境。我们将以这份引导文档为主体,结合 pagination-visualization 演示项目的真实源码与 convex npm 包中的 usePaginatedQuery 实现,讲透 query/mutation 的完整写法、_generated 类型生成机制,以及在此基础上进阶的分页查询原理。读完本文,你将能独立编写、校验、调用和部署自己的 Convex 后端函数。

一、convex/ 函数目录与引导文档的定位

在 Convex 项目中,你的所有后端函数都集中放在根目录下的 convex/ 文件夹里。pagination-visualization 演示项目的目录结构为:

npm-packages/private-demos/pagination-visualization/
├── convex/                 # 后端函数目录
│   ├── _generated/         # CLI 自动生成的类型与 API 引用
│   ├── README.md           # 本文所依据的引导文档
│   ├── names.ts            # 真实的 query/mutation 函数
│   └── schema.ts           # 可选的数据库 schema 定义
├── src/                    # 前端 React 代码
│   ├── App.tsx             # 分页可视化界面
│   └── main.tsx
└── package.json            # 依赖与启动脚本

README.md 的第一行 "Welcome to your Convex functions directory!" 明确点出了它的身份——这是脚手架生成的标准引导页,告诉新项目开发者:

  • 在哪里写函数(convex/ 目录内的任意 .ts 文件);
  • query 和 mutation 分别长什么样、怎么在 React 里调用;
  • 如何用 CLI 把函数部署到远端。

它提到的两处官方文档入口(docs.convex.dev/functions、docs.convex.dev/database/reading-data)对应着本仓库中 convex 包 等源码注释里反复引用的同名文档。也就是说,这份 README 是整个函数开发流程的"目录页",而本仓库里的源码则是它背后完整的实现。

二、Query 函数:从定义到 React 调用

2.1 带参数校验的 query 定义

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;
  },
});

这里有几个值得展开的要点:

(1)query 来自 ./_generated/server,而不是从 convex 包直接导入。 _generated/ 目录由 Convex CLI 自动生成,它在编译期把你的函数与类型系统连接起来。该演示项目的 convex/_generated/server.d.ts 就是生成产物之一,你可以打开查看其中的 query、mutation 类型签名。

(2)args 中的 Validator 是参数校验器。 v.number()、v.string() 来自 convex/values,用于在运行时校验客户端传入的参数。README 注释里说"Validators for arguments"——如果客户端传入的类型不匹配,函数会直接拒绝执行并返回错误。这是 Convex 相比普通 JS 后端的显著差异:参数契约在函数定义处就强制执行。在 npm-packages/convex/src/values 中可以看到完整的校验器体系,包括 v.id()、v.array()、v.union()、v.optional() 等。

(3)handler 的第一个参数 ctx 是执行上下文。 通过 ctx.db 可以查询数据库。ctx.db.query("tablename").collect() 返回表中全部文档;README 注释特别说明"Read the database as many times as you need here"——即 handler 内可以自由多次读取数据库。

2.2 在 React 组件中使用 query

README 给出了对应的 React 端用法:

const data = useQuery(api.myFunctions.myQueryFunction, {
  first: 10,
  second: "hello",
});

要点是 useQuery 的第一个参数不是字符串函数名,而是 api.myFunctions.myQueryFunction——这个 api 对象同样来自 ./_generated/api(如演示项目中的 convex/_generated/api.ts),它提供全类型安全的函数引用:函数名拼错、参数类型不匹配都会在编译期报错。

useQuery 是响应式的:当 first、second 对应的查询结果在服务端发生变化时,组件会自动重新渲染拿到最新数据,无需手动刷新。

三、Mutation 函数:写入数据库的正确姿势

3.1 标准 mutation 模板

README 给出的 mutation 模板(原文完整继承):

// 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);
  },
});

与 query 的关键差异:

  • mutation 用于写入数据,ctx.db.insert 插入文档、ctx.db.delete 删除文档;同时 mutation 内也可以像 query 一样读取数据库(README 注释明示 "Mutations can also read from the database like queries");
  • mutation 的 handler 执行在事务中,要么全部生效要么全部回滚;
  • mutation 可以返回一个值(上例返回刚插入的文档),也可以什么都不返回。

3.2 在 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),
  );
}

两种方式的取舍在 README 注释里说得很清楚:

  • fire and forget(直接调用不等待):最常见的方式,适用于不需要关心结果的场景(如"记录一次点击");
  • 等待完成(.then(...) 获取返回值):当 UI 需要依赖 mutation 的执行结果(如展示新文档 ID、跳转页面)时使用。

注意 useMutation 返回的 mutation 本身就是一个可调用函数,它的签名与后端 myMutationFunction 的 args 严格对应。

四、进阶示例:pagination-visualization 如何落地这些模板

引导文档教你写第一个 query/mutation,而演示项目则把它们用到了真实场景。查看 convex/names.ts,可以看到模板的实战变形:

4.1 一个真正的 query:带索引的分页查询

export const getPeople = query({
  args: {
    paginationOpts: paginationOptsValidator,
  },
  handler: async ({ db }, { paginationOpts }) => {
    return await db
      .query("people")
      .withIndex("by_name")
      .paginate(paginationOpts);
  },
});

与引导模板相比,这里出现了三个新概念:

  • paginationOptsValidator(来自 convex/server):分页参数校验器,定义在 npm-packages/convex/src/server/pagination.ts,结构为 { numItems, cursor, endCursor?, id?, maximumRowsRead?, maximumBytesRead? };
  • .withIndex("by_name"):按 convex/schema.ts 中声明的 people 表索引查询:
    export default defineSchema({
      people: defineTable({
        name: v.string(),
      }).index("by_name", ["name"]),
    });
    
    schema 文件是可选的(README 注释 "The schema is entirely optional. You can delete this file and the app will continue to work."),它的价值在于提供更精确的 TypeScript 类型,并声明查询索引;
  • .paginate(paginationOpts):服务端分页 API。它的底层实现会发起 1.0/queryPage 异步系统调用,携带 cursor、endCursor、pageSize、maximumRowsRead、maximumBytesRead 等参数(见 query_impl.ts)。

4.2 一组真正的 mutation:seed / addPerson / deletePerson

export const seed = mutation({
  args: { names: v.array(v.string()) },
  handler: async ({ db }, { names }) => {
    // Remove all existing rows
    for await (const row of db.query("people")) {
      await db.delete(row._id);
    }
    for (const name of names) {
      await db.insert("people", { name });
    }
  },
});

export const addPerson = mutation({
  args: { name: v.string() },
  handler: async ({ db }, { name }) => {
    await db.insert("people", { name });
  },
});

export const deletePerson = mutation({
  args: { id: v.id("people") },
  handler: async ({ db }, { id }) => {
    await db.delete(id);
  },
});

这三个 mutation 演示了引导模板之外的能力:

  • v.array(v.string()) 表示参数是字符串数组;
  • v.id("people") 表示参数必须是 people 表的合法文档 ID,类型校验直接与 schema 关联;
  • 在 mutation 中用 for await 遍历并删除全部旧数据,实现了"先清空再灌入"的 seed 逻辑——这正是引导文档所说"mutation 内也可以读取数据库"的实际应用。

在 src/App.tsx 中,它们通过 useMutation(api.names.addPerson)、useMutation(api.names.deletePerson)、useMutation(api.names.seed) 接入 UI,点击 Seed 按钮会随机抽取 20 个名字灌入数据库。

五、深入分页:引导模板之外的完整链路

pagination-visualization 的核心价值是把"分页过程中每一页到底发生了什么"可视化出来。这需要理解前端 hook 与服务端 API 的配合。

5.1 客户端:usePaginatedQuery 与 usePaginatedQueryInternal

前端核心代码在 src/App.tsx:

const {
  user: { results, status, loadMore },
  internal,
} = usePaginatedQueryInternal(
  api.names.getPeople,
  {},
  { initialNumItems: 5, [includePage]: true },
);

这里用到的是 convex/react 导出的内部版本 usePaginatedQueryInternal(usePaginatedQuery 的底层实现,见 use_paginated_query.ts)。普通项目用公开的 usePaginatedQuery 即可:

const { results, status, isLoading, loadMore } = usePaginatedQuery(
  api.messages.list,
  { channel: "#general" },
  { initialNumItems: 5 },
);

usePaginatedQuery 会做三件事:

  1. 注入分页参数:自动在 args 里加上 paginationOpts: { numItems, cursor, id },其中 cursor: null 表示从第一页开始(见源码 L231-L237);
  2. 拼接所有页:把已加载的每一页 page 结果拼成一个完整列表 results;
  3. 管理状态机:返回 status(LoadingFirstPage / CanLoadMore / LoadingMore / Exhausted)和 loadMore(n) 回调。

5.2 分页状态机与异常恢复

从 use_paginated_query.ts 的状态构造逻辑可以看到完整的状态定义:

status isLoading 含义 loadMore 行为
LoadingFirstPage true 正在加载第一页 noop
CanLoadMore false 还有更多数据可加载 发起下一页请求
LoadingMore true 正在加载后续页 noop
Exhausted false 已到列表末尾 noop
Error(内部版本) false 查询出错 noop

另外,当服务端返回 InvalidCursor 错误时(例如分页所依赖的数据在读取过程中发生了变化),hook 会主动重置分页状态从头开始(见源码 L290-L310),并在 logger 中打印警告。每个分页会话还会携带一个自增的 paginationId 作为 "cache-buster",保证新会话不会错误复用旧的订阅结果(见 L452-L480)。

5.3 服务端:PaginationResult 与页面拆分

服务端 .paginate() 的返回结构 PaginationResult 定义在 pagination.ts:

interface PaginationResult<T> {
  page: T[];                          // 本页结果
  isDone: boolean;                    // 是否已到末尾
  continueCursor: Cursor;             // 下一页的游标
  splitCursor?: Cursor | null;        // 拆分本页为两半的游标
  pageStatus?: "SplitRecommended" | "SplitRequired" | null;
}

其中 pageStatus 是响应式分页的进阶机制:当一页读取的数据量过大时,服务端可能返回 SplitRecommended(建议拆分)甚至 SplitRequired(页面可能不完整,必须拆分)。客户端检测到这些信号后,会调用 splitQuery 把这一页拆成 (cursor, splitCursor] 和 (splitCursor, continueCursor] 两个半页并行加载(见 L60-L96)。

pagination-visualization 的 App.tsx 正是把这些"页面"的边界、每个分页参数(numItems、cursor、endCursor、id 等)逐条渲染出来,并用颜色标记游标,让你直观看到响应式数据变化时分页如何自动调整——这是理解 endCursor 参数作用(确保数据变化时页面之间不出现空隙,见 pagination.ts)的最佳实验场。

六、用 Convex CLI 推送与运行

README 的最后一段说明了 CLI 的使用方式:"Use the Convex CLI to push your functions to a deployment. See everything the Convex CLI can do by running npx convex -h in your project root directory. To learn more, launch the docs with npx convex docs."

在 pagination-visualization 项目中实际运行:

npx convex dev --start 'vite --open'

这是 package.json 中定义的 dev 脚本:convex dev 会持续监听 convex/ 目录,把函数同步到本地开发部署,并自动生成 _generated/ 文件;--start 'vite --open' 则同时启动 Vite 开发服务器并打开浏览器。

常用 CLI 命令速查:

命令 作用
npx convex -h 查看全部 CLI 命令
npx convex docs 在本地启动官方文档
npx convex dev 本地开发:监听函数变更、同步部署、生成 _generated
npx convex dev --once 单次同步后退出(CI 场景常用)
npx convex deploy 推送函数到生产部署

README 特别提示要在 project root directory(项目根目录)运行这些命令——因为 CLI 需要读取根目录下的 convex.json 与 package.json 来确定项目配置。

七、快速上手清单

结合引导文档与演示项目,一个完整的新手路径如下:

  1. 初始化项目:创建 convex/ 目录,放入 README.md(脚手架会生成)与函数文件;
  2. 定义 schema(可选):在 convex/schema.ts 中用 defineSchema / defineTable 声明表和索引;
  3. 编写函数:query 用 query({ args: {...}, handler }),写入用 mutation({...}),参数一律用 v 校验器声明;
  4. 跑一次 CLI:npx convex dev 生成 _generated/,此后 import ./_generated/server、../convex/_generated/api 均获得类型安全;
  5. 接入前端:useQuery(api.xxx, args) 读、useMutation(api.xxx) 写;列表加载用 usePaginatedQuery 配合 initialNumItems 与 loadMore;
  6. 验证效果:对照 pagination-visualization 的可视化界面(loadMore(5)、Seed 按钮、页面边界渲染),确认每个 status 的流转是否符合预期。

结语

convex/README.md 虽然只是一份脚手架引导,但它浓缩了 Convex 函数开发的全部核心动作:用 Validator 声明参数契约、用 ctx.db 读写数据、用 _generated 获得类型安全、用 CLI 完成部署。在此基础上,pagination-visualization 演示项目把 query/mutation 模板延展成了带索引、带分页、带响应式可视化的完整应用,而 use_paginated_query.ts 与 pagination.ts 则揭示了游标、页面拆分与状态机背后的实现细节。从模板到实战,再到源码级原理,这条路径正是理解 Convex 后端开发的最佳入口。

登录后查看全文
convex-backend