Convex 函数创建器 - 生成安全类型安全的查询、变更和操作函数

function-creator by get-convex/agent-skills

550 周安装量

15 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/get-convex/agent-skills --skill function-creator

函数式编程开发云服务

🇨🇳中文介绍

Convex 函数创建器

遵循所有最佳实践，生成安全、类型安全的 Convex 函数。

使用场景

创建新的查询函数（读取数据）
创建新的变更函数（写入数据）
创建新的操作函数（外部 API、长时间运行）
向你的 Convex 后端添加 API 端点

函数类型

查询（只读）

只能从数据库读取
不能修改数据或调用外部 API
具有缓存和响应式特性
在事务中运行

import { query } from "./_generated/server";
import { v } from "convex/values";

export const getTask = query({
  args: { taskId: v.id("tasks") },
  returns: v.union(v.object({
    _id: v.id("tasks"),
    text: v.string(),
    completed: v.boolean(),
  }), v.null()),
  handler: async (ctx, args) => {
    return await ctx.db.get(args.taskId);
  },
});

变更（事务性写入）

可以读取和写入数据库
不能调用外部 API
在 ACID 事务中运行
冲突时自动重试

import { mutation } from "./_generated/server";
import { v } from "convex/values";

export const createTask = mutation({
  args: {
    text: v.string(),
    priority: v.optional(v.union(
      v.literal("low"),
      v.literal("medium"),
      v.literal("high")
    )),
  },
  returns: v.id("tasks"),
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    return await ctx.db.insert("tasks", {
      text: args.text,
      priority: args.priority ?? "medium",
      completed: false,
      createdAt: Date.now(),
    });
  },
});

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

操作（外部 + 非事务性）

可以调用外部 API（fetch、AI 等）
可以通过 ctx.runMutation 调用变更
不能直接访问数据库
没有自动重试
当需要 Node.js API 时，使用 "use node" 指令

重要提示： 如果你的操作需要 Node.js 特定的 API（crypto、第三方 SDK 等），请在文件顶部添加 "use node"。包含 "use node" 的文件只能包含操作，不能包含查询或变更。

"use node"; // 对于像 OpenAI SDK 这样的 Node.js API 是必需的

import { action } from "./_generated/server";
import { api } from "./_generated/api";
import { v } from "convex/values";
import OpenAI from "openai";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

export const generateTaskSuggestion = action({
  args: { prompt: v.string() },
  returns: v.string(),
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    // 调用 OpenAI（需要 "use node"）
    const completion = await openai.chat.completions.create({
      model: "gpt-4",
      messages: [{ role: "user", content: args.prompt }],
    });

    const suggestion = completion.choices[0].message.content;

    // 通过变更写入数据库
    await ctx.runMutation(api.tasks.createTask, {
      text: suggestion,
    });

    return suggestion;
  },
});

注意： 如果你只需要基本的 fetch（不需要 Node.js API），可以省略 "use node"。但对于第三方 SDK、crypto 或其他 Node.js 功能，必须使用它。

始终使用验证器定义 args：

args: {
  id: v.id("tasks"),
  text: v.string(),
  count: v.number(),
  enabled: v.boolean(),
  tags: v.array(v.string()),
  metadata: v.optional(v.object({
    key: v.string(),
  })),
}

2. 返回类型验证

始终定义 returns：

returns: v.object({
  _id: v.id("tasks"),
  text: v.string(),
})

// 或者对于数组
returns: v.array(v.object({ /* ... */ }))

// 或者对于可空值
returns: v.union(v.object({ /* ... */ }), v.null())

3. 身份验证检查

始终在公开函数中验证身份：

const identity = await ctx.auth.getUserIdentity();
if (!identity) {
  throw new Error("Not authenticated");
}

始终验证所有权/权限：

const task = await ctx.db.get(args.taskId);
if (!task) {
  throw new Error("Task not found");
}

if (task.userId !== user._id) {
  throw new Error("Unauthorized");
}

带身份验证的安全查询

