如今，AI 工具（Claude、ChatGPT、Cursor、Gemini、Copilot）已经深度融入我们的工作。开发速度呈指数级提升，但坦率地说，我感觉服务的完成度并没有同步跟上。功能越多，随之增加的 bug 也越多，我们也越来越常听到“我不知道为什么会变成这样”。

开发越快，我们就越少逐行细看代码。正因如此，我认为我们更需要具备一种能够为 AI 指明正确方向的基本功。只有能发现 AI 生成代码中的问题，并重新引导它朝预期方向前进，才能守住交付质量。这些基本功可以包括从领域视角开发、抽象、TDD（Test-Driven Development，测试驱动开发）、善用库，以及建立性能优势等很多方面。

不过，每当我问前端同事以及其他 IT 岗位的同事“前端开发中最棘手的工作是什么？”时，听到最多的答案始终如一：“管理状态流。”

本文将梳理为什么状态流管理如此棘手，以及要想做好这件事，需要培养怎样的判断力与感觉。

什么是状态（State）

在正式展开之前，先从最基础的问题说起。我们所说的“状态”究竟是什么？

学习前端开发时，我常读 hoseung.me 的文章。其中将状态定义为**“所有可能影响 UI 的数据”**。点赞数、购物车列表、模态框是否打开、输入值、当前登录用户的信息、当前选中的标签页、搜索结果、是否正在加载——这些全都是状态。

React 官方文档给出了更形式化的定义。页面标题就是 “State: A Component's Memory”，展开来说，大致是指**“组件在多次渲染之间保留（retain）数据，并在数据更新时触发 React 重新渲染的机制”。也就是说，这类数据不会随时间消失，会因某个事件而更新，并在更新时让 UI 重新绘制。还有一点需要指出：状态按组件实例彼此隔离。** 即使页面上存在十个相同组件，它们也各自拥有独立状态。这个事实与后文“状态应该放在哪里”的讨论直接相关。

两种定义指向的是同一件事：**“会影响渲染，并随时间变化的值”**就是状态。不变的常量（constant）不是状态。构建时就固定下来的原始设计 token 不是状态，但由用户切换的深色模式是状态。（严格来说，值本身会根据深色/浅色主题这一状态完成 resolve，因此更准确的理解是，“主题选择”才是状态，token 则是映照该状态的镜子。）

这里还有一点需要明确：并非所有状态都存在于组件中。 有些状态存在 Cookie 中，有些存在 localStorage、sessionStorage 或 IndexedDB 中，还有些存在 URL 中。把服务端数据带到客户端并加以缓存，也会形成一种状态。浏览器自身维护的滚动位置和历史记录栈，在它们会决定应用行为时，也需要被当作状态处理。

为什么如此棘手

先简单想一想，处理状态为什么困难。创建需要的状态，把它传到需要的地方，再妥善处理更新与初始化，不就可以了吗？

把这个问题留在脑中，然后打开你正在开发的服务中的任意一个页面。

这个页面有多少个组件？即使是简单页面，也可能由少则几十、多则几百个组件组成一棵树。每个组件可能持有自己的状态，可能与兄弟组件共享状态，也可能从父组件接收状态。状态还会在页面之间迁移：有些状态刷新后必须保留，有些状态则应在关闭标签页时消失。

状态真正难以管理的原因就在这里：我们无法一眼看清大量状态分别在哪里声明、如何更新，又在何时消亡。 职责相似的组件越多，给状态命名以及追踪修改状态的代码就越困难。

于是，一张看不见的蛛网形成了。A 组件中的某次点击使 B 的数据失效，B 的失效又让 C 的 UI 关闭，C 关闭时表单输入随之消失。如果这种连锁关系没有在代码的任何地方明确表达，那么调试 bug 时，我们就只能在脑中重新画出这张蛛网。

那么，该如何整理这张蛛网？在我看来，第一步是意识到：“状态有不同的种类。”

并非所有状态都是同一种状态

Kent C. Dodds 将状态分为 Server Cache（服务端保存信息，客户端为便于快速访问而持有的副本）与 UI State（只存在于 UI 中，用于控制界面行为）。我们经常在把两者混为一谈时犯错。

TanStack Query 官方文档将 TanStack Query 定义为 Server State 库，用于管理服务端与客户端之间的异步工作；Redux、MobX、Zustand 等工具则被定义为 Client State 库。（它们虽然能够存储异步数据，但这样做效率不高。）

关键点很明确：Server State 与 Client State 是不同的问题。 Server State 是异步的，可能被其他用户修改，并会随时间变得 stale。Client State 是同步的、受我们控制，并会在刷新后消失。（准确地说，页面 unload 时，JavaScript 运行时会重新启动，heap 内存中的组件树及其状态会一并被回收。 因此再次 mount 时，会从 useState 的初始值重新开始。）如果试图用同一种工具管理两者，就必须亲手实现缓存失效、后台刷新、乐观更新等模式。

在此基础上，我会更进一步，把前端状态分为七个类别。需要提前说明的是，这七类并不能沿单一维度整齐划分。存储位置、来源、生命周期和职责彼此交织，因此一个状态可能同时属于多个类别。请不要把它看作一张完美的分类表，而应把它理解为决定如何管理状态时需要提出的一组问题。

• 局部状态（Local State） — 只在一个组件或较小子树中使用的状态
• 全局状态（Global State） — 需要由整个应用共享的状态
• 服务端状态（Server State） — 以服务器为 Single Source of Truth、客户端副本仅作为缓存的状态
• 表单状态（Form State） — 用户输入期间暂时存在的状态
• URL 状态（URL State） — 位于地址栏中、可分享且刷新后仍保留的状态
• 外部状态（External State） — 位于 React 外部的状态，如 Cookie、localStorage、sessionStorage 和 IndexedDB
• 状态守卫（State Guard） — 根据状态组合阻止、允许或校验访问与操作的逻辑，而不是状态本身

除此之外，还有适合用状态机精细建模的工作流状态，以及基于 WebSocket 或 CRDT 的实时协作状态。

下面逐一说明为什么它们需要不同的工具，以及应以怎样的判断力来对待它们。

局部状态（Local State）

这是最简单的一类状态。它只在一个组件内使用，外部既不需要知道，也无权知道。例如模态框是否打开、切换按钮的 on/off、悬停状态、正在输入的搜索词。

