Wagmi 项目中 BigInt 在 JSON 序列化中的处理问题

问题背景

在 Web3 开发中，Wagmi 是一个流行的 React Hooks 库，用于与区块链交互。当开发者使用 Wagmi 的 readContractQueryOptions 方法时，如果参数中包含 BigInt 类型的数据，会遇到 JSON 序列化问题。

问题本质

React Query 作为 Wagmi 的底层状态管理库，其查询键(query key)默认不支持 BigInt 类型的序列化。当开发者尝试将包含 BigInt 值的参数传递给 readContractQueryOptions 时，生成的查询键会包含 BigInt 值，导致 React Query 在序列化过程中抛出错误。

技术细节

BigInt 是 JavaScript 中用于表示大整数的数据类型，但 JSON 规范本身不支持 BigInt 的序列化。当开发者使用如下代码时：

useSuspenseQuery(readContractQueryOptions(config, {
  args: [0n],
});

查询键中会包含 BigInt 值 0n，这会导致 React Query 的序列化过程失败。

解决方案

Wagmi 提供了两种处理方式：

1. 使用内置的序列化工具：如果项目中使用 TanStack Query 的持久化功能，可以利用 Wagmi 提供的 serialize 和 deserialize 工具函数。

import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
import { deserialize, serialize } from 'wagmi'

const persister = createSyncStoragePersister({
  serialize,
  storage: window.localStorage,
  deserialize,
})

2. 使用 hashFn 处理查询键：对于不需要持久化但需要处理 BigInt 的场景，可以使用 Wagmi 提供的 hashFn 函数。

import { hashFn } from 'wagmi/query'

useSuspenseQuery(readContractQueryOptions(config, {
  args: [0n],
  queryKeyHashFn: hashFn,
});

最佳实践

1. 在使用包含 BigInt 参数的合约读取操作时，始终考虑查询键的序列化问题
2. 对于需要持久化查询数据的应用，配置适当的序列化/反序列化方法
3. 在文档中明确标注 BigInt 参数可能带来的序列化问题，并提供解决方案
4. 考虑在项目初始化时统一配置查询键的序列化处理，避免每个查询点都需要单独处理

总结

Wagmi 与 React Query 的集成提供了强大的区块链数据管理能力，但开发者需要注意 JavaScript 数据类型与 JSON 规范之间的差异。通过合理使用 Wagmi 提供的工具函数，可以优雅地解决 BigInt 序列化问题，确保应用的稳定运行。