TanStack Router中处理非标准数组返回类型的最佳实践

在TanStack Router项目中，开发者在使用createServerFn创建服务端函数时，可能会遇到一个常见的类型检查问题——当尝试返回带有额外属性的非标准数组时，TypeScript会报类型错误。本文将深入分析这一问题产生的原因，并提供几种实用的解决方案。

问题背景

在开发过程中，我们经常会使用像Ronin这样的数据查询库，这些库有时会返回带有分页信息的特殊数组结构。例如：

const posts = await get.posts(); // 返回Array<Post> & { moreAfter: string; moreBefore: string }

当开发者尝试在createServerFn中直接返回这种特殊数组时，会遇到类型错误，因为TanStack Router默认期望返回的是标准的JSON可序列化类型。

问题本质

这个问题的核心在于JSON序列化的限制。JSON规范中数组只能是纯数组，不能带有额外属性。当服务端函数返回带有额外属性的数组时，这些属性在序列化为JSON传输到客户端的过程中会丢失。

解决方案

1. 解构重组法

最直接的方法是将数组和额外属性分开处理：

export const $getPosts = createServerFn({
  method: "GET",
}).handler(async () => {
  const posts = await get.posts();
  return {
    records: [...posts],  // 展开为纯数组
    moreBefore: posts.moreBefore,
    moreAfter: posts.moreAfter
  };
});

2. 类型断言法

如果你确定只需要数组部分数据，可以使用类型断言：

export const $getPosts = createServerFn({
  method: "GET",
}).handler(async () => {
  const posts = await get.posts();
  return {
    posts: posts as Post[],  // 明确告诉TypeScript我们只需要数组部分
    pagination: {
      before: posts.moreBefore,
      after: posts.moreAfter
    }
  };
});

3. 创建通用工具函数

对于项目中频繁使用的情况，可以创建一个通用的序列化工具函数：

type PaginatedArray<T> = ReadonlyArray<T> & {
  moreBefore?: string | null;
  moreAfter?: string | null;
};

function serializePaginated<T>(data: PaginatedArray<T>) {
  return {
    records: [...data],
    pagination: {
      before: data.moreBefore,
      after: data.moreAfter
    }
  };
}

// 使用示例
export const $getPosts = createServerFn({
  method: "GET",
}).handler(async () => {
  const posts = await get.posts();
  return serializePaginated(posts);
});

最佳实践建议

1. 明确数据需求：在服务端函数中，明确你需要传输哪些数据给客户端，避免传输不必要的信息。

2. 保持类型安全：虽然可以使用类型断言，但要确保你确实了解数据结构和序列化行为。

3. 文档记录：对于特殊的数据结构转换，添加适当的代码注释说明转换原因和预期行为。

4. 考虑性能：对于大型数组，展开操作(...)可能会有性能影响，需要权衡可维护性和性能。

通过以上方法，开发者可以优雅地解决TanStack Router中非标准数组返回的类型问题，同时确保数据的正确序列化和传输。