企业官网建设流程全解析

• 后端
• 前端
• 企业应用

导读

本文围绕 Papermark 项目中前端数据请求的最佳实践规则展开，讲解如何在 React 应用中通过 SWR 实现跨组件实例的请求自动去重（deduplication）、缓存与重新验证（revalidation），避免多个组件同时挂载时对同一 API 接口发起重复请求。读完本文，你将掌握从useState + useEffect + fetch到useSWR的改造方法，理解不可变数据与变更操作的两种进阶用法，并了解 Papermark 在 lib/swr 目录下 40 余个数据 hooks 中如何配置dedupingInterval、条件 key 与轮询刷新，直接指导你在真实项目中落地这套模式。

一、问题背景：为什么客户端请求需要去重

在 React 应用中，同一个数据源经常被多个组件实例消费。典型场景包括：文档列表页同时渲染多个卡片组件、分析面板中多个图表组件读取同一份统计数据、数据室（Dataroom）详情页中多个区块都需要文档访问记录。

如果每个组件都在useEffect中独立发起fetch请求，则 N 个组件实例会向服务器发出 N 份完全相同的请求，造成：

• 重复网络流量：同一份数据被反复拉取，浪费带宽；
• API 负载放大：后端接口被无意义地打满，尤其在仪表盘类页面格外明显；
• 数据不一致风险：各实例各自维护一份状态，刷新时机不同步时界面会出现短暂差异。

Papermark 的这条规则（见 client-swr-dedup.md）将其影响等级标为 MEDIUM-HIGH，正是因为它直接关系到客户端性能与后端 API 稳定性。

二、反模式：useState + useEffect + fetch 各自拉取

规则文档首先给出了需要避免的写法——每个组件实例独立发起请求，无任何去重机制：

function UserList() { const [users, setUsers] = useState([]) useEffect(() => { fetch('/api/users') .then(r => r.json()) .then(setUsers) }, []) }

这种写法的问题在于：fetch是"一次性"的——组件挂载时执行一次，结果只写入本地useState。当UserList在页面上出现两次（例如同时存在于侧边栏与主内容区），两个实例各自请求/api/users，产生两份重复请求；同时没有任何缓存层，组件卸载再挂载、路由切换返回时，都会再次请求。

三、正确模式：useSWR 让多个实例共享同一请求

SWR（Stale-While-Revalidate）的核心价值在于：它把请求的结果提升为全局共享的缓存层，而不是组件私有的 state。相同 key 的请求在去重窗口内只发出一次，所有订阅该 key 的组件实例共享同一份数据和缓存。

规则文档给出的标准写法：

import useSWR from 'swr' function UserList() { const { data: users } = useSWR('/api/users', fetcher) }

其中/api/users是缓存 key（SWR 也支持数组形式的 key），fetcher是接收 key 并返回 Promise 的请求函数。SWR 会保证：

• 去重（deduplication）：同一时间窗口内，相同 key 的并发请求只触发一次网络请求；
• 缓存（caching）：请求结果缓存于全局缓存池，组件重挂载时先返回缓存数据；
• 重新验证（revalidation）：在组件聚焦、网络重连等时机自动后台重新拉取并更新缓存，让界面数据保持新鲜。

在 Papermark 中，SWR 依赖版本为^2.4.1（见 package.json），fetcher 统一封装在 lib/utils 中导出，所有数据 hooks 共用同一套请求函数，例如 use-document.ts 中的：

const { data: document, error, mutate } = useSWR<DocumentWithVersion>( teamInfo?.currentTeam?.id && id && `/api/teams/${teamInfo?.currentTeam?.id}/documents/${encodeURIComponent(id)}`, fetcher, { /* 详见下文配置小节 */ }, );

可以看到，key 是由团队 ID 与文档 ID 拼接而成的完整 API 路径，天然具备"按资源隔离缓存"的能力。

四、进阶用法一：不可变数据与 useSWRImmutable

对于配置、用户代理信息、预览元数据这类几乎不会变化的数据，频繁重新验证毫无意义，反而徒增 API 请求。规则文档提示使用不可变模式：

import { useImmutableSWR } from '@/lib/swr' function StaticContent() { const { data } = useImmutableSWR('/api/config', fetcher) }

在 Papermark 仓库中，实际落地用的是 SWR 官方导出的useSWRImmutable（来自swr/immutable），效果等价——禁用所有自动重新验证，数据仅在首次请求时获取。仓库中多处使用这一模式，例如 use-document-preview.ts：

const { data: document, error, mutate, } = useSWRImmutable<DocumentPreviewData>( isOpen && currentTeamId && documentId ? `/api/teams/${currentTeamId}/documents/${documentId}/preview-data` : null, fetcher, { dedupingInterval: 10000, revalidateOnFocus: false, revalidateOnReconnect: false, }, );

这个例子同时示范了两个关键实践：

1. 条件 key（conditional key）：当isOpen、currentTeamId或documentId任一为假时，key 传null，SWR 不会发起请求。这解决了"弹窗未打开时也预取数据"的浪费问题，是 SWR 官方推荐的按需请求手法；
2. 显式关闭聚焦/重连重新验证：预览数据以打开弹窗时获取的版本为准，避免用户切回标签页时数据被意外刷新。