function SearchBox() {
  const [query, setQuery] = useState("");
  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

这些大家应该已经很熟悉了。但局部状态真正棘手的地方，是**“这个状态应该放在哪里”**这一位置决策。

Kent C. Dodds 的 State Colocation一文指出：人们习惯于把状态“提升（lift up）”，却不擅长在代码发生变化后，重新把状态“就近放置（colocate）”。

当兄弟组件需要共享同一状态时，提升状态是我们很自然的做法。既然两个兄弟组件要读取同一份数据，就把状态提升到共同父组件，再通过 props 向下传递。

问题出在兄弟组件不再需要该状态时。我们通常不会把状态重新下移到子组件中。结果，父组件积累了大量实际上与自身无关的状态，每次父组件重新渲染时，整棵子树也会随之重新渲染。

因此，处理局部状态的第一条判断准则是：为了让代码更快、更简单，应让状态尽可能靠近使用它的代码。 如果某个状态只被一个组件的某个子组件使用，父组件就没有理由持有它。把它移到该子组件内部，父组件也会因此变得更轻。

全局状态（Global State）

全局状态是需要在应用任意位置访问的状态。登录信息、主题、语言、通知（toast）等都可能属于这一类。

局部状态与全局状态的区别，并不只是“存在于哪里”。二者对引用方式的承诺不同。局部状态向代码承诺的是**“只在这个组件内部有意义”；全局状态则向整个代码库发布一项承诺：“应用中的任何位置，都可以用这个名字引用这个值。”** 这项承诺成本高昂，正是全局状态的本质。

创建一个全局状态，实际上就是为整个应用增加一项隐式依赖。

服务端状态（Server State）

把 API 返回的数据塞进 Client State，亲自用 boolean 管理加载与错误，做着做着便会产生疑问：“为什么每次都在写同样的样板代码？”

TanStack 的主要维护者 Tanner Linsley 曾表示：“Client State 是同步且可预测的。Server State 是异步的，会被多个组件共享，必须谨慎处理缓存、后台刷新与错误状态。” 也就是说，Server State 与 Client State 本质上是不同的物种，不应使用同一种工具处理。

Server State 的棘手之处，不在于工具，而在于数据的本质。

客户端看到的数据属于服务端。客户端持有的只是某一时刻的快照。随着时间推移，这份数据会产生 staleness。它还是异步的，可能失败，并拥有 pending、error、success 等状态。

最重要的本质是：响应无法保证按照请求发出的顺序返回。 假设用户在搜索框中快速输入“react”。r → re → rea → reac → react 的请求会依次发出，但如果“react”的响应先到，随后“rea”的响应才到，页面最终显示的就会是“rea”的结果。要避免这类问题，每次都得手动编写 AbortController 或请求 ID 追踪逻辑，因此必须关注这种并发风险（race conditions）。

表单状态（Form State）

表单是一类微妙的状态。用户输入期间，它会剧烈变化；一旦提交，通常就会消失。它不会与其他地方共享，也（大多）没有需要保存的去处。

问题在于，这种“剧烈变化”代价不菲。如果每次按键都触发 React 重新渲染，那么在大型表单中，输入延迟会明显到可以被用户察觉。而且表单不只是“持有值”。校验、dirty check、提交状态、错误信息、多步骤流程等多种状态，会同时在一个表单内部运转。

像三步支付流程这样的多步骤表单，通常会被期待**“即使中途刷新，进度状态也能保留”。如果只用 useState 保存表单值，刷新后所有内容都会丢失。更自然的做法是保存在 sessionStorage（标签页级临时存储）或 URL（可分享的步骤）中。也就是说，表单状态会根据生命周期要求，与外部状态**或 URL 状态结合。

URL 状态（URL State）

假设我们正在搜索页面中按分类、排序方式和页码进行筛选。如果用 useState 保存这些状态，会同时出现三个问题。

• 刷新后，所有筛选条件都会重置
• 即使把 URL 分享给朋友，对方看到的仍是没有应用筛选条件的页面
• 点击后退，也无法回到之前的筛选条件

解决这些问题时，把状态放进 URL 是很自然的选择。 URL 本身就是一种无需额外成本的持久存储，天然支持刷新、分享和历史记录。

/products?category=shoes&sort=price-desc&page=2

这一行 URL 中已经包含了**“鞋类商品按价格降序排列后的第 2 页”**这一完整状态，无需再用 useState 单独保存。

那么，什么时候适合用 URL 管理状态？URL 是公开接口。 密码、认证 token、用户不愿让他人看到的临时备忘等信息，都不应放入 URL。此外，如果把变化过于频繁的值（每次输入都会变化的搜索词）直接写进 URL，历史记录栈就会被垃圾填满。这种情况下，应在 debounce 后再同步，仅在合适时使用 push，而对不应新增历史记录的更新使用 replace。

URL 中的值始终是字符串。数字、boolean、数组、对象都必须经过序列化与反序列化。并且 URL 必须遵循百分号编码（percent-encoding）规则，&、=、韩文、空格等字符都需要特殊处理。如果每次都手写这些逻辑，很快就会成为 bug 的温床。

const params = new URLSearchParams(location.search);
const page = Number(params.get("page") ?? "1");
params.set("page", String(page + 1));
navigate(`?${params.toString()}`);
 
const [page, setPage] = useQueryState("page", parseAsInteger.withDefault(1));

nuqs 之类的库通过*解析器（parser）*概念解决了这两个问题。parseAsInteger、parseAsBoolean、parseAsJson 等解析器统一负责序列化、反序列化与类型。它支持 Next.js（App/Pages Router）、React Router v6/v7、TanStack Router、Remix 等大多数环境。

那么，可以把任意多的状态都塞进 URL 吗？除了序列化和类型问题之外，还有最后一个约束需要注意。RFC 7230 并未规定精确上限，但建议“服务器至少应支持 8,000 个 octet（在网络或数据通信中，用于明确指代由 8 Bit 组成的 1 Byte 的单位）”。不同浏览器的限制也各不相同。现代浏览器大多允许 8KB 到数万字符，但搜索引擎、社交媒体的 OG/分享处理，以及部分网关，可能在接近 2KB 时就截断内容。因此，不要无限制地往 URL 中塞数据。只保留可分享的核心筛选条件，其余内容交给 sessionStorage 或服务端存储会更安全。

外部状态（External State）

React 只知道自身内部的状态，但我们的应用也在不断与 React 之外的世界交互。存在于那个世界中的状态，不受 React 生命周期约束，会独立存续，也会发生变化。这里所说的外部状态包括 Cookie、localStorage、sessionStorage、IndexedDB。

应该如何选择存储方式？我通常从生命周期、容量、同步性、安全性四个维度思考。

对于认证 token，OWASP 的建议首选 HttpOnly + Secure Cookie。localStorage 可由 JavaScript 访问，因此一旦暴露于 XSS，token 就会被直接窃取。部分安全指南建议采用混合模式：access token 放在内存中，refresh token 放在 HttpOnly Cookie 中。需要持久保存、不敏感且不经常变化的数据，可以放在 localStorage；应随标签页关闭而消失的数据，则可以使用 sessionStorage。离线缓存、大体量数据和文件通常使用 IndexedDB。

Cookie 与 Web Storage（local/session）只能存储字符串。因此，要存入对象就必须经过 JSON.stringify/JSON.parse。但 JSON 存在局限。

JSON.stringify({ when: new Date() });
// → { "when": "2026-05-19T..." } — Date becomes a string
 
JSON.stringify({ map: new Map([["a", 1]]) });
// → { "map": {} } — Map is lost entirely
 
JSON.stringify({ value: undefined });
// → "{}" — the undefined field is omitted

Date 在 JSON 往返转换后会变成字符串，Map、Set 和 undefined 则可能丢失数据。默认情况下，BigInt 会让 JSON.stringify 抛出 TypeError，导致序列化直接失败。把对象存入外部存储时，必须始终留意哪些类型可能消失、改变或导致序列化失败，必要时应提供序列化适配器。

外部状态真正的难点是：React 无法自动检测它的变化。 即使向 localStorage 写入值，React 组件也不会重新渲染。解决这一问题通常有三种模式。

• 用自定义 hook（useLocalStorage）再封装一层，把外部状态同步为 React state。 这种方式轻量，但如果自行实现，就必须处理多标签页、SSR、tearing 等各种边界情况。
• 使用 React 18 引入的 useSyncExternalStore hook，“与 React 外部状态同步”。 借此可以确保并发渲染中不会发生 tearing。 它是连接 localStorage、浏览器 API 与外部 store 的标准工具。
• Zustand 的 persist middleware、Jotai 的 atomWithStorage 等状态库，把外部存储集成作为一等能力提供，因此也可以直接使用已有的库。

这里再补充一条判断准则：一旦把外部状态带入 React，同步责任就落到了我们身上。 如果另一个标签页更新了它呢？如果服务端修改了 Cookie 呢？如果用户通过浏览器开发者工具直接修改 localStorage 呢？这些情况往往会成为最严重的 bug 温床。

状态守卫（State Guard）

最后一类稍有不同。它不是状态本身，而是根据状态组合来阻止、允许或校验某个流程的逻辑。

最常见的例子是认证守卫（Auth Guard）。

function ProtectedRoute({ children }) {
  const { isAuthenticated, isLoading } = useAuth();
 
  if (isLoading) return <Spinner />;
  if (!isAuthenticated) return <Navigate to="/login" replace />;
  return children;
}

这里，isAuthenticated 状态控制了路由流程，这就是守卫逻辑。守卫有很多种，包括认证守卫（是否已认证）、权限守卫（特定角色、权限）、流程守卫（进入分支）、校验守卫（启用步骤）等。

守卫逻辑很容易堆积在一个地方。常见的情况是，一个组件里同时写满了**“未登录就去登录页、无权限就去 403、购物车为空就去商品页、用户被封禁就显示封禁提示”**。守卫越臃肿，就越难调试究竟是哪个条件在哪里阻断了流程。

好的守卫只检查一件事。 组合则通过 Composition 完成。

<AuthGuard>
  <RoleGuard role="admin">
    <FlowGuard require={["cartHasItems"]}>
      <CheckoutPage />
    </FlowGuard>
  </RoleGuard>
</AuthGuard>

每个守卫只作出一个决定，组合关系由树形结构负责。添加新守卫时，无需修改现有守卫。

处理守卫时，比“是否拦截”更需要仔细考虑的是：拦截后把用户送到哪里，以及后续如何处理。 只会拦截、没有 fallback 的守卫，最终只会留下白屏或无限 spinner。

最常见的 bug 是：“在守卫的异步检查完成前，受保护内容会短暂闪现。” 认证 token 校验、权限查询大多是异步操作，在此期间，isAuthenticated 会有一小段时间处于 undefined 或 false。如果不显式处理加载状态，受保护页面就可能在这个间隙暴露，或用户可能被错误重定向到登录页。

// Ignores loading and handles only missing data => incorrect
if (!user) return <Navigate to="/login" />;
 
// Treat loading as a first-class state (early return) => correct
if (isLoading) return <Spinner />;
if (!user) return <Navigate to="/login" replace />;
return children;

编写权限守卫时，常见的模型有两种。

• RBAC（Role-Based Access Control）：按角色授予权限，例如“admin 可以查看所有用户信息”。它简单、快速，但随着角色不断细分，角色数量会爆炸式增长
• ABAC（Attribute-Based Access Control）：根据属性组合决定权限，例如“用户是该帖作者、与作者属于同一团队，或用户是 admin”。它表达能力强，但实现和调试更困难

如 TanStack Router 的 RBAC 指南所示，推荐在路由层的 beforeLoad 中设置守卫。关键在于：权限检查不应散落在代码各处，而应能表达为数据（角色/权限列表）。这样一来，权限策略调整只需变更数据。

总结

总结一下。状态管理之所以困难，不是因为库难用，而是因为我们经常忘记：状态有不同种类，也容易忽略不同种类需要不同的工具与思考方式。

局部状态应尽量就近放置；面对全局状态，要再确认一次它是否真的需要全局；Server State 应作为缓存处理；表单应与领域分离；URL 应更积极地使用；外部存储需要明确意识到自身责任；守卫则应拆薄后进行组合。这就是处理七类状态的基本功。

而凌驾于这些具体做法之上的判断力，最终可以浓缩为四个问题。

• 这份数据的 Single Source of Truth 在哪里？
• 这是可以计算得到的值，还是确实必须存储的值？
• 这些状态的组合中，是否存在不可能的组合？
• 这个状态真的应该位于这里吗？

每次开发新页面、审查 PR、接收 AI 生成的代码时，都把这些问题问上一遍。我相信，这是培养判断力与感觉最可靠的方式。

正如开头所说，AI 会长久地留在我们身边。我们逐行查看代码的时间会越来越少。但越是如此，能够回答**“这个状态应该放在哪里？”**这类小问题的能力就越有价值。让 AI“在这里再加一个 useState”很容易；但那一行代码会在应用的蛛网上增添一根怎样的丝线，只有阅读代码的人凭借自己的判断力才能看清。

不存在唯一正确答案。但至少，**“不知道状态是什么就创建状态”与“意识到状态的种类和位置后再创建状态”**之间，有着明确的区别。希望读者下次写下一行 useState 之前，也能暂时停一下，问问自己：“它属于哪一类状态？”

参考资料

在开发过程中，我经常会遇到**“领域（Domain）”**这个词。但真要回答“领域到底是什么？”，却很难给出一个清晰明了的答案。（说实话，刚开始学开发时，我还以为领域就是指 www。）

查找领域相关资料时，自然会延伸到领域模型、领域对象、领域对象模型等概念。但一直让我觉得遗憾的是，很少有文章能讲清它们彼此有何不同，以及这些概念在并非后端的前端中意味着什么。本文会从各个概念的定义出发，结合示例梳理如何在前端恰当地分离和抽象领域逻辑。

我最近对税务相关领域很感兴趣。眼看 5 月的综合所得税申报期即将到来，本文就用税务来举例。

领域（Domain）

先从最基础的问题开始。什么是领域？

Eric Evans 在其著作 Domain-Driven Design: Tackling Complexity in the Heart of Software（2003） 中对领域作出了如下定义。

知识、影响力或活动的范围。

"A sphere of knowledge, influence, or activity."

简单来说，领域就是希望通过编程解决的问题范围本身。如果要开发报税服务，“报税”就是领域；如果要开发保险理赔平台，“保险理赔”就是领域。领域不是代码，而是在软件出现之前就已存在的现实世界问题范围。

这对前端开发者意味着什么？我们构建的用户界面，归根结底是一个让用户看见并操作领域的窗口（window）。如果开发 Toss Income、3o3 这类以税务领域为核心的退税服务，就要通过用户界面呈现收入类型、费用率、所得扣除、税额抵免、退税额等领域概念。因此，前端开发者也必须深入理解自己处理的领域。换句话说，了解**“这项服务要解决什么问题”**，与出色地实现用户界面组件同样重要。

然而，即便只有“税务”这一个领域，深入其中也会发现大量子领域。仅以我略知皮毛的综合所得税计算流水线为例，就已经是这样。

这条流水线的每一个阶段，都是拥有独立规则和数据的子领域。“税务”这一大领域内部，交织着收入（Income）、扣除（Deduction）、税额（Tax）、申报结果（Filing）等细分领域。如何在代码中划分它们，正是领域建模的核心问题。

领域模型（Domain Model）

那么，什么是领域模型？领域和“领域模型”有什么区别？

Martin Fowler 与 Eric Evans 对领域模型作出了如下定义。

同时包含行为和数据的领域对象模型。—— Martin Fowler

An object model of the domain that incorporates both behavior and data.

一种描述领域中选定方面的抽象体系，可用于解决与该领域相关的问题。—— Eric Evans

A system of abstractions that describes selected aspects of a domain and can be used to solve problems related to that domain.

关键在于**“选择性抽象”。领域模型不会囊括现实世界的一切。就像电影导演不会拍下现实中的所有场景，而只选择叙事所需的场景一样，领域模型也是选取解决问题所需的方面并加以结构化**的结果。

这里有一点很重要：领域模型不一定非得是代码。它可以是白板上的图，也可以是团队成员头脑中共享的心智模型（Mental Model）。归根结底，“领域模型”这个术语本身可以是一个独立于软件的概念。

这里还有一个前端开发者特别容易混淆的地方：看到 API 响应结构，就认为“这就是领域模型”。但它其实是数据模型（Data Model），而不是领域模型。

数据模型与领域模型的区别如下。

数据模型定义“数据以什么形式流转”，而**领域模型定义“这些数据在业务上意味着什么，又遵循哪些规则”。**如果无法区分两者，组件就会直接依赖 API 响应结构，每当后端 schema 发生变化，整个前端都会受到牵连。

领域对象（Domain Object）

如果说领域模型是一套概念体系，那么领域对象就是这些概念在代码中的具体实现。

经营 Code with Jason 的 Jason Swett 在文章中这样定义领域对象。

在我的对象模型中，凡是在领域模型里也作为一个概念存在的对象，我都会称之为领域对象。

Any object in my object model that also exist as a concept in my domain model I would call a domain object.

也就是说，如果领域模型中存在“综合所得”这一概念，代码中又有名为 Income 的类型，那么这个 Income 就是领域对象。但并非所有代码对象都是领域对象。HttpClient、LocalStorageAdapter、useDebounce 等只是技术工具，并不是领域概念。

实体与值对象

Evans 将领域对象分为实体（Entity）、值对象（Value Object）、**服务（Service）**三类。（Martin Fowler 将这种分类称为“Evans Classification”。）服务是一个独立概念，用来表达“无法自然归属于某个特定对象的领域操作”。不过，本文关注的核心是如何识别数据，因此将重点讨论实体和值对象。

**实体（Entity）**是具有唯一身份、能够贯穿时间与多种表现形式的对象。报税申报单（TaxFiling）、纳税人（Taxpayer）、收入记录（IncomeRecord）等都通过唯一标识符识别；即使属性发生变化，只要标识符相同，就仍是同一个实体。即使修改了申报单的扣除项目，只要申报单标识符没有变化，它就仍是同一份申报单。

**值对象（Value Object）**是仅由属性组合赋予意义的对象，所有属性值都相同时，就视为同一个对象。金额（Money）、税率（TaxRate）、税级（TaxBracket）等都属于其数值本身即有意义的对象。“6% 的税率”无论用在哪里，都只是“6% 的税率”。

为什么这种区分在前端很重要？来看下面的代码示例。

interface TaxFiling {
  id: string;
  taxpayerName: string;
  taxYear: number;
  status: FilingStatus;
}
 
const isSameFiling = (a: TaxFiling, b: TaxFiling) => a.id === b.id;
 
interface Money {
  amount: number;
  currency: "KRW" | "USD";
}
 
const isSameMoney = (a: Money, b: Money) =>
  a.amount === b.amount && a.currency === b.currency;

TaxFiling 以 id 作为身份判断标准，因此是实体。（拥有 id 字段本身并不是实体的定义，关键在于“用这个 id 判断对象是否相同”。）Money 没有 id，仅通过 amount 与 currency 的组合来识别；所有属性相同时，就视为同一个值。

实体基于标识符比较，值对象基于属性比较。明确这种区分后，状态管理中判断“这份数据是否相同”的逻辑就会自然地得到梳理。比如更新列表项时，如果是实体，就通过标识符找到并替换；如果是值对象，则执行不可变替换（immutable replace）。

领域对象模型（Domain Object Model）

已经知道了“领域模型”和“领域对象”，那么领域对象模型又是什么？

查阅资料后发现，这个概念出人意料地没有公认定义。许多文献把“领域模型”“领域对象模型”“概念模型（conceptual model）”“分析对象模型（analysis object model）”视为实质上的同义词，认为它们只是对面向对象分析阶段所绘制概念模型的不同称呼。

但也有观点认为，它们属于划分得更细的不同层次。其中有一种典型解释：领域模型转化为实际代码的地方，正是对象模型。

按照第二种观点，对象模型是系统中所有代码对象的结构，也包含 HttpClient、useDebounce 等技术工具。其中，用于表达领域概念的对象子集及其相互关系，就是领域对象模型。这也与面向对象建模的传统一脉相承——在这一传统中，“对象模型”被定义为系统的静态结构，包括类、属性、操作与关系。

我认为，这种观点对前端开发者更实用，因为我们实际编写的代码总是混合着领域对象和技术对象。

归根结底，领域 → 领域模型 → 领域对象模型 → 领域对象是一组从抽象走向具体的层次关系。领域最宽泛，领域对象最具体。因此，编写前端代码时，我们真正要思考的终究是：如何组织领域对象模型，也就是表达领域概念的类型及其相互关系。

前端的领域逻辑应该放在哪里？

概念定义就讲到这里，现在来聊聊实践。前端的领域逻辑究竟应该放在哪里？

热衷于软件设计的 Khalil Stemmler 起初主张“业务逻辑不属于前端”，后来又调整了立场，表示“后端在架构层面所做的几乎一切，前端也能做，而且应该做。”

我也认同这一观点。当然，前端不应成为业务逻辑的唯一事实来源（Single Source of Truth），那是后端的职责。但前端确实存在前端独有的领域逻辑。

设想这样一种情况：“需要根据用户输入的信息，实时展示预计退税额。”如果这类计算逻辑只存在于后端，用户每修改一个收入金额的字符，就要调用一次 API。用户界面会在网络往返期间停顿；如果用户输入很快，还会产生爆炸式增长的无用请求。即使加入防抖，数百毫秒的延迟也足以破坏“实时预览”的体验。最终，需要即时反馈的计算只能由前端自行完成，于是也就出现了只能在前端执行的逻辑。

领域逻辑混入组件的情况

以综合所得税预览页面为例。用户输入收入信息后，页面会实时展示预计税额。下面是一段常见的代码，其中领域逻辑和用户界面逻辑混在了一起。

function TaxPreviewPage() {
  const [총수입, set총수입] = useState(0);
  const [경비율, set경비율] = useState(0.641); 
  const [인적공제대상인원, set인적공제대상인원] = useState(1); 
 
  const 종합소득금액 = 총수입 - 총수입 * 경비율;
 
  const 소득공제합계 = 인적공제대상인원 * 1_500_000;
  const 과세표준 = Math.max(0, 종합소득금액 - 소득공제합계);
 
  let calculatedTax = 0;
  if (과세표준 <= 14_000_000) {
    calculatedTax = 과세표준 * 0.06;
  } else if (과세표준 <= 50_000_000) {
    calculatedTax = 과세표준 * 0.15 - 1_260_000;
  } else if (과세표준 <= 88_000_000) {
    calculatedTax = 과세표준 * 0.24 - 5_760_000;
  } else if (과세표준 <= 150_000_000) {
    calculatedTax = 과세표준 * 0.35 - 15_440_000;
  } else {
    calculatedTax = 과세표준 * 0.38 - 19_940_000;
  }
 
  const 기납부세액 = 총수입 * 0.033;
  const refundOrPayment = 기납부세액 - calculatedTax;
 
  return <div>...</div>;
}

看出这段代码的问题了吗？“每人 150 万韩元的人身扣除”“8 级累进税率”“3.3% 预扣税”等由税法规定的业务规则被直接写死在 React 组件中。税法每年都会修订，如果这些规则散落在各个组件里，修订时就必须四处寻找需要修改的位置。如果质量保证团队还有端到端测试场景需要维护，测试成本也不会低。

最终，视图逻辑与业务逻辑变得难以区分，代码也会被大量条件语句和自定义钩子缠成一团。

分离领域逻辑

借用 Alex Bespoyasov 的 Clean Architecture 方法中的一项核心原则：把领域逻辑分离为不依赖框架的纯函数。

领域是区分一个应用与另一个应用的核心。可以把领域理解为，即使从 React 迁移到 Angular，也不会发生变化的部分。

The domain is the core that distinguishes one application from another. You can think of the domain as something that won't change if we move from React to Angular.

来重构上面的税额计算示例。

首先定义领域类型和规则，将相关信息聚合起来。

export interface Income {
  grossAmount: number;
  expenseRate: number;
}
 
export interface Deductions {
  personalCount: number;
  pensionPaid: number;
  additionalDeductions: number;
}
 
const PERSONAL_DEDUCTION_PER_PERSON = 1_500_000;
const WITHHOLDING_RATE = 0.033;
const TAX_BRACKETS = [
  { limit: 14_000_000, rate: 0.06, progressiveDeduction: 0 },
  /** ...구간들... **/
] as const;

然后，将领域逻辑分离为纯函数。

把前面计算收入、扣除、计税依据、税额、退税额等逻辑分离到 computeFullTax 函数中，再把每个阶段拆成更小的纯函数。结果类型可以通过 ReturnType<typeof computeFullTax> 推断，无需单独声明接口。

之后，组件只需“使用”领域逻辑。

import { computeFullTax } from "../domain/tax";
 
function TaxPreviewPage() {
  const [income, setIncome] = useState<Income>({
    grossAmount: 0,
    expenseRate: 0.641,
  });
  const [deductions, setDeductions] = useState<Deductions>({
    personalCount: 1,
    pensionPaid: 0,
    additionalDeductions: 0,
  });
 
  const result = computeFullTax(income, deductions);
 
  return (
    <div>
      <IncomeForm value={income} onChange={setIncome} />
      <DeductionForm value={deductions} onChange={setDeductions} />
      <TaxResultSummary result={result} />
    </div>
  );
}

发生了哪些变化？

• 8 级累进税率表（TAX_BRACKETS）集中在一处，税法修订时只需修改 domain/tax.ts
• 计算流水线聚合在 computeFullTax 这一个函数中，整体流程一目了然。（为了让示例保持简单，这里将它合并成了一个函数；在实际项目中，更适合按收入计算、扣除计算、税额计算等目的进一步细分。）
• 组件只专注于“如何展示”。即使税率变化，也无需修改组件
• 即使从 React 迁移到其他框架，domain/tax.ts 也无需变化

分离领域逻辑后，测试会变得出奇简单。在税务领域，计算是否准确直接关系到用户的钱，所以这一点尤其重要。

包含税务计算逻辑的纯函数不需要 React Testing Library，也不需要 render 或 screen.getByText。传入输入、检查输出即可。“1,400 万韩元及以下适用 6% 税率”“计税依据为 0 韩元时税额也为 0 韩元”“自由职业者收入 3,000 万韩元时的退税额”等用例，都可以用一行 it 来表达。领域单元测试会自然地帮助确定组件的拆分边界，测试代码本身也能充当文档。

贫血领域模型（Anemic Domain Model）

上一节分离了计算逻辑。但领域逻辑除了计算，还包括状态转换规则和权限判断。例如：“现在可以修改这份申报单吗？”“可以提交吗？”“可以切换申请方式吗？”在分离这些规则时，很容易落入一个陷阱，也就是 Martin Fowler 命名的贫血领域模型（Anemic Domain Model）。

贫血领域模型是指：类型虽然用领域语言定义得很好，但作用于类型之上的规则却散落到了领域之外。以报税申报（Filing）领域为例，类型本身很整洁。

// types/filing.ts
export interface TaxFiling {
  id: string;
  status: "draft" | "submitted" | "reviewing" | "completed" | "amended";
  taxYear: number;
  filingType: "regular" | "late" | "amendment";
  determinedTax: number;
}

但针对这个类型的判断和转换规则，却写死在其他地方。

// utils/filingHelpers.ts
export function canAmendFiling(filing: TaxFiling) {
  return filing.status === "completed" && filing.filingType !== "amendment";
}
 
// components/FilingDetail.tsx
function FilingDetail({ filing }: { filing: TaxFiling }) {
  // 같은 도메인 규칙을 컴포넌트 안에 다시 작성한다
  const canEdit = filing.status === "draft" || filing.status === "reviewing";
  // ...
}
 
// hooks/useSubmitFiling.ts
export function handleSubmitFiling(filing: TaxFiling) {
  if (filing.status !== "draft") return;
  // ...
}

同一条领域规则分别以不同形式存在于工具函数、组件和钩子这三个地方。此时，如果收到“申请条件将发生变化”的需求，就必须四处寻找要修改的位置；任何一个被遗漏的地方，都会在网站的某处作出错误判断。Fowler 批评这类代码，称其**“与只披了一层面向对象外衣的过程式代码别无二致”**。

解决办法与上一节处理计算逻辑的方法相同：把规则放在类型旁边。

export interface TaxFiling {
  id: string;
  status: FilingStatus;
  taxYear: number;
  filingType: FilingType;
  determinedTax: number;
}
 
export type FilingStatus =
  | "draft"
  | "submitted"
  | "reviewing"
  | "completed"
  | "amended";
 
export type FilingType = "regular" | "late" | "amendment";
 
// 도메인 규칙은 도메인 옆에 둔다
export function canEdit(filing: TaxFiling): boolean {
  return filing.status === "draft";
}
 
export function canSubmit(filing: TaxFiling): boolean {
  return filing.status === "draft" && filing.determinedTax >= 0;
}
 
export function canAmend(filing: TaxFiling): boolean {
  return filing.status === "completed" && filing.filingType !== "amendment";
}

现在，申报相关规则都在 domain/filing.ts 中统一管理。任何组件只需调用 canAmend(filing)；规则发生变化时，也只需修改这一个文件。关键在于，**应该把类型及其上的规则视为一个整体。**如果只把类型放进领域文件夹，却把规则抽到工具函数中，这种局部分离即使外表整洁，仍然处于贫血状态。

API 响应与领域模型之间的转换层

在实际工作中，还要考虑另一件事：后端 API 的响应结构不一定总与前端领域模型一致。如果是与国家机关对接的税务服务，就更是如此。韩国国税厅 Hometax 的对接数据充斥着缩写和代码值，几乎不可能以与前端领域模型相同的形式返回。

此时就需要转换层（Mapper）。不要让 API 响应类型原封不动地一路流入组件，而应先将其整理成领域类型，再交给组件使用。一个纯函数就足够了。

import type { Income } from "../domain/tax";
 
interface HometaxIncomeResponse {
  총수입금액: number;
  경비율: number;
  소득유형코드: string;
  // ... 나머지 약어 필드들
}
 
export function toIncome(response: HometaxIncomeResponse): Income {
  return {
    총수입_금액: response.총수입금액,
    경비_비율: response.경비율,
  };
}

这样一来，就能在一个地方把 API 响应中的 총수입금액、경비율 等缩写，以及基于代码值的分类，转换为适合前端领域的形式。像收入类型代码这样需要展开为枚举的值，可以在转换器中放一张小型查找表。即使 Hometax API 的字段名发生变化，也只需修改一个转换器。

工具函数与领域逻辑

分离领域逻辑时，必然会遇到一个问题：“这不就是工具函数吗？”

来看下面两个函数。

function formatCurrency(amount: number): string {
  return `${amount.toLocaleString()}원`;
}
 
function calculateTax(taxableBase: number): number {
  const bracket = TAX_BRACKETS.find((bracket) => taxableBase <= bracket.limit);
  return Math.floor(taxableBase * bracket.rate - bracket.progressiveDeduction);
}

formatCurrency 是把数字转换成字符串的纯表现层逻辑（Presentation）。加上“韩元”单位和千位分隔符并不是业务规则，而是如何把内容展示给用户的问题。相反，calculateTax 包含“应用 8 级累进税率”这一基于税法的业务规则。即使没有用户界面，这条领域规则也必须同样适用。

我在实际工作中使用的判断标准是：

如果这段逻辑消失，受损的是业务，还是只有页面？

如果业务受损，它就是领域逻辑；如果只有页面受损，它就是表现层逻辑。仅凭这个问题，就能划清大多数边界。

但现实并没有这么清晰。最棘手的是，有些逻辑看起来像领域逻辑，其实却是表现层逻辑。

来看下面的代码。因为它以 FilingStatus 这一领域概念作为参数，所以被归类为领域逻辑。但它真的是领域逻辑吗？

// domain/filing.ts
function getStatusBadgeColor(status: FilingStatus): string {
  const colors: Record<FilingStatus, string> = {
    draft: "gray",
    submitted: "blue",
    reviewing: "yellow",
    completed: "green",
    amended: "purple",
  };
  return colors[status];
}
 
function getStatusDisplayText(status: FilingStatus): string {
  const labels: Record<FilingStatus, string> = {
    draft: "작성 중",
    submitted: "제출 완료",
    reviewing: "검토 중",
    completed: "신고 완료",
    amended: "경정청구",
  };
  return labels[status];
}

getStatusBadgeColor 和 getStatusDisplayText 虽然使用了 FilingStatus 这一领域概念，但它们做的事情是页面呈现。徽章颜色变化并不会对业务造成任何影响。把这类函数放进 domain/filing.ts，会让领域模块越来越臃肿，真正的领域逻辑和表现层逻辑也会混在一起。

分离领域模型与 ViewModel

有一种实用的方法可以解决这个问题：在同一个领域文件夹中，把 ViewModel 分离到单独的文件里。与 .ui.ts 相比，采用 .viewModel.ts 这一命名能自然地与 MVVM 模式中的 ViewModel 概念衔接，因为“把领域数据转换成适合页面呈现的形式”这一职责能够直接从名称中体现出来。

domains/
└── filing/
    ├── filing.ts              # 순수 도메인 모델 + 도메인 로직
    ├── filing.viewModel.ts    # ViewModel (표현 변환 계층)
    ├── filing.test.ts         # 도메인 로직 테스트
    └── filingMapper.ts        # API ↔ 도메인 변환

把前面看到的 getStatusBadgeColor、getStatusDisplayText 原样移到 filing.viewModel.ts。此外，像 getFilingTypeLabel(type: FilingType): string 这样把申报类型转换成韩文标签的逻辑，也集中放在这里。filing.ts 只负责业务规则，filing.viewModel.ts 只负责页面呈现。

关键在于依赖方向。filing.viewModel.ts 会导入 filing.ts，但 filing.ts 绝不能导入 filing.viewModel.ts。领域不了解表现层，而表现层了解领域。可以把它看作 Robert C. Martin 所说的依赖规则（Dependency Rule）的缩小版。

我认为共同变化的文件应该放在同一目录，因此把它们放在了同一个文件夹。给 FilingStatus 类型添加新值（例如 'rejected'）时，filing.ts 和 filing.viewModel.ts 都需要修改。由于位于同一个文件夹，修改范围一目了然。

边界与内聚

与分离领域逻辑同样重要的是：边界应该画在哪里。下面整理几种我在实际工作中经常遇到的边界判断问题。

前端处理的数据大致来自四种来源。

• 服务端数据：通过 API 响应获得的数据
• 派生数据：由服务端数据计算得到的数据
• 用户界面状态：用于控制页面的状态，以及用户交互
• 用户输入：正在表单中输入的数据

如果把这四类数据混进同一个类型，领域模型就会受到污染。

// 안티패턴: 모든 것이 섞인 타입
interface TaxFiling {
  // 서버 데이터 (도메인)
  id: string;
  status: FilingStatus;
  determinedTax: number;
 
  // 파생 데이터 (도메인)
  refundAmount: number;
  canAmend: boolean;
 
  // UI 상태 (표현)
  isExpanded: boolean;
  activeStep: number;
 
  // 임시 상태
  editingDeductions: Deduction[];
}

这个类型把领域概念、用户界面状态和临时数据都塞进了同一个篮子。每次 activeStep 变化，就等于更新了一次申报领域。（表单步骤变化并不是业务事件。）

改进方法是按照边界拆分类型。领域模型只包含 id、status、determinedTax 等业务概念；用户界面状态（FilingFormViewState）只包含 isExpanded、activeStep 等页面控制信息；表单状态（DeductionEditForm）只保存正在输入的临时数据。

这样一来，每种类型都只有一个变化原因。领域类型只在税法变化时修改，用户界面状态只在页面设计变化时修改，表单状态只在输入体验变化时修改。

把共同变化的内容放在一起

Eric Evans 的 DDD 中有一个**聚合（Aggregate）**概念，指的是“把一组相关对象作为一个单元来处理”。前端无需照搬这一概念，但其中的核心原则值得借鉴：把共同变化的数据和规则放在一起。

以税务服务为例，Income（收入）和 ExpenseRate（费用率）总是共同变化。收入类型变化时，适用的费用率也会变化，综合所得金额的计算也会受到影响。因此，应把这些内容聚合到同一个文件 domain/tax.ts 中。

相反，TaxFiling（申报单）可以独立于税额计算而变化。即使申报单的状态转换规则发生变化，税率计算逻辑也不会受到影响。因此，把它分离到 domain/filing.ts 才是合适的做法。

이렇게 묻자: "A가 변할 때 B도 반드시 변해야 하는가?"
  → Yes: 같은 모듈에 둔다 (Income + ExpenseRate + TaxBracket)
  → No: 분리한다 (Tax 계산 ↔ Filing 상태관리)

类与函数式风格

读到这里，可能会产生一个根本问题：前面的示例都是 interface + 纯函数的组合，如果用类来表达领域，内聚不是会更自然吗？

确实如此。使用类来表达领域，会把数据与行为封装在同一个对象中，因此内聚性能够直接体现在代码结构里。

class TaxFilingModel {
  constructor(
    public readonly id: string,
    public readonly status: FilingStatus,
    public readonly taxYear: number,
    public readonly filingType: FilingType,
    public readonly determinedTax: number,
  ) {}
 
  canEdit(): boolean {
    return this.status === "draft";
  }
 
  canAmend(): boolean {
    return this.status === "completed" && this.filingType !== "amendment";
  }
 
  canSubmit(): boolean {
    return this.status === "draft" && this.determinedTax >= 0;
  }
}
 
const filing = new TaxFilingModel(
  "F-001",
  "completed",
  2025,
  "regular",
  547200,
);
 
filing.canAmend();

使用类时，行为归属于数据，而且调用处的主语非常明确。filing.canAmend() 读起来像自然语言一样直观，主语（filing）和动词（canAmend）清楚地结合在一起。就像写下 jihoon.eat('감자탕')，马上就能读出“Jihoon 吃脊骨土豆汤”。

而函数式风格是这样的。

canAmend(filing);
eat("jihoon", "감자탕");

在函数式风格中，数据存在于函数之外。上面第一段代码接收 filing 数据作为参数并执行某种行为；eat 函数则接收 jihoon 和 감자탕 两项数据作为参数来执行行为。

这样一来，主语和动词的结合会变得松散。只有打开文件或查看类型签名，才能知道 canAmend 函数与 TaxFiling 有关。如果同一文件中混杂着 canAmend(filing)、canEdit(filing)、calculateTax(taxableBase) 等函数，就可能很难一眼看出每个函数分别属于哪个领域。

那么，应该使用类吗？

坦率地说，答案是**“视情况而定”**。但根据我的经验，在 React + TypeScript 环境中，类并非万能，这背后有一些现实原因。

1. 与 React 状态管理之间的摩擦

React 的状态管理与**普通对象（Plain Object）**配合得最自然。useState 和 useReducer 在技术上可以保存任何值，Redux DevTools 本身也不会移除类实例的原型。但如果 Redux/Zustand 持久化中间件以 JSON 保存并恢复状态，类实例就会在 JSON.stringify → JSON.parse 循环中丢失方法和原型，退化为普通对象。从 React Server Component 向 Client Component 传递 props 的边界则有另一种限制：它只接受受支持的可序列化（serializable）值，因此任意类实例从一开始就无法通过该边界。

来看下面的代码。

const [filing, setFiling] = useState(
  new TaxFilingModel("F-001", "draft", 2025, "regular", 0),
);

仅仅更新 React 状态并不会让 filing 失去 TaxFilingModel 实例的身份。但如果 Redux/Zustand 持久化以 JSON 保存并恢复它，恢复后的值可能变成没有方法的普通对象，此时无意间调用 filing.canAmend() 就可能触发运行时错误。从 React Server Component 传递到 Client Component 时，失败会更早发生，因为类实例不是受支持的可序列化 props 值。

2. 难以保证不可变性

React 基于**引用相等性（referential equality）**检测状态变化。如果类实例的方法执行 this.items.push(...) 之类的内部修改，引用保持不变，React 就不会触发重新渲染。因此，最终只能让 addDeduction(item) 像 return new DeductionList([...this.items, item]) 一样，每次都返回一个新实例。这样一来，类的优势——“封装后的状态变更”——也就失去了意义，代码与函数式更新并没有太大区别。

在函数式风格中获得内聚的策略

那么，在函数式风格中，如何改善 eat('jihoon', '감자탕') 这种内聚松散的问题？下面介绍三种我认为有效的方法。

1. 通过模块命名空间实现内聚

这是最直观的方法。把文件（模块）本身按领域组织，并在导入时使用命名空间。直接使用前面定义的 domain/filing.ts 即可。

import * as FilingModel from "../domain/filing";
 
FilingModel.canEdit(filing);
FilingModel.canAmend(filing);
FilingModel.canSubmit(filing);

FilingModel.canAmend(filing) 虽然不如 filing.canAmend() 简洁，但至少能直接从代码中看出这个函数属于申报领域，也不会再出现函数跨多个领域混杂的风险。

2. 统一把第一个参数作为领域主体

函数式风格还有另一种表达内聚的约定：**始终把第一个参数设为“行为主体”。**将签名统一为 canAmend(filing)、calculateTotalIncome(income) 这样的形式后，canAmend(filing) 就可以理解为“询问 filing 是否可以修改”。这也与 Unix 的流水线思维（data |> transform）一脉相承。事实上，Go 语言的方法接收者正是这种模式，Rust 的 impl 块把 self 作为第一个参数也是同样的思路。

3. 用领域对象工厂函数聚合行为

想念类的内聚性时，可以使用这种模式。工厂函数一次性返回领域对象及其行为。

export function createFilingModel(data: TaxFiling) {
  return {
    ...data,
    canEdit: () => data.status === "draft",
    canSubmit: () => data.status === "draft" && data.determinedTax >= 0,
    canAmend: () =>
      data.status === "completed" && data.filingType !== "amendment",
  } as const;
}
 
const filing = createFilingModel(rawFiling);
filing.canAmend();
filing.canEdit();

这种模式能够同时获得类的表现力（filing.canAmend()）和通过对象字面量组合行为的实用性。不过，返回的对象包含函数属性，因此它本身并不是可 JSON 序列化的数据。它每次还会创建新的函数对象，但对于前端处理的数据规模来说，几乎不会构成性能问题。

应该分离到什么程度？

阅读 Clean Architecture 时，会看到一种理想结构：划分 3～4 个层，并定义端口与适配器。但在现实中，把这套结构应用于所有项目，可能会造成过度设计（over-engineering）。

我认为实用的判断标准如下。

• **将领域类型与 API 响应类型分离。**无论使用 interface 还是 type，都应在单独的文件中定义前端使用的领域概念。
• **把包含业务规则的逻辑移出组件。**不放在 domain/ 文件夹也没关系，重要的是把它写成不依赖 React 的纯函数。
• **集中完成 API 响应 → 领域模型的转换。**无论使用转换器函数还是 Zod schema，都要建立一种结构：只需修改这一处，变化就不会继续传播。

如果项目变得更加复杂，还可以进一步考虑以下做法。

• 按限界上下文划分文件夹。Toss 前端团队也强调“把共同变化的文件放在同一目录”这一原则。按领域划分文件夹后，导入路径会自然地显露领域边界。
• **引入用例层。**当领域逻辑的组合变得复杂时，就需要一个应用层，将“查询收入信息 → 应用费用率 → 计算扣除项目 → 计算税额 → 确定退税额”这一场景封装成一个函数。

src/
├── domains/
│   ├── tax/
│   │   ├── tax.ts                  # 세액 계산 도메인 (세율, 공제, 계산 파이프라인)
│   │   ├── tax.viewModel.ts        # 세액 표현 (금액 포맷, 구간 라벨)
│   │   ├── tax.test.ts             # 세액 계산 테스트
│   │   └── incomeMapper.ts         # 홈택스 API ↔ 도메인 변환
│   ├── filing/
│   │   ├── filing.ts               # 신고 상태 도메인 (상태 전이, 권한)
│   │   ├── filing.viewModel.ts     # 신고 표현 (상태 배지, 라벨)
│   │   ├── filing.test.ts
│   │   └── filingMapper.ts
│   └── deduction/
│       ├── deduction.ts            # 공제 항목 도메인 (자격 조건, 한도)
│       └── deduction.viewModel.ts
├── hooks/                           # React 의존 로직
├── components/                      # UI 컴포넌트
└── api/                             # API 호출

即使同属税务这一领域，税额计算（tax）、申报管理（filing）、**扣除项目（deduction）**也会被分成彼此独立的子领域。即使税率发生变化，申报状态转换逻辑也不会受到影响；即使新增扣除项目，申报单的提交流程也保持不变。这就是限界上下文在实践中的应用。

结语

总而言之，领域是我们要解决的问题范围；领域模型是对这一问题进行选择性抽象后形成的概念体系；领域对象模型是用代码实现这套概念体系的结果；领域对象则是实现中的各个具体对象。

而在前端实践这些概念，并不只是划分文件夹，更是要有意识地判断多层边界。“这是业务规则，还是表现层逻辑？”“这些数据属于领域状态，还是用户界面状态？”“这个函数的内聚性足够吗？”只要养成反复提出这些问题的习惯，代码结构自然会逐渐改善。

当然，并非所有项目都需要完整搭建 Clean Architecture 的各个层。为简单的增删改查应用划分四个层，并给每个领域都应用工厂模式，未免本末倒置。在类的优雅内聚与函数式风格的实用灵活之间，答案取决于项目复杂度和团队语境。

没有唯一正确答案。但至少，**“不知道领域是什么就开始写代码”与“识别领域、判断边界并有意识地分离代码”**之间有着明确差异。希望读者也能在自己的项目中问一次：“这里的领域是什么？这段代码又应该放在哪里？”

参考资料

我平时就对代码审查和重构很感兴趣，因此参与了 Toss 发布的一项形式颇为有趣的 Frontend Fundamentals 模拟考试。题目提供了一个会议室预订应用，要求对它进行重构。项目还附带了测试代码，为验证重构过程中功能是否遭到破坏提供了安全网。

最终，我用了两天时间完成重构，也想借此整理一下过程中的感受。

初次面对代码时

第一次打开代码时，我做的第一件事就是阅读测试规格。因为测试代码是最如实说明这个应用应该做什么的文档。我浏览了 App.easy.spec.tsx 和 App.hard.spec.tsx，了解了应用的整体需求。

接着查看实际代码时，最先映入眼帘的是两个单体组件。

• ReservationStatusPage 是一个 400 多行的组件，日期选择、时间线可视化、预订详情工具提示、我的预订列表和取消功能全都塞在同一个文件里。
• RoomBookingPage 是一个 300 多行的组件，筛选器、房间列表、创建预订逻辑和 URL 参数同步交织在一起。

阅读代码时，比起先下结论说“需要改进”，我更专注于对代码的特性进行分类。也就是区分哪些代码承载领域信息，哪些具有工具性质，哪些属于纯粹的 UI 层。

// 도메인 정보: 장비 라벨, 타임 슬롯 등 비즈니스 상수
const EQUIPMENT_LABELS: Record<string, string> = {
  tv: 'TV', whiteboard: '화이트보드', video: '화상장비', speaker: '스피커',
};
 
// 유틸리티: 날짜 포맷, 시간 변환
function formatDate(date: Date): string { ... }
function timeToMinutes(time: string): number { ... }
 
// 서버 상태: 인라인 useQuery, useMutation 호출
const { data: rooms = [] } = useQuery(['rooms'], getRooms);
const { data: reservations = [] } = useQuery(['reservations', date], () => getReservations(date));
 
// UI + 비즈니스 로직 혼재: 필터링, 정렬, 충돌 감지가 JSX 사이에 산재

完成这样的特性分类后，该从哪里着手也就自然清晰起来。我在各个代码区域旁加上简短注释，记录改进方向。（感觉就像刚进现在这家公司时迁移基于 jquery 的项目一样）

那么，究竟应该从哪里开始呢？

制定重构策略

我计划按照以下顺序进行重构。

1. 处理服务器代码：拆分 query、mutation
2. 拆分领域逻辑：Equipment、Room、Reservation 模型
3. 声明类型：梳理基于领域模型的类型体系
4. 拆分工具函数：日期格式化、时间线计算等
5. 拆分 UI 层：按关注点将组件划分为节奏合适的单元
6. 抽象与关注点分离：错误/加载处理、查询键管理

之所以选择这个顺序，是为了沿着依赖方向从外到内推进。先整理基础设施（服务器代码、工具），确立领域模型，最后再打磨 UI。如果先拆分 UI 组件，尚未整理好的领域逻辑和查询代码可能就得在多个组件之间反复搬动。

策略已经定好，接下来逐项付诸实践。

先整理服务器代码和工具

拆分日期显示工具

我最先处理的是 formatDate 函数，因为两个页面里分别内联定义了同一个函数。

// utils/formatYYYYMMDD.ts
export function formatYYYYMMDD(date: Date): string {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
  const date = String(date.getDate()).padStart(2, '0');
  return `${year}-${month}-${date}`;
}

改动虽小，但作为重构的第一个提交却有着重要意义。先从最独立、副作用最少的部分入手，再确认测试是否依然通过，就像一次热身。

拆分 React Query hook

接下来，我把直接写在组件内部的 useQuery、useMutation 调用拆到了单独的文件中，并利用 queryOptions 模式将查询配置整理为可复用单元。

在这个过程中，也显式定义了 remotes.ts 中的 API 响应类型。原先以 any 流转的类型，变得明确为 GetRoomsResponse、GetReservationsResponse 等。

基础设施层已经整理完毕，接下来把目光转向领域模型。

拆分领域模型

这次重构最重要的转折点，是将领域模型拆分到独立的 models/ 目录中。

原有代码把 EQUIPMENT_LABELS、TIME_SLOTS 等业务常量声明在组件文件顶部。Room 或 Reservation 的类型也只存在于服务器处理器（_tosslib/server/types.ts）中，在客户端代码中使用时几乎等同于 any。

// models/equipment.ts
export const EQUIPMENT_LABELS = {
  tv: 'TV', whiteboard: '화이트보드', video: '화상장비', speaker: '스피커',
} as const;
 
export type Equipment = keyof typeof EQUIPMENT_LABELS;
export const ALL_EQUIPMENT = Object.keys(EQUIPMENT_LABELS) as Equipment[];

// models/reservation.ts
export interface Room {
  id: string;
  name: string;
  floor: number;
  capacity: number;
  equipment: Equipment[];
}
 
export interface Reservation {
  id: string;
  roomId: string;
  date: string;
  start: string;
  end: string;
  attendees: number;
  equipment: Equipment[];
}

为什么拆分领域模型如此重要？如果业务逻辑依附于 UI 组件，修改这段逻辑时，就不得不连组件的渲染逻辑一起查看。反过来，如果它独立存在于 models/ 目录，业务规则的变更就可以与 UI 分离。当然，现实中很难做到完美分离，但关键至少是构建一种能让人预测“这段逻辑应该在这里”的结构。

既然领域模型已经拆分，UI 又能变得多轻量呢？

拆解组件

ReservationStatusPage

这是带来最显著变化、同时也最耗时的一次提交。我将 385 行的单体组件拆分成了以下结构。

ReservationStatusPage/
├── index.tsx                    # 페이지 레벨
└── components/
    ├── DateSelector.tsx         # 날짜 선택 UI
    ├── ReservationTimeline.tsx  # 타임라인
    └── MyReservation.tsx        # 내 예약 목록 + 취소

拆分标准是**“这段代码能否独立表达意义”**。时间线可视化接收某个日期的预订数据并绘制网格，是一个独立的关注点。我的预订列表负责查询和取消用户的预订数据，同样是一个独立的关注点。它们没有理由待在同一个文件里。

拆分后，index.tsx 只承担**协调者（orchestrator）**的角色。它仅负责状态管理、消息展示和组合子组件，而将实际的数据获取和渲染细节交给子组件。

RoomBookingPage

预订页面也按照同样的原则进行了拆分。

RoomBookingPage/
├── index.tsx                    # 페이지 레벨
├── components/
│   ├── BookingFilter.tsx        # 날짜, 시간, 인원, 장비, 층 UI
│   └── AvailableRoomList.tsx    # 예약 가능 방 목록
└── hooks/
    └── useBookingParams.ts      # URL searchParams 기반 상태 관리

这个过程中有一个有趣的取舍。起初，我尝试引入 react-hook-form + zod 来进行表单校验。但最终还是将它移除，换成了自定义 hook useBookingParams。关于这个决定，后面还会更详细地谈到。

读到这里，自然会浮现出一个问题：究竟应该抽象到什么程度？

抽象的适当边界

这一节是我在本次模拟考试中思考最多的部分。

嵌套条件语句，应该拆到什么程度

判断房间能否预订的逻辑结合了多个条件：容纳人数是否足够、是否具备所需设备、是否符合偏好的楼层，以及时间是否冲突。在原始代码中，所有条件都内联写在一个 filter 回调里。

我将其提取到 models/roomFilter.ts 时，把每个条件拆成了有名字的函数。

const isEnoughCapacity = (room: Room, attendees: number) => room.capacity >= attendees;
const hasRequiredEquipment = (room: Room, equipment: Equipment[]) =>
  equipment.every(eq => room.equipment.includes(eq));
const isOnPreferredFloor = (room: Room, floor: number | null) =>
  floor === null || room.floor === floor;
const hasNoTimeConflict = (room: Room, reservations: Reservation[], date: string, start: string, end: string) =>
  !reservations.some(reservation => reservation.roomId === room.id && reservation.date === date && reservation.start < end && reservation.end > start);
 
export function filterAvailableRooms(rooms: Room[], reservations: Reservation[], params: Params): Room[] {
  return rooms
    .filter(room =>
      isEnoughCapacity(room, params.attendees) &&
      hasRequiredEquipment(room, params.equipment) &&
      isOnPreferredFloor(room, params.floor) &&
      hasNoTimeConflict(room, reservations, params.date, params.startTime, params.endTime)
    )
    .sort((a, b) => {
      if (a.floor !== b.floor) return a.floor - b.floor;
      return a.name.localeCompare(b.name);
    });
}

这里的关键在于，只有在能够明确命名抽象时才拆分成函数。像 isEnoughCapacity、hasRequiredEquipment 这样的名字，无需查看实现也能预测它们的作用。如果名字只能像 processRoomConditions 一样模糊，这种抽象反而会增加读者的认知负担。

当然，这并不意味着它就是标准答案。我的判断标准只是：**“仅凭函数名能否预测其行为？”**如果可以预测，就进行抽象；如果不能，保留内联反而可能更有利于可读性。

searchParams 与 form state

预订筛选状态应该放在哪里，也是让我颇费思量的问题。原始代码使用 useState 管理各项筛选值，再通过 useEffect 与 URL searchParams 同步。

// 원본: useState + useEffect 동기화 방식
const [date, setDate] = useState(searchParams.get('date') || formatDate(new Date()));
const [startTime, setStartTime] = useState(searchParams.get('startTime') || '');
 
// ... 6개의 개별 상태
useEffect(() => {
  const params: Record<string, string> = {};
  if (date) params.date = date;
 
  // ... 모든 상태를 searchParams에 동기화
  setSearchParams(params, { replace: true });
}, [date, startTime, endTime, ...]);

我一开始引入了 react-hook-form + zod，尝试以表单的方式管理。但最终还是将其移除，改用把 **searchParams 作为单一事实来源（Single Source of Truth）**的 useBookingParams hook。

// useBookingParams: searchParams가 곧 상태
export function useBookingParams() {
  const [searchParams, setSearchParams] = useSearchParams();
 
  const params = useMemo<BookingParams>(() => ({
    date: searchParams.get('date') || formatYYYYMMDD(new Date()),
    startTime: searchParams.get('startTime') || '',
    // ...
  }), [searchParams]);
 
  const updateParam = useCallback(<K extends keyof BookingParams>(key: K, value: BookingParams[K]) => {
    setSearchParams(prev => {
      // 기존 파라미터 병합 후 업데이트
      return result;
    }, { replace: true });
  }, [setSearchParams]);
 
  return { params, updateParam };
}

这一决定的核心依据，是我认为**“让状态各自独立变动并不合适”**。如果 useState 和 searchParams 各自持有状态，就可能因同步时机不同而产生不一致。反之，如果只用 searchParams 作为状态，URL 就等同于应用状态，同步问题本身也就消失了。用户分享 URL 时能够复现相同的筛选状态，则算是额外的好处。

在其他参与者的复盘中，我也发现了类似的思考。“将 URL searchParams 统一为单一事实来源”“选择把各个筛选器 prop 合并为一个 filter 对象。”表达方式虽然不同，但都意识到了同一个问题：“需要将分散的状态归拢成一个概念。”

稳定性

Suspense 与 ErrorBoundary

组件结构确定后，我才添加了错误和加载状态处理。之所以顺序重要，是因为只有在组件树确定后，才能判断边界（Boundary）应该设置在哪里。

我使用 react-error-boundary 库，为每个独立的数据获取单元分别包裹 ErrorBoundary 和 Suspense。这样即使时间线加载失败，我的预订列表仍能正常显示，反之亦然。

{/* 각 영역이 독립적으로 에러/로딩을 처리 */}
<ErrorBoundary FallbackComponent={ErrorFallback} resetKeys={[date]}>
  <Suspense fallback={<Loading message="예약 현황을 불러오는 중..." />}>
    <ReservationTimeline date={date} />
  </Suspense>
</ErrorBoundary>
 
<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Suspense fallback={<Loading message="내 예약을 불러오는 중..." />}>
    <MyReservation onCancel={handleCancel} />
  </Suspense>
</ErrorBoundary>

集中管理 Query Key

重构过程中，随着查询 hook 被拆分，query key 也开始分散到多个文件里。于是，在 mutation 的 onSuccess 中执行 invalidation 时，很难追踪究竟应该使用哪个 key。

我引入 @lukemorales/query-key-factory，改为集中管理查询键。

// queries/queryKeys.ts
export const roomKeys = createQueryKeys('rooms', {
  list: { queryKey: null, queryFn: () => remotes.getRooms() },
});
 
export const reservationKeys = createQueryKeys('reservations', {
  list: (date: string) => ({ queryKey: [date], queryFn: () => remotes.getReservations(date) }),
  my: { queryKey: null, queryFn: () => remotes.getMyReservations() },
});

这样就能以 useSuspenseQueries({ queries: [roomKeys.list, reservationKeys.list(date)] }) 的形式使用，让查询键和获取函数始终一起移动。此外，我还把 route 路径提取为 PATHS 常量，移除了硬编码字符串。

出题者的意图是什么

完成重构后，我退一步重新思考：这场模拟考试究竟想考察什么？

阅读其他参与者的复盘时，我发现了一个有趣的共通点。几乎所有文章里都出现了这样一句话：**“代码不是靠阅读，而是靠预测。”**我们的大脑并非逐行解释代码，而是根据经验中积累的模式进行预测式阅读。当预测落空时，认知负担就会急剧增加。

从这个角度来看，模拟考试评估的不只是编码能力，而是**“能把写给同事阅读的代码变得多可预测”**这种协作能力。（也许读懂出题者和同事的心，才是软件工程师真正的能力）

查看其他参与者的复盘后，**“理解别人写的代码并不容易”“优先设计接口很重要，但面对庞大的现有代码时，这种方法也可能动摇”等内容让我很有共鸣。我也有过类似的经历。当现有代码已经能够运行时，人很容易产生替它的结构寻找合理解释的诱惑，也就是“代码都已经能跑了，有必要吗？”这样的念头。但模拟考试的核心，正是越过这种诱惑，以“不是我，而是其他人阅读这段代码时，能多快理解它；能否依据自己的认知判断并逐步解决问题”**为标准做出判断。

从重构中学到的事

**重构顺序决定结果。**从外部（基础设施）向内部（UI）推进，是避免中途纠缠的稳妥路径。在工具和领域模型都梳理完毕后再拆分组件，各组件依赖什么便一目了然。

**判断是否抽象的标准是“命名”。**如果提取成函数或变量后，其名称能够说明行为，就值得抽象。如果名字不可避免地变得模糊，保留内联反而可能是更好的选择。

**状态的位置就是架构。**需要一起变化的状态应该放在同一个地方。与其同步 useState 和 searchParams，不如只把 searchParams 作为事实来源，这在结构上更加健康。

结语

完成题目后，我和两位同事聊了聊。独自阅读代码时看不见的问题，在通过对话梳理思路的过程中逐渐显露出来。当别人对我觉得理所当然、随手略过的结构选择问出“为什么这么做？”时，我才看见自己此前没有意识到的判断盲点。

AI 确实正在大幅缩短编写和审查代码所需的时间。但即便如此，我依然认为代码审查和每日会议很重要，原因正是这种经历。AI 可以验证代码的一致性，但指出**“你遗漏的是这个视角”**，终究还是要靠共享相同语境的同事。发现我未曾看到的部分，再通过这些发现让产品更加稳定——这或许就是协作的本质。

在解决问题、编写代码的过程中，并不存在唯一的正确答案。参加同一场模拟考试的其他人也选择了各自不同的路径，并且都有自己的依据。重要的是，能够解释**“为什么要这样写”**。也建议各位读者偶尔用第一次看到自己代码的人的视角重新审视它。仅仅这一种视角，就可能成为决定代码质量的最有力标准。

在我还是初级工程师时，读过的文章中给我印象最深的一篇，是裴辉东的《前端工程师职业路线图：面向初级工程师的三条专业发展路径》。文章将前端工程师的职业发展分为三条路径：Web 专精（Software Engineer）/ 产品专精（Product Engineer）/ 运营专精（Full-Stack Engineer），还进一步梳理了“优秀工程师的五项基本能力”和“成为资深工程师的三个要点”。那时，最大的议题还是思考自己该在每条路径上积累哪些能力。然而，读完那篇文章还不到两年，议题本身就彻底变了。

最近和工程师同事们聊天时，我能感觉到，大家的烦恼和过去几年听到的已经不太一样了。

• “公司引入 AI 之后，把设计稿丢给它，基本都能做出来。方便倒是方便……”
• “招聘市场冷得厉害。”
• “直接合并 AI 写的代码又有点怕，可要逐一检查，效率又会下降，挺让人纠结的。”

我也经历过类似的阶段，现在仍然身处其中。一两年前，我还只把 AI 当作“好用的辅助工具”，如今却已经到了无法想象没有 AI 要怎么开发的程度（我写这篇文章时，也在请 Claude 帮忙做调研）。这篇文章算是裴辉东那篇文章的续篇。我想从自己的视角梳理一下：这段时间里，景象发生了怎样的变化；面对变化后的环境，前端工程师又该进一步培养哪些能力。

这次我也尽可能查找并核验了大量资料，但这个领域变化实在太快，文章发布时，其中部分内容可能已经过时，还请大家谅解。如果有值得反驳或讨论之处，欢迎随时留言。

“现在不是什么都能让 AI 做了吗？”

首先，有一件事必须说清楚：“AI 什么都能做”这句话是真的吗？到什么程度是真的，又从哪里开始只是幻想？

2025 年 2 月，OpenAI 联合创始人、前特斯拉 AI 总监 Andrej Karpathy 在 Twitter 上写下了这样一句话。

出现了一种我称之为“vibe coding”的新编程方式：你完全顺着感觉走，拥抱指数级增长，甚至忘记代码本身的存在。

There's a new kind of coding I call 'vibe coding', where you fully give in to the vibes, embrace exponentials, and forget that the code even exists.

所谓 vibe coding，简单来说就是“把键盘交给 AI，自己只用自然语言描述想要的东西”的编程方式。没有架构文档，没有样板代码，也不用搜索分号。代码就这样跟着感觉跑起来。不到一年，这个词就成了英语开发者社区里的标准用语。

但整整一年后的 2026 年 2 月，同一位 Karpathy 却往后退了一步。他提议用 “agentic engineering” 取代 vibe coding。两者的区别很明确。

• Vibe coding：描述自己想要什么，然后接受产出
• Agentic engineering：设计系统、明确约束，再用 AI 加速实现那些已经在脑中推理完成的方案

一年前，“只要吩咐一下，它就全都能做出来”还是基本共识；如今，“设计该让 AI 做什么、怎么做的能力”本身，已经成为一种工程能力。这股趋势并不只来自某一个人的推文。同一时期，Google 工程师 Addy Osmani 出版了《Beyond Vibe Coding: From Coder to AI-Era Developer》，并明确指出：“AI 只是助手，不是可以自主信赖的程序员。你才是资深开发者，LLM 的存在是为了加速你的判断。”

工具正在狂飙

工具阵营也顺应这股趋势快速演进。截至 2026 年 5 月，最常被提及的编程工具包括 Cursor、Claude Code、GitHub Copilot、Windsurf、v0 by Vercel、Bolt.new 和 Devin。

v0 的变化尤其具有象征意义。Vercel 使用了“90% problem”这个说法，意思是现实开发中 90% 的工作都发生在现有代码库和基础设施之内。起初，只要能做好全新项目原型就够了；如今，v0 已经可以直接导入 GitHub 仓库进行开发、强制遵循设计系统，并自动读取部署环境变量。对于资深工程师提出的“AI 不就只会做好玩具式演示吗”这一质疑，工具阵营正在亲自作答。

大型科技公司的代码库最能体现这种变化。

Google 的 Sundar Pichai 在 2024 年 10 月的第三季度财报电话会议上宣布，“超过 25% 的新代码由 AI 生成，再由工程师审核和批准”，到 2025 年 4 月，这一比例已升至 30% 以上。Microsoft 的 Satya Nadella 在 2025 年 4 月的 LlamaCon 上透露，“我们的代码中，最多有 30% 是 AI 编写的”。Meta 的内部目标甚至已经提高到“截至 2026 年上半年，让 65% 的工程师使用 AI 生成至少 75% 的提交内容”。

韩国国内的趋势也没有不同。Toss 为了让开发者不再需要自己找文档、提升开发者体验，搭建了基于 AI 的文档系统，并更进一步探讨了“AI 时代，取消设计师岗位之后发生的事”之类的话题。Daangn 每周二通过 AI Show & Tell 分享各团队的实验，还开始打出“超越工程师，成为构建者”的招聘口号。Woowa Brothers 则通过“在 AI 编写代码的时代，你还愿意成为开发者吗？”等文章传递这样的信息：“开发者的本质不在代码，而在于定义和解决问题的能力。”

但数字讲述的是另一个故事

只看到这里，很容易得出“现在只要吩咐一下，什么都能做”的结论。但真正查看数据后，故事却有些不同。

先看综合分析软件开发现状的 2025 Stack Overflow Developer Survey 中的数据。

• 84% 的开发者表示正在使用或计划使用 AI 工具。（高于 2024 年的 76%）
• 51% 的专业开发者每天都使用 AI 工具。
• 但对 AI 工具的好感度（positive sentiment）反而下降了。2023 年和 2024 年都在 70% 以上，2025 年却降到了 60%。
• 从业 10 年以上的资深开发者对 AI 输出的信任度最低。

总结起来就是：“大家确实都在用，但越用越不放心。”

非营利研究机构 METR 在 2025 年开展的一项实验，更鲜明地展现了认知与现实之间的落差。这是一项对照实验：16 名熟练的开源开发者平均拥有 5 年经验和 1,500 次提交，研究者让他们完成 246 项任务，并随机决定是否允许使用 AI。结果如下。

• 开始前，开发者预测“使用 AI 会快 24%”。
• 完成任务后，他们仍自我评价“感觉大约快了 20%”。
• 但实际测量结果却是：慢了 19%。

研究人员指出的原因很有意思。AI 生成代码的接受率低于 44%；即使代码被拒绝，审查和测试它也要花时间；就连被接受的代码，也需要大量时间来审核和修改。明明变慢了，却误以为自己变快了——这种落差正是资深开发者对 AI 日益怀疑的原因之一。

此外，“AI 编写的代码质量”本身也并不理想。来看 Veracode 让 100 多个 AI 模型编写代码的实验。

• AI 生成代码中有 45% 包含 OWASP Top 10 安全漏洞。
• XSS（跨站脚本）防护失败率为 86%。
• 日志注入（Log Injection）防护失败率为 88%。
• 另一项研究报告称，AI 代码的漏洞密度是人类代码的 2.7 倍。

尤其是与前端直接相关的 XSS 防护失败率高达 86%，值得更严肃地看待。直接合并 AI 写出的表单输入框究竟意味着什么，这个数字已经说明得很清楚。（有过前端安全审计经验的开发者，哪怕亲手写 dangerouslySetInnerHTML 时也会觉得别扭、心里不安；AI 悄悄塞进去的就更让人害怕了。）

质量方面也释放出相似的信号。GitClear 分析了 2020 至 2024 年间 2.11 亿行代码变更，结果如下。

• 编写后两周内被回滚（reverted）的代码比例（Code Churn）：2020 年 5.5% → 2024 年 7.9%
• 重构所占比例：2021 年 25% → 2024 年低于 10%
• 复制粘贴（克隆）比例：2021 年 8.3% → 2024 年 12.3%（2025 年更是增长到四倍）

这并不难解读。快速产出代码的能力增强了，但写出值得再次打磨的代码的能力却下降了。分析《财富》50 强企业的 Apiiro 数据给出的结果更为强烈：借助 AI 开发的开发者，提交数量是同事的 3～4 倍，却制造出 10 倍的安全问题。权限提升路径（privilege escalation）暴增 322%，架构设计缺陷则暴增 153%。

AI 取代了什么，又没能取代什么

工具在狂飙，数据却很微妙。那么 AI 究竟取代了什么，又有哪些事情尚未取代？只有把这条界线划清楚，我们才知道该把时间投入在哪里。

被取代的，是开发者亲手输入代码的那部分工作。编写样板代码和重复代码的场景减少了；只要有设计稿，几分钟内就能产出符合约定水准的页面；搜索语法和 API 所需的时间，以及学习曲线，也都大幅缩短。简而言之，AI 拉平了“生产速度”。

但在“判断”这一领域，它还没能取代人。（准确地说，更接近于“尚未达到我们的期待”。虽然每个人运用 AI 的能力存在差距，但这里以平均使用体验为准展开讨论。）

首先遇到的难题，是将需求转化为规格。把模糊的业务需求转化成明确的边界情况和状态机，仍然更需要人类深度参与。理解系统层面的影响也是如此：这个组件会如何影响 bundle、依赖项能否 tree-shaking、数据获取模式会怎样影响 Core Web Vitals 中的 INP（Interaction to Next Paint）得分——面对这类问题，即便 AI 给出了看似合理的答案，最终仍要由人再看一遍才能放心。

如前文所述，45% 的 OWASP 漏洞意味着安全与风险评估也不能忽视；除此之外，还有维护设计系统与一致性，即检查新组件是否与现有系统的 token、无障碍规范和交互模式保持一致；以及理解客户与市场语境，即判断为什么需要这项功能、它应该放进哪条用户流程。这些领域同样如此。

最后，借用 yceffort 文章中的说法，“系统复杂度与团队对该系统理解程度之间的差距”就是认知债务（Cognitive Debt）。AI 引入后，这条差距反而扩大得更快，因此缩小差距本身依然是人的职责。

消失的不是开发者，而是开发者过去所做工作的形式。瓶颈已从“创造的速度”转移到“决策的速度”。

同样地，Toss 的《开发者会被 AI 取代吗？》给出了更沉重的判断。文章的核心是：AI 并非取代所有人力，而是在移除学徒阶梯（apprenticeship ladder）。等到如今的资深工程师在 10～20 年后退休时，能够设计复杂系统的下一代人才将会不足。这已不只是“我们公司明年该怎么招聘”的问题，而像是一颗埋在整个行业里的延时炸弹。（我认为这是在这个令人忧虑的时期写得非常好的一篇文章。）

AI 做出的“能运行的第一个版本”占 70%。走到“可以真正提供给用户使用的版本”，剩下的 30% 属于人。而补足这 30% 的能力并非一朝一夕可以形成。这正是学徒阶梯问题的本质：如果编写样板代码和简单组件、让自己“亲手沾上代码”的时间消失了，能够补足那 30% 的人也会一同消失。

裴辉东的原文将写出好代码、最大化当前价值（在快速发布与长期可维护性之间取得平衡）、基于数据决策、帮助同事有效决策、持续学习列为“优秀工程师的五项基本能力”。这五项在 AI 时代依然有效，但其中最后一项正处在最危险的位置。学习本身没有消失，改变的是学习对象。过去我们学习“这个工具怎么用”，现在则应该把时间花在理解“整个系统是如何运转的”上。更可怕的是 Evan Moon 所指出的：“当 AI 代替人编写代码时，大脑的认知负荷会骤然降低。”认知负荷降低听起来是件好事，但危险在于，这种负荷恰恰是学习的材料。越轻松，越难成长。

这里自然会出现一个问题：那么，裴辉东文章中的三条路径（Web 专精/产品专精/运营专精）如今已经没有意义了吗？

我的看法不同。这些路径本身依然有效，只是每条路径都顺应 AI 时代向前演进了一个阶段。下面就来梳理各条路径的景象发生了怎样的变化。

从生产者到“验证者”

在裴辉东的原文中，Web 专精路径被归入 Software Engineer。其核心包括“深入理解并运用互联网、Web 浏览器和 HTML/CSS/JS”，了解 Web 生态工具的优缺点并具备故障排查经验，以及对新技术保持敏锐。通往资深岗位的方向则包括 Web 生态工具厂商工程师 / 前端教育者 / 复杂产品组织的技术负责人。简单说，他们是“深入钻研浏览器与 HTML/CSS/JS 工作原理的人”。直到一两年前，他们最大的武器还是“能比任何人都更准确地写代码”。

AI 时代，他们的价值发生了怎样的变化？如果只看写代码的速度，AI 已经追了上来。但**“准确评估 AI 所写代码的能力”**，反而几乎成了他们独有的优势。

• 使用 AI 的普通人：已经按我的需求实现了，运行也正常。
• 使用 AI 的开发者：虽然能运行，但这个依赖项可能引发某些问题；这种模式按这样的方式改进才更符合约定。再把相关部分检查一遍吧。

前文提到的 Veracode 研究中，有 XSS 防护失败率 86%、日志注入防护失败率 88% 这两项数据。能够发现并解决这些问题的人，正是像我们这样的专业人士。他们会自然演变为负责 AI 产出质量保证（QA）的资深角色。

此外，专业人士的领域中还新增了一个全新的主题：**生成式 UI（Generative UI）**与 AI 界面设计。比如，以流式方式呈现 LLM 回答的聊天 UI、可在中途停止的 abort 控件、Markdown/代码块的渐进式渲染、以内联方式展示工具调用结果的用户体验，以及运用 Vercel AI SDK 或 MCP（Model Context Protocol）进行助手集成。在这个领域，“既准确理解 Web 工作原理，又理解 LLM 的运行特性，并能加以应用和利用的人”正迎来爆发式需求。

自然而然地演进为 Product Engineer

产品专精是受益最大的一条路径。对市场和客户理解深入、经常与外部利益相关者沟通的人，一旦加上 AI，就拥有了强大得多的武器。这条路径的另一项特点，是其资深发展方向中也包括增长工程师、顾问 / 转型为 PM、PO、CPO等向其他职能的扩展。

一个有趣的变化是，这条路径的名称开始成为全球标准。原文其实已经将其称为“Product Engineer”，但我读到那篇文章时，这个表达对我来说还有些陌生。一年后的今天，它已经普及到Vercel 将职位描述中的“Fullstack Engineer”统一改为“Product Engineer”的程度。

Lee Robinson 将 Product Engineer 的核心素质归纳为三项。

• 重视迭代（Iteration）：快速完成部署 → 反馈 → 调整的循环。
• 以客户为中心：直接与客户交谈并改进产品。
• 务实：“所有技术选择都只是手段。”对产品目标没有贡献的工具要果断舍弃。

这里有一个陷阱：如果产品专精工程师只被理解为“做得快的人”，就会很危险。AI 出现后，这种风险更大了，因为“快速塞进功能”如今任何职能的人都可以借助 AI 工具完成。Product Engineer 的差异化优势在于“准确定义客户问题，并用最小的解决方案快速验证”，而不在于“手快”。

在这股趋势下，Design Engineer 开始升级为正式岗位。Vercel 正在把设计工程师作为年薪 20 万美元以上的正式发展路径进行招聘，Linear 和 Stripe 也在朝类似方向发展。这个岗位直接消除了前端与设计之间的交接。AI 能快速把图画出来，因此，同时处理“该画什么 + 画出的结果是否符合一致的设计系统”的能力变得更加稀缺。

AI 编排者

运营专精是变化最剧烈的一条路径。裴辉东的原文将其归为 Full-Stack Engineer，定义是“高度关注项目结构、集成、测试和部署，能亲自处理简单的 API 与基础设施，填补组织空白并改善流程的人”。过去一两年间，运营 AI 智能体本身的职责又叠加在这条路径之上，使其边界迅速扩张。

在梳理2026 年趋势时，Addy Osmani 将**“编排编程智能体（Orchestrating Coding Agents）”**列为核心概念。它意味着不再只是让一个 AI 做事，而是设计并运营一个让多个 AI 智能体同时协作的系统。在同样的脉络下，他提出了名为“agent-skills”的框架，并有人主张将专业工作流、质量门槛和行业最佳实践直接编码进智能体的行为逻辑中。

汇总相关资料后，我认为运营路径工程师接下来需要掌握的新关键词如下。

• MCP（Model Context Protocol）：Anthropic 提出的 LLM 与外部工具连接标准
• AI 治理：管理谁能在什么上下文中使用 AI，以及密钥或机密信息是否会泄露
• 智能体评估（Evaluation）：自动评测智能体产出的流水线
• AI 门禁：PR 合并前自动验证安全与质量，并为 AI 代码添加标签

原文将大型组织的平台团队工程师 / 技术负责人 / 敏捷教练 / 技术项目经理（TPM）/ CTO等岗位列为运营路径的资深发展方向。这些方向如今依然有效，只是可以认为又增加了 “AI 开发基础设施负责人”、**“开发者生产力（DevProd）工程师”**等新岗位。

三条路径各自演进的同时，也有一些能力在所有路径中都变得更加重要。我原本想以五年后为基准来思考，但按照如今的发展速度，就连一年都显得太长。因此，先把视野缩短到“明年”左右，谈谈在我看来会变得更加重要的能力。

五项能力

第一项是编写规格（Specification）的能力。 AI 时代，“编程的起点”不是键盘，而是规格。准确写清楚要让 AI 做什么的能力，已经比代码本身更重要。这里所说的规格，并不是什么宏大的 RFC 文档，而是像这样一些东西：用代码写下业务逻辑预期行为的测试；整理 UI 组件场景和视觉契约的 Storybook story；明确数据流契约的类型定义。归根结底，这是预先铺设一套能自动验证 AI 产出的标准。缺少这一步就开始让 AI 编程，问题会不断累积。

第二项是验证与判断力。 AI 会自信地生成看似合理、实则错误的代码。因此，我认为“快速而准确地审查 AI 代码的能力”本身就是核心。要能判断它是否漏掉了安全标头、输入净化、CSRF 令牌，无障碍能力（ARIA、键盘导航、焦点陷阱）是否仍然有效，以及渲染成本、内存、包体积等性能影响是否存在问题。不经审查就把 AI 垃圾代码扔进 PR，是工程师的失职。点击合并按钮的仍然是人，这份责任不能推给 AI。Stack Overflow 调查中，资深工程师对 AI 的信任度最低，很可能正是因为他们拥有发现这些细节的眼光。

第三项是系统理解与架构思维。 AI 擅长一次处理一个文件，对流程和关联也具备出色的理解能力。AI 能快速修复症状，但能力出众的开发者会寻找根本原因。培养这项能力的方法之一，是有意识地开展 Architecture Retrospective 等活动。代码变化得越快，团队就越需要主动提升对系统的理解，否则认知债务会迅速积累。

第四项是 AI 编排能力。 运用 AI 本身的能力，也正在分化成独立的技能组合。这已经不只是“善于写提示词”，而是需要整体掌握：把工作拆分成小工单的能力；为同一项工作选择合适模型的能力；设计智能体评估与验证流水线的能力；以及智能体失败时的回滚策略。Steve Yegge 将这一趋势归纳为六个阶段（traditional → completions → chat → coding agents → agent clusters → agent fleets）。

第五项是 Context Engineering。 这是从 2025 年年中起，Karpathy 与 Shopify CEO Tobi Lütke 一同推动的概念。简单说，就是“设计要让 AI 看到哪些上下文、以什么形式呈现、呈现多少的能力”。具体表现包括：把项目约定、架构原则和禁忌事项整理到 AI 随时能够触及的地方，即维护 CLAUDE.md / rules 文件；不把所有文件都塞进上下文，只筛选相关模块展示给 AI，即有意缩减上下文；将计划 → 实现 → 验证拆分到不同会话，避免上下文污染，即明确划分阶段；以及通过标准接口接入设计系统、API schema、监控数据等外部上下文，即通过 MCP 引入外部上下文。Anthropic 官方文档将其称为“the new prompt engineering”，并明确指出，单个提示词绝不可能容纳系统的架构知识、模式和隐性经验。换句话说，比起“一次写出好的提示词”，“设计一个让 AI 始终获得优质上下文的环境”已经重要得多。

读到这里，自然会产生一个问题：那么具体该怎么学习？我自己采用的方法大致有四种。

学习方法

原文提到的“持续学习”依然有效，但学习时间的分配必须改变。

有些领域过去投入了很多时间，如今可以减少；相对地，也有些复杂领域过去因为太难或耗时太久而没有去做。后者包括编写测试规格、使用性能测量工具（Lighthouse、WebPageTest、Chrome DevTools Performance）、无障碍（WCAG）、安全（尤其是 OWASP Top 10）等。另外，还有 Vercel AI SDK、LangChain.js、MCP、流式 UI 模式、智能体评估流水线等需要从头学习的新领域。重要的是认识到自己需要哪些能力，并合理分配时间。

AI 生成的代码很容易变得庞大，一分钟就能产出几百行。因此，如果不主动管理 PR 大小和合并周期，代码审查本身就会崩溃。公司引入 AI 后，平均 PR 大小增加了 18%，每个 PR 的事故数量增加了 24%，变更失败率增加了 30%。结合前文的数据来看，如果写得太大、一次性合并，就很难掌握流程和体现意图，因此细分工作单元非常重要。

这也直接关联到 Evan Moon 文章所指出的认知负荷降低问题。最好每天单独留出一两个小时，在不使用 AI 的情况下写代码。例如亲手画架构图，或逐行阅读自己不熟悉领域的代码。（我自己也会在每天午饭后容易犯困的时段，不用 AI 写一会儿代码。这段时间让我不至于离曾经熟悉的感觉越来越远。）

这并不只是为了“不忘记旧方法”。AI 代劳了多少时间，你自己的深度就少成长多少。验证与判断力、系统理解等能力，都是亲自碰壁时间的函数。

所以，我们要做的是

虽然前面写了很长，但其实，AI 时代能够生存下来的前端工程师形象，与原文得出的结论并没有太大不同。原文列出的优秀资深工程师的三个要点如下。

• 努力忠于基本功。（持续保持并加强五项基本能力）
• 即便不是名义上的领导者，也通过示范性行动自然地发挥影响力。
• 不满足于做好分配到手的工作，而是审视前后语境，创造更大的影响力。

把这些应用到 AI 时代，就会变成下面这样。

• 忠于 AI 生成的代码之外的基本功（Web、系统、业务领域）。
• 方向由自己决定，而不是交给 AI。即便不是名义上的负责人，也要判断“该往哪里走”。
• 不只把 AI 当作个人生产力工具，还要用它解决团队和系统的瓶颈。

从 Open AI 权威专家 Andrej Karpathy 的文章来看，他如今强调的 “agentic engineering”，核心归根结底也是一样的：设计系统、明确约束，再用 AI 加速实现那些已经在脑中推理完成的方案。工具变了，但方向键仍然掌握在人手中。

原文最后传达的信息，同样是“不满足于做好分配到手的工作，而是审视前后语境，创造更大影响力的人”才会成为资深工程师。AI 时代只是“影响力”的定义发生了变化。有人会把 AI 一小时做出的页面，以“能运行就行”为由直接合并；也有人会再花 30 分钟，检查这个页面在无障碍、安全、性能和系统一致性方面究竟有多合理。一年后被认可为资深工程师的，会是后者。站在 70%（运行）与 30%（应用和运用）的边界上，选择站到 30% 那一侧的人，才能生存下来。

希望读到这篇文章的前端工程师，也能对“现在还该继续学什么？”这个问题找到自己的答案。没有人知道标准答案，但我相当确信：越是在 AI 编写代码的时代，越是能看到“代码之外的东西”的人，越能生存下去。希望一年后还能再次整理成文章，回顾这幅景象又发生了怎样的变化。就此收笔。

（如果一年后再看，这篇文章显得过于理所当然或已经过时，那或许正说明我们应对得很好。）

参考资料

在从事前端开发的过程中，我无数次纠结过：“这段逻辑到底该拆到什么程度？”“这个组件应该按什么粒度拆分？”起初，我以为只要把共同部分提取出来就是抽象：把重复代码写成函数，提取相似组件的共同点再合并到一起。但几次经历告诉我，这样写出的代码随着时间推移，反而可能变成难以下手的怪物。于是，我开始重新思考抽象究竟是什么。

本文将整理我对抽象本质的思考，以及在前端开发中如何运用抽象才能写出好代码。

抽象与抽象化

在进入正题之前，先来厘清“抽象”与“抽象化”在编程中究竟意味着什么。这两个词看起来相近，性质却颇为不同。

抽象（Abstract）既是一种状态，也是一种属性。当我们说“这是抽象的”时，意味着具体细节已被省略，处于一种只保留核心概念的状态。Java 或 TypeScript 中带有 abstract 关键字的类或方法就是这个含义：具体实现尚未填充，只定义了本质形态，是一张尚未完成的设计图。

抽象化（Abstraction）既是一个过程，也是一种行为。它指的是从复杂对象中只保留核心特征、去除不必要细节，使其简化的过程本身。重要的是，抽象化并非“笼统地归为一类”，而是在每个层级上准确界定职责的行为。

日常生活中，“抽象”常带有“模糊”的意味。但编程中的抽象恰恰相反。抽象的目的不是变得模糊，而是建立一个可以做到绝对准确的新语义层级。在给定上下文中保留相关信息、忘掉无关信息，正是抽象的本质。

因此，可以这样理解抽象与抽象化的区别：抽象是“只剩核心的状态”，抽象化是“只留下核心的过程”。我们设计代码时所做的，正是抽象化——从复杂实现中留下核心接口，并隐藏其余部分。

那么，编程为什么需要这样的抽象呢？

为什么需要抽象

编程需要抽象的根本原因出乎意料地简单：为了构建更复杂的东西。当复杂元素太多时，我们很难全部记住并处理它们。因此，我们把复杂元素分组，形成简化后的抽象概念。

前端开发者每天使用的 React 就是如此。渲染一个组件时，内部会经历创建 Virtual DOM、协调（Reconciliation）、操作真实 DOM 等复杂过程。但我们无需在意这些，只要编写 JSX 即可，因为 React 已经把复杂过程抽象掉了。

看看下面的代码。使用 UserProfile 组件时，即使不了解内部发生的 VDOM 创建、差异比较等复杂过程，我们也完全可以构建和操作 UI。

<UserProfile name="jihoon" />

过去，亲自配置 Webpack 是前端开发者的日常；如今，Next.js、Vite 等框架已经把打包配置抽象掉了。于是，我们即使不了解打包器的内部工作方式，也能开发应用，并把这些时间用于关注业务逻辑、用户体验等更高层次的问题。（也正因如此，我认为抽象这一概念对前端开发者的职责非常重要。）

归根结底，抽象的核心价值在于：隐藏复杂性，使其看起来简单，并让每个人只专注于自己的领域。正因为如此，我们无需独自理解一切，也能构建日益庞大而复杂的软件。

既然抽象这么好，是不是做得越多越好？让我们思考一下，究竟应该抱着怎样的目的进行抽象。

减少上下文

许多开发者把抽象理解为“提取共同部分”。这并没有错，但它只是进行抽象的一种手法，并不能说明抽象的本质。

在我看来，抽象的本质是**“把代码阅读者需要掌握的上下文减少到适当层级”**。

来看一个简单的例子。

interface Order {
  id: string;
  status: "pending" | "completed";
  amount: number;
}
 
let total = 0;
 
const orders: Order[] = [
  { id: "a", status: "pending", amount: 10000 },
  { id: "b", status: "completed", amount: 5000 },
  { id: "c", status: "completed", amount: 8000 },
];
 
for (let i = 0; i < orders.length; i++) {
  if (orders[i].status === "completed") {
    total += orders[i].amount;
  }
}

阅读这段代码的开发者，必须理解循环的初始化、条件和递增方式，通过索引访问元素，检查条件并进行分支，还要把外部累加变量如何更新全部记在脑中。可这段代码真正想做的，不过是**“计算已完成订单的总额”**这一句话。为了理解这句话，读者却不得不同时承载四种不同的上下文。

const total = orders
  .filter((order) => order.status === "completed")
  .reduce((sum, order) => sum + order.amount, 0);

借助 filter 和 reduce 这两层抽象，开发者只需跟随“只筛选已完成订单”和“累加金额”这两个意图。索引管理，以及累加变量的声明与更新，都从代码表面消失了。

还可以再进一步。

const total = sumCompletedOrders(orders);

现在，阅读代码的人甚至不必知道这项计算是通过遍历数组完成的。留下的只有“计算已完成订单总额”这一业务意图。读者可以关注代码计算的是什么（What），而不是如何（How）计算。

从这个角度看，我们每天编写的 React 代码其实也是无数抽象的组合。

import { css } from "@emotion/css";
import { format } from "date-fns";
 
const TodayHeader = () => {
  const now = new Date(); // Date 객체 생성이라는 복잡한 과정을 추상화
  const formatted = format(now, "yyyy-MM-dd"); // 날짜 포맷팅 로직을 추상화
 
  return (
    <h1
      className={css`
        font-size: 1.8rem;
      `}
    >
      {/* CSS-in-JS 처리 과정을 추상화 */}
      Today is {formatted}
    </h1> // React.createElement를 추상화
  );
};
 
// 그리고 위 모든 것을 다시 추상화
<TodayHeader />;

试想，如果 emotion、date-fns、react 的内部代码全都铺开在这个组件文件里，会怎么样？我们将难以判断该从哪里读起，也难以分辨哪部分是业务逻辑，哪部分是库代码。正因为抽象适当地隐藏了各个领域的上下文，我们才能只关注“显示今天的日期”这一实质。

那么，在实际设计代码时，应该从什么方向着手抽象呢？

抽象层级的高与低

谈到抽象，就绕不开**抽象层级（Level of Abstraction）**这个概念。代码的抽象层级“高”或“低”，究竟是什么意思？

抽象层级低的代码更接近计算机执行的具体步骤，例如直接解析字符串、通过索引遍历数组、操作字节。它赤裸裸地展现了**如何（How）**运行。

// 추상화 수준이 낮은 코드
const response = await fetch('/api/users');
const users = await response.json();
const filteredUsers = users.filter(user => user.status === 'active');
 
filteredUsers.forEach(user => {
  const element = document.getElementById(`user-${user.id}`);
  if (element) element.style.display = 'block';
});

抽象层级高的代码则使用业务领域或问题域的语言来表达，例如 processPayment(order)、sendNotification(user, message)、validateUserInput(formData)。高抽象层级的代码展现的是做什么（What），而隐藏了具体做法。

Robert C. Martin 在 Clean Code 中把这一概念总结为**“每个函数只处于一个抽象层级（One Level of Abstraction per Function）”**原则。因为当高层级与低层级代码混在同一个函数中时，读者每读一行都要判断：“这是核心逻辑，还是实现细节？”

放到实际代码里，这个问题会更加清楚。

// 추상화 수준이 뒤섞인 함수
async function registerUser(name: string, email: string, password: string) {
  // ✅ 높은 수준: 비즈니스 규칙 검증
  validateUserInput({ name, email, password });
  await ensureEmailNotDuplicated(email);
 
  // ❌ 낮은 수준: 비밀번호 해싱 직접 구현
  const encoder = new TextEncoder();
  const data = encoder.encode(password);
  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
  const hashedPassword = Array.from(new Uint8Array(hashBuffer))
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
 
  // ✅ 높은 수준: 사용자 저장
  const user = await userRepository.save({ name, email, password: hashedPassword });
 
  // ❌ 낮은 수준: 이메일 전송 직접 구현
  const verifyToken = crypto.randomBytes(32).toString("hex");
  await db.execute(
    "INSERT INTO email_tokens (user_id, token, expires_at) VALUES (?, ?, ?)",
    [user.id, verifyToken, new Date(Date.now() + 86_400_000)]
  );
  await transporter.sendMail({
    from: "noreply@example.com",
    to: user.email,
    subject: "Welcome! Please verify your email",
    html: `<a href="/verify?token=${verifyToken}">Verify your account</a>`,
  });
 
  // ✅ 높은 수준: 환영 이메일 발송
  await sendWelcomeEmail(user);
}

阅读这个函数的人，本来正沿着“用户注册流程”这一基于业务规则的高层上下文前进，却突然被拽到哈希缓冲区操作、SQL 查询和邮件模板字符串这些底层上下文中，随后又跳回 sendWelcomeEmail 这一高层抽象。抽象层级这样忽高忽低，读者的思路也会随之上下跳跃。

将同一个函数改写为统一抽象层级后，会是这样。

// 추상화 수준이 일관된 함수
async function registerUser(name: string, email: string, password: string) {
  validateUserInput({ name, email, password });
  await ensureEmailNotDuplicated(email);
 
  const hashedPassword = await hashPassword(password);
  const user = await userRepository.save({ name, email, password: hashedPassword });
 
  await sendVerificationEmail(user);
  await sendWelcomeEmail(user);
}

每条语句都处于相同的抽象高度。邮件发送如何实现、密码哈希采用什么算法，分别由下层函数负责。阅读这个函数的人只需关注“用户注册的完整流程”这一种上下文。

Martin 也把它称为**“降层规则（The Stepdown Rule）”**。从上到下阅读代码时，应当像读新闻报道一样：顶部呈现全貌，越往下细节越多。

Kent Beck 也在 Smalltalk Best Practice Patterns 中以组合方法（Composed Method）模式提出了相同原则：一个方法只能由处于同一抽象层级的操作组成，每个步骤都应表示为一行方法调用。

这些讨论最终都指向同一个结论：**一个函数只能在一个抽象层级上叙事。**仅仅遵守这一点，代码可读性就会发生显著变化。

那么，抽象的方向应该如何确定？该从具体事物开始，还是从抽象事物开始？

不要提取共同点，而要思考部件的组合

OOP 中有一条常见指导：“提取具体事物的共同点，以定义抽象事物。”这种做法本身没有错，但我认为，如果过度拘泥于此，就有可能设计出被当前需求束缚的结构。

举个例子。假设需求中有 A、B、C 三个按钮，它们都是蓝色圆角样式，唯一差别只是标签文字。只提取共同点来设计，可以写成下面这样。

const BlueRoundButton = ({ label }: { label: string }) => {
  return <button className="blue round">{label}</button>;
};

当前需求得到了完美满足。然而几天后，产品经理说：

“请让 B 按钮的颜色可以修改。”

这一刻，BlueRoundButton 这个名字就开始显得别扭。确实可以添加颜色 prop，但从“蓝色圆角按钮”这一具体共同点出发的设计，本来就很容易受需求变更影响。（这还算好的。现实里还会不断冒出按钮形状、按钮尺寸等无数需求。）

这类情况反复发生后，我们自然会意识到：从具体需求中提取共同点的方式，往往会让抽象后的产物也只反映当前需求。

所以我更偏好相反的方向：不是从具体事物中提取抽象，而是先思考抽象部件，再把它们组装成具体事物。

假设要制作一个 Toast 通知组件。最初的需求很简单：“保存完成后，请在底部显示一条简短提示。”如果按照提取共同点的方式处理，会变成这样。

// 현재 요구사항의 공통 특성에서 출발한 설계
type ToastProps = {
  message: string;
  hasAction?: boolean;
  actionLabel?: string;
  onAction?: () => void;
};
 
const Toast = ({ message, hasAction, actionLabel, onAction }: ToastProps) => (
  <div className="toast">
    <span>{message}</span>
    {hasAction && <button onClick={onAction}>{actionLabel}</button>}
  </div>
);

当前需求被完美覆盖。可几天后，产品经理提出：“请根据成功或警告状态，在左侧放置图标。”于是增加了 hasIcon、iconName。紧接着又来了“还需要带上传进度条的 Toast”。于是再加一个 progress prop。这个过程重复几次后，Toast 会拥有十多个 props，开发者还必须记住这种组合可用、那种组合不可用之类的隐藏规则。（而且这些规则通常连注释都不会留下。）

归根结底，从**“Toast 就应该长这样”这一当下的具体形象**出发的设计，很难应对变化。

如果改用部件组合的方式，情况就不同了。

// 부품을 조립하는 설계
const Toast = ({ children }: PropsWithChildren) => (
  <div className="toast">{children}</div>
);
 
Toast.Icon = ({ name }: { name: "check" | "warn" | "info" }) => {
  /* ... */
};
 
Toast.Message = ({ children }: PropsWithChildren) => <span>{children}</span>;
 
Toast.Action = ({
  children,
  onClick,
}: PropsWithChildren<{ onClick: () => void }>) => (
  <button onClick={onClick}>{children}</button>
);
 
Toast.Progress = ({ value }: { value: number }) => {
  /* ... */
};
 
// 필요한 부품만 골라 조립한다
<Toast>
  <Toast.Message>저장되었습니다</Toast.Message>
</Toast>;
 
<Toast>
  <Toast.Icon name="check" />
  <Toast.Message>업로드 완료</Toast.Message>
  <Toast.Action onClick={undo}>실행 취소</Toast.Action>
</Toast>;
 
<Toast>
  <Toast.Progress value={0.4} />
  <Toast.Message>파일 전송 중...</Toast.Message>
</Toast>;

“Toast 是一个用来容纳内容的轻量容器”这一不变本质，与“里面装什么”这一容易变化的具体内容被分离开来。现在，无需触碰 Toast 内部，就可以任意添加新部件，或把现有部件排列成新的组合。prop 组合的有效性规则也消失了，只需放入想放的内容即可。

当然，经验丰富的开发者可能会说：“一开始就用 IoC（控制反转）来设计不就行了吗？”确实如此。但之所以能够做出这样的判断，是因为过去经历了无数次踩坑，逐渐形成了对“哪里容易发生变化”的直觉。

如果这份直觉尚不充分，从“这个功能由哪些部件组成，各个部件应该如何组合”这个问题出发，会更容易做出对变化开放的设计。

读到这里，自然会产生一个问题：那么，该依据什么标准划分部件，又该如何对外表达它们呢？

做好抽象的三个要点

思考如何表达

抽象模块最重要的品质，是无需查看源代码也能推断其行为。Kent Beck 把它称为**“揭示意图的命名（Intention-Revealing Name）”模式**，并指出，如果无法取出简洁的名字，就应该重新审视抽象本身。

我们为此可以使用的工具主要有两个：名称与类型。

// 도대체 뭘 하는 건지 알 수 없는 함수
function calculate(price: number, rate: number): number;
 
// 이름과 타입만으로 동작을 유추할 수 있는 함수
function calculateDiscountedPrice(originalPrice: number, discountRate: number): number;

只看 calculateDiscountedPrice 这个名字，就能知道它接收原价与折扣率，并计算折后价格；接收 number 并返回 number 的类型信息进一步支撑了这种理解。至于内部采用了什么计算逻辑，我们不必知道。

相反，calculate(price: number, rate: number): number 没有说明计算对象，因此无法预期结果。最终只能查看源代码后才能使用，抽象的优势也就丧失了。

这里值得注意的是，命名方式本身就反映了抽象层级。编程中的函数名大多采用动词 + 名词的组合，而选择什么动词，会显露出函数处于哪个抽象层级。

不过，抽象层级并非由动词单独决定。与它搭配的名词（领域上下文）才决定最终层级。

在抽象层级较低的一侧，常用的动词包括 parse、encode、decode、serialize、read、write、push、pop、convert、transform。这些词暗示数据的物理转换或对数据结构的直接操作。

中间层级常出现 get、save、load、validate 等动词。它们仍属于技术操作，但已经在一定程度上揭示了行为意图。

在抽象层级较高的一侧，则会使用 register、refund、confirm、cancel、submit 等动词。这些词属于业务领域语言，完全不体现内部发生了什么技术步骤，只表达用户行为或业务流程。

// 낮은 수준: 기술적 동작이 드러남
function parseJSON(text: string): object;
function encodeBase64(data: Uint8Array): string;
 
// 중간 수준: 의도가 드러나되 기술적 맥락이 남아있음
function getUserById(id: string): Promise<User>;
function validateEmail(email: string): boolean;
 
// 높은 수준: 비즈니스 의도만 드러남
function registerUser(form: RegistrationForm): Promise<User>;
function refundPayment(orderId: OrderId, amount: Money): Promise<Refund>;

Robert C. Martin 在 Clean Code 中对此说过：**“长而具有描述性的名字，胜过短而晦涩的名字。”他还提出了“每个概念只使用一个词”**的原则。假如在同一上下文的操作中混用 fetch、retrieve、get，读者就会困惑：“这三者是不同操作吗？”

这一原则同样适用于 React 组件与 hook 的命名。

<Button />           
<SearchInput />      
<SubmitOrderButton />

组件名称的具体程度会随抽象层级而变化。Button 在较低层级作为通用 UI 基础组件使用，而 SubmitOrderButton 则在较高层级清楚揭示了业务意图。

const handleSubmit = async(data: FormData) => { 
  await registerUser(data);
};
 
<Form onSubmit={handleSubmit} />           

on* 是组件对外暴露的 prop 名称，使用组件的一方通过它声明“要响应哪种事件”。handle* 则是实际传递给该 prop 的实现函数名。

const user = useAuth();                  
const [items, setItems] = useCartItems();
const { isOpen, toggle } = useModal();   

自定义 hook 使用 use 前缀，以遵循 React 的规则，并让组件可以使用 hook 提供的状态或行为。

运营 Coding Horror 的 Jeff Atwood 曾指出 Manager 这一后缀的问题。UrlManager 这个名字完全看不出它是在池化、验证还是生成 URL。UrlBuilder、UrlValidator、UrlPool 这类揭示具体职责的名称要好得多。名称模糊，可能正说明模块本身的职责就很模糊。

归根结底，好的名称应当让读者立刻知道这段代码处于哪个抽象层级。

有意识地设计输入自由度

设计抽象模块时，经常会遇到一个问题：“功能要开放到什么程度？”这个决定会极大影响使用模块的开发者体验。

// 기능이 닫힌 컴포넌트
const Button = ({ children }: {children?: React.ReactNode}) => {
  return <button>{children}</button>;
};
 
// 기능이 완전히 열린 컴포넌트
const Button = (props: ComponentProps<"button">) => {
  return <button {...props} />;
};

第一个按钮只能接收 children，无法设置 onClick、type 或 disabled。但使用者不必做任何选择。

第二个按钮可以接收 button 元素的所有属性，自由度很高，但使用者必须从几十个 prop 中思考该用哪一个。我把这种情况称为**“组件强迫开发者思考”**。

这没有标准答案，只需根据模块的目的与用户找到适当程度。若是设计系统的基础按钮，限制 Props 以保持一致性也许更好；若是通用工具组件，灵活开放或许更合适。

// 지나치게 닫힌 인터페이스 — 다양한 상황에 대응 불가
<Button onClick={handleSubmit}>제출</Button>
// onClick 외의 이벤트, className, disabled 등을 전달할 방법이 없다
 
// 지나치게 열린 인터페이스 — 의도가 사라짐
<Button {...anyProps} />
// 무엇을 전달해야 하는지 사용자가 직접 파악해야 한다

抽象的开放范围应由用户是谁来决定。对于需要理解内部实现并精细控制的用户，低层级接口更合适。反之，如果向不需要了解细节的用户提供过度开放的接口，只会增加困惑；而如果过度限制需要应对多种场景的用户输入，则会直接堵死使用方式。

将抽象维持在适当粒度

抽象的粒度，也就是“应该把多大范围捆绑成一个模块”，同样是一个重要问题。

前端中常见的反模式之一，是过度提取 Custom Hook。

// 이 훅은 단 하나의 컴포넌트에서만 사용된다
const useUserProfileData = () => {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
 
  useEffect(() => {
    fetchUser()
      .then(setUser)
      .finally(() => setLoading(false));
  }, []);
 
  return { user, loading };
};

如果把只在一个组件中使用的逻辑硬拆成 hook，阅读代码的人反而要在两个文件之间来回切换才能掌握上下文。抽象非但没有减少上下文，反而增加了它。

反过来，在一个 hook 中塞入太多内容也有问题。

// 관련 없는 관심사가 하나의 훅에 뒤섞여 있다
const useEverything = () => {
  const auth = useAuth();
  const theme = useTheme();
  const analytics = useAnalytics();
  const toast = useToast();
 
  return { auth, theme, analytics, toast };
};

这种“God Hook”很难测试，修改其中一项，还可能影响不相关的部分。

判断抽象粒度是否合适的标准是：**“这次拆分真的减少了代码阅读者的上下文吗？”**如果拆分后上下文反而变得分散、更难把握，就说明还没到进行这次抽象的时候。

警惕过早抽象

读到这里，也许还会留下一个问题：“那到底什么时候该抽象？”我的看法是：基本前提应该是，不要贸然抽象。

只要还没出现明确的抽象信号，保持代码原样的下限，就高于先做出错误抽象、日后再把它拆开的下限。错误抽象的形成过程大致如下。

1. 在代码 A 和代码 B 中发现相似模式。
2. 想着“既然有 DRY 原则，就提成公共函数吧！”于是进行抽象。
3. 在代码 C 中也发现相似模式，于是使用同一个函数，并为稍有不同的行为添加一个参数。
4. 随着代码 D、E 也开始使用它，条件语句与参数不断增加。
5. 现在这个函数到处都在使用，却变成了谁也不敢修改的代码。

// 처음에는 단순했던 함수가...
const formatUserName = (user: User) => `${user.firstName} ${user.lastName}`;
 
// 요구사항이 추가될 때마다 매개변수가 늘어나고...
const formatUserName = (
  user: User,
  includeMiddleName?: boolean,
  format?: "full" | "short" | "initials",
  locale?: string,
  honorific?: boolean,
) => {
  if (format === "initials") {
    /* ... */
  }
  if (includeMiddleName && user.middleName) {
    /* ... */
  }
  if (honorific && locale === "ko") {
    /* ... */
  }
  // ...끝없는 분기
};

如果陷入这种局面，解决办法很明确：把抽象后的代码重新内联到各个使用处，删除每个使用处不需要的代码，然后在清理后的状态下，等真正的共同点显现时再重新抽象。“最快的前进方式，是先退回去。”

那么，什么时候该进行抽象？我感受到的抽象信号大致有以下几种。

• **一致性正在被破坏。**明明是同一段逻辑，却在某些组件中内联，在另一些组件中拆成单独函数；相同的计算逻辑散落各处。
• **内部结构被不必要地暴露给外部。**调用者不得不逐一处理它根本不需要知道的实现细节。
• **自身行为不断暴露。**模块无法隐藏内部步骤，使用方必须原样跟随这些步骤。

问题在于，发现这些信号通常并不困难，但在实践中，人们很容易忽略它们，转而专注于满足更“重要”的需求。被进度追赶或埋头实现功能时，我们会觉得“反正先跑起来，以后再整理”，但那个“以后”很少真正到来。

还有一点同样重要，那就是保持一致的抽象标准。如果代码库中的同类逻辑，有些地方内联，有些地方写成函数，还有些地方拆成自定义 hook，新来的代码阅读者就会困惑：“这些差异是刻意设计的吗？”无论抽象与否，团队内部的标准都应保持一致。

Joel Spolsky 在 2002 年提出的**“抽象泄漏定律（The Law of Leaky Abstractions）”**也值得结合这一上下文记住。抽象试图隐藏复杂实现，但实现细节最终仍会泄漏（leak）到外部。也就是说，设计原本声称使用者无需了解内部实现，实际使用时却可能只有了解它才能正确操作。

TCP 把不稳定的网络抽象成稳定连接，但网线断开时，这层抽象就会破裂。React 以声明式方式抽象 UI 更新，但为了优化重新渲染，最终还是需要理解内部行为。完美的抽象并不存在，因此做抽象时，还必须思考：“当这层抽象破裂时，用户能否应对？”

归根结底，“抽象会节省我们的工作时间，却不会节省学习时间。”

抽象是一种内化的能力

我曾和同事讨论过抽象，当时有一个观点令我印象深刻：发现抽象信号，并在恰当时机以恰当层级进行拆分，归根结底靠的是直觉。

当然，前面提到的原则——统一抽象层级、起好名字、设计输入自由度——无疑都很重要。但真正开始写代码时，如果逐条想起这些原则，再逐一斟酌“要不要把这个拆出去”，反而可能打断节奏。就像比赛中出刺拳时，如果刻意想着肘部角度，反而会错过时机；写代码时，抽象也应该源于自然直觉，而非每次都有意识地判断。

一路写代码时，有时会突然产生排斥感：“这段逻辑好像不该放在这里。”“这个组件好像知道得太多了。”这种感觉就是抽象信号。能够自然地发现并回应它，就是所谓的内化。

不过，这份直觉并非一朝一夕就能形成。只有学习大量模式、阅读各种代码，并亲自踩过坑，才会自然涌现**“这个似乎应该拆分”**的感觉。日后同事问“为什么把它拆开？”时，如果能够自然回答“因为它属于 X，所以才拆分”，就说明它已经内化了。

任何领域似乎都一样。试图靠背诵来做好一件事，反而会让判断变得困难。最终应该只把握大方向，让细节自然补足。而这种自然，终究来自平时积累的各种模式与经验。

结语

编程中的抽象，是隐藏复杂事物、让其看起来简单，并让代码阅读者只关注必要上下文的行为。

最后，再回顾一下做好抽象需要记住的要点。

• 基本前提是不要过早抽象，等明确的信号出现后再拆分。
• 一个函数只在一个抽象层级上叙事。
• 通过名称与类型充分表达行为，让人无需查看源代码即可使用。
• 根据模块目的与用户，有意识地设计输入自由度。
• 与其在错误抽象上继续叠加，不如拥有拆开并重新开始的勇气。
• 还要内化各种模式，让这一切无需刻意思考也能自然发生。

当然，我在本文中的观点并非标准答案。适当的抽象层级会因业务情况、团队构成与项目性质而异。但有一点始终不变：抽象的最终目的，是写出便于人理解的代码。

也希望读到这篇文章的各位，能在自己的代码库中问一句：“这层抽象真的减少了上下文吗？”仅仅这一个问题，或许就会稍微改变你看待代码的方式。

参考资料

本文从多份官方文档与既有文章中获得了许多启发。下面一并列出直接引用内容的出处，以及帮助我建立思考框架的文章。

我在实际项目中使用 TanStack Query 时，曾多次彻底重构 queryKey 的管理方式。最初，我只是在组件里内联写上 ['user', userId] 这样的数组；后来每次做缓存失效都要在不同地方重复写相同的键，开始频繁出现拼写错误，于是又把它们迁移到 QUERY_KEYS 这样的常量对象中。再后来读了 TkDodo 的文章，转向 query key factory 模式；过了很久，又引入了 @lukemorales/query-key-factory；等到 v5 发布，又用 queryOptions 重构了一遍。

明明只是一个缓存标识符的小数组，为什么会衍生出这么多模式？为什么一个 queryKey 会留下如此丰富的演进痕迹？ 每一个阶段究竟想解决什么问题？

本文会沿着 TanStack Query 官方文档、TkDodo 的系列博客，以及 v5 引入的 queryOptions 内部实现，梳理 queryKey 的工作原理，以及它为何逐步演进成今天的形态。

没有 queryKey 的时代

在进入正题之前，先回顾一件事。如今我们使用 TanStack Query、SWR 之类的库已经习以为常，但在这些库出现之前，异步数据是怎么处理的？

最常见的方式，大概是把 useState、useEffect、fetch、axios 等组合起来。

function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);
 
  useEffect(() => {
    let cancelled = false;
    setLoading(true);
 
    fetch(`/api/users/${userId}`)
      .then((res) => res.json())
      .then((data) => {
        if (!cancelled) setUser(data);
      })
      .catch((err) => {
        if (!cancelled) setError(err);
      })
      .finally(() => {
        if (!cancelled) setLoading(false);
      });
 
    return () => {
      cancelled = true;
    };
  }, [userId]);
 
  // ...
}