export const getMyTasks = query({
  args: {
    status: v.optional(v.union(
      v.literal("active"),
      v.literal("completed")
    )),
  },
  returns: v.array(v.object({
    _id: v.id("tasks"),
    text: v.string(),
    completed: v.boolean(),
  })),
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    const user = await ctx.db
      .query("users")
      .withIndex("by_token", q =>
        q.eq("tokenIdentifier", identity.tokenIdentifier)
      )
      .unique();

    if (!user) throw new Error("User not found");

    let query = ctx.db
      .query("tasks")
      .withIndex("by_user", q => q.eq("userId", user._id));

    const tasks = await query.collect();

    if (args.status) {
      return tasks.filter(t =>
        args.status === "completed" ? t.completed : !t.completed
      );
    }

    return tasks;
  },
});

带验证的安全变更

export const updateTask = mutation({
  args: {
    taskId: v.id("tasks"),
    text: v.optional(v.string()),
    completed: v.optional(v.boolean()),
  },
  returns: v.id("tasks"),
  handler: async (ctx, args) => {
    // 1. 身份验证
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    // 2. 获取用户
    const user = await ctx.db
      .query("users")
      .withIndex("by_token", q =>
        q.eq("tokenIdentifier", identity.tokenIdentifier)
      )
      .unique();

    if (!user) throw new Error("User not found");

    // 3. 获取资源
    const task = await ctx.db.get(args.taskId);
    if (!task) throw new Error("Task not found");

    // 4. 授权
    if (task.userId !== user._id) {
      throw new Error("Unauthorized");
    }

    // 5. 更新
    const updates: Partial<any> = {};
    if (args.text !== undefined) updates.text = args.text;
    if (args.completed !== undefined) updates.completed = args.completed;

    await ctx.db.patch(args.taskId, updates);
    return args.taskId;
  },
});

调用外部 API 的操作

为需要 Node.js 的操作创建单独的文件：

// convex/taskActions.ts
"use node"; // SendGrid SDK 必需

import { action } from "./_generated/server";
import { api } from "./_generated/api";
import { v } from "convex/values";
import sendgrid from "@sendgrid/mail";

sendgrid.setApiKey(process.env.SENDGRID_API_KEY);

export const sendTaskReminder = action({
  args: { taskId: v.id("tasks") },
  returns: v.boolean(),
  handler: async (ctx, args) => {
    // 1. 身份验证
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    // 2. 通过查询获取数据
    const task = await ctx.runQuery(api.tasks.getTask, {
      taskId: args.taskId,
    });

    if (!task) throw new Error("Task not found");

    // 3. 调用外部服务（使用 Node.js SDK）
    await sendgrid.send({
      to: identity.email,
      from: "noreply@example.com",
      subject: "Task Reminder",
      text: `Don't forget: ${task.text}`,
    });

    // 4. 通过变更更新
    await ctx.runMutation(api.tasks.markReminderSent, {
      taskId: args.taskId,
    });

    return true;
  },
});

注意： 将查询和变更保留在 convex/tasks.ts 中（不带 "use node"），将需要 Node.js 的操作保留在 convex/taskActions.ts 中（带 "use node"）。

对于仅限后端使用的函数（由调度器、其他函数调用）：

import { internalMutation } from "./_generated/server";

export const processExpiredTasks = internalMutation({
  args: {},
  handler: async (ctx) => {
    // 无需身份验证 - 仅可从后端调用
    const now = Date.now();
    const expired = await ctx.db
      .query("tasks")
      .withIndex("by_due_date", q => q.lt("dueDate", now))
      .collect();

    for (const task of expired) {
      await ctx.db.patch(task._id, { status: "expired" });
    }
  },
});

args 已使用验证器定义
returns 已使用验证器定义
身份验证检查（ctx.auth.getUserIdentity()）
授权检查（所有权/权限）
所有 Promise 都已 await
索引查询（不在查询上使用 .filter()）
具有描述性消息的错误处理
计划函数使用 internal.* 而不是 api.*
如果使用 Node.js API：在文件顶部添加 "use node"
如果文件包含 "use node"：仅包含操作（无查询/变更）
使用 "use node" 时，操作与查询/变更分开放在单独的文件中

