用途
convex-helpers 是 Convex 官方提供的工具集合，用于为 Convex 后端补充常见模式与实用工具，避免重复造轮子。它提供经过实践检验的模式，覆盖常见后端需求。
安装
npm install convex-helpers
主要能力
1. 关系辅助（Relationship Helpers）
以可读、类型安全的方式遍历表之间的关系。适用于跨表加载关联数据、跟随外键关系、构建嵌套数据结构。
关键函数：
getOneFrom：获取单个关联文档getManyFrom：获取多个关联文档getManyVia：通过中间表获取多对多关系
导入路径：convex-helpers/server/relationships
2. 自定义函数（数据保护）——最重要
这是 Convex 中行级安全（RLS）的替代方案。不使用数据库级策略，而是通过自定义函数包装器，自动为所有查询和变更添加鉴权与访问控制。
适用场景：数据保护与访问控制（主要用途）、为所有函数添加鉴权逻辑、多租户应用、基于角色的访问控制（RBAC）、向 ctx 注入公共数据、构建仅内部使用的函数、为所有函数添加日志/监控。
相比 RLS 的优势：使用 TypeScript 而非 SQL 策略、完整的类型安全、易于测试和调试、比数据库策略更灵活、可作用于整个后端。
导入路径：convex-helpers/server/customFunctions
3. 过滤辅助（Filter Helper）
对数据库查询应用复杂的 TypeScript 过滤。适用于按计算值过滤、过滤逻辑过于复杂无法使用索引、处理较小结果集的场景。注意：仍应尽可能优先使用索引，filter 用于无法索引的复杂逻辑。
导入路径：convex-helpers/server/filter
4. 会话（Sessions）
即使用户未登录，也能跨请求追踪用户。适用于追踪匿名用户、为访客构建购物车、在注册前追踪用户行为、无需鉴权的 A/B 测试。
服务端导入路径：convex-helpers/server/sessions（提供 SessionIdArg）
客户端（React）导入路径：convex-helpers/react/sessions（提供 useSessionId）
5. Zod 校验
使用 Zod 模式替代 Convex 校验器。适用于项目中已使用 Zod、需要更复杂的校验逻辑、需要自定义错误消息的场景。
导入路径：convex-helpers/server/zod（提供 zCustomQuery）
6. 替代方案：行级安全辅助
Convex 推荐将自定义函数（见第 2 项）作为主要的数据保护模式。此 RLS 辅助是模仿传统 RLS 的替代方案。自定义函数通常更好，因为：编译时类型安全（RLS 是运行时）、更显式（容易看出应用了哪些鉴权）、更好的错误消息、更易于测试。
7. 迁移（Migrations）
安全地运行数据迁移。适用于回填新字段、转换现有数据、在模式版本之间迁移。
导入路径：convex-helpers/server/migrations（提供 makeMigration）
运行方式：npx convex run migrations:addDefaultPriority
8. 触发器（Triggers）
数据变更时自动执行代码。适用于数据变更时发送通知、更新关联记录、记录变更日志、维护计算字段。
导入路径：convex-helpers/server/triggers
使用方式
各辅助工具通过对应的导入路径引入，在 Convex 的 query、mutation、action 中使用。自定义函数通过 customQuery、customMutation 等包装器创建带自定义行为的函数版本，在 input 回调中执行鉴权、注入上下文等逻辑，并返回新的 ctx 与 args。
适用场景
- 跨表加载关联数据
- 为所有函数统一添加鉴权与访问控制
- 多租户应用与 RBAC
- 匿名用户追踪与访客购物车
- 使用 Zod 进行复杂校验
- 数据迁移与回填
- 数据变更触发通知或关联更新
限制与注意事项
- 过滤辅助应仅在无法使用索引的复杂逻辑时使用，仍应优先使用索引。
- 数据保护方面，Convex 推荐自定义函数而非 RLS 辅助。
- 文档未提供收费、价格、平台或效果相关信息。