输入校验与错误处理

输入校验

接口在 .input() 中使用 Zod，明确字符串长度、枚举、数量和格式。对外部文件和网址，还需要在处理阶段验证真实内容、响应大小和可访问范围；仅校验后缀或网址格式不够。

import { z } from "zod";

const listInput = z.object({
  limit: z.number().int().min(1).max(100).default(20),
});

统一错误

apps/api/lib/trpc.ts 为校验错误附加 data.zodError，客户端可把字段错误放回表单。业务错误使用 TRPCError，选择与实际情况一致的类型。

错误类型	场景
BAD_REQUEST	输入或请求状态不合法
UNAUTHORIZED	缺少有效会话
FORBIDDEN	已登录但无操作权限
NOT_FOUND	资源不存在或不可见
CONFLICT	唯一约束或当前状态冲突
INTERNAL_SERVER_ERROR	未预期的内部失败

import { TRPCError } from "@trpc/server";

throw new TRPCError({
  code: "FORBIDDEN",
  message: "当前账号没有管理权限",
});

示例说明错误表达方式；客户站文案按产品语言配置。

前端处理

使用 apps/app/lib/errors.ts 提取状态和可展示消息，区分校验错误、权限错误与网络故障。401 可以引导重新登录；403 应解释权限不足；网络故障保留输入供用户重试。

不要把所有异常改成“没有登录”，也不要在支付失败后自动重试创建订阅。日志保留内部原因和请求标识，响应隐藏堆栈、数据库连接和密钥。

环境错误

启动时 parseEnv() 检查字段组合，诊断只报告错误字段名。先修复缺失变量再重启；不要为了绕过报错把半组凭据补成无效占位值。