convex-backend by cloudai-x/claude-workflow-v2
npx skills add https://github.com/cloudai-x/claude-workflow-v2 --skill convex-backend使用 TypeScript 构建 Convex 后端的综合指南。涵盖函数语法、验证器、模式、查询、变更、操作、调度和文件存储。
在以下情况下参考本指南:
| 类别 | 影响程度 | 描述 |
|---|---|---|
| 函数语法 | 关键 | 带有参数/返回/处理程序的新函数语法 |
| 验证器 | 关键 | 类型安全的参数和返回验证 |
| 模式设计 | 高 | 表定义、索引、系统字段 |
| 查询模式 | 高 | 使用索引进行高效数据获取 |
| 变更模式 |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 中 |
| 数据库写入,修补与替换 |
| 操作模式 | 中 | 外部 API 调用,Node.js 运行时 |
| 调度 | 中 | 定时任务和延迟函数执行 |
| 文件存储 | 低 | 二进制大对象存储和元数据 |
// 公共函数(暴露给客户端)
import { query, mutation, action } from "./_generated/server";
// 内部函数(仅可从其他 Convex 函数调用)
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 |
// 公共函数
import { api } from "./_generated/api";
api.example.myQuery; // convex/example.ts → myQuery
// 内部函数
import { internal } from "./_generated/api";
internal.example.myInternalMutation;
// 模式
messages: defineTable({...}).index("by_channel", ["channelId"])
// 查询
await ctx.db
.query("messages")
.withIndex("by_channel", (q) => q.eq("channelId", channelId))
.order("desc")
.take(10);
args 和 returns 验证器v.null() 表示无返回值 - 切勿省略返回验证器withIndex() 而非 filter() - 在模式中定义索引internalQuery/Mutation/Actionctx.db - 请改用 runQuery/runMutation有关所有规则和详细代码示例的完整指南,请参阅:AGENTS.md
每周安装量
96
代码仓库
GitHub 星标数
1.3K
首次出现
2026年1月21日
安全审计
安装于
claude-code76
opencode73
codex69
gemini-cli68
cursor65
github-copilot61
Comprehensive guide for building Convex backends with TypeScript. Covers function syntax, validators, schemas, queries, mutations, actions, scheduling, and file storage.
Reference these guidelines when:
| 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 |
// 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;
},
});
| Type | Validator | Example |
|---|---|---|
| String | v.string() | "hello" |
| Number | v.number() | 3.14 |
| Boolean | v.boolean() | true |
| ID | v.id("tableName") |
// 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);
args and returns validators on all functionsv.null() for void returns - never omit return validatorwithIndex() not filter() - define indexes in schemainternalQuery/Mutation/Action for private functionsctx.db - use runQuery/runMutation insteadFor the complete guide with all rules and detailed code examples, see: AGENTS.md
Weekly Installs
96
Repository
GitHub Stars
1.3K
First Seen
Jan 21, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
claude-code76
opencode73
codex69
gemini-cli68
cursor65
github-copilot61
Supabase Postgres 最佳实践指南 - 8大类别性能优化规则与SQL示例
78,800 周安装
通过Rube MCP实现Make自动化:集成Composio工具包管理场景与操作
72 周安装
Microsoft Teams自动化指南:通过Rube MCP实现频道消息、聊天与会议管理
72 周安装
Electrobun 最佳实践:TypeScript + Bun 跨平台桌面应用开发指南
72 周安装
ATXP Memory:AI代理记忆管理工具 - 云端备份与本地向量搜索
72 周安装
Brave Search Spellcheck API:智能拼写检查与查询纠正,提升搜索准确性
72 周安装
Amazon竞品分析器 - 自动化抓取ASIN数据,深度分析竞争对手定价、规格与评论
72 周安装
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 |