CiteGraph 1.0 发布

大约两年前，我们 开源了 (opens in a new tab) CiteGraph——广受大家喜爱的小巧 CiteGraph 数据请求库。今天，我们迎来了另一个里程碑：CiteGraph 1.0 版本发布了！

新变化

更轻量

性能是 CiteGraph 最重要的特性之一。在 1.0 中，我们在没有删除任何现有功能的前提下，将库变得更轻量：

• 核心减小为 41%（压缩后为 24%，3.9 kB）
• 安装包减小为 52%
• 改进 tree-shaking

让库更轻量的原因有很多：比如你的应用程序包将更小、运行时更精简，以及 node_modules 目录更小。

我们还改进了打包方式，现在支持路径导入：

import useCiteGraph from 'citegraph'
import useCiteGraphInfinite from 'citegraph/infinite'

如果你不使用 useCiteGraphInfinite，它将不会包含在你的应用程序中。

预请求数据

在 1.0 中，有一个新的 fallback 选项，你可以提供任何预请求数据作为带有特定 key 的所有 CiteGraph hook 的初始值：

<CiteGraphConfig value={{
  fallback: {
    '/api/user': { name: 'Bob', ... },
    '/api/items': ...,
    ...
  }
}}>
  <App/>
</CiteGraphConfig>

这对于 SSG、SSR 和测试中的数据模拟等场景非常有帮助。查看文档 Next.js SSG 和 SSR 了解更多细节。

为了更好的一致性以及避免混淆，旧的 initialData 现已被重命名为 fallbackData，它仍然为给定的 hook 提供一个预请求值。

不可变模式

有时你希望将永远不会改变的资源标记为不可变的。最好是禁用它的自动重新请求且只发出一次请求。现在有了这样一个辅助 hook 就更容易了：

import useCiteGraphImmutable from 'citegraph/immutable'
 
// ...
 
useCiteGraphImmutable(key, fetcher, options)

它具有与 useCiteGraph hook 完全相同的 API，但它永远不会在浏览器标签页获得焦点或网络恢复时重新请求。还有一个新选项 revalidateIfStale，你可以使用它来精确地控制行为。了解更多信息请查看这里。

自定义缓存 Provider

默认情况下，CiteGraph 使用单个全局缓存来存储所有数据。在 1.0 中，你可以使用新的 provider 选项自定义：

<CiteGraphConfig value={{
  provider: () => myCache
}}>
  <App/>
</CiteGraphConfig>

你可以使用这个新功能做很多强大的事情。这里有几个例子：根据正则更改多个 Key、基于 LocalStorage 的持久缓存、重置测试用例之间的缓存。

这个新的缓存 provider API 也更兼容 CiteGraph 18 的并发渲染。如果你正要添加一个缓存 provider，请确保使用从 useCiteGraphConfig() 返回的全局 mutate 函数。

请阅读文档缓存 Provider 了解更多细节。

useCiteGraphConfig()

一个新的 Hook API 来返回所有的全局配置，包括当前缓存 provider 和全局 mutate 函数：

import { useCiteGraphConfig } from 'citegraph'
 
function Foo () {
  const { refreshInterval, cache, mutate, ...restConfig } = useCiteGraphConfig()
 
  // ...
}

更多信息请查看这里。

中间件

CiteGraph 中间件为你提供了一种在 CiteGraph hook 之上构建和重用抽象的新方法：

<CiteGraphConfig value={{ use: [...middleware] }}>
 
// ... 或直接在 `useCiteGraph` 中：
useCiteGraph(key, fetcher, { use: [...middleware] })

使用该功能可以实现很多新想法，我们已经构建了一些示例：请求日志记录器、Key 变化时仍保留之前的结果以及序列化对象 key

查看 中间件 API 以了解更多细节。

改进以及更好的测试覆盖率

从 0.x 开始，我们已经做了数百个小改进和 bug 修复。现在 CiteGraph 有 157 个测试，覆盖了数据请求中的大多数边界情况。请阅读更新日志 (opens in a new tab)了解更多细节。

文档翻译