这段代码的问题很明显：页面上只要有两个查看同一 userId 的组件，相同的请求就会发送两次。 原因是没有缓存。用户跳转到其他页面后再回来，也会从头重新获取数据。我们无法判断数据是 1 秒前还是 1 小时前获取的，因此也很难模拟“先展示缓存值，再在后台更新”这样的行为。（当然可以自己引入缓存系统来实现，但我认为它的维护成本相当高。）

为了解决这个问题，后来出现了 Redux + redux-thunk（或 redux-saga）的组合。把数据获取逻辑抽到 thunk 中，再把结果存进状态仓库，其他组件就能复用相同的数据。但每次都要定义 action 类型、编写 reducer，并手动管理加载、成功和失败状态。仅仅获取一份数据，就要写大量样板代码。（我正是在这个时期进入职场的，当时一直困惑：“为什么取一份数据要新建这么多个文件？”）

上述流程的本质归根结底是：“只有能够识别这个请求究竟是什么请求，才能避免重复发送相同请求。” 而标识“这是什么请求”的东西，正是 queryKey。

SWR 和 React Query（现 TanStack Query）正面解决了这个问题：“异步请求必须有标识符，相同标识符共享缓存。”就凭这一条简单原则，前面所有的样板代码都消失了。

queryKey 的本质