🇺🇸English

Convex Function Creator

Generate secure, type-safe Convex functions following all best practices.

When to Use

Creating new query functions (read data)
Creating new mutation functions (write data)
Creating new action functions (external APIs, long-running)
Adding API endpoints to your Convex backend

Function Types

Queries (Read-Only)

Can only read from database
Cannot modify data or call external APIs
Cached and reactive
Run in transactions

import { query } from "./_generated/server"; import { v } from "convex/values";

export const getTask = query({ args: { taskId: v.id("tasks") }, returns: v.union(v.object({ _id: v.id("tasks"), text: v.string(), completed: v.boolean(), }), v.null()), handler: async (ctx, args) => { return await ctx.db.get(args.taskId); }, });

Mutations (Transactional Writes)

Can read and write to database
Cannot call external APIs
Run in ACID transactions
Automatic retries on conflicts

import { mutation } from "./_generated/server"; import { v } from "convex/values";

export const createTask = mutation({ args: { text: v.string(), priority: v.optional(v.union( v.literal("low"), v.literal("medium"), v.literal("high") )), }, returns: v.id("tasks"), handler: async (ctx, args) => { const identity = await ctx.auth.getUserIdentity(); if (!identity) throw new Error("Not authenticated");
```
return await ctx.db.insert("tasks", {
  text: args.text,
  priority: args.priority ?? "medium",
  completed: false,
  createdAt: Date.now(),
});
```
}, });

Actions (External + Non-Transactional)

Can call external APIs (fetch, AI, etc.)
Can call mutations via ctx.runMutation
Cannot directly access database
No automatic retries
Use"use node" directive when needing Node.js APIs

Important: If your action needs Node.js-specific APIs (crypto, third-party SDKs, etc.), add "use node" at the top of the file. Files with "use node" can ONLY contain actions, not queries or mutations.

"use node"; // Required for Node.js APIs like OpenAI SDK

import { action } from "./_generated/server";
import { api } from "./_generated/api";
import { v } from "convex/values";
import OpenAI from "openai";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

export const generateTaskSuggestion = action({
  args: { prompt: v.string() },
  returns: v.string(),
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    // Call OpenAI (requires "use node")
    const completion = await openai.chat.completions.create({
      model: "gpt-4",
      messages: [{ role: "user", content: args.prompt }],
    });

    const suggestion = completion.choices[0].message.content;

    // Write to database via mutation
    await ctx.runMutation(api.tasks.createTask, {
      text: suggestion,
    });

    return suggestion;
  },
});

Note: If you only need basic fetch (no Node.js APIs), you can omit "use node". But for third-party SDKs, crypto, or other Node.js features, you must use it.

Required Components

1. Argument Validation

Always define args with validators:

args: {
  id: v.id("tasks"),
  text: v.string(),
  count: v.number(),
  enabled: v.boolean(),
  tags: v.array(v.string()),
  metadata: v.optional(v.object({
    key: v.string(),
  })),
}

2. Return Type Validation

Always define returns:

returns: v.object({
  _id: v.id("tasks"),
  text: v.string(),
})

// Or for arrays
returns: v.array(v.object({ /* ... */ }))

// Or for nullable
returns: v.union(v.object({ /* ... */ }), v.null())

3. Authentication Check

Always verify auth in public functions:

const identity = await ctx.auth.getUserIdentity();
if (!identity) {
  throw new Error("Not authenticated");
}

4. Authorization Check

Always verify ownership/permissions:

const task = await ctx.db.get(args.taskId);
if (!task) {
  throw new Error("Task not found");
}

if (task.userId !== user._id) {
  throw new Error("Unauthorized");
}

Complete Examples

Secure Query with Auth

