Uploadthing文件路由中对象数组输入类型的解析与解决方案

问题背景

在使用Uploadthing文件路由功能时，开发者可能会遇到一个关于输入类型的TypeScript错误。具体表现为当尝试在文件路由的输入中使用对象数组时，类型系统会报错，提示类型不兼容。

错误现象

当开发者定义如下输入模式时：

const imageSchema = z.object({
  media: z.array(z.object({ id: z.string() }))
});

系统会抛出类型错误，指出对象数组类型不符合预期的JSON类型定义。核心错误信息表明：

类型'{ id: string; }[]'不能赋值给类型'JsonArray'

技术分析

Uploadthing内部定义了一套JSON类型系统，用于确保输入数据可以被正确序列化。原始的类型定义如下：

type JsonValue = string | number | boolean | null | undefined;
type JsonArray = JsonValue[];
type JsonObject = {
    [key: string]: JsonValue | JsonObject | JsonArray;
};
type Json = JsonValue | JsonObject | JsonArray;

这个定义存在一个关键限制：JsonArray只能包含基本类型的值(JsonValue)，而不能包含嵌套的对象结构。这与实际JSON序列化的能力不符，因为JSON本身是支持嵌套对象数组的。

解决方案

项目团队已经通过代码提交修复了这个问题。修复的核心思路是：

1. 扩展JsonArray类型定义，使其能够包含JsonObject类型
2. 确保类型系统能够正确识别嵌套的对象结构

修正后的类型定义应该类似于：

type JsonArray = Json[];

这样修改后，类型系统就能正确识别包含对象结构的数组，同时仍然保持类型安全性。

最佳实践建议

1. 类型安全：即使系统修复了这个问题，开发者仍应确保输入数据确实是可序列化的JSON
2. 复杂结构：对于特别复杂的嵌套结构，建议进行适当的扁平化处理
3. 版本更新：确保使用最新版本的Uploadthing以获取此修复

总结

这个问题的本质是类型定义与实际JSON能力之间的不匹配。通过扩展类型系统的表达能力，Uploadthing现在能够更好地支持复杂的数据结构输入，同时保持类型安全。开发者可以放心地在文件路由中使用对象数组作为输入参数。