convex-functions by waynesutton/convexskills
npx skills add https://github.com/waynesutton/convexskills --skill convex-functions掌握 Convex 函数,包括查询、变更、操作和 HTTP 端点,并具备适当的验证、错误处理和运行时注意事项。
本技能中的所有示例均符合 @convex-dev/eslint-plugin 规则:
handler 属性的对象语法有关代码检查设置的详细信息,请参阅 convex-best-practices 中的代码质量部分。
在实现之前,请勿假设;请获取最新文档:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 类型 | 数据库访问 | 外部 API | 缓存 | 使用场景 |
|---|---|---|---|---|
| 查询 | 只读 | 否 | 是,响应式 | 获取数据 |
| 变更 | 读/写 | 否 | 否 | 修改数据 |
| 操作 | 通过 runQuery/runMutation | 是 | 否 | 外部集成 |
| HTTP 操作 | 通过 runQuery/runMutation | 是 | 否 | Webhooks、API |
查询是响应式、缓存且只读的:
import { query } from "./_generated/server";
import { v } from "convex/values";
export const getUser = query({
args: { userId: v.id("users") },
returns: v.union(
v.object({
_id: v.id("users"),
_creationTime: v.number(),
name: v.string(),
email: v.string(),
}),
v.null(),
),
handler: async (ctx, args) => {
return await ctx.db.get("users", args.userId);
},
});
// 使用索引的查询
export const listUserTasks = query({
args: { userId: v.id("users") },
returns: v.array(
v.object({
_id: v.id("tasks"),
_creationTime: v.number(),
title: v.string(),
completed: v.boolean(),
}),
),
handler: async (ctx, args) => {
return await ctx.db
.query("tasks")
.withIndex("by_user", (q) => q.eq("userId", args.userId))
.order("desc")
.collect();
},
});
变更修改数据库并且是事务性的:
import { mutation } from "./_generated/server";
import { v } from "convex/values";
import { ConvexError } from "convex/values";
export const createTask = mutation({
args: {
title: v.string(),
userId: v.id("users"),
},
returns: v.id("tasks"),
handler: async (ctx, args) => {
// 验证用户存在
const user = await ctx.db.get("users", args.userId);
if (!user) {
throw new ConvexError("User not found");
}
return await ctx.db.insert("tasks", {
title: args.title,
userId: args.userId,
completed: false,
createdAt: Date.now(),
});
},
});
export const deleteTask = mutation({
args: { taskId: v.id("tasks") },
returns: v.null(),
handler: async (ctx, args) => {
await ctx.db.delete("tasks", args.taskId);
return null;
},
});
操作可以调用外部 API,但不能直接访问数据库:
"use node";
import { action } from "./_generated/server";
import { v } from "convex/values";
import { api, internal } from "./_generated/api";
export const sendEmail = action({
args: {
to: v.string(),
subject: v.string(),
body: v.string(),
},
returns: v.object({ success: v.boolean() }),
handler: async (ctx, args) => {
// 调用外部 API
const response = await fetch("https://api.email.com/send", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(args),
});
return { success: response.ok };
},
});
// 调用查询和变更的操作
export const processOrder = action({
args: { orderId: v.id("orders") },
returns: v.null(),
handler: async (ctx, args) => {
// 通过查询读取数据
const order = await ctx.runQuery(api.orders.get, { orderId: args.orderId });
if (!order) {
throw new Error("Order not found");
}
// 调用外部支付 API
const paymentResult = await processPayment(order);
// 通过变更更新数据库
await ctx.runMutation(internal.orders.updateStatus, {
orderId: args.orderId,
status: paymentResult.success ? "paid" : "failed",
});
return null;
},
});
HTTP 操作处理 Webhooks 和外部请求:
// convex/http.ts
import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
import { api, internal } from "./_generated/api";
const http = httpRouter();
// Webhook 端点
http.route({
path: "/webhooks/stripe",
method: "POST",
handler: httpAction(async (ctx, request) => {
const signature = request.headers.get("stripe-signature");
const body = await request.text();
// 验证 webhook 签名
if (!verifyStripeSignature(body, signature)) {
return new Response("Invalid signature", { status: 401 });
}
const event = JSON.parse(body);
// 处理 webhook
await ctx.runMutation(internal.payments.handleWebhook, {
eventType: event.type,
data: event.data,
});
return new Response("OK", { status: 200 });
}),
});
// API 端点
http.route({
path: "/api/users/:userId",
method: "GET",
handler: httpAction(async (ctx, request) => {
const url = new URL(request.url);
const userId = url.pathname.split("/").pop();
const user = await ctx.runQuery(api.users.get, {
userId: userId as Id<"users">,
});
if (!user) {
return new Response("Not found", { status: 404 });
}
return Response.json(user);
}),
});
export default http;
对敏感操作使用内部函数:
import {
internalMutation,
internalQuery,
internalAction,
} from "./_generated/server";
import { v } from "convex/values";
// 仅可从其他 Convex 函数调用
export const _updateUserCredits = internalMutation({
args: {
userId: v.id("users"),
amount: v.number(),
},
returns: v.null(),
handler: async (ctx, args) => {
const user = await ctx.db.get("users", args.userId);
if (!user) return null;
await ctx.db.patch("users", args.userId, {
credits: (user.credits || 0) + args.amount,
});
return null;
},
});
// 从操作中调用内部函数
export const purchaseCredits = action({
args: { userId: v.id("users"), amount: v.number() },
returns: v.null(),
handler: async (ctx, args) => {
// 在外部处理支付
await processPayment(args.amount);
// 通过内部变更更新积分
await ctx.runMutation(internal.users._updateUserCredits, {
userId: args.userId,
amount: args.amount,
});
return null;
},
});
调度函数在稍后运行:
import { mutation, internalMutation } from "./_generated/server";
import { v } from "convex/values";
import { internal } from "./_generated/api";
export const scheduleReminder = mutation({
args: {
userId: v.id("users"),
message: v.string(),
delayMs: v.number(),
},
returns: v.id("_scheduled_functions"),
handler: async (ctx, args) => {
return await ctx.scheduler.runAfter(
args.delayMs,
internal.notifications.sendReminder,
{ userId: args.userId, message: args.message },
);
},
});
export const sendReminder = internalMutation({
args: {
userId: v.id("users"),
message: v.string(),
},
returns: v.null(),
handler: async (ctx, args) => {
await ctx.db.insert("notifications", {
userId: args.userId,
message: args.message,
sentAt: Date.now(),
});
return null;
},
});
// convex/messages.ts
import { query, mutation, internalMutation } from "./_generated/server";
import { v } from "convex/values";
import { ConvexError } from "convex/values";
import { internal } from "./_generated/api";
const messageValidator = v.object({
_id: v.id("messages"),
_creationTime: v.number(),
channelId: v.id("channels"),
authorId: v.id("users"),
content: v.string(),
editedAt: v.optional(v.number()),
});
// 公共查询
export const list = query({
args: {
channelId: v.id("channels"),
limit: v.optional(v.number()),
},
returns: v.array(messageValidator),
handler: async (ctx, args) => {
const limit = args.limit ?? 50;
return await ctx.db
.query("messages")
.withIndex("by_channel", (q) => q.eq("channelId", args.channelId))
.order("desc")
.take(limit);
},
});
// 公共变更
export const send = mutation({
args: {
channelId: v.id("channels"),
authorId: v.id("users"),
content: v.string(),
},
returns: v.id("messages"),
handler: async (ctx, args) => {
if (args.content.trim().length === 0) {
throw new ConvexError("Message cannot be empty");
}
const messageId = await ctx.db.insert("messages", {
channelId: args.channelId,
authorId: args.authorId,
content: args.content.trim(),
});
// 调度通知
await ctx.scheduler.runAfter(0, internal.messages.notifySubscribers, {
channelId: args.channelId,
messageId,
});
return messageId;
},
});
// 内部变更
export const notifySubscribers = internalMutation({
args: {
channelId: v.id("channels"),
messageId: v.id("messages"),
},
returns: v.null(),
handler: async (ctx, args) => {
// 获取频道订阅者并通知他们
const subscribers = await ctx.db
.query("subscriptions")
.withIndex("by_channel", (q) => q.eq("channelId", args.channelId))
.collect();
for (const sub of subscribers) {
await ctx.db.insert("notifications", {
userId: sub.userId,
messageId: args.messageId,
read: false,
});
}
return null;
},
});
npx convex deploy"use node";每周安装量
1.8K
代码仓库
GitHub 星标数
383
首次出现
2026年1月24日
安全审计
安装于
codex1.3K
claude-code1.3K
opencode1.3K
cursor1.2K
github-copilot1.2K
gemini-cli1.1K
Master Convex functions including queries, mutations, actions, and HTTP endpoints with proper validation, error handling, and runtime considerations.
All examples in this skill comply with @convex-dev/eslint-plugin rules:
handler propertySee the Code Quality section in convex-best-practices for linting setup.
Before implementing, do not assume; fetch the latest documentation:
| Type | Database Access | External APIs | Caching | Use Case |
|---|---|---|---|---|
| Query | Read-only | No | Yes, reactive | Fetching data |
| Mutation | Read/Write | No | No | Modifying data |
| Action | Via runQuery/runMutation | Yes | No | External integrations |
| HTTP Action | Via runQuery/runMutation | Yes | No | Webhooks, APIs |
Queries are reactive, cached, and read-only:
import { query } from "./_generated/server";
import { v } from "convex/values";
export const getUser = query({
args: { userId: v.id("users") },
returns: v.union(
v.object({
_id: v.id("users"),
_creationTime: v.number(),
name: v.string(),
email: v.string(),
}),
v.null(),
),
handler: async (ctx, args) => {
return await ctx.db.get("users", args.userId);
},
});
// Query with index
export const listUserTasks = query({
args: { userId: v.id("users") },
returns: v.array(
v.object({
_id: v.id("tasks"),
_creationTime: v.number(),
title: v.string(),
completed: v.boolean(),
}),
),
handler: async (ctx, args) => {
return await ctx.db
.query("tasks")
.withIndex("by_user", (q) => q.eq("userId", args.userId))
.order("desc")
.collect();
},
});
Mutations modify the database and are transactional:
import { mutation } from "./_generated/server";
import { v } from "convex/values";
import { ConvexError } from "convex/values";
export const createTask = mutation({
args: {
title: v.string(),
userId: v.id("users"),
},
returns: v.id("tasks"),
handler: async (ctx, args) => {
// Validate user exists
const user = await ctx.db.get("users", args.userId);
if (!user) {
throw new ConvexError("User not found");
}
return await ctx.db.insert("tasks", {
title: args.title,
userId: args.userId,
completed: false,
createdAt: Date.now(),
});
},
});
export const deleteTask = mutation({
args: { taskId: v.id("tasks") },
returns: v.null(),
handler: async (ctx, args) => {
await ctx.db.delete("tasks", args.taskId);
return null;
},
});
Actions can call external APIs but have no direct database access:
"use node";
import { action } from "./_generated/server";
import { v } from "convex/values";
import { api, internal } from "./_generated/api";
export const sendEmail = action({
args: {
to: v.string(),
subject: v.string(),
body: v.string(),
},
returns: v.object({ success: v.boolean() }),
handler: async (ctx, args) => {
// Call external API
const response = await fetch("https://api.email.com/send", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(args),
});
return { success: response.ok };
},
});
// Action calling queries and mutations
export const processOrder = action({
args: { orderId: v.id("orders") },
returns: v.null(),
handler: async (ctx, args) => {
// Read data via query
const order = await ctx.runQuery(api.orders.get, { orderId: args.orderId });
if (!order) {
throw new Error("Order not found");
}
// Call external payment API
const paymentResult = await processPayment(order);
// Update database via mutation
await ctx.runMutation(internal.orders.updateStatus, {
orderId: args.orderId,
status: paymentResult.success ? "paid" : "failed",
});
return null;
},
});
HTTP actions handle webhooks and external requests:
// convex/http.ts
import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
import { api, internal } from "./_generated/api";
const http = httpRouter();
// Webhook endpoint
http.route({
path: "/webhooks/stripe",
method: "POST",
handler: httpAction(async (ctx, request) => {
const signature = request.headers.get("stripe-signature");
const body = await request.text();
// Verify webhook signature
if (!verifyStripeSignature(body, signature)) {
return new Response("Invalid signature", { status: 401 });
}
const event = JSON.parse(body);
// Process webhook
await ctx.runMutation(internal.payments.handleWebhook, {
eventType: event.type,
data: event.data,
});
return new Response("OK", { status: 200 });
}),
});
// API endpoint
http.route({
path: "/api/users/:userId",
method: "GET",
handler: httpAction(async (ctx, request) => {
const url = new URL(request.url);
const userId = url.pathname.split("/").pop();
const user = await ctx.runQuery(api.users.get, {
userId: userId as Id<"users">,
});
if (!user) {
return new Response("Not found", { status: 404 });
}
return Response.json(user);
}),
});
export default http;
Use internal functions for sensitive operations:
import {
internalMutation,
internalQuery,
internalAction,
} from "./_generated/server";
import { v } from "convex/values";
// Only callable from other Convex functions
export const _updateUserCredits = internalMutation({
args: {
userId: v.id("users"),
amount: v.number(),
},
returns: v.null(),
handler: async (ctx, args) => {
const user = await ctx.db.get("users", args.userId);
if (!user) return null;
await ctx.db.patch("users", args.userId, {
credits: (user.credits || 0) + args.amount,
});
return null;
},
});
// Call internal function from action
export const purchaseCredits = action({
args: { userId: v.id("users"), amount: v.number() },
returns: v.null(),
handler: async (ctx, args) => {
// Process payment externally
await processPayment(args.amount);
// Update credits via internal mutation
await ctx.runMutation(internal.users._updateUserCredits, {
userId: args.userId,
amount: args.amount,
});
return null;
},
});
Schedule functions to run later:
import { mutation, internalMutation } from "./_generated/server";
import { v } from "convex/values";
import { internal } from "./_generated/api";
export const scheduleReminder = mutation({
args: {
userId: v.id("users"),
message: v.string(),
delayMs: v.number(),
},
returns: v.id("_scheduled_functions"),
handler: async (ctx, args) => {
return await ctx.scheduler.runAfter(
args.delayMs,
internal.notifications.sendReminder,
{ userId: args.userId, message: args.message },
);
},
});
export const sendReminder = internalMutation({
args: {
userId: v.id("users"),
message: v.string(),
},
returns: v.null(),
handler: async (ctx, args) => {
await ctx.db.insert("notifications", {
userId: args.userId,
message: args.message,
sentAt: Date.now(),
});
return null;
},
});
// convex/messages.ts
import { query, mutation, internalMutation } from "./_generated/server";
import { v } from "convex/values";
import { ConvexError } from "convex/values";
import { internal } from "./_generated/api";
const messageValidator = v.object({
_id: v.id("messages"),
_creationTime: v.number(),
channelId: v.id("channels"),
authorId: v.id("users"),
content: v.string(),
editedAt: v.optional(v.number()),
});
// Public query
export const list = query({
args: {
channelId: v.id("channels"),
limit: v.optional(v.number()),
},
returns: v.array(messageValidator),
handler: async (ctx, args) => {
const limit = args.limit ?? 50;
return await ctx.db
.query("messages")
.withIndex("by_channel", (q) => q.eq("channelId", args.channelId))
.order("desc")
.take(limit);
},
});
// Public mutation
export const send = mutation({
args: {
channelId: v.id("channels"),
authorId: v.id("users"),
content: v.string(),
},
returns: v.id("messages"),
handler: async (ctx, args) => {
if (args.content.trim().length === 0) {
throw new ConvexError("Message cannot be empty");
}
const messageId = await ctx.db.insert("messages", {
channelId: args.channelId,
authorId: args.authorId,
content: args.content.trim(),
});
// Schedule notification
await ctx.scheduler.runAfter(0, internal.messages.notifySubscribers, {
channelId: args.channelId,
messageId,
});
return messageId;
},
});
// Internal mutation
export const notifySubscribers = internalMutation({
args: {
channelId: v.id("channels"),
messageId: v.id("messages"),
},
returns: v.null(),
handler: async (ctx, args) => {
// Get channel subscribers and notify them
const subscribers = await ctx.db
.query("subscriptions")
.withIndex("by_channel", (q) => q.eq("channelId", args.channelId))
.collect();
for (const sub of subscribers) {
await ctx.db.insert("notifications", {
userId: sub.userId,
messageId: args.messageId,
read: false,
});
}
return null;
},
});
npx convex deploy unless explicitly instructed"use node"; at the top of action files using Node.js APIsWeekly Installs
1.8K
Repository
GitHub Stars
383
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
codex1.3K
claude-code1.3K
opencode1.3K
cursor1.2K
github-copilot1.2K
gemini-cli1.1K
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
102,200 周安装