那么，queryKey 究竟是什么？TanStack Query 官方文档是这样定义的。

从根本上说，TanStack Query 根据 query key 管理查询缓存。query key 的顶层必须是数组……只要 query key 可序列化，并且对查询数据而言是唯一的，就可以使用。

At its core, TanStack Query manages query caching for you based on query keys. Query keys have to be an Array at the top level... As long as the query key is serializable, and unique to the query's data, you can use it.

核心有两点：必须可序列化，并且必须对该数据唯一。 相同的键代表相同的数据，不同的数据必须拥有不同的键。这条简单规则决定了整个缓存系统的行为。

还有一点同样重要：queryKey 同时也扮演依赖数组的角色。 就像 React 的 useEffect 会在依赖变化时重新执行副作用一样，queryKey 变化后，TanStack Query 会自动获取新数据。

const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

当 userId 为 'A' 和 'B' 时，queryKey 彼此不同。不同就意味着缓存未命中，进而触发数据获取，而且这一切都是自动的。得益于这种简洁性，我们无需亲自编写“userId 变了，所以要重新获取”的逻辑。

这里自然会产生一个疑问：TanStack Query 如何判断 queryKey 是“同一个键”？如果只是用 === 比较，对象引用会不同，那岂不是每次都会缓存未命中？