类似的不可变用法还出现在数据室访客 UA 信息的获取中：use-dataroom-stats.ts 用useSWRImmutable拉取访客的设备、浏览器、城市与操作系统信息——这类信息在一次会话内恒定不变，非常适合 immutable 模式。

五、进阶用法二：变更操作与 useSWRMutation

去重解决的是"读"的问题，而"写"操作同样需要规范。规则文档给出的变更写法：

import { useSWRMutation } from 'swr/mutation' function UpdateButton() { const { trigger } = useSWRMutation('/api/user', updateUser) return <button onClick={() => trigger()}>Update</button> }

useSWRMutation的特点是：请求只在trigger()被调用时才发起，不会在组件挂载时自动执行；它天然兼容 SWR 的缓存体系，变更完成后可以配合mutate触发相关 key 的重新验证，实现"写后刷新"的闭环。相比在useEffect中手动调用fetch再自己管理 loading/error 状态，这种模式显著减少了样板代码，也避免了"写操作被重复触发"的隐患。

六、dedupingInterval 与重新验证策略的工程化配置

SWR 的自动去重并非无限期生效，而是受dedupingInterval（去重窗口，单位毫秒）约束：窗口内相同 key 的请求被合并为一次，窗口过期后才会允许再次请求。Papermark 的各个数据 hooks 针对不同数据特性配置了差异化的去重与重新验证策略，可直接作为调参参考：

其中 agreement-section.tsx 的注释非常典型："Only hydrate while unconfirmed (null key disables the request); useSWRImmutable since signed status is effectively one-shot."——签约状态在确认后即为终态，属于一次性数据，用 immutable + 条件 key 组合实现"未确认不请求、确认后只请求一次"。

从这些示例可以总结出调参原则：

• 数据变化越频繁，dedupingInterval越短，或配合refreshInterval主动轮询（如处理进度 3 秒一刷）；
• 数据变化越罕见，窗口越长，甚至直接使用 immutable 模式彻底禁用自动刷新（如缩略图 20 分钟）；
• revalidateOnFocus: false/revalidateOnReconnect: false适用于对"焦点回切刷新"不敏感的页面，可显著降低后台 API 流量；
• 条件 key（传null）是所有场景都值得采用的默认习惯，用于阻止未就绪或未打开的组件浪费请求。

七、Papermark 中的规模化实践：lib/swr 目录

去重规则的价值在 Papermark 中体现为体系化的数据层：仓库在 lib/swr 目录下集中维护了 40 余个数据 hooks，覆盖文档、数据室、访客、团队、计费、域名、标签、权限组等全部领域，每个 hook 都以useXxx命名并统一返回{ data, loading, error, mutate }形状。

从源码结构看，这套目录的设计思路是：

1. 统一 fetcher：所有 hooks 从 lib/utils 引入同一个fetcher，保证请求行为一致；
2. 统一缓存 key 规则：key 一律由teamId+ 资源 ID + API 路径拼接而成，例如/api/teams/${teamId}/documents/${id}/stats，同一资源在所有页面共享同一份缓存；
3. hook 内封装去重策略：每个 hook 内部针对自己数据的特点配置dedupingInterval与重新验证选项，业务组件无需关心去重细节，直接消费 hook 返回值；
4. 与上下文联动：hooks 大量依赖 team-context 提供的currentTeamId，团队切换时 key 自然变化，缓存自动按团队隔离。

这种"数据 hooks 集中管理"的模式，让 SWR 的去重、缓存与重新验证能力贯穿整个客户端：无论是useDocument（文档详情）、useDataroomStats（数据室统计）还是useVisitorUserAgent（访客设备信息），都只需关心数据与 key，网络层的去重由 SWR 统一完成。团队切换、路由跳转、组件卸载重挂载都不会产生重复请求风暴。

八、最佳实践清单

结合规则文档与 Papermark 源码，可将客户端数据请求去重总结为以下可执行清单：

1. 用useSWR替代useState + useEffect + fetch，让相同 key 的请求在去重窗口内只发出一次；
2. key 使用完整的、可唯一标识资源的 API 路径（如teamId + documentId拼接），保证缓存粒度正确；
3. 对几乎不变的数据使用 immutable 模式（swr/immutable的useSWRImmutable），显式关闭自动重新验证；
4. 对写操作使用useSWRMutation，仅在trigger()时发起请求，并配合mutate做写后刷新；
5. 按数据特性配置dedupingInterval：频繁变化的数据用短窗口或refreshInterval轮询，罕见变化的数据用长窗口或 immutable；
6. 利用条件 key（null）按需请求，未就绪、未打开、未确认的场景一律不发请求；
7. 在后台类页面显式关闭revalidateOnFocus与revalidateOnReconnect，削减不必要的后台流量。

这套模式的最终效果正如规则文档所总结：SWR 让请求去重、缓存与重新验证在组件实例之间自动生效——写更少的请求代码，获得更稳的缓存一致性与更低的后端负载。

• 后端
• 前端
• 企业应用