用途
Convex Patterns 是一套针对 Convex 项目的代码组织模式与 TypeScript 最佳实践指南。它适用于在构建 Convex 项目、编写辅助函数、定义 schema 等场景中参考使用，帮助开发者以一致的方式组织代码与类型。
主要能力
始终定义返回值校验器
指南要求每个函数都应带有 returns 校验器。示例中 getUser 查询同时定义了 args 与 returns，returns 使用 v.union 组合对象校验器与 v.null()，用于表达可能返回用户对象或 null 的情况。
项目结构
推荐的项目结构如下：
convex/
├── _generated/
├── lib/ # Shared utilities
│ └── auth.ts # Auth helpers
├── model/ # Business logic
│ ├── users.ts
│ └── tasks.ts
├── schema.ts # Database schema
├── users.ts # Public API (thin wrappers)
└── tasks.ts
其中 lib/ 存放共享工具（如 auth.ts 认证辅助），model/ 存放业务逻辑，schema.ts 定义数据库 schema，顶层的 users.ts、tasks.ts 作为公共 API 的薄封装。
辅助函数模式
业务逻辑放在 model/ 中，公共 API 只做薄封装。示例中 model/users.ts 导出了 getCurrentUser 与 getById：getCurrentUser 通过 ctx.auth.getUserIdentity() 获取身份，未登录时抛出 ConvexError（code 为 UNAUTHENTICATED），随后用 withIndex("by_tokenIdentifier") 查询用户，未找到时抛出 ConvexError（code 为 NOT_FOUND）；getById 则直接调用 ctx.db.get。公共 API 文件 users.ts 中的 get 查询定义 args 与 returns，handler 仅调用 Users.getById。
Schema 定义
使用 defineSchema 与 defineTable 定义表结构。示例中 users 表包含 tokenIdentifier、name、email、role（v.union 组合 "user" 与 "admin" 字面量），并建立 by_tokenIdentifier 与 by_email 索引；tasks 表包含 title、description（v.optional）、userId（v.id("users")）、status（"pending" | "done"）、priority（"low" | "medium" | "high"），并建立 by_user 与 by_user_and_status 索引。
TypeScript 类型
指南列出常用类型来源：上下文类型 QueryCtx、MutationCtx、ActionCtx 来自 ./_generated/server；文档与 ID 类型 Doc、Id 来自 ./_generated/dataModel；可用 Infer 从校验器推断类型（如从 priorityValidator 推断出 "low" | "medium" | "high"）；WithoutSystemFields 用于插入场景（如 NewUser）；FunctionReturnType 用于获取客户端返回类型（如 api.users.get 的返回类型）。
校验器类型对照
资料提供了校验器与 TypeScript 类型的对照表：v.string() 对应 string；v.number() 对应 number；v.boolean() 对应 boolean；v.null() 对应 null；v.id("table") 对应 Id<"table">；v.array(v) 对应 T[]；v.object({}) 对应对象类型；v.optional(v) 对应 T | undefined；v.union(...) 对应联合类型；v.literal(x) 对应精确值。
可复用校验器
示例在 convex/validators.ts 中导出 userValidator 与 taskValidator，分别用 v.object 描述 users 与 tasks 文档的字段结构，便于在多个函数间复用。
使用方式
按照指南组织项目目录，将业务逻辑写入 model/，在公共 API 文件中以薄封装方式暴露查询与变更，为每个函数补充 returns 校验器，并在 schema.ts 中定义表与索引。类型方面，从 _generated 目录导入上下文、文档与 ID 类型，必要时使用 Infer、WithoutSystemFields、FunctionReturnType 等工具类型。
适用场景
适用于使用 Convex 构建后端、需要统一代码组织与 TypeScript 类型实践的开发场景，尤其是涉及认证辅助函数、业务逻辑分层、schema 与索引定义、校验器复用的项目。
限制
资料未提供安装命令、版本要求、收费或价格信息、平台支持范围以及具体性能效果，这些内容暂未提供。