export const getMyTasks = query({
  args: {
    status: v.optional(v.union(
      v.literal("active"),
      v.literal("completed")
    )),
  },
  returns: v.array(v.object({
    _id: v.id("tasks"),
    text: v.string(),
    completed: v.boolean(),
  })),
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    const user = await ctx.db
      .query("users")
      .withIndex("by_token", q =>
        q.eq("tokenIdentifier", identity.tokenIdentifier)
      )
      .unique();

    if (!user) throw new Error("User not found");

    let query = ctx.db
      .query("tasks")
      .withIndex("by_user", q => q.eq("userId", user._id));

    const tasks = await query.collect();

    if (args.status) {
      return tasks.filter(t =>
        args.status === "completed" ? t.completed : !t.completed
      );
    }

    return tasks;
  },
});

Secure Mutation with Validation

export const updateTask = mutation({
  args: {
    taskId: v.id("tasks"),
    text: v.optional(v.string()),
    completed: v.optional(v.boolean()),
  },
  returns: v.id("tasks"),
  handler: async (ctx, args) => {
    // 1. Authentication
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    // 2. Get user
    const user = await ctx.db
      .query("users")
      .withIndex("by_token", q =>
        q.eq("tokenIdentifier", identity.tokenIdentifier)
      )
      .unique();

    if (!user) throw new Error("User not found");

    // 3. Get resource
    const task = await ctx.db.get(args.taskId);
    if (!task) throw new Error("Task not found");

    // 4. Authorization
    if (task.userId !== user._id) {
      throw new Error("Unauthorized");
    }

    // 5. Update
    const updates: Partial<any> = {};
    if (args.text !== undefined) updates.text = args.text;
    if (args.completed !== undefined) updates.completed = args.completed;

    await ctx.db.patch(args.taskId, updates);
    return args.taskId;
  },
});

Action Calling External API

Create separate file for actions that need Node.js:

// convex/taskActions.ts
"use node"; // Required for SendGrid SDK

import { action } from "./_generated/server";
import { api } from "./_generated/api";
import { v } from "convex/values";
import sendgrid from "@sendgrid/mail";

sendgrid.setApiKey(process.env.SENDGRID_API_KEY);

export const sendTaskReminder = action({
  args: { taskId: v.id("tasks") },
  returns: v.boolean(),
  handler: async (ctx, args) => {
    // 1. Auth
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    // 2. Get data via query
    const task = await ctx.runQuery(api.tasks.getTask, {
      taskId: args.taskId,
    });

    if (!task) throw new Error("Task not found");

    // 3. Call external service (using Node.js SDK)
    await sendgrid.send({
      to: identity.email,
      from: "noreply@example.com",
      subject: "Task Reminder",
      text: `Don't forget: ${task.text}`,
    });

    // 4. Update via mutation
    await ctx.runMutation(api.tasks.markReminderSent, {
      taskId: args.taskId,
    });

    return true;
  },
});

Note: Keep queries and mutations in convex/tasks.ts (without "use node"), and actions that need Node.js in convex/taskActions.ts (with "use node").

Internal Functions

For backend-only functions (called by scheduler, other functions):

import { internalMutation } from "./_generated/server";

export const processExpiredTasks = internalMutation({
  args: {},
  handler: async (ctx) => {
    // No auth needed - only callable from backend
    const now = Date.now();
    const expired = await ctx.db
      .query("tasks")
      .withIndex("by_due_date", q => q.lt("dueDate", now))
      .collect();

    for (const task of expired) {
      await ctx.db.patch(task._id, { status: "expired" });
    }
  },
});

Checklist

args defined with validators
returns defined with validator
Authentication check (ctx.auth.getUserIdentity())
Authorization check (ownership/permissions)
All promises awaited
Indexed queries (no .filter() on queries)
Error handling with descriptive messages
Scheduled functions use internal.* not api.*
If using Node.js APIs: "use node" at top of file
If file has "use node": Only actions (no queries/mutations)
Actions in separate file from queries/mutations when using "use node"

Weekly Installs

550

Repository

get-convex/agent-skills

GitHub Stars

First Seen

Feb 18, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

github-copilot545

opencode544

codex544

amp544

kimi-cli544

gemini-cli544

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

103,800 周安装