QueryCache 内部

根据 TkDodo 的 Inside React Query，QueryCache 归根结底只是保存在内存中的一个数据结构。更准确地说，在 v5 的官方实现中，这个数据结构不是普通对象，而是 Map<string, Query>。它在类内部声明为 #queries = new Map<string, Query>()，所有读写都通过 #queries.set(query.queryHash, query) 和 #queries.get(queryHash) 完成。键是 queryKey 的序列化形式（queryHash），值是 Query 类的实例。

旧版本也曾使用普通对象，但到 v5 已统一为原生 Map。（Map 不存在键冲突或原型污染风险，能保留插入顺序，而且字符串键的查找平均为 O(1)，作为缓存数据结构几乎是标准答案。）

每次调用 useQuery 时发生的事情很简单：把 queryKey 转换成哈希值，再用这个哈希值在 Map 中查找。 如果存在，就取出缓存的 Query 实例；如果不存在，就创建新的实例并 set 进去。

这里又自然会产生一个疑问：为什么一定要把 queryKey 序列化成字符串？ 直接像 Map<QueryKey, Query> 那样把数组本身当作键不行吗？

答案藏在 JavaScript 的相等性模型里。原生 Map 使用**引用相等（reference equality）**比较键。即便内容相同，只要是内存中不同的对象，就会被视为不同的键。

