convex-backend

Convex 后端指南

何时加载

• 触发条件：使用 Convex 进行开发，编写 Convex 函数、架构、查询、变更、操作或实时订阅时
• 跳过条件：项目未使用 Convex 作为后端

使用 TypeScript 构建 Convex 后端的综合指南。涵盖函数语法、验证器、架构、查询、变更、操作、调度和文件存储。

何时应用

在以下场景中参考本指南：

• 编写新的 Convex 函数（查询、变更、操作）
• 定义数据库架构和验证器
• 实现实时数据获取
• 设置 cron 作业或计划函数
• 使用文件存储
• 设计 API 结构

规则类别

类别	影响	描述
函数语法	CRITICAL	使用包含 args/returns/handler 的新函数语法
验证器	CRITICAL	类型安全的参数和返回值验证
架构设计	HIGH	表定义、索引、系统字段
查询模式	HIGH	使用索引高效获取数据
变更模式	MEDIUM	数据库写入、patch 与 replace 的区别
操作模式	MEDIUM	外部 API 调用、Node.js 运行时
调度	MEDIUM	Cron 和延迟函数执行
文件存储	LOW	Blob 存储和元数据

快速参考

函数注册

// Public functions (exposed to clients)
import { query, mutation, action } from "./_generated/server";

// Internal functions (only callable from other Convex functions)
import {
  internalQuery,
  internalMutation,
  internalAction,
} from "./_generated/server";

函数语法（始终使用此语法）

export const myFunction = query({
  args: { name: v.string() },
  returns: v.string(),
  handler: async (ctx, args) => {
    return "Hello " + args.name;
  },
});

常见验证器

类型	验证器	示例
字符串	v.string()	"hello"
数字	v.number()	3.14
布尔值	v.boolean()	true
ID	v.id("tableName")	doc._id
数组	v.array(v.string())	["a", "b"]
对象	v.object({...})	{name: "x"}
可选值	v.optional(v.string())	undefined
联合类型	v.union(v.string(), v.number())	"x" 或 1
字面量	v.literal("status")	"status"
空值	v.null()	null

函数引用

// Public functions
import { api } from "./_generated/api";
api.example.myQuery; // convex/example.ts → myQuery

// Internal functions
import { internal } from "./_generated/api";
internal.example.myInternalMutation;

使用索引的查询

// Schema
messages: defineTable({...}).index("by_channel", ["channelId"])

// Query
await ctx.db
  .query("messages")
  .withIndex("by_channel", (q) => q.eq("channelId", channelId))
  .order("desc")
  .take(10);

关键规则

1. 所有函数都必须包含 args 和 returns 验证器
2. 无返回值时使用 v.null()——绝不可省略返回值验证器
3. 使用 withIndex()，而非 filter()——在架构中定义索引
4. 私有函数使用 internalQuery/Mutation/Action
5. 操作无法访问 ctx.db——改用 runQuery/runMutation
6. 在同一文件中调用函数时添加类型注解

完整编译文档

完整指南包含所有规则和详细代码示例，请参阅 AGENTS.md。