convex-backend

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Convex Backend Guidelines

Convex后端开发指南

Comprehensive guide for building Convex backends with TypeScript. Covers function syntax, validators, schemas, queries, mutations, actions, scheduling, and file storage.

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

When to Apply

适用场景

Reference these guidelines when:

Writing new Convex functions (queries, mutations, actions)
Defining database schemas and validators
Implementing real-time data fetching
Setting up cron jobs or scheduled functions
Working with file storage
Designing API structure

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

编写新的Convex函数（查询、变更、操作）
定义数据库模式和验证器
实现实时数据获取
设置定时任务或调度函数
处理文件存储
设计API结构

Rule Categories

规则分类

Category	Impact	Description
Function Syntax	CRITICAL	New function syntax with args/returns/handler
Validators	CRITICAL	Type-safe argument and return validation
Schema Design	HIGH	Table definitions, indexes, system fields
Query Patterns	HIGH	Efficient data fetching with indexes
Mutation Patterns	MEDIUM	Database writes, patch vs replace
Action Patterns	MEDIUM	External API calls, Node.js runtime
Scheduling	MEDIUM	Crons and delayed function execution
File Storage	LOW	Blob storage and metadata

分类	影响级别	描述
函数语法	关键	包含参数/返回值/处理器的新函数语法
验证器	关键	类型安全的参数和返回值验证
模式设计	高	表定义、索引、系统字段
查询模式	高	使用索引的高效数据获取
变更模式	中	数据库写入、部分更新vs全量替换
操作模式	中	外部API调用、Node.js运行时
任务调度	中	定时任务和延迟函数执行
文件存储	低	Blob存储和元数据

Quick Reference

快速参考

Function Registration

函数注册

typescript

// 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";

typescript

// 公开函数（对客户端暴露）
import { query, mutation, action } from "./_generated/server";

// 内部函数（仅可从其他Convex函数调用）
import {
  internalQuery,
  internalMutation,
  internalAction,
} from "./_generated/server";

Function Syntax (Always Use This)

函数语法（请始终使用此格式）

typescript

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

typescript

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

Common Validators

常用验证器

Type	Validator	Example
String	`v.string()`	`"hello"`
Number	`v.number()`	`3.14`
Boolean	`v.boolean()`	`true`
ID	`v.id("tableName")`	`doc._id`
Array	`v.array(v.string())`	`["a", "b"]`
Object	`v.object({...})`	`{name: "x"}`
Optional	`v.optional(v.string())`	`undefined`
Union	`v.union(v.string(), v.number())`	`"x"` or `1`
Literal	`v.literal("status")`	`"status"`
Null	`v.null()`	`null`

类型	验证器	示例
字符串	`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"` or `1`
字面量	`v.literal("status")`	`"status"`
空值	`v.null()`	`null`

Function References

函数引用

typescript

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

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

typescript

// 公开函数
import { api } from "./_generated/api";
api.example.myQuery; // convex/example.ts → myQuery

// 内部函数
import { internal } from "./_generated/api";
internal.example.myInternalMutation;

Query with Index

使用索引的查询

typescript

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

typescript

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

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

Key Rules

核心规则

Always include
args
and
returns
validators on all functions
Use
v.null()
for void returns - never omit return validator
Use
withIndex()
not
filter()
- define indexes in schema
Use
internalQuery/Mutation/Action
for private functions
Actions cannot access
ctx.db
- use runQuery/runMutation instead
Include type annotations when calling functions in same file

所有函数必须包含
args
和
returns
验证器
使用
v.null()
表示无返回值 - 绝不要省略返回值验证器
使用
withIndex()
而非
filter()
- 在模式中定义索引
使用
internalQuery/Mutation/Action
处理私有函数
操作函数无法直接访问
ctx.db
- 请改用runQuery/runMutation
在同一文件中调用函数时添加类型注解

Full Compiled Document

完整文档

For the complete guide with all rules and detailed code examples, see:

AGENTS.md

如需包含所有规则和详细代码示例的完整指南，请查看：

AGENTS.md