const m = new Map();
m.set(['user', 1], 'alice');
m.get(['user', 1]); // undefined — 새로 만든 배열은 다른 참조다

而在 React 组件中，useQuery({ queryKey: ['user', userId] }) 会在每次渲染时创建新的数组实例。 第一次和第二次渲染得到的 queryKey 数组，即使内容相同，也是内存中彼此独立的对象。如果缓存依赖引用相等，那么查看同一数据的组件每次渲染都会缓存未命中，后果将不堪设想。

解决引用相等问题的方法很简单：把引用相等转换为结构相等（structural equality）。只根据 queryKey 的内容生成确定性的字符串，再用这个字符串作为 Map 的键。这样就恢复了我们想要的“内容相同即键相同”的语义。JSON.stringify 只是完成这种转换最简单的工具。（这也是 TanStack Query 在 v3 时期尝试多种序列化策略后，最终采用稳定版 JSON.stringify 的原因。）

这里的关键是生成哈希值的函数 hashKey。packages/query-core/src/utils.ts 中的官方实现正是如此。

export function hashKey(queryKey: QueryKey | MutationKey): string {
  return JSON.stringify(queryKey, (_, val) =>
    isPlainObject(val)
      ? Object.keys(val)
          .sort()
          .reduce((result, key) => {
            result[key] = val[key]
            return result
          }, {} as any)
      : val,
  )
}

