数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载导读Convex 是一个为应用开发者设计的开源响应式数据库与后端平台函数Functions是它的核心编程模型开发者用 TypeScript 编写查询Query、修改Mutation与动作Action即可获得自动的类型安全、参数校验、实时订阅与数据库读写能力。本文以本仓库中npm-packages/private-demos/components-legacy/convex/README.md的函数模板文档为骨架结合仓库内真实的函数实现、_generated生成代码与convexnpm 包源码系统讲解 Convex 函数从定义、校验到前端调用的完整链路并演示其在组件化 demo 中的实际用法帮助读者直接照搬到自己的 Convex 项目中。Convex 函数全景Query、Mutation 与 ActionConvex 的服务器端代码全部集中在项目的convex/目录下。每个被导出的函数会自动成为部署 API 的一部分前端通过api对象按模块.函数名的路径引用它。函数按能力分为三类函数类型能否读库能否写库能否执行任意 JavaScript含副作用典型用途query✅❌仅确定性代码读取并派生数据供客户端实时订阅mutation✅✅仅确定性代码写入数据库业务状态变更action间接通过runQuery/runMutation间接✅调用第三方 API、执行不确定/有副作用逻辑从 convex/_generated/server.js 的生成代码可以看出这三类函数在公共 API 之外还有仅供服务端互相调用的内部版本internalQuery、internalMutation、internalAction以及用于响应 HTTP 请求的httpAction。该文件是npx convex dev自动生成的文件头明确提示THIS CODE IS AUTOMATICALLY GENERATED开发者不应手工修改它。编写第一个 Query 函数关联文档给出的 query 模板是函数开发的最小骨架// convex/myFunctions.ts import { query } from ./_generated/server; import { v } from convex/values; export const myQueryFunction query({ // Validators for arguments. args: { first: v.number(), second: v.string(), }, // Function implementation. handler: async (ctx, args) { // Read the database as many times as you need here. const documents await ctx.db.query(tablename).collect(); // Arguments passed from the client are properties of the args object. console.log(args.first, args.second); // Write arbitrary JavaScript here: filter, aggregate, build derived data, // remove non-public properties, or create new objects. return documents; }, });这个模板包含三个要点query({...})是工厂函数它接收一个配置对象配置对象必须包含args参数校验器和handler函数实现体两个字段。query与mutation、action一样都从./_generated/server导入——这是类型安全的入口它把泛型实现queryGeneric/mutationGeneric/actionGeneric与当前部署的 schema 类型绑定在一起。args声明参数契约v.number()、v.string()来自convex/values。Convex 会在每次调用时对传入参数做运行时校验非法参数直接拒绝执行同时校验器也承担 TypeScript 类型推导的职责让handler里的args.first具备精确类型。ctx.db是数据库访问句柄ctx.db.query(tablename)按表名查询.collect()把结果集物化为数组。Query 函数体内可以多次读取数据库也可以做任意确定性变换过滤、聚合、构造派生数据、剔除非公开字段、创建新对象最终返回值会通过响应式订阅通道推送给客户端。响应式Query 的本质是订阅query 与普通 HTTP 接口最大的区别在于响应式。前端通过useQuery订阅某个 query 后只要 query 依赖的表发生变化Convex 后端会重新执行该函数并把最新结果推送到客户端——开发者无需手写缓存失效或轮询。这种机制在本仓库有完整的 Rust 后端支撑例如crates/database/src/subscription.rs与crates/database/src/query目录下即包含订阅追踪与查询执行相关实现。在真实 demo 中读取数据本仓库的组件化 demo 在 convex/messages.ts 中给出了一个带返回类型标注的 query 实例import { Doc } from ./_generated/dataModel; export const list query({ args: {}, handler: async (ctx): PromiseDocmessages[] { const result await ctx.runQuery(waitlist.index.sayGoodbyeFromQuery, {}); console.log(result); return await ctx.db.query(messages).collect(); }, });这里展示了两个进阶能力通过PromiseDocmessages[]显式声明返回类型Docmessages由_generated/dataModel根据 schema 自动生成以及通过ctx.runQuery在函数内部调用另一个组件暴露的 query——实现函数间跨组件的服务端调用。Validator参数校验与类型推导的底层原理关联文档把args里的v.number()、v.string()注释为 Validators for arguments。这套 validator 体系并不只是 TypeScript 层的玩具它在运行时真正生效其实现位于 npm 包源码 convex/src/values/validators.ts 与 convex/src/values/validator.ts。从源码结构看所有校验器都继承自BaseValidator抽象类该类维护了三个关键成员type仅供 TypeScript 使用的类型占位用于把校验器映射为对应的 TS 类型isOptional标记该字段是否可选required或optionalisConvexValidator恒为true的运行时标记用于区分校验器对象与普通对象。isValidator()函数正是通过检查v?.isConvexValidator true来判断一个值是否为合法校验器见 validator.ts。asObjectValidator()则允许把一个属性到校验器的映射自动包成v.object(...)。demo 的 schema 展示了 validator 在表结构定义中的另一种用法// convex/schema.ts import { defineSchema, defineTable } from convex/server; import { v } from convex/values; export default defineSchema({ messages: defineTable({ author: v.string(), body: v.string(), }), notes: defineTable({ text: v.string(), }), });defineSchema/defineTable来自convex/server这里v.string()定义的是列的字段类型。值得注意的是源码中throwUndefinedValidatorError会专门提示 A validator is undefined ... often caused by circular imports提醒开发者不要在模块顶层出现循环导入导致 validator 求值失败。编写 Mutation写入与返回结果关联文档给出的 mutation 模板如下// convex/myFunctions.ts import { mutation } from ./_generated/server; import { v } from convex/values; export const myMutationFunction mutation({ // Validators for arguments. args: { first: v.string(), second: v.string(), }, // Function implementation. handler: async (ctx, args) { // Insert or modify documents in the database here. // Mutations can also read from the database like queries. const message { body: args.first, author: args.second }; const id await ctx.db.insert(messages, message); // Optionally, return a value from your mutation. return await ctx.db.get(messages, id); }, });Mutation 的要点ctx.db.insert(table, doc)写入第一个参数是表名第二个是待插入文档返回新文档的Id。mutation 可以同时读写与 query 一样支持ctx.db.query(...)读取且所有操作处于同一个事务中要么全部成功要么全部回滚。返回值可选ctx.db.get(table, id)按 ID 取回文档后返回客户端可拿到Promise化的结果。demo 中的sendmutation 是更精简的等价写法export const send mutation({ args: { body: v.string(), author: v.string(), }, handler: async (ctx, { body, author }) { const message { body, author }; await ctx.db.insert(messages, message); }, });这里用了解构写法({ body, author })直接提取参数写入后不返回值前端默认fire and forget。同一文件中的scheduleSendWaitlistMessage还展示了 mutation 中调用ctx.scheduler.runAfter(30 * 1000, waitlist.index.scheduleMessage, {})定时调度另一个函数的能力以及通过ctx.db.system.query(_scheduled_functions)读取系统表验证调度结果。事务回滚的一个真实测试场景demo 的testPartialRollbackmutation 专门演示了跨组件调用时的部分回滚语义await ctx.runMutation(waitlist.index.writeSuccessfully, { text: hello }); try { await ctx.runMutation(waitlist.index.writeThenFail, { text: world }); } catch (e) { console.log(caught error, e); } const result await ctx.runQuery(waitlist.index.latestWrite, {});它先让组件成功写入一次再故意触发一次会失败的写入捕获错误后查询最新写入内容——验证失败的 mutation 是否已回滚、成功的那次是否保留这正是 mutation 事务性在组件嵌套场景下的行为测试。React 集成useQuery 与 useMutation关联文档给出了函数在 React 组件中的两种调用方式。用 useQuery 订阅数据const data useQuery(api.myFunctions.myQueryFunction, { first: 10, second: hello, });useQuery的第一个参数是函数引用api.myFunctions.myQueryFunction第二个参数是与该函数args完全匹配的参数对象返回值data的类型由函数返回类型推导而来由于 query 是响应式的data会随数据库变化自动更新组件无需关心请求时机。useQuery的真实实现在 convex/src/react/client.ts约 L922 处它要求传入的参数必须是FunctionReferencequery类型——这正是api对象anyApi见 convex/_generated/api.js提供的类型安全引用。同类 hook 还包括useQueries批量订阅多个 query、usePaginatedQuery分页查询、useMutation、useAction与useConvex等均在convex/src/react目录下。用 useMutation 触发写入const mutation useMutation(api.myFunctions.myMutationFunction); function handleButtonPress() { // fire and forget, the most common way to use mutations mutation({ first: Hello!, second: me }); // OR // use the result once the mutation has completed mutation({ first: Hello!, second: me }).then((result) console.log(result), ); }useMutation返回一个触发函数它有两种调用语义fire and forget直接mutation({...})发起调用不关心结果这是最常见的方式适合按钮点击等事件处理等待结果调用后拿到 Promise通过.then((result) ...)或await使用 mutation 的返回值对应 mutation handler 的return语句。由于useMutation返回的函数是稳定的引用见 client.ts L1084 处实现它可以安全地放进useEffect依赖数组或作为 props 传递不会因组件重渲染而失效。从模板到真实项目组件化 demo 的函数调用链关联文档所在的项目components-legacy是一个专门用于测试组件 API 导入的 demo。其 convex.config.ts 展示了组件注册方式import { defineApp } from convex/server; import waitlist from ../examples/waitlistname-with-dashes/convex.config.js; import nestedComponent from ./nested-component/convex.config.js; const app defineApp(); app.use(waitlist, { name: waitlist }); app.use(waitlist, { name: waitlist2 }); app.use(nestedComponent); export default app;同一个waitlist组件被注册了两次waitlist与waitlist2外加一个嵌套组件nestedComponent。而 messages.ts 通过const waitlist components.waitlist satisfies ComponentApi拿到类型安全的组件句柄后即可用ctx.runQuery、ctx.runMutation、ctx.runAction、ctx.scheduler.runAfter跨组件调用其内部函数——这正是函数模板文档 组件体系结合后的实际形态也印证了模板中ctx参数在多函数编排中的核心地位。CLI 工作流从开发到部署关联文档最后给出两条最常用的 CLI 命令npx convex dev本地开发模式。启动后会持续监听convex/目录自动重新生成_generated代码server.ts、api.ts、dataModel.ts等并同步函数到本地部署配合前端框架实现热更新开发体验npx convex -h在项目根目录运行列出 Convex CLI 的全部可用命令npx convex docs在本地启动官方文档。在本仓库中_generated文件如 convex/_generated/server.js头部都明确写着 To regenerate, runnpx convex dev说明生成文件与 CLI 的绑定关系。若使用其他框架可用npx convex dev --help查看对接参数部署到线上环境的命令是npx convex deploy。小结一套模板三种能力关联文档的这份函数目录模板浓缩了 Convex 开发中最核心的三件事用query({ args, handler })定义可订阅的读函数参数由 validator 校验并推导类型ctx.db提供事务性读取用mutation({ args, handler })定义写函数支持读写混合与返回值在 React 中用useQuery订阅、用useMutation触发获得端到端类型安全与实时数据同步。在此基础上本仓库的components-legacydemo 展示了函数在组件体系下的进阶用法跨组件runQuery/runMutation/runAction、定时调度、事务回滚验证等。无论你是在一个简单的单表 demo 上起步还是在复杂的多组件应用中编排逻辑这套模板都是进入 Convex 函数世界最直接的入口。赞分享数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载相关推荐NV-Generate-MR API使用教程从基础配置到高级参数调优NV Generate MR API使用教程从基础配置到高级参数调优 NV Generate MR是一款基于3D潜在扩散模型的尖端工具专为生成高质量合成磁共数据库后端SpacetimeDB keynote-2在 convex/ 函数目录编写 Convex Query 与 Mutation 函数并接入转账基准测试SpacetimeDB keynote 2在 convex/ 函数目录编写 Convex Query 与 Mutation 函数并接入转账基准测试 本文以数据库关系型数据库后端如何设计高性能HTTP APIhttp-api-design-ZH_CN的10个核心原则与实战案例如何设计高性能HTTP APIhttp api design ZH_CN的10个核心原则与实战案例 HTTP API设计是现代应用开发的核心环节一个高性能的数据库后端上一篇FlyingCarpet无缝穿梭数据迁移的魔法地毯下一篇超实用babel-plugin-preval构建时预编译实战指南从原理到性能优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
