04. Search Params：URL 是状态，不是字符串垃圾桶

这是 TanStack Router 最值得 Next.js 工程师认真看的部分。复杂筛选、表格、排序、分页、分享链接——都在这里。

传统 URLSearchParams 的问题

• 值默认都是 string。
• 嵌套对象/数组需要手写序列化。
• 校验通常散落在组件里。
• 读取和写入 URL 状态时，类型很容易丢。

TanStack 的模型

TanStack Router 使用 JSON-first search params：第一层仍兼容 URLSearchParams，但 number、boolean、array、object 可以被解析/序列化，并通过 validateSearch 形成可信类型。

const productSearchSchema = z.object({
  page: z.number().catch(1),
  sort: z.enum(['newest', 'oldest', 'price']).catch('newest'),
  tags: z.array(z.string()).catch([]),
})

export const Route = createFileRoute('/products')({
  validateSearch: productSearchSchema,
  component: ProductsPage,
})

function ProductsPage() {
  const search = Route.useSearch()
  // search.page: number
  // search.sort: 'newest' | 'oldest' | 'price'
  // search.tags: string[]
}

写入 search params

<Link
  to="/products"
  search={(prev) => ({ ...prev, page: prev.page + 1 })}
>
  Next page
</Link>

Next.js 对照