虽然用的是 JSON.stringify，但不是直接序列化，而是通过 replacer callback，先将普通对象的键按字母顺序排序后再序列化。

这种排序之所以至关重要，是因为字符串序列化还必须满足一个更强的条件：语义相同的输入，必须始终转换为相同的字符串。 但普通的 JSON.stringify 会保留键的原始顺序。{ a: 1, b: 2 } 和 { b: 2, a: 1 } 在语义上是同一个对象，却会序列化为不同的字符串，最终落入两个不同的缓存槽。这样一来，相同的数据又会被请求两次。

稳定避免这一问题的技术叫作 canonical form（规范形式）：强制语义相同的输入始终对应唯一的一种表示。hashKey 的 replacer 对普通对象的键进行排序，正是出于这个原因。无论输入顺序如何，都让输出保持一致，使序列化结果与对象语义形成一一对应。用数学语言来说，就是从键顺序不同的对象构成的等价类（equivalence class）中，选出排序后的形式作为代表元。

不对数组排序，也是同一原则的另一面。数组是一种顺序本身承载语义的数据结构，一旦排序就会丢失信息。对象的键顺序是偶然的，数组的元素顺序则是有意的。hashKey 对二者作了准确区分。正因如此，官方指南才建议按“通用 → 具体”的顺序组织 queryKey。只要数组顺序承载语义，这层语义就必须由开发者亲自定义。

还有一个细节值得说明：键排序只作用于普通对象。同一文件中的 isPlainObject 并不只是检查 typeof === 'object'，还会检查 Object.getPrototypeOf(o) === Object.prototype，以区分纯对象字面量和类实例。因此，{ foo: 1 } 这样的字面量会被排序，而通过 class User { ... } 创建的实例不会排序，直接进入下一步。（如果把类实例直接放进 queryKey，JSON.stringify 又只会输出可枚举属性，两者结合后可能得到违背预期的哈希值，这正是一个容易踩坑的地方。）

这种工作方式会带来两个重要结果。

1. 对象的键顺序无关紧要。

useQuery({ queryKey: ['todos', { status: 'done', page: 1 }], queryFn });
useQuery({ queryKey: ['todos', { page: 1, status: 'done' }], queryFn });
// 두 쿼리는 같은 캐시 슬롯을 공유한다

因为键会先排序再序列化。否则，每次使用对象字面量时都得记住键的顺序。

2. 数组的元素顺序很重要。

useQuery({ queryKey: ['todos', status, page], queryFn });
useQuery({ queryKey: ['todos', page, status], queryFn });
// 두 쿼리는 다른 캐시이다

因为数组是一种顺序本身就有意义的数据结构。JSON.stringify 也会保留数组顺序。

另外还应知道，undefined 值会在序列化过程中消失。{ a: 1, b: undefined } 和 { a: 1 } 会生成相同的 hash。（我以前不知道这一点，还犯过“既然显式写了 undefined，那肯定是不同的 cache！”这样的错误。）

此外，queryKey 不能包含循环引用或函数，因为 JSON.stringify 无法处理它们。Date 对象、Map/Set、BigInt 等，在默认行为下同样不建议使用。queryKey 应当是可序列化的纯数据结构。

有趣的是，这项约束并非完全不可绕过。TanStack Query 提供了 queryKeyHashFn 选项，留出了一个替换 hash 函数本身的逃生口。内部的 hashQueryKeyByOptions(queryKey, options) 会判断 options 中是否有 queryKeyHashFn：有则调用它，没有则调用默认的 hashKey。

useQuery({
  queryKey: [{ id: userId, fetchedAt: new Date() }],
  queryFn,
  // Date를 ISO 문자열로 바꿔서 해싱
  queryKeyHashFn: (key) =>
    JSON.stringify(key, (_, v) => (v instanceof Date ? v.toISOString() : v)),
});

但这个选项必须为每个查询单独指定，而且通过 queryClient.setQueryData 之类不掌握选项信息的命令式 API 调用时不会生效，这是它的局限（Issue #1343）。因此在实践中，与其使用这个逃生口，更安全的做法是在创建 queryKey 时就将值转换为可序列化的形式。（我也曾直接放入 Date，然后困惑了很久：“明明是同一个时间点，为什么缓存没有更新？”最终答案是：“虽然那个 Date 表示同一时间点，但它是不同的对象实例，所以每次哈希值都不同。”）

queryKey 编写规则

理解了前面较为复杂的内部机制后，编写规则也就顺理成章了。官方文档推荐的规则可以归纳如下。

规则 1：queryKey 必须是数组。

传入字符串也能工作（内部会转换成数组），但为了保持一致，最好从一开始就使用数组。

// 비권장
useQuery({ queryKey: 'todos', queryFn });
 
// 권장
useQuery({ queryKey: ['todos'], queryFn });

规则 2：把 queryFn 依赖的所有变量都放进 queryKey。

// 잘못된 예: userId가 쿼리키에 없다
useQuery({
  queryKey: ['user'],
  queryFn: () => fetchUser(userId),
});
 
// 올바른 예
useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

思路和 useEffect 的依赖完全一样：函数内部使用的所有变量，都必须进入键（也就是依赖）中。违反这条规则，就可能出现用户已经切换，界面上却仍显示前一个用户数据的隐蔽缺陷。

规则 3：按照从最 generic 到最 specific 的顺序排列。

// 좋다
['todos', 'list', { filter: 'done' }]
['todos', 'detail', todoId]
 
// 안 좋다 (순서가 뒤집혀 있음)
[{ filter: 'done' }, 'list', 'todos']

这种顺序之所以重要，是因为缓存失效（invalidation）。TanStack Query 的 invalidateQueries 默认采用 prefix matching。

// 모든 todos 관련 쿼리 무효화
queryClient.invalidateQueries({ queryKey: ['todos'] });
// → ['todos', 'list', ...], ['todos', 'detail', ...] 모두 매치된다
 
// list 쿼리만 무효화
queryClient.invalidateQueries({ queryKey: ['todos', 'list'] });
// → ['todos', 'list', ...]만 매치된다

把键设计成树状结构后，从“重新获取这个领域的所有数据”到“只重新获取这个确切条目”，都可以用一行代码表达。（初看时可能觉得没什么特别，但只要经历过一次键设计不当、失效范围与预期不符，就会切身体会到它的价值。）

queryKey 管理方式的演进

到这里，我们讨论了 queryKey 的工作原理和使用方法。接下来正式进入另一个问题：queryKey 的管理方式是怎样一步步变化的？

下面按时间顺序整理我在实际项目中经历过的阶段。

1. 内联数组

这是最简单的形式：在组件内部组合固定字符串和 props 值。

function UserProfile({ userId }: { userId: string }) {
  const { data } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  });
  // ...
}
 
function PostList({ filter }: { filter: PostFilter }) {
  const { data } = useQuery({
    queryKey: ['posts', filter],
    queryFn: () => fetchPosts(filter),
  });
  // ...
}

项目刚起步时，这样已经足够。

问题会随着代码库扩大而出现。在修改用户信息的 mutation 中需要做缓存失效时，每次都要搜索“用户相关的 query key 到底是什么来着？”有的地方写成 ['user', userId]，另一些地方却写成 ['users', userId]（复数）。它们是完全不同的缓存槽，因此失效只会作用于其中一边。

2. 常量对象

为了避免拼写错误，把 query key 集中到常量中。

// queryKeys.ts
export const QUERY_KEYS = {
  USER: 'user',
  POSTS: 'posts',
  COMMENTS: 'comments',
} as const;
 
// 사용처
useQuery({
  queryKey: [QUERY_KEYS.USER, userId],
  queryFn: () => fetchUser(userId),
});

拼写错误消失了，但组装键的责任依然落在使用方。有人把它写成 [QUERY_KEYS.USER, userId]，有人写成 [QUERY_KEYS.USER, userId, 'detail']，还有人写成 ['user', 'detail', userId]。到了这个阶段，还得额外记住究竟哪一种才符合约定。

3. Query Key Factory

这一模式在 TkDodo 的 Effective React Query Keys 一文中得到了具体化：为每个领域定义一个创建键的对象，再用函数表达层级结构。

// features/todos/queries.ts
const todoKeys = {
  all: ['todos'] as const,
  lists: () => [...todoKeys.all, 'list'] as const,
  list: (filters: string) => [...todoKeys.lists(), { filters }] as const,
  details: () => [...todoKeys.all, 'detail'] as const,
  detail: (id: number) => [...todoKeys.details(), id] as const,
};
 
// 사용
useQuery({ queryKey: todoKeys.detail(1), queryFn: ... });
useQuery({ queryKey: todoKeys.list('done'), queryFn: ... });
 
// 무효화
queryClient.invalidateQueries({ queryKey: todoKeys.all });        // 전체
queryClient.invalidateQueries({ queryKey: todoKeys.lists() });    // 모든 리스트
queryClient.invalidateQueries({ queryKey: todoKeys.detail(1) });  // 특정 항목

这个模式的强大之处在于，层级结构会明确地体现在代码中。todoKeys.all 指向所有 todos 相关查询，todoKeys.lists() 指向所有列表型查询，todoKeys.detail(1) 则指向某个具体条目。只用一行代码，就能准确表达失效范围。

另一个优点是 co-location（共置）。TkDodo 不建议把键全部集中到一个全局文件中，而是建议在功能目录内放置 queries.ts，将键和 hook 一起放在其中。

src/
└── features/
    └── todos/
        ├── index.tsx
        └── queries.ts   # 키와 훅을 모두 여기에

这样一来，就形成了一个简单的心智模型：“要修改 todos，只看 todos 文件夹就够了。”这正是“把共同变化的内容放在一起”这一原则的忠实实现。

4. @lukemorales/query-key-factory

如果每次都手写第三种模式，样板代码会逐渐堆积。而当我们想合并管理多个领域的键时，也会需要一个标准化接口。@lukemorales/query-key-factory 正是把这一模式库化后的产物。

import { createQueryKeys, mergeQueryKeys } from '@lukemorales/query-key-factory';
 
const users = createQueryKeys('users', {
  detail: (userId: string) => ({
    queryKey: [userId],
    queryFn: () => api.getUser(userId),
  }),
  list: (filters: UserFilters) => ({
    queryKey: [{ filters }],
    queryFn: () => api.getUsers(filters),
  }),
});
 
const todos = createQueryKeys('todos', {
  detail: (id: number) => ({
    queryKey: [id],
    queryFn: () => api.getTodo(id),
  }),
});
 
export const queries = mergeQueryKeys(users, todos);
 
// 사용
useQuery(queries.users.detail('abc'));
useQuery(queries.todos.detail(1));
 
// 무효화
queryClient.invalidateQueries(queries.users._def);            // 모든 user 쿼리
queryClient.invalidateQueries(queries.users.detail('abc'));   // 특정 항목

createQueryKeys 会自动添加前缀，mergeQueryKeys 可以合并多个领域。还可以通过约定好的 _def 属性访问整个领域的键。手写 factory 时每次都要加 as const、手动收窄类型的工作也随之消失。

这个库一度几乎被当作事实标准使用。（我自己也用了很长时间。）但 queryOptions 出现后，情况发生了变化。

5. queryOptions（v5 官方）

TanStack Query v5 最重要的变化之一，就是引入 queryOptions API。从 v4 升级到 v5 后，所有 hook 的参数统一成了单个对象，而这一变化真正的目的，是让这个对象可以被抽取为可复用单元。

import { queryOptions } from '@tanstack/react-query';
 
export const userDetailOptions = (userId: string) =>
  queryOptions({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
    staleTime: 5 * 60 * 1000,
  });
 
// 어디서나 사용 가능
useQuery(userDetailOptions('abc'));
useSuspenseQuery(userDetailOptions('abc'));
queryClient.prefetchQuery(userDetailOptions('abc'));
queryClient.setQueryData(userDetailOptions('abc').queryKey, newUser);

第一眼看到它时，可能会想：“这有什么不同？不就是把对象包进一个函数吗？”TkDodo 在 The Query Options API 一文中也承认了这一点：在运行时，它确实只是把收到的对象原样返回。

真正高效的工作发生在类型系统内部。接下来继续展开。

queryOptions 的 DataTag

queryOptions 不只是一个普通辅助函数，因为它会把数据类型信息嵌入返回的 queryKey 中。 在 TanStack Query 内部，这套机制叫作 DataTag。

大致实现如下。

declare const dataTagSymbol: unique symbol;
declare const dataTagErrorSymbol: unique symbol;
 
export type DataTag<TType, TValue, TError = unknown> = TType & {
  [dataTagSymbol]: TValue;
  [dataTagErrorSymbol]: TError;
};

这是一个使用 unique symbol 的 branded type。它在运行时不会产生任何影响，只是一个标记；但对 TypeScript 来说，它携带着这样一条信息：“这个数组不是普通数组，而是与 TValue 类型数据相连的数组。”

这里使用 unique symbol 是有原因的。zenn 的 Uncovering the unique symbol Behind DataTag 一文把它比作“类型信息的专属停车位”。如果使用普通字符串键，就可能与其他库或用户代码中的键冲突；而每个 unique symbol 声明本身都会创建独一无二的类型，所以它不会与其他任何声明成为同一种类型，相当于一个绝不会冲突的标识符。

仅凭这一个机制，就能带来很大的差异。

const data = queryClient.getQueryData(['user', 'abc']); // unknown
const data = queryClient.getQueryData(userDetailOptions('abc').queryKey); // User | undefined

getQueryData 和 setQueryData 虽然只接收一个 queryKey，但数据类型已经刻在 queryKey 里，因此返回类型可以自动推断。无需手动传入 generic；如果向 setQueryData 传入错误类型，编译器也会立即捕获。

当然，它也有局限。getQueriesData 这类一次获取多个查询的方法，返回结果是异构的元组数组，无法应用这种类型推断。另外，由于使用了 unique symbol，在单体仓库环境生成 .d.ts 时可能出现 TS4023 错误，可以通过显式导入 dataTagSymbol 规避。

梳理到这里，有一点已经十分明确：queryOptions 的类型推断完全依赖于 queryKey 和 queryFn 在同一处声明。 要把 queryFn 的返回类型刻进 queryKey，两者就必须在同一个地方定义。

这一点对 query key factory 的设计方向有着重要启示。上一代模式更注重把 queryKey 管理拆分成独立的抽象单元，而 v5 的建议恰好相反：重新把 queryKey 和 queryFn 绑定为一个单元。 TkDodo 甚至表示，“拆开 queryKey 和 queryFn 是一个错误”。键归根结底是函数依赖的集合，两者本来就无法割裂。

实践中的 queryOptions 组合模式

当 queryOptions 与 domain factory 结合时，它的真正价值才会体现出来。v5 官方文档推荐的形式如下。

import { queryOptions } from '@tanstack/react-query';
 
export const todoQueries = {
  all: () => ['todos'] as const,
  lists: () => [...todoQueries.all(), 'list'] as const,
  list: (filters: TodoFilters) =>
    queryOptions({
      queryKey: [...todoQueries.lists(), filters],
      queryFn: () => fetchTodos(filters),
      staleTime: 30 * 1000,
    }),
  details: () => [...todoQueries.all(), 'detail'] as const,
  detail: (id: number) =>
    queryOptions({
      queryKey: [...todoQueries.details(), id],
      queryFn: () => fetchTodo(id),
      staleTime: 5 * 60 * 1000,
    }),
};

下面逐一解释这个模式的优点。

1. 同时获得层级结构和类型推断。

todoQueries.all() 和 todoQueries.lists() 只返回数组，而 todoQueries.detail(1) 返回通过 queryOptions 创建、带有 data tag 的对象。做缓存失效时使用数组，调用查询时则使用 options 对象。

useQuery(todoQueries.detail(1));                                // 옵션 객체
queryClient.invalidateQueries({ queryKey: todoQueries.all() }); // 배열

2. 可以在组件中局部覆盖 options。

queryOptions 的结果归根结底是对象，因此可以在调用时组合一部分 options。

const { data: title } = useQuery({
  ...todoQueries.detail(1),
  select: (todo) => todo.title,  // 컴포넌트별로 다른 select 적용
});

这个模式尤其强大的一点是，select 的返回类型会被自动推断，data 的类型也随之收窄为 string。对组件来说，可以只选择自己需要的部分，同时把 domain 定义完整保留在同一处。

3. 包装 useQuery 的自定义 hook 会逐渐消失。

在 v4 时代，常见模式是为每个 domain 创建自定义 hook。

这种方式的问题在于：一旦需要 prefetch，就必须再写一遍相同定义。 useTodoDetail 是 hook，无法在组件外调用，因此在 router loader 或 event handler 中，还得重新写一遍 queryClient.prefetchQuery({ queryKey: [...], queryFn: ... })。

使用 queryOptions 后，这种重复就消失了。

同一份定义可以在任何地方工作。因此，TkDodo 建议“在 v5 中，与其创建 hook，不如定义 queryOptions”。hook 只在需要时作为一层薄封装，而 domain 定义即使没有 hook 也能自成一体。

变更后的缓存失效

queryKey 的层级结构真正大放异彩的场景，是 mutation 之后的缓存失效。根据 TanStack Query 的 Query Invalidation 文档，invalidateQueries 默认采用 prefix matching。

// 모든 todos 관련 쿼리 (list, detail, lists 모두)
queryClient.invalidateQueries({ queryKey: todoQueries.all() });
 
// 모든 list만 (detail은 건드리지 않음)
queryClient.invalidateQueries({ queryKey: todoQueries.lists() });
 
// 정확히 이 키만 (자식 키 매치 안 함)
queryClient.invalidateQueries({
  queryKey: todoQueries.detail(1).queryKey,
  exact: true,
});
 
// 더 복잡한 조건은 predicate으로
queryClient.invalidateQueries({
  predicate: (query) =>
    query.queryKey[0] === 'todos' &&
    (query.queryKey[2] as any)?.version >= 10,
});

如果键按层级设计，缓存失效的范围就会与代码语义一致。 “更新全部 todos”用 all() 表达，“只更新列表”用 lists() 表达，“只更新这个条目”则用 detail(id) 表达。

如果键像 ['todoList']、['todoDetail', 1] 那样扁平地散落各处，要让“整个 todos 领域”失效，就必须分别调用两行代码，或者另行创建并维护前缀常量。（每次新增领域键时，一旦忘记把它加进那个常量，就会发生缓存失效遗漏的问题。）

在 queryFn 中重新取出 queryKey

最后还有一种模式值得介绍。queryFn 实际上会接收一个名为 QueryFunctionContext 的对象作为参数，其中原样包含调用时的 queryKey。

queryOptions({
  queryKey: ['user', userId, { include: 'profile' }] as const,
  queryFn: ({ queryKey }) => {
    const [, id, options] = queryKey;
    return fetchUser(id, options);
  },
});

这个模式为什么有用？根据 TkDodo 的 Leveraging the Query Function Context，它可以强制同步 queryKey 与 queryFn 的依赖关系。

const sortBy = 'name';
 
queryOptions({
  queryKey: ['users'],
  queryFn: () => fetchUsers({ sortBy }),
});

这段代码存在风险，因为 queryFn 依赖外部变量；而且即便 sortBy 发生变化，缓存也不会更新，因为没有把这个依赖放进键。只要 queryFn 仍从外部闭包取值，这类失误就随时可能发生。

解决方案很简单：不要让 queryFn 依赖外部变量。**如果所有依赖都从 queryKey 中取出，**那么没有放进 queryKey 的变量，从一开始就无法在函数内部使用。

queryOptions({
  queryKey: ['users', { sortBy }] as const,
  queryFn: ({ queryKey: [, { sortBy }] }) => fetchUsers({ sortBy }),
});

采用这种写法后，出现新依赖时，如果不把它加入 queryKey，函数内部就根本无法使用。编译器会直接提示：“键里没有这个属性。”也就是说，我们把键与函数的同步从编码约定交给了类型系统。

应当拆分到什么程度

读到这里，可能会有一个疑问：“那么，所有查询都应该抽成 queryOptions 吗？”

我的回答一如既往：“视情况而定。”

需要记住的是，抽象并不总是好事。对于只使用一次的查询，如果也硬要抽进领域工厂，只会让读代码的人不得不在两个文件间来回切换。queryKey 管理模式的演进并不意味着“始终都要使用更精细的工具”，而应该理解为：“在需要时，可以选择逐级采用更复杂的方案。”

总结

