用途:指导在编写 Convex 的查询(query)、变更(mutation)与动作(action)时,判断是否应添加返回验证器(returns)。Convex 最新指引已从旧规则“总是添加 returns 验证器”调整为“默认优先使用简单 TypeScript 类型与推断”,仅在确实需要 Convex 运行时强制精确契约时才使用 returns:。
主要能力与要点:返回验证器用于声明返回值形状并在运行时校验,对象验证器不允许多余属性,返回多余字段会触发运行时错误。其真正价值在于 TypeScript 结构类型不具备“精确类型”,当涉及 any 或未验证外部数据时,验证器能在运行时捕获意外泄漏的数据。
建议使用 returns 的场景:components 代码生成(推断不可用,验证器即契约)、静态代码生成(无验证器时默认 v.any())、OpenAPI 生成(缺失验证器会变成 any)、以及处理 any 或未验证外部数据(更宜在边界即 action 内 fetch 后校验)。
不建议使用 returns 的场景:类型良好的标准查询与变更、AI/LLM 生成的默认代码(可减少冗长、token 与幻觉风险)、快速原型(形状未稳定)、以及 internalQuery、internalMutation、internalAction 等不面向客户端的内部函数。
“总是添加”旧规则的代价:导致冗长与复制粘贴脆弱、AI token 低效、模型幻觉风险,以及 _id 与 _creationTime 等系统字段重复声明。若需大量使用,可参考 convex-helpers 的验证器工具。
AI 规则更新建议:将旧规则替换为新规则,并在使用 returns 时鼓励复用集中定义的共享验证器、用对象的 .pick()、.omit()、.extend() 派生返回类型、在无需验证器时使用 Doc<"tableName"> 与 WithoutSystemFields,以及用 convex-helpers 减少系统字段重复。
限制:资料未提供具体安装命令、版本要求或收费信息。