使用 Convex 构建响应式 TypeScript 全栈后端

解决传统后端开发中 API 编写冗余、状态同步复杂的问题：通过 Convex 的响应式架构，让前端通过 TypeScript 函数直接查询数据并自动接收实时更新，无需手动配置 WebSocket 或轮询。

为什么需要这个技能

在传统的 Web 开发中，实现“实时更新”需要处理复杂的 WebSocket 逻辑或频繁的 API 轮询，且前后端类型同步（Type Safety）往往依赖于手动维护的接口文档或繁琐的生成工具。

Convex 提供了一种“文档-关系型”数据库方案，其核心特点是原生响应式：当数据库数据变化时，所有依赖该数据的查询会自动重新运行并推送更新到客户端。同时，所有后端逻辑均由 TypeScript 编写，实现了从数据库 Schema 到前端 Hook 的端到端类型安全，极大地提升了开发效率。

适用场景

• 实时协作应用：如聊天室、实时看板、多人协作文档。
• 快速原型开发：需要快速搭建具备用户认证、文件存储和定时任务的后端。
• 强类型全栈项目：希望在 Next.js、React Native 等框架中获得极致的类型检查体验。
• AI 集成应用：利用 Convex Action 调用 LLM API 并将结果持久化到数据库。

核心工作流

1. 环境初始化

安装依赖并启动开发环境，npx convex dev 会自动处理项目创建、部署同步及环境变量配置。

npm install convex
npx convex dev

2. 定义 Schema

在 convex/schema.ts 中定义数据模型。Convex 通过验证器（Validator）确保运行时的类型正确。

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  tasks: defineTable({
    text: v.string(),
    isCompleted: v.boolean(),
    userId: v.id("users"),
  }).index("by_user", ["userId"]),
});

3. 编写三种核心函数

根据需求选择不同的函数类型，确保逻辑隔离：

• Query (查询)：只读，天然响应式。用于获取数据并推送给前端。
• Mutation (变更)：读写，支持 ACID 事务。用于修改数据库状态。
• Action (动作)：允许调用外部 API（如 OpenAI, Stripe），不能直接读写数据库，需通过 ctx.runQuery 或 ctx.runMutation 操作。

4. 前端集成

在 React/Next.js 中使用 useQuery 和 useMutation Hook 绑定后端函数。

const tasks = useQuery(api.tasks.list);
const addTask = useMutation(api.tasks.create);

下载和安装

下载 convex 中文版 Skill ZIP

解压后将目录放入你的 AI 工具 skills 文件夹，重启工具后即可使用。具体路径参考内附的 USAGE.zh.md。

你可能还需要

暂无推荐