总而言之，queryKey 是 TanStack Query 识别并缓存异步数据最根本的单元。这个小数组中浓缩了缓存槽标识符、依赖数组、缓存失效范围；到了 v5，甚至还包含数据类型信息。正因为如此多的责任都聚集在这一点上，queryKey 的编写和管理方式会直接影响整个代码库的认知负担。

每一个阶段，都是对当时某位开发者所遇到真实问题的回答。因此，正确的顺序不是“现在已经是 v5，所以一律只用 queryOptions”，而是先看：“我的代码库现在正面临哪一阶段的问题？” 对一个内联数组已经足够的项目引入 domain factory，本身就可能是过度设计。

也希望读到这里的各位，能抽时间检查一下自己的项目：queryKey 如何散落在整个代码库中，缓存失效以什么方式进行，以及当前结构是否与团队规模和 domain 复杂度相匹配。

参考资料

笔者在实际工作中编写错误处理代码时，经常会有一种说不清的不踏实感。有些错误用 try/catch 捕获，有些由 ErrorBoundary 捕获，还有些则交给 TanStack Query 的 onError。它们的职责范围既有细微重叠，又存在错位。结果就是，有时错误悄悄漏了出去，有时又传播到了本不希望它抵达的地方。

问题在于，我们很少把这些工具的运行方式放在一起系统梳理。虽然知道“Error Boundary 只能捕获渲染阶段的错误”，但如果被追问这句话在实际运行中究竟意味着什么、调用 reset 后内部会发生什么，以及开启 throwOnError 后 TanStack Query 会在什么时机重新抛出错误，往往就很难准确回答。

本文将以 React 官方指南、react-error-boundary 库和 TanStack Query v5 官方文档为基础，梳理前端错误处理工具各自负责到哪里，以及应该如何组合。

React 能捕获与不能捕获的错误

先从最基础的问题开始：React 能捕获哪些错误？

React 官方文档明确区分了 Error Boundary 能捕获和不能捕获的错误。

Error Boundary 能捕获的范围

• 子组件**渲染（render）**过程中发生的错误
• **生命周期方法（lifecycle method）**中发生的错误
• **构造函数（constructor）**中发生的错误

Error Boundary 无法捕获的范围

• **事件处理器（event handler）**中的错误
• setTimeout、requestAnimationFrame、Promise 等异步代码中的错误
• **服务端渲染（SSR）**过程中的错误
• Error Boundary 自身发生的错误

为什么这种区分如此重要？因为我们平时处理的大多数错误，其实都属于第二类。比如点击按钮触发 mutation 后服务器返回 500、useEffect 中的 fetch 失败，或提交表单时校验逻辑抛出异常。这些错误不会被 React 自动捕获，必须由我们显式捕获并处理。

因此，前端错误处理分成两条路径：渲染阶段的错误交给 Error Boundary，其他错误交给 try/catch 或库提供的回调。TanStack Query 这类异步状态管理库，会在两条路径交汇之处充当桥梁。

Error Boundary 的本质

Error Boundary 本质上是一个拥有两个生命周期方法的类组件。根据 React 官方文档，要成为 Error Boundary，需要实现下面两个方法中的至少一个（通常两个都会实现）。

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }
 
  // 에러 발생 시 state를 업데이트해 다음 렌더에서 fallback UI를 보여준다
  static getDerivedStateFromError(error) {
    return { hasError: true };
  }
 
  // 에러가 발생한 직후에 호출. 로깅 같은 사이드이펙트는 여기서 처리한다
  componentDidCatch(error, info) {
    logErrorToMyService(error, info.componentStack);
  }
 
  render() {
    if (this.state.hasError) {
      return this.props.fallback;
    }
    return this.props.children;
  }
}

getDerivedStateFromError 必须是纯函数。它只负责返回新的 state，不能产生副作用。与之相对，componentDidCatch 正是用来执行副作用的地方。向 Sentry 上报错误或在控制台输出组件堆栈，都应该在这里完成。

这里有一点很重要：这两个方法只存在于类组件中。目前仍没有官方方式可以用函数组件创建 Error Boundary。React 官方文档也明确说明了这一点。

目前还无法将 Error Boundary 编写为函数组件。

There is currently no way to write an Error Boundary as a function component.

每次都亲自编写类组件很麻烦，因此通常会使用 react-error-boundary 库。（它由曾任 React 核心维护者的 Brian Vaughn 编写，实际上已经成为一种事实标准。）

react-error-boundary 的 3 种 fallback

react-error-boundary 的 ErrorBoundary 组件提供了三种方式来通过 prop 指定 fallback UI。下面简单看看各自的用法。

fallback

这是最简单的形式，直接传入静态 JSX。

<ErrorBoundary fallback={<div>문제가 발생했습니다.</div>}>
  <Page />
</ErrorBoundary>

不需要访问错误对象或 reset 函数时可以使用。实际项目通常需要显示错误消息或提供重试操作，所以笔者至今还没有在工作中用过这种方式。

FallbackComponent

将 fallback UI 拆成独立组件，再传入它的引用。

function ErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div role="alert">
      <p>오류가 발생했습니다.</p>
      <pre>{error.message}</pre>
      <button onClick={resetErrorBoundary}>다시 시도</button>
    </div>
  );
}
 
<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Page />
</ErrorBoundary>

错误对象和 resetErrorBoundary 函数会自动通过 props 注入。如果 fallback UI 可能在其他地方复用，这种方式会很清晰。

fallbackRender

希望内联编写 fallback 时使用。

<ErrorBoundary
  fallbackRender={({ error, resetErrorBoundary }) => (
    <div role="alert">
      <p>오류가 발생했습니다: {error.message}</p>
      <button onClick={resetErrorBoundary}>다시 시도</button>
    </div>
  )}
>
  <Page />
</ErrorBoundary>

它与 FallbackComponent 本质上做的是同一件事，但可以不创建独立组件，直接内联处理。需要访问外部闭包（例如父组件的 state 或处理函数）时很有用。

三种方式没有唯一正确答案。笔者在实际工作中最常用的模式，是创建一个共用的 ErrorFallback 组件，再通过 FallbackComponent 注入，因为需要保持设计系统和产品语调的一致性。只有当页面需要不同的 fallback 时，才会用 fallbackRender 内联编写。

reset 实际上做了什么？

使用 react-error-boundary 时，自然会遇到 resetErrorBoundary 函数，也就是在 fallback 中点击“重试”按钮时调用的函数。下面看看它实际做了什么。

先说结论：resetErrorBoundary 只是向 ErrorBoundary 组件发出信号，让它重置自身状态并重新渲染 children。它不会自动修改 TanStack Query 缓存等任何外部状态。

按步骤展开，内部会发生以下事情。

1. 调用 resetErrorBoundary()。
2. ErrorBoundary 内部的 hasError 状态恢复为 false。
3. （可选）执行 onReset 回调，用户自定义的副作用会在这里发生。
4. 重新渲染 children。如果引发错误的根因（状态、缓存等）依然存在，同一个错误就会再次被抛出。

关键在最后一步。**reset 只意味着“忘掉错误，再尝试渲染一次”，并不意味着“修复导致错误的原因”。**因此，如果只做 reset，同一个错误可能会无限重复。

为了解决这个问题，还需要另外两个工具。

onReset

它的作用类似一个在 reset 即将发生前调用的钩子，可在这里清理导致错误的外部状态。

<ErrorBoundary
  FallbackComponent={ErrorFallback}
  onReset={() => {
    queryClient.invalidateQueries({ queryKey: ['user'] });
  }}
>
  <Page />
</ErrorBoundary>

resetKeys

当数组中的值发生变化时，ErrorBoundary 会自动 reset。可以传入 URL 参数、搜索词、当前标签页等能够判断“这个值变了，重新尝试就有意义”的键。

<ErrorBoundary
  FallbackComponent={ErrorFallback}
  resetKeys={[userId]}
>
  <UserProfile userId={userId} />
</ErrorBoundary>

userId 变化时会自动执行 reset，并重新渲染 children。用户切换到另一个个人资料后，之前的错误也会自然消失。

如何捕获事件处理器和异步错误？

前面提到，Error Boundary 无法捕获事件处理器和异步代码中的错误。但我们处理的大多数错误恰恰发生在那里，该怎么办？

为此，react-error-boundary 提供了 useErrorBoundary 钩子。这个钩子返回一个名为 showBoundary 的函数，调用它就能将错误强制抛给最近的 ErrorBoundary。

import { useErrorBoundary } from 'react-error-boundary';
 
function MyComponent() {
  const { showBoundary } = useErrorBoundary();
 
  const handleClick = async () => {
    try {
      await someAsyncOperation();
    } catch (error) {
      showBoundary(error);
    }
  };
 
  return <button onClick={handleClick}>실행</button>;
}

关键是，开发者必须显式地把错误向上提升，React 不会自动代劳。如果希望将异步错误转移到 ErrorBoundary 的职责范围，就要用 try/catch 捕获，再传给 showBoundary。

理解这个模式后，“为什么有些错误能被 ErrorBoundary 捕获，有些却不能”这个问题便迎刃而解。答案很简单：“有没有把它提升到渲染阶段。”

TanStack Query 如何处理错误？

梳理到这里，自然会产生另一个问题。我们每天使用的 useQuery 负责异步请求，其中发生的错误究竟如何处理？

TanStack Query 默认会通过 error 字段暴露错误。

const { data, error, isError } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
});
 
if (isError) {
  return <div>에러: {error.message}</div>;
}

这是最简单的形式。即使发生错误，组件仍会正常渲染，只不过 error 字段中有了值。ErrorBoundary 不会介入。

这里需要强调一个重要事实：**TanStack Query 的默认行为是“不抛出错误”。**无论 queryFn 中是 throw 还是 reject，错误都只会进入 error 字段，不会打断 React 的渲染流程。因此，如果没有额外配置，ErrorBoundary 永远不会被触发。

还有一点，TanStack Query 默认会在出错后自动重试 3 次。

默认 retryDelay 采用指数退避（exponential backoff），最长会增加到 30 秒。也就是说，首次失败后用户不会立刻看到错误。系统会分别间隔 1 秒、2 秒、4 秒重试，如果仍然失败，才会填充 error 字段。（如果你在开发时曾疑惑“为什么错误这么晚才出现？”，十有八九就是这个原因。）

用 throwOnError 连接 ErrorBoundary

那么，怎样才能让 TanStack Query 的错误流向 ErrorBoundary？答案是 throwOnError 选项。（在 v4 之前它叫 useErrorBoundary，到 v5 更名为 throwOnError。）

const { data } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  throwOnError: true,
});

启用这个选项后，TanStack Query 会在下一个渲染周期重新 throw 错误。这样，该 throw 就成为渲染阶段的错误，ErrorBoundary 终于能够捕获它。

throwOnError 也可以接收函数。这样就能分流：某些错误交给 ErrorBoundary，另一些由组件自行处理。

useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  // 5xx 서버 에러만 ErrorBoundary로 보낸다
  throwOnError: (error) => error.response?.status >= 500,
});

这个模式之所以实用，是因为4xx 之类的客户端错误（例如输入校验失败、权限不足）通常更适合就地显示消息，而对于5xx 之类的服务端错误，则更适合覆盖整个页面并提示“请稍后重试”。

useSuspenseQuery

如果使用的是 useSuspenseQuery，就无需考虑 throwOnError。在 Suspense 模式下，默认行为就是始终抛出错误。

换句话说，使用 useSuspenseQuery 就意味着：加载状态由 Suspense 处理，错误由 ErrorBoundary 处理。组件内部不再需要 if (isError) 或 if (isLoading) 之类的分支，但需要在外部用这两个边界包裹组件。

QueryErrorResetBoundary

读到这里，又会产生一个问题：用户在 fallback 中点击“重试”按钮后会发生什么？

如前所述，resetErrorBoundary 只会重置 ErrorBoundary 的 hasError 状态。但 TanStack Query 缓存里仍然留着持续处于错误状态的查询。children 重新渲染后，TanStack Query 查看缓存，判断“这个查询已经出错”，便会立即再次抛出同一个错误。（这会形成可怕的无限循环。）

为了解决这个问题，TanStack Query 提供了 useQueryErrorResetBoundary 钩子和 QueryErrorResetBoundary 组件。名字虽长，作用却很简单：发出一条命令，“重置这个区域内所有查询的错误状态”。

import { useQueryErrorResetBoundary } from '@tanstack/react-query';
import { ErrorBoundary } from 'react-error-boundary';
 
function App() {
  const { reset } = useQueryErrorResetBoundary();
 
  return (
    <ErrorBoundary
      onReset={reset}
      fallbackRender={({ resetErrorBoundary }) => (
        <div>
          <p>에러가 발생했습니다.</p>
          <button onClick={resetErrorBoundary}>다시 시도</button>
        </div>
      )}
    >
      <Page />
    </ErrorBoundary>
  );
}

下面按时间顺序梳理这里发生的事情。

1. 用户点击“重试”按钮 → 调用 resetErrorBoundary()
2. ErrorBoundary 执行 onReset 回调 → 调用 reset()（重置 TanStack Query 的错误状态）
3. ErrorBoundary 重置自身状态并重新渲染 children
4. children 中的 useQuery 开始运行 → 错误状态已清除，因此重新尝试 fetch

关键是把 onReset 与 reset 连接起来的部分。正是这一行代码让 ErrorBoundary 和 TanStack Query 的状态保持同步。

使用组件形式

不用钩子，也可以通过组件完成同样的事情。两者选择一个即可。

import { QueryErrorResetBoundary } from '@tanstack/react-query';
import { ErrorBoundary } from 'react-error-boundary';
 
function App() {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary
          onReset={reset}
          fallbackRender={({ error, resetErrorBoundary }) => (
            <div role="alert">
              <p>에러가 발생했습니다: {error.message}</p>
              <button onClick={resetErrorBoundary}>다시 시도</button>
            </div>
          )}
        >
          <Page />
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}

它与钩子版本最大的区别，是通过 render prop 模式把 reset 函数传给子组件。QueryErrorResetBoundary 将函数作为自己的 children，调用时传入 { reset }，再渲染该函数的返回值。因此，可以在函数内部直接连接 onReset={reset}。

如果找不到最近的 QueryErrorResetBoundary，钩子版本会重置全局缓存中的错误。组件版本则只会在自己的子组件区域内限定 reset 范围。如果希望精确控制作用域，组件版本更稳妥。

这里还要说明一点：**reset 不会清空缓存。**它不会删除全部数据，而更接近于“解除被标记为错误的查询状态”。如果确实要让数据失效，需要另行调用 queryClient.invalidateQueries()。

Mutation 的错误

到目前为止，讨论的模式几乎都以 useQuery 为基准。但 useMutation 的情况有所不同。

最大的区别在于，mutation 通常由**用户的显式操作（点击、提交）**触发。因此，在靠近操作发生的位置处理错误更自然。与其用 fallback 覆盖整个页面，不如通过 toast 消息或表单旁的错误文字提示“支付失败：请重新检查银行卡信息”。

TkDodo 在 精通 React Query 中的 Mutation一文中，用一句话概括了这种差异的本质：**Query 是声明式（declarative）的，而 Mutation 是命令式（imperative）的。**Query 会在组件挂载后自动执行，其他组件也能订阅同一个键，并且结果会被缓存复用。相对地，mutation 只有在用户点击按钮后才会执行，既不缓存，也与调用它的组件实例一一绑定。这种本质差异将两者的错误处理方式分开了。

useQuery 的默认 retry 是 3，但 useMutation 的默认 retry 是 0。原因很简单：mutation 会产生副作用（side effect）。如果支付请求因网络超时失败，而库自动再调用两次，用户的银行卡可能会被扣款三次。

因此，原则上只有在开发者确信操作具有幂等性（idempotent）时，才应显式开启 mutation 重试。例如，重复发送同一请求也能保证结果一致的 GET 类安全查询，或者服务端接收幂等键（idempotency key）并能阻止重复操作的情况。

useQuery 的错误会写入缓存。因此，它会立即传播给订阅相同 queryKey 的其他组件，必须使用 QueryErrorResetBoundary 等机制统一重置。

mutation 则不同。某个组件的 mutation 实例发生错误后，错误只会保留在该实例的状态中，不会影响其他使用同一 mutationFn 的组件。因此，TanStack Query 中没有 MutationErrorResetBoundary 这种东西，因为根本不需要。

这一差异会给实际工作带来一个影响：如果两个组件调用同一个 useMutation，其中一个组件发生的错误不会出现在另一个组件中。如果希望“在应用全局感知这次 mutation 的错误”，组件级 onError 就不够了，需要将它提升到 MutationCache.onError。

mutate 与 mutateAsync

useMutation 会返回两种执行函数，它们的差异决定了错误处理方式。

mutate 的返回类型是 void，不返回 Promise。因此不能用 await 等待结果，只能通过 onSuccess/onError 等回调获取调用结果。

const mutation = useMutation({
  mutationFn: createPost,
  onError: (error) => {
    toast.error(`등록 실패: ${error.message}`);
  },
});
 
mutation.mutate(newPost);

相对地，mutateAsync 返回 Promise，可以用 try/catch 处理错误。

const mutation = useMutation({ mutationFn: createPost });
 
const handleSubmit = async () => {
  try {
    const result = await mutation.mutateAsync(newPost);
    router.push(`/posts/${result.id}`);
  } catch (error) {
    // 여기서 처리
  }
};

应该在什么情况下使用哪一个？笔者按以下标准区分。

• mutation 结束后需要执行后续操作（例如成功后跳转、使用返回值）→ mutateAsync
• 只需发起调用，副作用交给回调处理（例如切换点赞状态、只显示 toast）→ mutate + onError

这里有一个常见错误：**使用 mutateAsync 却没有添加 try/catch，会引发 unhandled promise rejection。**基于回调的 mutate 会自行吸收错误，而 mutateAsync 默认会把错误抛给调用方。如果不了解这个差异而混用两者，控制台就会充满红色警告。

onError

还有一个经常被忽略的细节：useMutation 的 onError 可以在两个位置（hook、mutate）定义。

const mutation = useMutation({
  mutationFn: createPost,
  onError: (error) => {
    Sentry.captureException(error);
  },
});

钩子级回调始终会执行，而 mutate 调用级回调只针对当前调用执行。

mutation.mutate(newPost, {
  onError: (error) => {
    setFormError(error.message);
  },
});

官方文档明确规定的执行顺序是：**钩子级 → mutate 调用级。**如果两个回调都已定义，会先执行钩子级回调，再执行 mutate 调用级回调。

全局错误处理

目前为止的模式都在组件层面。但实际也可能有“希望集中记录所有查询错误”或“遇到 401 错误必须退出登录”等需求。对于这类横切关注点，可以在创建 QueryClient 时为 QueryCache/MutationCache 注册回调。

import { QueryClient, QueryCache, MutationCache } from '@tanstack/react-query';
 
const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error, query) => {
      if (query.state.data !== undefined) {
        toast.error(`데이터 갱신 실패: ${error.message}`);
      }
    },
  }),
  mutationCache: new MutationCache({
    onError: (error) => {
      if (error.status === 401) {
        redirectToLogin();
      }
    },
  }),
});

关键在于，QueryCache.onError 对每个查询只调用一次。即使有多个组件订阅同一个查询，回调也只执行一次，因此不会出现重复 toast 等问题。

也可以像上面的例子一样检查 query.state.data !== undefined。如果是已有缓存数据时 refetch 失败，用户至少还能在页面上看到数据。这时用 ErrorBoundary 覆盖整个页面就有些过度，只需告知用户刷新失败即可。相反，如果首次加载就在没有缓存数据的情况下失败，则应该由 ErrorBoundary 捕获并显示 fallback。

将两条流程结合起来，就能设计出一套清晰的策略：“首次加载失败交给 ErrorBoundary，后台 refetch 失败则显示 toast”。

共用组件

读到这里，很自然会产生一个想法：每次都用 QueryErrorResetBoundary、ErrorBoundary 和 Suspense 包三层太麻烦，能否组合成一个组件复用？

这个想法很自然。笔者过去也曾创建并使用过下面这样的 AsyncBoundary 组件。

import { QueryErrorResetBoundary } from '@tanstack/react-query';
import { Suspense, type ComponentType, type ReactNode } from 'react';
import { ErrorBoundary, type FallbackProps } from 'react-error-boundary';
import { ErrorFallback } from './ErrorFallback';
import { Spinner } from './Spinner';
 
interface Props {
  children: ReactNode;
  pendingFallback?: ReactNode;
  rejectedFallback?: ComponentType<FallbackProps>;
}
 
export function AsyncBoundary({
  children,
  pendingFallback = <Spinner />,
  rejectedFallback = ErrorFallback,
}: Props) {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary onReset={reset} FallbackComponent={rejectedFallback}>
          <Suspense fallback={pendingFallback}>{children}</Suspense>
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}