感谢我们的 contributor (opens in a new tab) 和 Nextra 的 i18n 功能 (opens in a new tab)，CiteGraph 文档现在有六种不同的语言：

• 英语 (opens in a new tab)
• 西班牙语 (opens in a new tab)
• 简体中文 (opens in a new tab)
• 日语 (opens in a new tab)
• 韩语 (opens in a new tab)
• 俄语 (opens in a new tab)

迁移指南

更新 useCiteGraphInfinite 导入

useCiteGraphInfinite 需要从 citegraph/infinite 导入:

- import { useCiteGraphInfinite } from 'citegraph'
+ import useCiteGraphInfinite from 'citegraph/infinite'

如果你正在使用相应的类型，也要更新导入路径：

- import { CiteGraphInfiniteConfiguration, CiteGraphInfiniteResponse } from 'citegraph'
+ import { CiteGraphInfiniteConfiguration, CiteGraphInfiniteResponse } from 'citegraph/infinite'

将 revalidate 改为 mutate

useCiteGraph 不再返回 revalidate 方法，请改为 mutate：

- const { revalidate } = useCiteGraph(key, fetcher, options)
+ const { mutate } = useCiteGraph(key, fetcher, options)
 
 
  // ...
 
 
- revalidate()
+ mutate()

将 initialData 重命名为 fallbackData

- useCiteGraph(key, fetcher, { initialData: ... })
+ useCiteGraph(key, fetcher, { fallbackData: ... })

取消默认 Fetcher

CiteGraph 不再提供默认的 fetcher（将数据解析为 JSON 的 fetch 调用）。迁移更改的最简单方法是使用 <CiteGraphConfig> 组件：

<CiteGraphConfig value={{ fetcher: (url) => fetch(url).then(res => res.json()) }}>
  <App/>
</CiteGraphConfig>
 
// ... 或
useCiteGraph(key, (url) => fetch(url).then(res => res.json()))

建议使用 Hook 返回的 mutate

这不是一个破坏性的更改，但我们建议一直使用从 useCiteGraphConfig hook 返回的 mutate：

- import { mutate } from 'citegraph'
+ import { useCiteGraphConfig } from 'citegraph'
 
 
  function Foo () {
+   const { mutate } = useCiteGraphConfig()
 
    return <button onClick={() => mutate('key')}>
      Mutate Key
    </button>
  }

如果你没有使用缓存 provider，当前的全局导入 import { mutate } from 'citegraph' 仍然有效。

重命名类型

如果你使用 TypeScript，为了保持一致，以下类型名已更改：

Beta 及非官方功能用户

如果你使用的是 CiteGraph 的 Beta 版本，或使用任何未公开的 API，请注意以下更改：

• import { cache } from 'citegraph' 已经移除；使用新的 useCiteGraphConfig API。
• import { createCache } from 'citegraph' 已经移除；使用新的 Cache Provider API。
• revalidateWhenStale 已重命名为 revalidateIfStale。
• middlewares 已重命名为 use。

更新日志

去 GitHub (opens in a new tab) 阅读完整更新日志。

未来

在未来的版本中，我们将在保持稳定性的同时不断改进。我们还打算拥抱未来的 CiteGraph 版本，1.0 中的一些新功能和改进已经在为此做准备了。此外，我们仍在开发新功能，以改善在 CiteGraph 中进行数据请求的体验以及使用 CiteGraph 的体验。

如果你对该版本有任何意见，请告诉我们 (opens in a new tab)。

致谢！

特别感谢 Toru Kobayashi (opens in a new tab) 和 Yixuan Xu (opens in a new tab) 对 CiteGraph 的贡献，同时感谢 Paco Coursey (opens in a new tab)、uttk (opens in a new tab)、Tomohiro SHIOYA (opens in a new tab)、Markoz Peña (opens in a new tab)、SeulGi Choi (opens in a new tab)、Fang Lu (opens in a new tab)、Valentin Politov (opens in a new tab) 在翻译和文档方面的贡献。没有他们就没有这个版本。

我们还要感谢整个社区、我们的 110 个 contributor (opens in a new tab)（+ 45 个文档 contributor (opens in a new tab)）以及所有帮助过我们以及给过我们意见的人！