本文是对 innei.in/posts/tech/lobehub-performance-dx-optimization 一文的分析。原文以 LobeHub 这个 ChatGPT/LLM 客户端项目为例，介绍了它在前端组件、Electron 主进程、Next.js 开发体验等多个层面做的一系列优化。本文不重复原文叙述，而是把里面散落的具体改动归纳成一个可以迁移的工程框架：四类成本 × 成本位置转移。

相关笔记

• [[笔记/web/Java/JVM 原理、性能调优与故障排查]]：JVM 调优和本文思路类似，都在做"把高频小成本摊薄"。

1. 先建立一个直觉：基础设施小成本会被组件数量放大

LobeHub 这一系列优化的共同前提是：单次操作 0.1 ms 不算贵，但乘以组件数量之后是另一回事。

文章里给出一个粗略的乘法：

0.1 ms × 500 个组件 = 50 ms

流畅渲染的帧预算是 16.7 ms。一旦基础设施里的某个微小操作变成了"每个组件渲染时都要做一次"，再乘以一两百个组件，就会从"可以忽略"变成"明显卡顿"。

这个直觉很重要。它解释了为什么 LobeHub 优化的是普通读者看上去根本不起眼的东西：

• 一个 <Flexbox> 组件函数本身的执行；
• 一次 useStyles() Hook 调用；
• 一次 Tooltip 的浮层初始化；
• 一个平时不可见的 Modal 在 React 树里挂着的 Hook。

这些都是"基础设施层小动作"。优化单个不会让某个页面从 1000 ms 降到 10 ms，但合起来，可以让一个打开首页就要 mount 几百个组件的应用变得明显顺畅。

接下来所有的具体改动，都可以理解为：把这个 0.1 ms 的小动作从"每次都发生"挪到"只发生一次"，或者挪到"真正需要时再发生"。

3. 替换 react-layout-kit：把 CSS-in-JS 的运行时挪到模块加载

react-layout-kit 的 Flexbox 看起来只是一个布局组件，但在 antd-style / Emotion 体系下，它内部仍然要：

组件执行
  ↓
读取 props
  ↓
构造样式对象
  ↓
序列化成 CSS 字符串
  ↓
计算 Hash
  ↓
查询 Emotion Cache
  ↓
没有命中则插入 CSS 规则
  ↓
返回 className

五种不同 props 组合：

<Flexbox gap={8} />
<Flexbox gap={12} />
<Flexbox gap={16} />
<Flexbox gap={8} align="center" />
<Flexbox gap={8} justify="center" />

每种都可能生成不同的 CSS：

.css-a1 { display: flex; gap: 8px; }
.css-b2 { display: flex; gap: 12px; }
.css-c3 { display: flex; gap: 16px; }

就算命中缓存，前面仍然要：执行组件函数、构造样式参数、做对象分配、做序列化、做 Hash 计算和查询。开发环境下还要保存调试信息和 source map，内存问题会更突出。

新方案：所有实例共享一份 CSS

LobeHub 自己写了一个内部 Flex，保持原 API，但底层换成固定类：

:where(.lobe-flex) {
  --lobe-flex: 0 1 auto;
  --lobe-flex-direction: column;
  --lobe-flex-wrap: nowrap;
  --lobe-flex-justify: flex-start;
  --lobe-flex-align: stretch;
  --lobe-flex-width: auto;
  --lobe-flex-height: auto;
  --lobe-flex-padding: 0;
  --lobe-flex-gap: 0;

  display: flex;
  flex: var(--lobe-flex);
  flex-direction: var(--lobe-flex-direction);
  flex-wrap: var(--lobe-flex-wrap);
  justify-content: var(--lobe-flex-justify);
  align-items: var(--lobe-flex-align);
  width: var(--lobe-flex-width);
  height: var(--lobe-flex-height);
  padding: var(--lobe-flex-padding);
  gap: var(--lobe-flex-gap);
}

组件只把 props 映射成 CSS 变量：

{children}

效果是：

gap=8   → 共享 .lobe-flex + 设置 --lobe-flex-gap: 8px
gap=12  → 共享 .lobe-flex + 设置 --lobe-flex-gap: 12px
gap=16  → 共享 .lobe-flex + 设置 --lobe-flex-gap: 16px

省掉的成本：

• 不再为每个 gap 值生成新 Hash 类名；
• 不再向 <style> 持续插入规则；
• 不再需要 Emotion Cache 查询。

新增的成本：

• 每次渲染需要构造一个小的 cssVars 对象；
• 拼一下 className。

后者明显比前者便宜。文章里指出，单组件开销大约 0.1 ms，真正严重的是几百个组件 × 0.1 ms。

CSS 变量默认值为什么要写在每个 Flex 上

CSS 自定义属性默认会继承。假设：

子元素没有显式定义 --lobe-flex-gap，可能继承父元素的 16px，子布局就多出一段间距。

所以内部 CSS 在每个 .lobe-flex 上都重置默认值：

:where(.lobe-flex) {
  --lobe-flex-gap: 0;
  --lobe-flex-direction: column;
  --lobe-flex-align: stretch;
}

这一层默认值是必要成本。读到类似的"用 CSS 变量驱动组件样式"代码时，可以直接检查是不是每一层都重置了默认值。

5. 首页常驻：React Activity 与"访问后缓存"

LobeHub 的首页（DesktopHomeLayout）里塞了很多东西：

• 侧边栏；
• 最近记录；
• 输入区域；
• 技能列表；
• 多个弹窗入口；
• 大量 store selector；
• 数据恢复逻辑。

旧路由结构大致是：

<Route path="/" element={<Home />} />
<Route path="/settings" element={<Settings />} />

进设置页再回首页，要走完整的卸载-重建链路：

Home Fiber 被卸载
  ↓
Home DOM 被删除
  ↓
Home Effect 被清理
  ↓
Home 子组件状态丢失
  ↓
返回时：
重新执行 Home
  ↓
重新执行所有子组件
  ↓
重新运行所有 Hook 和 selector
  ↓
重新创建 Fiber
  ↓
重新创建 DOM
  ↓
重新插入 DOM
  ↓
重新计算布局和绘制

文章测得 DesktopHomeLayout 返回时接近 500 ms。

改法：把首页移出路由分支

改造后的结构大致是：

<DesktopLayoutContainer>
  <DesktopHomeLayout>
    <DesktopHome />
  </DesktopHomeLayout>
  <Suspense fallback={<Loading />}>
    <Outlet />
  </Suspense>
</DesktopLayoutContainer>

原来 index route 不再单独创建首页组件。

首页内部根据路径判断：

const { pathname } = useLocation();
const isHomeRoute = pathname === '/';

<Activity mode={isHomeRoute ? 'visible' : 'hidden'}>
  <Home />
</Activity>

Activity 在 mode="hidden" 时的行为：

• display: none 隐藏内容；
• 保留组件的 React State；
• 保留对应 DOM；
• 清理组件的 Effect 和订阅；
• 隐藏期间仍可能以低优先级响应新 props；
• 再次显示时恢复原状态、重新创建 Effect。

可以理解为：

Fiber、State、DOM：保留
Effect、订阅：清理
视觉：display: none

返回时主要工作变成：

hidden → visible
  ↓
恢复 Effect
  ↓
浏览器重新展示已有 DOM

不再重建整个 DOM 树。

hasActivated：访问后缓存，不是启动时预渲染

实际代码里加了：

const [hasActivated, setHasActivated] = useState(isHomeRoute);
useEffect(() => {
  if (isHomeRoute) setHasActivated(true);
}, [isHomeRoute]);

if (!hasActivated) return null;

逻辑是：

用户从未访问首页 → 不创建首页
用户第一次访问首页 → 创建首页
用户以后离开首页 → 隐藏但保留

这是"访问后缓存"，不是"应用启动时无条件预渲染"。否则用户直接进 /settings，应用也会在后台把沉重的首页 mount 一遍，反而增加启动时间和内存。

绝对定位和代价

常驻首页容器使用：

style={{
  inset: 0,
  position: 'absolute',
}}

因为首页已经不属于正常路由输出，要避免它参与其他页面的文档流布局。首页可见时覆盖主内容，隐藏时由 Activity 设为不可见。

这种优化的代价是常驻占用：

• Fiber 内存；
• DOM 内存；
• 组件 State；
• 缓存数据；
• 浏览器布局对象。

适合的场景：

• 高频返回的首页；
• 编辑器；
• 聊天会话；
• 需要保留输入状态的页面。

不适合的场景：

• 很少返回的页面；
• DOM 特别庞大的报表；
• 大量 <video> / <audio> / <iframe> 页面。

<video>、<audio>、<iframe> 隐藏后 DOM 仍存在，可能继续执行自身行为，需要在 Effect 清理函数里显式暂停或释放。

7. Tooltip 单例化：共享一个浮层

旧 Tooltip 的每个实例都可能拥有：

• useFloating 定位逻辑；
• 鼠标进入/离开定时器；
• Focus 和 Hover 交互 Hook；
• Portal；
• Arrow 定位；
• Open State；
• Motion 动画；
• ResizeObserver；
• Scroll 监听；
• 自动更新位置逻辑。

页面里如果有 200 个图标各自包了 Tooltip：

<Tooltip title="编辑"><Button /></Tooltip>
<Tooltip title="删除"><Button /></Tooltip>
<Tooltip title="复制"><Button /></Tooltip>

即使都没打开 Tooltip，每个实例的触发器和 Hook 仍然要创建。文章里那个 TooltipFloating 接近 200 行，包含 Floating UI、debounce、AnimatePresence、动态 transformOrigin、内容切换动画、箭头逻辑、Portal 和布局动画。

单例 Tooltip 的结构

<TooltipGroup>
  <Tooltip title="编辑"><Button /></Tooltip>
  <Tooltip title="删除"><Button /></Tooltip>
  <Tooltip title="复制"><Button /></Tooltip>
</TooltipGroup>

每个 Tooltip 只注册：

触发节点
title
placement
回调

整个 Group 共享一个真正浮层：

一个 Root
一个 Portal
一个 Floating Content
一个 Arrow
一套定位状态

鼠标进入某个触发器后，只更新当前 payload：

activeItem = {
  title: '删除',
  anchor: deleteButton,
  placement: 'top',
};

浮层被重新定位到新 anchor，而不是每个按钮都创建完整的浮层组件树。

实际实现基于 Base UI 的 <BaseTooltip.Root handle={handle}>，由 Group Context 共享 handle。普通 Tooltip 发现自己位于 Group 内部就进入共享模式；受控 Tooltip、带 defaultOpen 或显式 standalone 的 Tooltip 保留独立实现。

为什么 Base UI 比完整 UI 库更容易优化

Base UI 属于 Headless 组件，主要提供：

• 可访问性；
• 交互状态；
• 定位；
• 键盘行为；
• ARIA；
• 基础 Portal。

样式和动画由项目自己控制。对比完整组件库，可以少承担：

• 兼容层；
• 主题包装；
• 多层 Context；
• 默认 DOM；
• 默认动画；
• 样式注入逻辑。

更准确的表述不是"Ant Design 慢、Base UI 快"，而是 "LobeHub 能基于 Base UI 实现更小的组件树和共享浮层"。是否值得换基础库要看你自己的项目里这种场景有多少。

9. Electron 包体积与原生模块三件事

Electron 主进程原本可能直接依赖：

import somePackage from 'some-package';

如果构建工具把依赖全部 externalize，产物里只保留 require('some-package')，运行时必须携带完整 node_modules/some-package。整个 node_modules 还包含：

• 未使用文件；
• README；
• 类型声明；
• Source Map；
• 多模块格式；
• 测试代码；
• 可选资源；
• 重复依赖。

改为打包普通 JS 依赖

优化后的 electron-vite 不再把所有依赖 externalize。普通 JavaScript 包会被 Rollup 打入：

dist/main/index.js
dist/preload/index.js

Rollup 顺手做：

• Tree Shaking；
• 去重；
• 压缩；
• 内联依赖；
• 删除未引用代码。

electron-builder 配置：

files: [
  'dist',
  'resources',
  '!node_modules',
  ...getFilesPatterns(),
]

整体排除 node_modules，只重新加入必须保留的原生依赖。

原生模块不能一起 Bundle

比如：

better-sqlite3
sharp
node-mac-permissions

这些包可能带 .node 文件，是本机动态库，不是 JavaScript。Node.js 加载它需要真实文件路径：

process.dlopen(...)

所以原生模块要同时满足三件事：

Rollup 不打包它

rollupOptions: {
  external: getExternalDependencies(),
}

生成结果仍然保留 require('node-mac-permissions')。

electron-builder 把它放进安装包

files: [...getFilesPatterns()]

从 ASAR 中解包

asarUnpack: getAsarUnpackPatterns()

最终文件落在 app.asar.unpacked/node_modules/...。

项目还会递归读取原生模块的 package.json，把它的传递依赖一并加入，否则原生模块本身存在，但启动时仍可能因为缺少子依赖而失败。

三项必须一致：

external 列表 = builder include 列表 = asarUnpack 列表

少任何一项都可能"构建成功，运行时失败"。这是 Electron 打包最容易被新人踩的坑。

Electron 语言资源删除

Electron Framework 自带 Chromium 本地化资源：

en.lproj
zh_CN.lproj
ja.lproj
fr.lproj

这些是 Chromium 原生界面资源，不是应用自己的 i18n JSON。

构建完成后的 afterPack Hook 遍历：

Electron Framework.framework/
  Versions/A/Resources/*.lproj

只保留英语相关目录：

new Set(['en', 'en_GB', 'en-US', 'en_US']);

不能全部删掉，Electron Framework 仍需要基本本地化资源。

11. IPC 类型安全：从字符串到 Controller 注册表

旧写法：

ipcRenderer.invoke('minimizeWindow', params);
ipcMain.handle('minimize-window', handler);

拼写不一致、TS 检查不出来、通道名 / 参数 / 返回值 / 主进程实现 / 渲染进程调用彼此独立。重构主进程方法时，调用方可能仍然编译通过，运行时才报错。

Controller + 装饰器

主进程改成：

export default class BrowserWindowsCtr extends ControllerModule {
  static override readonly groupName = 'windows';

  @IpcMethod()
  minimizeWindow() {
    BrowserWindow.getFocusedWindow()?.minimize();
    return { success: true };
  }
}

通道名自动推导为 windows.minimizeWindow。Controller 统一注册到 controllerIpcConstructors，既用于运行时安装 IPC Handler，也用于 TypeScript 提取服务类型。

渲染进程用 Proxy

const ipc = ensureElectronIpc();
await ipc.windows.minimizeWindow();

ensureElectronIpc() 可以用 JavaScript Proxy 收集属性访问：

ipc.windows.minimizeWindow()
  ↓
window.electronAPI.invoke('windows.minimizeWindow')

TypeScript 类型来自 Controller 注册表，能推导：

• 可用 Controller；
• 可用方法；
• 参数；
• 返回值。

但 TS 类型只在编译期存在。IPC 是跨进程边界，渲染进程可能被攻击，主进程仍然要做运行时参数校验，不能只依赖 TS。

13. Next.js 到 Vite：拆分前后端构建职责

LobeHub 的方案不是简单"删 Next.js"，而是拆分职责：

Vite
  ├─ React SPA
  ├─ Desktop UI
  ├─ Mobile UI
  ├─ React Router
  └─ 前端开发服务器

Next.js
  ├─ API Route
  ├─ Auth
  ├─ 服务端逻辑
  ├─ Serverless 部署
  └─ 必要的服务端入口

开发纯 UI 时只启动 Vite，不启动完整 Next.js App Router、RSC、服务端打包、路由分析流程。

大型 Next.js 项目开发内存较高的原因

App Router 项目开发时可能同时维护：

• 客户端模块图；
• 服务端模块图；
• RSC 模块图；
• 路由树；
• Server Action；
• Route Handler；
• 中间件；
• 热更新状态；
• Source Map；
• 构建缓存。

同一个模块还可能存在客户端版本、服务端版本、RSC 引用版本。Vite 纯 SPA 模式主要维护浏览器端 ESM 图，按请求转换模块，只开发 UI 时进程模型简单很多。

文章里的 Next.js: 10 GB+，Vite: 约 1 GB 是 LobeHub 项目自身的实验结果，不是所有项目都会固定相差十倍。项目规模、插件、Source Map、依赖树、Node.js 版本都会影响。

迁移代价

迁移后要重新处理：

• App Router 到 React Router 的路由映射；
• SSR 和 SEO；
• 服务端配置向前端注入；
• 鉴权和路由守卫；
• Next API 的代理；
• Vite 与 Next 两个开发服务器；
• 静态资源路径；
• Electron 和 Web 的构建差异；
• RSC 组件边界。

这属于架构级 DX 优化，不是简单地把 next dev 改成 vite。如果当前 Next.js 用得很顺，未必值得搬。

参考

[1] LobeHub 性能与 DX 优化. innei. https://innei.in/posts/tech/lobehub-performance-dx-optimization

[2] antd-style createStaticStyles. antd-style. https://github.com/ant-design/antd-style

[3] Base UI. MUI. https://base-ui.com/

[4] React Activity (Offscreen Component). React. https://react.dev/blog/2025/04/23/react-19-updates

[5] class-variance-authority. https://github.com/joebell.co.uk/cva

[6] electron-vite. https://electron-vite.org/

[7] electron-builder. https://www.electron.build/

Finished reading? Leave a comment

阅读说明

本文以 Spring Boot 2.7.18 的实现为基线，沿着 ConfigDataEnvironment.processAndApply() 的真实执行链路展开。

文章中的代码主要保留方法名、条件和数据结构，省略日志、异常包装和与主线无关的细节，便于观察控制流。

全文严格区分五个动作：

• resolve：把 ConfigDataLocation 解析为 ConfigDataResource。
• load：Loader 把 Resource 读取为 ConfigData 和 PropertySource。
• bind：从单个 PropertySource 绑定 spring.config.import 与 spring.config.activate。
• active：Contributor 在当前 ActivationContext 下满足激活条件。
• apply：最终把有效的 PropertySource 加入真实 Environment。

ConfigData 不是"读取完 application.yml 就结束"的文件加载器，而是一个分阶段求解配置依赖图的过程。每一阶段都会持续展开当前能够确定的 import，直到 Contributor Tree 达到稳定状态。Profile 确定后，再补充 profile-specific 资源，最后统一应用到 Environment。

2. 启动入口与初始 Contributor Tree

ConfigData 的执行入口位于 Environment 准备阶段。

SpringApplication 在创建和刷新 ApplicationContext 之前，先准备 ConfigurableEnvironment。EnvironmentPostProcessorApplicationListener 调用 ConfigDataEnvironmentPostProcessor，后者构造 ConfigDataEnvironment 并执行 processAndApply()。

此时以下工作均尚未开始：

• BeanDefinition 扫描；
• 自动配置类解析；
• 单例 Bean 创建；
• ApplicationContext 刷新。

入口调用链如下：

SpringApplication.run()
  └─ prepareEnvironment()
      └─ EnvironmentPostProcessorApplicationListener
          └─ ConfigDataEnvironmentPostProcessor.postProcessEnvironment()
              └─ ConfigDataEnvironment.processAndApply()

2.1 初始 Contributor 的来源

ConfigDataEnvironment 构造时，会读取当前 Environment 中已经存在的 PropertySource，并将它们包装成 Kind.EXISTING 的 Contributor。

这些来源通常包括：

• commandLineArgs
• systemProperties
• systemEnvironment
• defaultProperties

它们参与早期 Binder 查询和占位符解析，但不会被 ConfigData 机制再次导入。

随后，框架根据以下配置创建 INITIAL_IMPORT 节点：

• spring.config.import
• spring.config.additional-location
• spring.config.location

若没有显式配置 spring.config.location，则使用默认搜索位置，例如：

classpath:/
classpath:/config/
file:./
file:./config/
file:./config/*/

初始位置采用 Contributor 表示，而不是立即调用 Resolver，是为了让初始位置和后续 spring.config.import 位置都经过相同的处理流程：

选择待处理节点
    ↓
resolveAndLoad
    ↓
生成子 Contributor
    ↓
替换不可变树

初始树的逻辑结构如下：

ROOT
├─ EXISTING: commandLineArgs
├─ EXISTING: systemProperties
├─ EXISTING: systemEnvironment
├─ INITIAL_IMPORT: spring.config.import
├─ INITIAL_IMPORT: spring.config.additional-location
├─ INITIAL_IMPORT: spring.config.location / 默认搜索位置
└─ EXISTING: defaultProperties

INITIAL_IMPORT 不对应某个已经加载的文件，也不贡献 PropertySource。它只持有一组 ConfigDataLocation，用于在 withProcessedImports() 中触发第一次 resolveAndLoad()。

4. 贯穿全文的配置样例

下面的配置同时包含：

• 无条件 import；
• CloudPlatform 条件；
• Profile 条件；
• 递归 import；
• profile-specific 文件。

假定运行环境最终被识别为 Kubernetes，基础文档激活 dev Profile。

application.yml 的文档 0：

spring:
  profiles:
    active: dev
  config:
    import: classpath:common.yml
app:
  source: base

application.yml 的文档 1：

spring:
  config:
    activate:
      on-cloud-platform: kubernetes
    import: classpath:k8s.yml
platform:
  mode: kubernetes

application.yml 的文档 2：

spring:
  config:
    activate:
      on-profile: dev
    import: classpath:feature.yml
feature:
  mode: dev-document

common.yml：

spring:
  config:
    import: classpath:db.yml
common:
  enabled: true

db.yml：

db:
  url: jdbc:mysql://localhost/base

k8s.yml：

platform:
  service-discovery: dns

feature.yml：

feature:
  enabled: true

application-dev.yml：

spring:
  config:
    import: classpath:dev-db.yml
app:
  source: application-dev

dev-db.yml：

db:
  pool-size: 20

这里必须区分"文件"和"文档"。

application.yml 会被 Loader 一次性读取，但其中三个 YAML 文档会成为三个独立 PropertySource，随后生成三个独立 Contributor。

每个 Contributor 都有自己的：imports、activate、active 状态、children。

因此，一个文件已经被 Loader 读取，并不表示文件中的每个文档都在当前阶段生效。

6. processAndApply 的三次导入处理

processAndApply() 会调用三次 withProcessedImports()，但 ImportPhase 只有两种：

• BEFORE_PROFILE_ACTIVATION
• AFTER_PROFILE_ACTIVATION

前两次调用都属于 BEFORE，差异在于 ActivationContext 的完整度。第三次在 Profiles 创建后进入 AFTER。

主干流程如下：

processAndApply() {
    importer = new ConfigDataImporter(...);
    contributors = processInitial(contributors, importer);
    activationContext =
        createActivationContext(contributors.getBinder(...));
    contributors =
        processWithoutProfiles(contributors, importer, activationContext);
    activationContext =
        withProfiles(contributors, activationContext);
    contributors =
        processWithProfiles(contributors, importer, activationContext);
    applyToEnvironment(contributors, activationContext, ...);
}

6.1 第一次：context 为 null 的 BEFORE

processInitial() 传入 null ActivationContext。

ImportPhase.get(null) 返回 BEFORE_PROFILE_ACTIVATION。

没有 spring.config.activate 的文档，在 properties.isActive(null) 中仍然 active，因为其 activate 字段为 null。

声明了任意 activate 条件的文档会进入 Activate.isActive(null)，并直接返回 false。

这一阶段不只是读取 application.yml 一层。

无条件文档的 imports 会持续展开，例如：

application.yml
    ↓ import
common.yml
    ↓ import
db.yml

外层 while 会一直运行，直到整条当前可见的无条件依赖链都完成绑定与 import 处理。

6.2 第二次：CloudPlatform 已知，Profiles 仍为 null 的 BEFORE

第一次达到稳定状态后，createActivationContext() 使用当前 Environment 与 Contributor-backed Binder 推导 CloudPlatform，并明确把 profiles 设置为 null。

推导顺序是：先检查配置中是否强制指定 CloudPlatform，再调用 CloudPlatform.getActive(environment)。

processWithoutProfiles() 再次调用 withProcessedImports()。

当前 phase 仍然是 BEFORE，但此前因为 on-cloud-platform 而 inactive 的文档，现在可以重新判断。

平台匹配时，这些文档的 import 会被展开。

只声明 on-profile 的文档仍然 inactive。

同时声明平台和 Profile 的文档要求两个条件同时满足，因此要等待第三阶段。

6.3 Profile 推导与第三次 AFTER

withProfiles() 从当前 Contributor Tree 构造 Binder，过滤带 IGNORE_PROFILES 的 PropertySource，并读取：

• spring.profiles.active
• spring.profiles.default
• spring.profiles.include
• spring.profiles.group
• additionalProfiles

Profiles 构造器还会展开 Profile group，并使用 LinkedHashSet 保持顺序和终止循环。

随后 activationContext.withProfiles(profiles) 生成同时包含 CloudPlatform 与 Profiles 的新上下文。

processWithProfiles() 第三次调用 withProcessedImports()。

此时 activationContext.getProfiles() != null，所以 ImportPhase.get() 返回 AFTER_PROFILE_ACTIVATION。

这个阶段具备两项新增能力：

1. on-profile 文档可以判断为 active；
2. Resolver 除了普通 resolve()，还会执行 resolveProfileSpecific()。

标准文件 Resolver 因此能够发现：application-dev.yml、common-dev.yml、application-prod.yml。

8. 使用真实数据结构推演完整执行过程

8.1 初始树

忽略 EXISTING 节点后，初始树如下：

ROOT
└─ INITIAL_IMPORT
     imports = [classpath:/]
     children = {}

8.2 第一次 BEFORE：加载基础文档并展开无条件 import

INITIAL_IMPORT 被选中。它没有激活条件，imports 非空，并且 children 中没有 BEFORE key。

Resolver 在 profiles == null 时只执行普通 resolve，找到 application.yml。

Loader 读取三个 YAML 文档，生成一个 ConfigData。

asContributors() 按 PropertySource 逆序生成三个 UNBOUND_IMPORT，并通过 INITIAL_IMPORT.withChildren(BEFORE, children) 挂入新树：

INITIAL_IMPORT
└─ BEFORE
   ├─ UNBOUND application.yml#2
   ├─ UNBOUND application.yml#1
   └─ UNBOUND application.yml#0

此时三个文档都已经物理读取，但尚未绑定 activate 和 import。

后序 priority-order 遍历首先找到 application.yml#2。由于 Kind 为 UNBOUND_IMPORT，不检查 active，执行 withBoundProperties()，得到：

BOUND application.yml#2
  activate.on-profile = dev
  imports = [feature.yml]

当前 context 为 null，因此 isActive(null) == false，feature.yml 暂不展开。

接下来绑定 application.yml#1：

BOUND application.yml#1
  activate.on-cloud-platform = kubernetes
  imports = [k8s.yml]

context 仍为 null，所以同样 inactive，k8s.yml 暂不展开。

最后绑定 application.yml#0：

BOUND application.yml#0
  activate = null
  imports = [common.yml]
  spring.profiles.active = dev

它在 null context 下 active，因此下一轮会被选中，加载 common.yml，并写入 BEFORE children。

common.yml 先成为 UNBOUND common.yml，随后绑定为：

BOUND common.yml
  imports = [db.yml]

它没有激活条件，所以继续加载 db.yml。db.yml 绑定后没有 imports，不再成为待处理节点。

第一次 BEFORE 达到稳定状态后的树如下：

INITIAL_IMPORT
└─ BEFORE
   ├─ BOUND application.yml#2
   │    activate.on-profile = dev
   │    imports = [feature.yml]
   │    当前 inactive
   │
   ├─ BOUND application.yml#1
   │    activate.on-cloud-platform = kubernetes
   │    imports = [k8s.yml]
   │    当前 inactive
   │
   └─ BOUND application.yml#0
        imports = [common.yml]
        └─ BEFORE
           └─ BOUND common.yml
                imports = [db.yml]
                └─ BEFORE
                   └─ BOUND db.yml

此时 application.yml#1 和 application.yml#2 已经完成 load 与 bind，但没有展开内部 import。

第一次阶段结束的条件不是"所有文件都激活"，而是当前树中不存在：

• UNBOUND_IMPORT
• 以及不存在"active 且 BEFORE 尚未处理的 Contributor"

8.3 第二次 BEFORE：平台条件配置加入

createActivationContext() 推导出 CloudPlatform.KUBERNETES、profiles = null。

第二次后序遍历中，application.yml#1 的平台条件匹配：

activate.on-cloud-platform = kubernetes
当前平台 = Kubernetes

因此 isActive(context) == true，其 BEFORE key 尚不存在，所以加载 k8s.yml。

application.yml#1
  activate.on-cloud-platform = kubernetes
  isActive(context) = true
  children[BEFORE] = [k8s.yml]

k8s.yml 完成绑定后没有 imports。

application.yml#2 仍然要求 dev Profile，而 profiles == null：

application.yml#2
  activate.on-profile = dev
  isActive(context) = false

所以保持 inactive。

8.4 withProfiles：从 active 配置中推导 dev

withProfiles() 创建的 Binder 会过滤 IGNORE_PROFILES，并对关键绑定启用 FAIL_ON_BIND_TO_INACTIVE_SOURCE。

基础文档 application.yml#0 当前 active，其中的 spring.profiles.active: dev 会被读取。

Profiles 同时处理：

• spring.profiles.active
• spring.profiles.default
• spring.profiles.include
• spring.profiles.group
• additionalProfiles

完成 group 展开后，最终上下文为：

CloudPlatform = KUBERNETES
Profiles.active = [dev]

8.5 第三次 AFTER：Profile 条件与 profile-specific 文件加入

application.yml#2 重新判断时：

on-profile = dev
Profiles 接受 dev

因此变为 active。它的 AFTER key 不存在，所以 feature.yml 在 AFTER 阶段被加载并绑定。

已经在 BEFORE 处理过 imports 的节点，其 AFTER key 仍然不存在。因此，同一个 imports 会带着 Profiles 再交给 Resolver。

Resolver 执行：

resolve(location)
resolveProfileSpecific(location, profiles)

普通资源已经存在于 ConfigDataImporter.loaded，会被去重。只有新出现的 profile-specific Resource 才会进入加载结果。

INITIAL_IMPORT 在 AFTER 阶段重新解析 classpath:/。普通 application.yml 已经加载并被去重。

StandardConfigDataLocationResolver 针对 dev 生成 application-dev.yml。

StandardConfigDataLoader 会为该 PropertySource 标记 PROFILE_SPECIFIC。

application-dev.yml 先作为 UNBOUND_IMPORT 加入 AFTER children，再绑定得到：

imports = [dev-db.yml]

当前 Profile 已知，并且该文档 active，所以 dev-db.yml 继续在 AFTER 阶段展开。

最终树的大致结构如下：

INITIAL_IMPORT
├─ AFTER
│  └─ BOUND application-dev.yml
│       imports = [dev-db.yml]
│       └─ AFTER
│          └─ BOUND dev-db.yml
│
└─ BEFORE
   ├─ BOUND application.yml#2
   │    activate.on-profile = dev
   │    └─ AFTER
   │       └─ BOUND feature.yml
   │
   ├─ BOUND application.yml#1
   │    activate.on-cloud-platform = kubernetes
   │    └─ BEFORE
   │       └─ BOUND k8s.yml
   │
   └─ BOUND application.yml#0
        └─ BEFORE
           └─ BOUND common.yml
                └─ BEFORE
                   └─ BOUND db.yml

application.yml 的条件文档最初都位于 INITIAL_IMPORT 的 BEFORE children，因为它们来自第一次普通解析。它们内部的 import 在之后变为 active 时，会写入对应 phase 的 children。

application-dev.yml 来自 resolveProfileSpecific()，属于 profile-specific 资源，并在树结构调整后位于 AFTER 高优先级区域。

10. BEFORE 与 AFTER 的真实区别

ImportPhase 描述的是：当前节点的 imports 在 Profile 推导之前执行，还是在 Profile 推导之后执行。

它不直接表示节点 inactive 或 active。

ImportPhase.get() 的逻辑只有一个判断：

phase = activationContext != null
    && activationContext.getProfiles() != null
        ? AFTER_PROFILE_ACTIVATION
        : BEFORE_PROFILE_ACTIVATION;

因此 BEFORE 表示 Profiles 尚未确定，AFTER 表示 Profiles 已经确定。

10.1 Resolver 行为的差异

ConfigDataImporter 从 ActivationContext 中取得 Profiles，并传给 ConfigDataLocationResolvers.resolve(...)。

Resolvers 总是先调用普通解析 resolver.resolve(context, location)。

如果 Profiles 为 null，直接返回普通解析结果。

如果 Profiles 不为 null，还会执行 resolver.resolveProfileSpecific(context, location, profiles)。

因此：

• 普通解析：resolve(location)
• Profile 已知后的解析：resolve(location) + resolveProfileSpecific(location, profiles)

对于标准文件位置，resolveProfileSpecific() 会遍历 accepted profiles，并把 Profile 传入 StandardConfigDataReference。

例如：

• 目录 classpath:/ 产生 application-dev.yml 候选
• 明确文件 common.yml 产生 common-dev.yml 候选

StandardConfigDataLoader 检测 resource.getProfile() != null 时，会给对应 PropertySource 添加 PROFILE_SPECIFIC。

10.2 同一个 imports 处理两次

一个 BOUND Contributor 的 imports 在 BEFORE 完成后，只会拥有 children[BEFORE]。

进入 AFTER 时，hasUnprocessedImports(AFTER) 仍然返回 true。因此，同一个 Location 会在两种上下文中各解析一次。

第一次：Profiles = null，只解析普通资源。

第二次：Profiles = [dev]，解析普通资源 + profile-specific 资源。

ConfigDataImporter.loaded 使用 ConfigDataResource 去重，所以普通资源不会重复执行 Loader.load()。

第二次解析的价值在于发现此前不存在的 profile-specific Resource。

"处理两次"指的是：同一个配置位置在两种上下文中各执行一次 resolve，并不表示同一个文件一定被物理读取两次。

10.3 PROFILE_SPECIFIC 的树结构调整

withChildren(AFTER, children) 会调用 moveProfileSpecific()。

该方法会在 BEFORE 子树中寻找带 PROFILE_SPECIFIC Option 的子节点，把它们从原位置移出，去掉临时 Option 后加入当前节点的 AFTER children。

这个调整让 profile-specific 来源进入 Profile 激活后的高优先级区域，同时保留非 profile-specific import 的原有父子关系。

下面两个状态相关，但含义不同：

• fromProfileSpecificImport：来自 ConfigDataResolutionResult.isProfileSpecific()，表示 Resource 是由 resolveProfileSpecific() 产生的。
• PROFILE_SPECIFIC Option：附着在 PropertySource 上，用于后续树结构与优先级调整。

12. Options、去重、异常与最终优先级

12.1 ConfigData.Option 的来源与作用

Options 由 ConfigDataLoader 在构造 ConfigData 时提供，并按照 PropertySource 传递给 ofUnboundImport()。

Spring Boot 不会根据"本地配置、远程配置、配置中心"等类型统一推断这些标记。自定义 Loader 决定返回哪些 Options。

EMPTY_LOCATION 使用 IGNORE_IMPORTS，表示该 Location 合法，但没有实际 PropertySource，不应再从空节点中读取 import。

IGNORE_PROFILES 的精确定义是：忽略该 PropertySource 中影响 Profile 推导的属性。它不等同于"远程配置必然忽略 Profile"。

12.2 Resource 去重与循环 import

ConfigDataImporter 维护 Set<ConfigDataResource> loaded。

候选 Resource 已存在时，不会再次调用 Loader。

对应 Location 会被记录到 loadedLocations。

假设 A import B，B import A：

load A
  loaded = [A]

A import B
  load B
  loaded = [A, B]

B 再解析出 A 时
  loaded.contains(A) == true
  → 不会生成新的 Contributor，循环自然终止

去重依据是 ConfigDataResource.equals() 与 ConfigDataResource.hashCode()，而不是字符串 Location。

不同 Location 解析到同一个 Resource 时，同样只加载一次。

同一个 Location 在 AFTER 阶段解析出新的 profile-specific Resource 时，因为 Resource 不同，仍然可以加载。

12.3 optional、空位置与强制位置检查

optional: 前缀和 Resource 自身的 optional 状态，会被 ConfigDataImporter 记录。

ConfigDataNotFoundException 对 optional 位置采用忽略策略。非 optional 位置则按照 spring.config.on-not-found 的策略处理。

Resolver 可能返回一个合法的空目录 Resource。Loader 返回 ConfigData.EMPTY，随后创建 EMPTY_LOCATION Contributor。

最终 apply 前，checkMandatoryLocations() 会收集 active Contributor 中的非 optional imports，再减去：

• 树中已经出现的 Location
• loadedLocations
• optionalLocations

仍然存在的 Location 被视为没有成功解析的强制 import。

12.4 最终 apply 与属性优先级

applyToEnvironment() 先执行：

• 非法 Profile 属性校验；
• 强制位置检查。

随后使用 ContributorIterator 遍历整棵树。

只有满足以下条件的节点会加入 Environment：

Kind == BOUND_IMPORT
PropertySource != null
在最终 ActivationContext 下 active

结构化逻辑如下：

for (contributor : contributors) {
    if (kind == BOUND_IMPORT
            && propertySource != null) {
        if (contributor.isActive(finalContext)) {
            environment
                .getPropertySources()
                .addLast(propertySource);
        }
    }
}

inactive 节点仍然留在 Contributor Tree 中，但不会进入 Environment。

命令行参数、systemProperties 等 EXISTING PropertySource 已经位于 Environment 中，并且在 ConfigData 结果之前，所以保持更高优先级。

ConfigData 节点内部依赖 AFTER → BEFORE → parent 的遍历顺序。

最后 DefaultPropertiesPropertySource 会被移动到末尾，维持默认属性最低优先级。

14. 完整执行模型

ConfigData 的完整执行可以压缩为以下连续过程。

第一步，包装已有 Environment PropertySource，创建 INITIAL_IMPORT，组成 ROOT。

ROOT
├─ EXISTING
├─ INITIAL_IMPORT
└─ EXISTING

第二步，执行第一次 BEFORE。

context = null
Profiles = null
CloudPlatform = null

持续加载并绑定无条件文档，递归展开无条件 imports。

第三步，创建 ActivationContext。从 Environment 与 Contributor Binder 推导 CloudPlatform，Profiles 仍然为 null。

第四步，执行第二次 BEFORE。重新判断平台条件，持续展开 on-cloud-platform 文档的 imports。

第五步，计算 Profiles：

• 过滤 IGNORE_PROFILES
• 读取 active
• 读取 default
• 读取 include
• 读取 additionalProfiles
• 展开 group

第六步，执行第三次 AFTER。

• 重新判断 on-profile 条件。
• 每个 imports 带着 Profiles 再解析。
• 发现 application-dev.yml、common-dev.yml、其他 profile-specific Resource。
• 使用 loaded Resource 集合去重，并继续递归展开新节点。

第七步，每个阶段内部都执行同一套不动点算法：

后序 priority-order 遍历
    ↓
选择一个待处理节点
    ↓
绑定或者加载
    ↓
withReplacement 生成新树
    ↓
从根重新遍历
    ↓
直到当前阶段稳定

第八步，执行最终 apply。

• 校验强制位置
• 校验非法 Profile 属性
• 只加入 active BOUND PropertySource
• 按照 AFTER → BEFORE → parent 排序
• 设置 Environment 的 defaultProfiles 和 activeProfiles

最终心智模型如下：

• Contributor Tree 是 ConfigData 的中间表示
• ActivationContext 决定当前哪些节点可以继续展开
• ImportPhase 决定位置解析时是否拥有 Profiles
• ContributorIterator 给出优先级后序遍历
• withProcessedImports 的 while 把当前可求解的配置依赖持续展开到稳定
• applyToEnvironment 才把最终结果交给真实 Environment

Finished reading? Leave a comment

写这篇是因为最近又在排查一个网络问题，顺手把 HTTP 这几个版本的演进重新过了一遍。HTTP/1.1 已经用了二十多年，HTTP/2 是 2015 年标准化的，HTTP/3 这两年才在主流站点铺开。它们不是简单加几个字段，而是底层传输模型在变。

这篇把 HTTP/1.1、HTTP/2、HTTP/3 (QUIC) 放一起讲，沿着"为什么不够用 → 怎么改 → 改完还剩什么问题"这条线写下来。

相关笔记

• [[笔记/web/计算机网络/TCP 重传、滑动窗口、流量控制与拥塞控制]]
• [[笔记/web/计算机网络/计算机网络框架]]
• [[笔记/web/计算机网络/HTTP 1.1 与 HTTP 2 协议对比]]

1. HTTP/1.0 简史

HTTP 是 Tim Berners-Lee 在 1989 年搞出来的，最初的需求很简单：让分布在全世界的物理学家能互相引用文档。每个文档就是一个文件，浏览器把文件名发给服务器，服务器把内容返回回来。

第一个正式版本 HTTP/1.0（RFC 1945，1996 年）核心就一条：一次请求一次响应，然后断开 TCP。

浏览器  ── GET /index.html ──>  服务器
浏览器  <─ 200 OK + HTML   ──  服务器
浏览器  ── GET /logo.png   ──>  服务器（再建一条 TCP）
浏览器  <─ 200 OK + PNG   ──  服务器

一个页面里 10 张图片，就要建 10 次 TCP。TCP 握手 1.5 个 RTT，加上 TLS 又是几个 RTT。在拨号上网那个年代，握手是大头。

HTTP/1.0 没解决这个问题，但它定了一套可扩展的协议骨架：方法、状态码、首部字段、Body。这套骨架后来没变过——HTTP/2 改的是"怎么把这些东西传过去"，不是"这些东西是什么意思"。

3. 浏览器为什么要开 6 个连接

既然 HTTP/1.1 的连接是串行的，要并发就只能多开几条 TCP。

Chrome 对同一个域名默认并发 6 条，Firefox 也是 6 条左右。这不是 bug，是 HTTP/1.1 时代的必要妥协。

浏览器 → 域名 example.com
  连接 #1: GET /
  连接 #2: GET /a.js
  连接 #3: GET /b.css
  连接 #4: GET /1.png
  连接 #5: GET /2.png
  连接 #6: GET /3.png

副作用：

• 每条连接独立跑 TCP 拥塞控制，互相不协调；
• 每条连接都吃内存、文件描述符、端口；
• 前端工程师为了"减少请求数"发明了雪碧图、CSS/JS 合并、域名分片（sharding）这些奇技淫巧。

这些技巧在 HTTP/2 之后都不再需要了。

5. 二进制分帧

HTTP/1.x 的报文是文本：

GET /index.html HTTP/1.1\r\n
Host: example.com\r\n
\r\n

文本协议的好处是可读、调试方便。代价是解析慢、歧义多（换行到底是 \n、\r\n、还是别的）。

HTTP/2 换成二进制。每个帧有 9 字节固定头：

+-----------------------------------------------+
|                 Length (24)                    |
+---------------+---------------+---------------+
|   Type (8)    |   Flags (8)   |
+-+-------------+---------------+-------------------------------+
|R|                 Stream Identifier (31)      |
+=+=============================================================+
|                   Frame Payload (0...)                      ...
+---------------------------------------------------------------+

• Length：帧负载字节数
• Type：帧类型（HEADERS、DATA、PRIORITY 等）
• Flags：标志位（END_STREAM、END_HEADERS）
• Stream Identifier：流 ID

常见帧类型：

注意 HEADERS 和 DATA 是分开的帧。所以一个请求可以先发 HEADERS，再分多个 DATA 帧发 Body，每个 DATA 帧任意长度。

7. HPACK 头部压缩

HTTP 头部是 Web 性能的老油条问题：

• 普通请求的头部大约 600-800 字节；
• Cookie、User-Agent、Accept、Referer 这些字段每个请求几乎一样；
• HTTP/1.x 不压缩头部（gzip 是压 body 的）；
• 一个页面 50 个请求，光头部就是 30-40 KB。

HTTP/2 引入了 HPACK（RFC 7541）。

静态表与动态表

核心是两张表：

• 静态表：规范写死的 61 个常见 header 名值对，比如 :method GET、:scheme https、:authority example.com。
• 动态表：连接双方各自维护的、可变化的表。

发送 header 时：

• 在静态表里 → 只发 1 字节索引；
• 在动态表里 → 发索引 + 匹配方式；
• 都不在 → 发字面值，可选地插入动态表。

第一次发：

:method = GET            → 索引 2
:scheme = https          → 索引 7
:authority = example.com → 字面值，插入动态表 #62
:path = /api/users       → 字面值，插入动态表 #63
user-agent = curl/7.0    → 字面值

第二次同域名请求：

:method = GET            → 索引 2（1 字节）
:scheme = https          → 索引 7（1 字节）
:authority = example.com → 索引 62（动态表，1 字节）
:path = /api/posts       → 字面值
user-agent = curl/7.0    → 字面值

Huffman 编码

字面值还会用一套专门为 HTTP 头部字符频率设计的 Huffman 编码再压一遍。解码是 O(n) 位运算，性能高。

为什么 HPACK 比 gzip 更适合 HTTPS

有人会问：gzip 压一下不就完了？

关键是安全：

• gzip 是基于上下文的压缩，靠重复模式；
• 攻击者可以通过观察压缩长度推断明文——这就是 CRIME 和 BREACH 攻击；
• HPACK 是基于字典索引的预定义编码，攻击者无法通过长度推断明文。

HPACK 是为了"在 HTTPS 下既压缩又安全"专门设计出来的。

9. HTTP/2 没解决的：TCP 层的队头阻塞

HTTP/2 解决了应用层的队头阻塞，没解决传输层的。

为什么？HTTP/2 的多路复用是逻辑层面的，底层还是一条 TCP。TCP 把数据看作有序字节流，协议规定：

任何一个包丢失，TCP 必须缓存所有后续包，直到丢失的包被重传并交付，才能交给上层应用。

所以一旦某个 TCP 包丢了，整条连接的所有 HTTP/2 流都卡住——即使其他流的帧早就到了。

Stream 1: HEADERS → DATA → DATA → [包丢失] → 等重传
Stream 3: HEADERS → DATA → DATA → [包到了] → 但被 TCP 缓存住
Stream 5: HEADERS → DATA → DATA → [包到了] → 但被 TCP 缓存住

在丢包率低的有线网络这不是问题。但移动网络、卫星网络、地铁车厢这些场景，HTTP/2 的优势会被严重削弱。

还有两个 HTTP/2 没解决的：

• 握手开销：TCP 三次握手 + TLS 1.2 至少 3-RTT 才能传第一个字节；
• 连接迁移：TCP 连接绑四元组（IP + 端口），切换网络（Wi-Fi → 4G）就断了。

为了解决这些，Google 干脆把 TCP 也换了，基于 UDP 做了 QUIC。这就是 HTTP/3。

11. 握手对比：为什么 HTTP/3 是 0-RTT

这是 HTTP/3 最容易被低估的改进。先看对比：

HTTP/1.1 + TLS 1.2

TCP 握手:   SYN → SYN+ACK → ACK                            (1 RTT)
TLS 握手:   ClientHello → ServerHello+Cert+... → Finished  (2 RTT)
HTTP 请求:  GET /                                          (3 RTT 才能传第一个字节)

HTTP/2 + TLS 1.2

跟 HTTP/1.1 一样的握手开销，只是 ALPN 协商时声明 h2。

HTTP/2 + TLS 1.3

TCP 握手:   SYN → SYN+ACK → ACK                            (1 RTT)
TLS 1.3:    ClientHello → ServerHello+Finished+Cert        (1 RTT)
HTTP 请求:  GET /                                          (2 RTT)

TLS 1.3 把握手从 2-RTT 降到 1-RTT。

HTTP/3 + QUIC

QUIC 握手（内置 TLS 1.3）:  ClientHello → ServerHello+Cert+Finished  (1 RTT)
HTTP 请求:                  GET /                                      (1 RTT)

如果是恢复连接（之前连过）：ClientHello 直接带 Early Data
                                              ↓
                                       (0 RTT 就能传应用数据)

QUIC 把 TCP 握手和 TLS 握手合并了。1-RTT 握手 + 0-RTT 恢复。

0-RTT 不是没有代价——存在重放攻击风险，所以一般只用于幂等请求（GET、HEAD）。涉及金钱的操作（POST、转账）不能用 0-RTT。

13. 落地：Nginx 怎么开 HTTP/2 和 HTTP/3

HTTP/2

server {
    listen 443 ssl http2;
    server_name example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    # 性能调优
    http2_max_field_size       16k;
    http2_max_header_size      32k;
    http2_max_requests         1000;
    http2_body_buffer_size     16k;

    location / {
        root /var/www/html;
    }
}

http2 是 listen 的参数，不是单独的配置项。必须搭配 HTTPS——浏览器不支持明文 HTTP/2。

HTTP/3

Nginx 1.25.0+ 原生支持 QUIC（之前是实验模块）：

server {
    # 监听 UDP 443（不是 TCP）
    listen 443 quic reuseport;
    # 同时监听 TCP 443 兜底
    listen 443 ssl http2;
    server_name example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    # 告诉客户端 HTTP/3 可用
    add_header Alt-Svc 'h3=":443"; ma=86400';

    location / {
        root /var/www/html;
    }
}

关键点：

• 443 端口要同时监听 TCP 和 UDP——HTTP/3 走 UDP，老客户端走 TCP/HTTP/2；
• add_header Alt-Svc 让浏览器知道这个站点支持 HTTP/3；
• reuseport 让多个 worker 进程共享同一个 UDP 端口；
• 防火墙必须放行 UDP 443（很多公司内网只放 TCP 443，HTTP/3 在这种网络下不可用）。

验证

# HTTP/2
curl -I --http2 https://example.com
# 输出：HTTP/2 200

# HTTP/3
curl -I --http3 https://example.com
# 需要 curl 编译时带 quiche 或 ngtcp2

# 浏览器
# Chrome DevTools → Network → Protocol 列
# 看到 h2 表示 HTTP/2，h3 表示 HTTP/3

15. 参考

[1] RFC 1945 - HTTP/1.0. https://datatracker.ietf.org/doc/html/rfc1945

[2] RFC 7230 - HTTP/1.1: Message Syntax and Routing. https://datatracker.ietf.org/doc/html/rfc7230

[3] RFC 7540 - HTTP/2. https://datatracker.ietf.org/doc/html/rfc7540

[4] RFC 7541 - HPACK. https://datatracker.ietf.org/doc/html/rfc7541

[5] RFC 8446 - TLS 1.3. https://datatracker.ietf.org/doc/html/rfc8446

[6] RFC 9000 - QUIC. https://datatracker.ietf.org/doc/html/rfc9000

[7] RFC 9114 - HTTP/3. https://datatracker.ietf.org/doc/html/rfc9114

[8] High Performance Browser Networking. Ilya Grigorik. https://hpbn.co/

[9] HTTP/2 简介. Google Developers. https://developers.google.com/web/fundamentals/performance/http2

[10] Chrome Status - HTTP/2 Server Push 移除. https://chromestatus.com/feature/5762410658996224

[11] Nginx HTTP/2 模块. https://nginx.org/en/docs/http/ngx_http_v2_module.html

[12] 图解网络. 小林. https://xiaolincoding.com/network/

Finished reading? Leave a comment

虚拟线程执行下面这段代码时，表面上和普通线程没有区别：

int count = socket.getInputStream().read(buffer);
process(buffer, count);

当 Socket 暂时没有数据，当前虚拟线程会暂停。承载它的 Carrier Thread 随后可以运行其他虚拟线程。网络数据到达后，原虚拟线程重新得到调度，read() 返回，代码继续执行 process()。

这里容易产生几个疑问：

• Carrier Thread 只能线性执行代码，当前方法还没有执行完，它怎么去运行另一个任务？
• 虚拟线程暂停后保存在哪里？
• 网络事件到达时，Poller 如何找到对应的虚拟线程？
• 调度队列中保存的是虚拟线程、回调函数，还是完整调用栈？
• 网络数据怎样回到原来的 buffer？
• Continuation.yield()、Thread.yield() 和 LockSupport.park() 分别负责什么？

本文以 JDK 21 的实现为基线，沿着一次 Socket 读取的调用过程分析这些问题。JDK 21 的虚拟线程采用 M:N 调度，大量虚拟线程由 JDK 调度到少量平台线程上运行；默认调度器是一个独立的 ForkJoinPool。（OpenJDK）

Carrier Thread 没有任务切换指令

先去掉虚拟线程，只看一个普通的工作线程：

final class Worker extends Thread {
    private final BlockingQueue<Runnable> queue;
    Worker(BlockingQueue<Runnable> queue) {
        this.queue = queue;
    }
    @Override
    public void run() {
        while (!isInterrupted()) {
            try {
                Runnable task = queue.take();
                task.run();
            } catch (InterruptedException e) {
                interrupt();
            }
        }
    }
}

这条线程始终线性执行。它从队列取出一个 Runnable，调用 run()，等待该方法返回，然后进入下一轮循环。

Runnable taskA = queue.take();
taskA.run();
Runnable taskB = queue.take();
taskB.run();

Carrier Thread 的工作方式也是如此。它不会在 taskA.run() 尚未返回时，突然跳到 taskB.run()。

虚拟线程能够切换，是因为 taskA.run() 可以在业务调用尚未完成时暂时返回。返回之前，JVM 会保存虚拟线程的调用栈。以后再次执行这个任务时，JVM 恢复原调用栈，代码继续运行。

因此，一条 Carrier Thread 上实际发生的是：

virtualThreadAResumeTask.run(); // 保存调用栈后暂时返回
virtualThreadBResumeTask.run(); // Carrier 回到调度循环后执行

Carrier Thread 仍然遵守普通方法调用规则。特殊能力位于 Continuation，它允许一段尚未完成的调用栈暂停和恢复。

调度队列中保存了什么

JDK 21 的 VirtualThread 内部有几个关键字段。省略诊断、线程容器和中断处理后，可以整理成下面的结构：

final class VirtualThread extends Thread {
    private final Executor scheduler;
    private final Continuation cont;
    private final Runnable runContinuation;
    private volatile int state;
    private volatile boolean parkPermit;
    private volatile Thread carrierThread;
}

其中：

• scheduler 指向虚拟线程调度器。
• cont 保存可暂停和恢复的执行状态。
• runContinuation 是提交给调度器的任务。
• state 记录虚拟线程当前处于运行、挂起或可调度状态。
• parkPermit 保存一次 unpark 许可。
• carrierThread 指向当前承载该虚拟线程的平台线程。

构造虚拟线程时，会创建 Continuation，并生成一个绑定到当前虚拟线程的方法引用：

this.cont = new VThreadContinuation(this, task);
this.runContinuation = this::runContinuation;

方法引用可以展开成一个普通的 Runnable：

final class ResumeTask implements Runnable {
    private final VirtualThread virtualThread;
    ResumeTask(VirtualThread virtualThread) {
        this.virtualThread = virtualThread;
    }
    @Override
    public void run() {
        virtualThread.runContinuation();
    }
}

调度队列中保存的核心内容是这样一个恢复任务。它持有 VirtualThread 引用，而 VirtualThread 再持有 Continuation。

ForkJoinPool.WorkQueue
    └── ForkJoinTask
          └── runContinuation
                └── VirtualThread
                      └── Continuation

VirtualThread 不直接操作 ForkJoinPool 中的某个工作队列。它只调用：

scheduler.execute(runContinuation);

默认调度器收到普通 Runnable 后，会将其包装为 ForkJoinTask，再放入内部队列。OpenJDK 的注释说明，在调度器 Worker 上提交时，任务进入本地队列；其他线程提交时，任务进入外部提交队列。（GitHub）

虚拟线程第一次运行

启动虚拟线程时，内部会把状态由 NEW 修改为 STARTED，随后提交 runContinuation：

void start() {
    if (!compareAndSetState(NEW, STARTED)) {
        throw new IllegalThreadStateException();
    }
    submitRunContinuation();
}
private void submitRunContinuation() {
    scheduler.execute(runContinuation);
}

某条 Carrier Thread 从 ForkJoinPool 队列中取出任务，最终调用：

virtualThread.runContinuation();

runContinuation() 的主要结构如下：

private void runContinuation() {
    int initialState = state();
    if (initialState != STARTED
            && initialState != UNPARKED
            && initialState != YIELDED) {
        return;
    }
    if (!compareAndSetState(initialState, RUNNING)) {
        return;
    }
    mount();
    try {
        cont.run();
    } finally {
        unmount();
        if (cont.isDone()) {
            afterDone();
        } else {
            afterYield();
        }
    }
}

mount() 将当前平台线程记录为 Carrier，并修改 JVM 中的当前线程身份：

private void mount() {
    Thread carrier = Thread.currentCarrierThread();
    setCarrierThread(carrier);
    carrier.setCurrentThread(this);
}

因此，虚拟线程中的业务代码调用：

Thread.currentThread()

得到的是 VirtualThread 对象，而不是底层 Carrier Thread。

随后执行：

cont.run();

第一次调用时，Continuation 从用户任务入口开始执行。OpenJDK 的 runContinuation() 确实是在 mount() 后调用 cont.run()，并在 finally 中完成 unmount() 和后续状态处理。（GitHub）

Continuation.yield() 如何释放 Carrier

假设业务代码的调用关系如下：

void handleRequest(Socket socket) throws IOException {
    User user = loadUser();
    byte[] buffer = new byte[1024];
    int count = socket.getInputStream().read(buffer);
    process(user, buffer, count);
}

虚拟线程执行到网络等待位置时，Carrier Thread 上的逻辑调用栈可能是：

ForkJoinPool.runWorker()
VirtualThread.runContinuation()
Continuation.run()
handleRequest()
InputStream.read()
NioSocketImpl.implRead()
Poller.poll()
LockSupport.park()
VirtualThread.park()
Continuation.yield()

执行 Continuation.yield() 后，JVM 会冻结属于当前 Continuation 的栈帧。局部变量、对象引用、调用关系和程序执行位置都会被保留。

例如，handleRequest() 对应的栈帧中可能存在：

socket  -> Socket@100
user    -> User@200
buffer  -> byte[]@300
count   -> 尚未赋值

这些数据属于虚拟线程的执行状态，不再依赖当前 Carrier Thread 的平台栈。

冻结成功后，控制流会离开 Continuation，回到调用 cont.run() 的位置。此时属于虚拟线程的深层调用栈已经从 Carrier Thread 上移走，Carrier Thread 上只剩调度器相关栈帧：

ForkJoinPool.runWorker()
VirtualThread.runContinuation()

cont.run() 随后返回，runContinuation() 进入 finally，执行 unmount()：

private void unmount() {
    Thread carrier = this.carrierThread;
    carrier.setCurrentThread(carrier);
    setCarrierThread(null);
}

runContinuation() 返回后，Carrier Thread 回到 ForkJoinPool 的工作循环，从队列中获取其他任务。

后续某条 Carrier Thread 再次调用 cont.run() 时，JVM 恢复此前冻结的栈帧，原来的 Continuation.yield() 开始返回，调用链依次继续：

Continuation.yield() 返回
VirtualThread.park() 返回
LockSupport.park() 返回
Poller.poll() 返回
NioSocketImpl.implRead() 继续

这里没有重新调用 handleRequest()，也没有从方法开头重新执行。恢复点位于此前暂停的位置。

park() 为什么不会立即重新入队

Continuation.yield() 只负责暂停执行，它并不决定虚拟线程什么时候继续。调度策略取决于是谁调用了它。

虚拟线程调用 Thread.yield() 时，当前线程依然具备运行条件，只是暂时让出 Carrier。执行栈冻结后，afterYield() 会立即重新提交 runContinuation：

RUNNING
  -> YIELDING
  -> YIELDED
  -> 重新提交
  -> RUNNING

LockSupport.park() 表达的是等待条件尚未满足。例如等待网络数据、等待锁释放或者等待队列元素。执行栈冻结后，虚拟线程不能立即重新进入运行队列，否则会不断恢复、检查条件、再次挂起，造成 CPU 空转。

它的状态变化为：

RUNNING
  -> PARKING
  -> PARKED

只有其他线程调用 unpark() 后，它才重新具备运行条件：

PARKED
  -> UNPARKED
  -> 重新提交
  -> RUNNING

OpenJDK 的 afterYield() 会检查当前状态。PARKING 会转为 PARKED，默认不重新提交；YIELDING 会转为 YIELDED 并立即提交。（GitHub）

对应代码可以简化为：

private void afterYield() {
    int s = state();
    if (s == PARKING) {
        setState(PARKED);
        if (parkPermit
                && compareAndSetState(PARKED, UNPARKED)) {
            submitRunContinuation();
        }
        return;
    }
    if (s == YIELDING) {
        setState(YIELDED);
        submitRunContinuation();
    }
}

Socket 读取如何进入 Poller

下面进入网络 I/O 路径。

int count = socket.getInputStream().read(buffer);

以 JDK 21 在 Linux 上的实现为例，JDK 会先尝试读取 Socket。内核接收缓冲区已有数据时，读取直接完成，不需要挂起虚拟线程。

如果当前没有数据，非阻塞读取会得到 EAGAIN 或等价状态。JDK 随后将文件描述符注册给 Poller，并挂起当前虚拟线程。JEP 444 描述了这一处理：JDK 中的阻塞网络操作无法立即完成时，虚拟线程会卸载；I/O 可以完成后，再把该虚拟线程提交回调度器。（OpenJDK）

简化后的读取逻辑如下：

int read(int fd, byte[] buffer) throws IOException {
    while (true) {
        int result = nonBlockingRead(fd, buffer);
        if (result >= 0) {
            return result;
        }
        Poller.poll(fd);
    }
}

Poller.poll(fd) 内部可以抽象为：

void poll(int fd) {
    Thread thread = Thread.currentThread();
    waiters.put(fd, thread);
    registerWithEpoll(fd);
    LockSupport.park();
}

由于当前执行的是虚拟线程，Thread.currentThread() 返回对应的 VirtualThread。

此时存在两份关联。

Linux 内核中的 epoll 记录：

监听 fd 37 的可读事件

JDK 的 Poller 记录：

fd 37 -> VirtualThread@500

操作系统只认识文件描述符，不认识 Java 虚拟线程。Poller 中的映射负责将内核事件重新关联到 Java 线程对象。JDK 21 的 Poller 就是网络事件通知和虚拟线程唤醒之间的中间层。（GitHub）

注册完成后，当前虚拟线程执行：

LockSupport.park();

park() 进入 VirtualThread.park()，设置 PARKING 状态并调用 Continuation.yield()。执行栈冻结后，虚拟线程变成 PARKED，Carrier Thread 被释放。

等待期间的对象关系如下：

Linux epoll
    └── fd 37
Poller
    └── fd 37 -> VirtualThread@500
VirtualThread@500
    ├── state = PARKED
    ├── carrierThread = null
    └── Continuation
          └── 保存 read() 及其上层调用栈
ForkJoinPool
    └── 当前没有该虚拟线程的恢复任务

虚拟线程此时没有占用 Carrier Thread，也不在运行队列中。Poller 保存它的等待关系，Continuation 保存它的执行状态。

网络就绪后如何重新调度

网络数据到达后，Linux 协议栈将字节放入 Socket 的内核接收缓冲区，并将 fd 标记为可读。

Linux 上的 Poller 线程通常阻塞在 epoll_wait()。事件返回后，它获得就绪的文件描述符：

int[] readyFds = epollWait();
for (int fd : readyFds) {
    Thread thread = waiters.remove(fd);
    if (thread != null) {
        LockSupport.unpark(thread);
    }
}

Poller 不执行用户的 handleRequest()，也不会在 Poller Thread 中调用原来的 InputStream.read()。它只找到等待该 fd 的虚拟线程，然后调用 unpark()。

VirtualThread.unpark() 的关键逻辑如下：

void unpark() {
    Thread currentThread = Thread.currentThread();
    if (!getAndSetParkPermit(true)
            && currentThread != this) {
        int s = state();
        if (s == PARKED
                && compareAndSetState(PARKED, UNPARKED)) {
            submitRunContinuation();
        }
    }
}

submitRunContinuation() 最终执行：

scheduler.execute(runContinuation);

这一步把虚拟线程重新交给调度器。OpenJDK 的 unpark() 会先设置 parkPermit，再通过状态 CAS 将已挂起的虚拟线程转为 UNPARKED，随后提交其恢复任务。（GitHub）

由于调用 unpark() 的通常是 Poller Thread，它不属于默认调度器的 Worker，因此这次任务一般走 ForkJoinPool 的外部提交路径。

某条 Carrier Thread 之后取出该任务，再次调用：

virtualThread.runContinuation();

状态由 UNPARKED 修改为 RUNNING，虚拟线程挂载到新的 Carrier Thread，然后执行：

cont.run();

此前冻结的调用栈被恢复，LockSupport.park() 返回，Socket 读取逻辑继续。

网络数据没有进入调度队列

调度队列中没有网络数据，也没有下面这种对象：

new ResumeTask(virtualThread, networkData);

Poller 的职责是通知“fd 现在可能可读”，调度器负责安排虚拟线程继续执行。网络字节仍然保存在 Socket 的内核接收缓冲区中。

虚拟线程恢复后，读取循环再次调用操作系统：

int read(int fd, byte[] buffer) throws IOException {
    while (true) {
        int result = nonBlockingRead(fd, buffer);
        if (result >= 0) {
            return result;
        }
        Poller.poll(fd);
        // park 返回后，再次进入循环
    }
}

第一次 nonBlockingRead() 返回 EAGAIN，虚拟线程进入等待。

网络就绪后，Poller 调用 unpark()，虚拟线程恢复，随后再次执行：

nonBlockingRead(fd, buffer);

这一次内核接收缓冲区已有数据，系统调用将字节复制到原来的 buffer 中，并返回字节数。

之所以仍然能够访问原来的 buffer，是因为 Continuation 保存的调用栈中仍持有：

buffer -> byte[]@300

数据传递路径为：

网卡
  -> Linux 网络协议栈
  -> Socket 内核接收缓冲区
  -> 虚拟线程被唤醒
  -> 恢复 read() 调用栈
  -> 再次执行 read()
  -> 数据复制到原 buffer

调度队列只传递执行资格。Poller 只传递就绪通知。网络数据由内核 Socket 缓冲区保存。

parkPermit 解决丢失唤醒

虚拟线程准备挂起时，网络事件可能提前到达。

考虑下面的时序：

虚拟线程发现当前没有数据
Poller 注册 fd
网络数据立即到达
Poller 调用 unpark()
虚拟线程随后才执行 park()

如果 unpark() 只能唤醒已经处于 PARKED 状态的线程，这次通知就会丢失。虚拟线程之后进入 park()，可能一直无法恢复。

parkPermit 相当于一个容量为 1 的许可：

private volatile boolean parkPermit;

unpark() 首先设置：

parkPermit = true;

park() 开始时先尝试消费许可：

if (getAndSetParkPermit(false)) {
    return;
}

如果网络事件已经到达，park() 直接返回，不再冻结调用栈。

连续调用多次 unpark() 也只会保存一个许可：

unpark(thread);
unpark(thread);
unpark(thread);

最终仍然只是：

parkPermit = true

下一次 park() 消费该许可后恢复为 false。

这也是 JUC 同步器通常使用循环检查条件的原因：

while (!conditionSatisfied()) {
    LockSupport.park();
}

park() 返回只说明线程重新获得执行机会，业务条件仍需重新判断。

PARKING 解决重复调度

RUNNING 和 PARKED 两个状态还不够，因为调用栈冻结需要一段执行过程。

虚拟线程会先执行：

state = PARKING;
Continuation.yield();

在设置 PARKING 后、Continuation 完成冻结前，Poller 可能已经调用 unpark()。

此时原 Carrier Thread 仍可能执行当前虚拟线程，不能立刻把恢复任务提交给调度器。否则另一条 Carrier Thread 可能同时取出该虚拟线程。

因此，在 PARKING 状态下，unpark() 只设置 parkPermit，暂不提交任务。

等 Continuation 冻结完成，原 Carrier 执行 afterYield()：

state = PARKED;
if (parkPermit
        && compareAndSetState(PARKED, UNPARKED)) {
    submitRunContinuation();
}

这样既保留了提前到达的唤醒通知，也避免两条 Carrier Thread 同时运行同一个虚拟线程。

另外，runContinuation() 在恢复前还会对状态执行 CAS。即使调度队列中意外出现两个指向同一虚拟线程的恢复任务，也只有一条 Carrier Thread 能成功将状态改为 RUNNING。

三条线程如何协作

完整实现虽然涉及 ForkJoinPool、Continuation、Poller 和操作系统，但运行过程仍然可以拆成三条普通线程循环。

Carrier Thread 的循环：

while (true) {
    Runnable task = scheduler.takeTask();
    task.run();
}

Poller Thread 的循环：

while (true) {
    int[] readyFds = epollWait();
    for (int fd : readyFds) {
        VirtualThread thread = waiters.remove(fd);
        LockSupport.unpark(thread);
    }
}

虚拟线程中的 Socket 读取循环：

while (true) {
    int count = tryRead(fd, buffer);
    if (count >= 0) {
        return count;
    }
    registerPoller(fd, Thread.currentThread());
    LockSupport.park();
}

三条执行流都保持线性。它们通过以下对象建立联系：

ForkJoinPool WorkQueue
    保存可运行的 runContinuation
VirtualThread
    持有 scheduler、Continuation 和线程状态
Poller
    保存 fd 到 VirtualThread 的等待关系
Socket 内核接收缓冲区
    保存网络数据

Carrier Thread 调用恢复任务，Poller 根据 fd 找到等待线程，虚拟线程通过 scheduler 重新提交自己，Continuation 保存暂停位置和局部对象引用。

完整调用路径

将整个过程连接起来，可以得到下面的关键路径：

Thread.startVirtualThread
  -> VirtualThread.start
  -> submitRunContinuation
  -> ForkJoinPool 工作队列
  -> Carrier 取出任务
  -> VirtualThread.runContinuation
  -> mount
  -> Continuation.run
  -> 用户代码
  -> Socket.read
  -> 非阻塞 read 返回 EAGAIN
  -> Poller 注册 fd
  -> LockSupport.park
  -> VirtualThread.park
  -> Continuation.yield
  -> 调用栈被冻结
  -> cont.run 暂时返回
  -> unmount
  -> VirtualThread 进入 PARKED
  -> Carrier 返回调度循环
网络数据到达
  -> Socket 内核接收缓冲区
  -> epoll_wait 返回 fd
  -> Poller 找到 VirtualThread
  -> LockSupport.unpark
  -> VirtualThread.unpark
  -> submitRunContinuation
  -> ForkJoinPool 工作队列
  -> Carrier 取出恢复任务
  -> VirtualThread.runContinuation
  -> mount
  -> Continuation.run
  -> 恢复被冻结的调用栈
  -> LockSupport.park 返回
  -> 再次执行 read
  -> 数据复制到原 buffer
  -> 用户代码继续

理解这条路径后，虚拟线程的调度就不再神秘。Carrier Thread 始终执行普通任务循环；Continuation 允许当前任务在保留调用栈的情况下暂时返回；Poller 将网络 fd 与等待中的虚拟线程关联起来；unpark() 在事件到达后重新提交恢复任务。

JDK 21 与 JDK 24 的 Pinning 差异

JDK 21 中，如果虚拟线程在持有 synchronized Monitor 时进入某些阻塞操作，Continuation 可能无法卸载，虚拟线程和 Carrier Thread 会一起阻塞，这种情况称为 Pinning。

因此，JDK 21 阶段经常建议避免在长时间 synchronized 临界区中执行网络 I/O，必要时使用 ReentrantLock。

JDK 24 交付了 JEP 491，修改了 JVM Monitor 与虚拟线程的协作方式。虚拟线程在 synchronized 方法或代码块中阻塞时，绝大部分情况下也能卸载并释放 Carrier Thread。JDK 24 之后，选择 synchronized 还是 java.util.concurrent.locks，应更多依据可中断获取、公平性、超时和条件变量等语义，而不是单纯为了规避 Monitor Pinning。（OpenJDK）

持锁期间执行长时间网络 I/O 仍然需要谨慎。即便 Carrier 能够释放，锁本身仍然处于持有状态，其他需要进入同一临界区的线程仍会等待。

参考源码

• JEP 444：Virtual Threads。（OpenJDK）
• JDK 21 java.lang.VirtualThread。（GitHub）
• JDK 21 jdk.internal.vm.Continuation。（GitHub）
• JDK 21 sun.nio.ch.Poller。（GitHub）
• JEP 491：Synchronize Virtual Threads without Pinning。（OpenJDK）

Finished reading? Leave a comment

最近在整理一套可以长期复用的 TypeScript 项目模板。

我的项目大多是 AI 工具、管理后台、工作流、编辑器和桌面端配套应用。技术栈以 React、TypeScript 和 Vite 为主，后端会使用 Node.js、PostgreSQL 和 Drizzle。

一开始考虑的是直接选择一个 React 全栈框架，把路由、SSR、数据请求、API 和部署统一起来。重点看了 Next.js、React Router Framework Mode 和 TanStack Start，也顺带关注了 Remix 3。

研究了一段时间后，我发现框架能力并不是越完整越合适。对于偏重交互的应用，SSR 和同构运行模型会引入不少额外概念，而这些概念未必能直接转化为产品收益。

最后确定的方向是：

公开站点使用 SSR 或 SSG
登录后的产品使用 SPA
业务能力通过统一 HTTP API 提供

这篇文章记录一下具体的判断过程。

TanStack Start 的吸引力

TanStack Start 很符合我对现代 TypeScript 框架的期待。

它建立在 TanStack Router 和 Vite 之上，提供类型安全路由、Search Params、Loader、Server Function、Middleware 和 SSR。再配合 TanStack Query、Form 和 Table，可以形成一套完整的前端应用开发体系。

一个简单的服务端查询可以写成：

export const listProjectsFn = createServerFn()
  .handler(async () => {
    return db.select().from(projects)
  })

路由中直接调用：

export const Route = createFileRoute('/projects')({
  loader: () => listProjectsFn(),
  component: ProjectsPage,
})

组件通过路由读取结果：

function ProjectsPage() {
  const projects = Route.useLoaderData()

  return <ProjectList projects={projects} />
}

这种写法不需要手动维护 HTTP Client 和返回类型。Server Function 在客户端表现得像一个普通的异步函数，输入和输出类型可以直接推导。

对于简单页面，这套模式很顺畅。

问题主要出现在页面交互开始变复杂之后。

例如，列表需要手动刷新，可以调用：

router.invalidate()

如果列表使用 TanStack Query，则会写成：

query.refetch()

新增一条记录后，可以重新执行路由 Loader：

await router.invalidate()

也可以让 Query Cache 失效：

await queryClient.invalidateQueries({
  queryKey: ['projects'],
})

这时项目里可能同时存在两套数据生命周期：

Route Loader 管理路由数据
TanStack Query 管理客户端缓存

如果继续加入 Query Options、Mutation、TanStack Form、TanStack Table 和 Zod，一个普通 Feature 很容易拆出很多文件：

project.server.ts
project.functions.ts
project.queries.ts
project.mutations.ts
project.schema.ts
project.form.ts
project.columns.tsx

这些模块单独看都有合理用途，但组合起来后，简单业务的框架代码占比会比较高。

TanStack 生态本身没有要求项目必须这样写。问题在于它提供的能力很多，开发者很容易在项目初期就把完整方案铺开。

对于复杂 Dashboard、实时数据、无限列表和乐观更新，这些抽象能够发挥作用。对于普通 CRUD，它们可能显得偏重。

Next.js 的复杂度在运行边界

Next.js 的代码通常更短。

Server Component 可以直接查询数据库：

export default async function ProjectPage() {
  const projectList = await db
    .select()
    .from(projects)

  return <ProjectList projects={projectList} />
}

修改操作可以写成 Server Action：

'use server'

export async function createProject(
  formData: FormData,
) {
  await db.insert(projects).values({
    name: String(formData.get('name')),
  })

  revalidatePath('/projects')
}

页面直接提交：

<form action={createProject}>
  <input name="name" />
  <button type="submit">创建</button>
</form>

这种模式对内容站、电商和以服务端渲染为主的页面很合适。页面、数据读取和修改逻辑可以放在相近的位置，项目初期的代码量也不大。

随着客户端交互增加，代码会逐渐涉及：

Server Component
Client Component
Server Action
Route Handler
Suspense
缓存失效
序列化边界

Next.js 的额外成本通常不表现为大量包装函数，而是运行模型和框架规则。

对于编辑器、工作流和管理后台，页面里往往有较多本地状态、轮询、实时数据、弹窗和多区域交互。此时 Server Component 与 Client Component 的边界需要持续维护。

Next.js 依然是成熟的生产方案，只是它更偏向以服务端组件和页面渲染为中心组织应用，不完全符合我目前的产品形态。

React Router 的数据模型比较统一

React Router Framework Mode 使用 Loader 和 Action 组织路由数据。

export async function loader() {
  return {
    projects: await listProjects(),
  }
}

export async function action({
  request,
}: Route.ActionArgs) {
  const formData = await request.formData()

  return createProject({
    name: String(formData.get('name')),
  })
}

export default function ProjectsPage({
  loaderData,
}: Route.ComponentProps) {
  return (
    <>
      <ProjectList projects={loaderData.projects} />

      <Form method="post">
        <input name="name" />
        <button type="submit">创建</button>
      </Form>
    </>
  )
}

它的模型比较接近传统 Web 开发：

读取数据使用 loader
修改数据使用 action
页面提交使用 Form 或 fetcher

Action 完成后，React Router 会重新验证相关 Loader，因此普通表单场景不需要额外维护 Query Cache。

这种方式适合表单和路由驱动的应用。Request、Response、Cookie、Session 和上传都使用标准 Web API，调试路径也比较清楚。

页面内操作较多时，Action 可能需要根据 intent 分发不同业务：

switch (formData.get('intent')) {
  case 'create':
    return createProject(formData)

  case 'archive':
    return archiveProject(formData)

  case 'delete':
    return deleteProject(formData)
}

也可以拆成独立 Resource Route。

React Router 的代码量通常介于 Next.js 和完整 TanStack 方案之间。它适合传统 Web 数据流，但对于复杂客户端缓存和多个组件共享远程状态，项目最终仍可能引入 TanStack Query。

SPA 的数据流更适合产品后台

把几个全栈框架放在一起比较之后，我重新审视了普通 SPA。

一个 SPA 项目的远程数据流很直接：

React Component
    ↓
TanStack Query
    ↓
HTTP API
    ↓
业务逻辑
    ↓
数据库

查询：

const projectsQuery = useQuery({
  queryKey: ['projects'],
  queryFn: projectApi.list,
})

手动刷新：

<button onClick={() => projectsQuery.refetch()}>
  刷新
</button>

新增后刷新列表：

const createProjectMutation = useMutation({
  mutationFn: projectApi.create,

  onSuccess: () => {
    queryClient.invalidateQueries({
      queryKey: ['projects'],
    })
  },
})

这套模型只有一份远程数据状态。

查询使用 useQuery
修改使用 useMutation
缓存刷新使用 invalidateQueries
页面参数使用 Router Search Params
本地状态使用 useState 或 Jotai

对于登录后的管理系统，这样的模型已经足够。

管理后台、AI 工具和工作流应用通常不会依赖搜索引擎索引内部页面。用户登录后会停留较长时间，主要操作发生在浏览器端。

SSR 在这些页面中的收益有限，但会增加 Hydration、服务端与客户端模块边界、Loader 生命周期和缓存同步等问题。

因此，我决定不让整个产品都进入 SSR 模型。

SSR 与 SPA 按路由区域拆分

最终的产品路由可以分成三个区域：

/                     官网首页
/pricing              定价页面
/blog/*                博客
/docs/*                文档
/tools/*               公开工具页面

/app/*                 登录后的产品
/app/projects/*        项目管理
/app/workflows/*       工作流
/app/analytics/*       数据分析

/api/*                 业务 API

公开区域使用 SSR 或 SSG，负责：

• SEO；
• 首屏内容；
• Open Graph；
• 博客和文档；
• 产品介绍；
• 公开工具页面。

/app 区域使用 SPA，负责：

• Dashboard；
• 工作流；
• 编辑器；
• AI 生成；
• 实时数据；
• 复杂表格；
• 多面板交互。

API 负责：

• 认证；
• 权限；
• 业务逻辑；
• 数据库访问；
• 文件上传；
• Webhook；
• Desktop 和其他客户端。

这样每个区域只维护一种主要数据模型。

最终的 Monorepo 结构

目前比较适合我的结构是：

repo/
├── apps/
│   ├── site/
│   ├── web/
│   ├── api/
│   ├── desktop/
│   └── worker/
│
├── packages/
│   ├── ui/
│   ├── contracts/
│   ├── db/
│   ├── shared/
│   └── config/
│
├── pnpm-workspace.yaml
├── package.json
└── tsconfig.json

各应用的职责如下：

apps/site
    官网、博客、文档和公开页面

apps/web
    登录后的 SPA 产品

apps/api
    统一业务 API

apps/desktop
    Tauri 客户端，需要时增加

apps/worker
    异步任务和 AI Job，需要时增加

共享包保持克制。

packages/ui 存放基础组件、样式 Token 和动画预设。

packages/contracts 存放真正需要跨客户端共享的 Zod Schema、错误结构和 API 类型。

packages/db 存放 Drizzle Schema、Migration 和数据库 Client。

业务代码默认留在具体 App 中，不会在项目开始阶段就提取到 packages/core。

API 使用 Hono

API 层选择 Hono。

它的路由写法比较轻：

const app = new Hono()

const projectRoutes = app
  .get('/projects', async (c) => {
    return c.json(await listProjects())
  })
  .post(
    '/projects',
    zValidator('json', createProjectSchema),
    async (c) => {
      const input = c.req.valid('json')
      const project = await createProject(input)

      return c.json(project, 201)
    },
  )

客户端可以使用 Hono RPC：

const client = hc<AppType>('/api')

在 TanStack Query 中调用：

export function useProjects() {
  return useQuery({
    queryKey: ['projects'],

    queryFn: async () => {
      const response =
        await client.projects.$get()

      if (!response.ok) {
        throw new Error(
          'Failed to load projects',
        )
      }

      return response.json()
    },
  })
}

完整调用链如下：

Component
    ↓
TanStack Query
    ↓
Hono RPC Client
    ↓
Hono Route
    ↓
Feature Function
    ↓
Drizzle

这套 API 可以同时提供给 Web、Desktop、浏览器扩展、Agent 和 Webhook。

相比框架内部专用的 Server Function，HTTP API 的复用范围更大。

后端按 Feature 组织

前后端拆分不意味着后端需要复制 Java 的分层方式。

不会采用这种全局目录：

controllers/
services/
repositories/
mappers/
dto/

API 仍然按 Feature 组织：

apps/api/src/features/project/
├── project.routes.ts
├── project.schema.ts
├── project.query.ts
├── project.command.ts
└── project.policy.ts

简单 Feature 只保留必要文件：

project.routes.ts
project.schema.ts

数据库实例可以直接导入：

import { db } from '@repo/db'

只有存在多个实现、复杂测试或运行时替换需求时，才使用参数注入或构造器注入。

不会为了保持架构形式，为每张表创建 Repository、Service 和 Mapper。

工具链保持激进，运行层保持稳定

项目工具链会使用相对新的方案：

Vite
Rolldown
Oxc
Oxlint
Oxfmt
Vite+
Vitest
Playwright

这些工具不会直接处理线上业务数据。即使某个版本出现兼容问题，也可以回退到对应的底层命令。

应用层使用：

React
TanStack Router
TanStack Query
TanStack Form
TanStack Table
Jotai
Tailwind CSS
shadcn/ui
Base UI
Motion
Lucide

其中 TanStack Form、Table 和 Jotai 都按需使用，不作为每个页面的固定依赖。

数据与安全层相对保守：

Node.js LTS
PostgreSQL
Drizzle ORM
Better Auth 稳定版本
Zod
正式数据库 Migration
Cookie Session

工具升级失败会影响开发效率，认证和数据库升级失败则可能影响用户和数据。两部分不应该使用相同的升级策略。

部署方式

源码上拆成多个 App，不代表生产环境必须维护大量服务。

可以使用同一个域名：

example.com/
    → Site

example.com/app/*
    → SPA

example.com/api/*
    → API

网关按路径分流：

/          → Site
/app/*     → Web
/api/*     → API

认证保持同源 Cookie。SPA 调用 /api 时不需要处理跨域 Token，Desktop 等外部客户端再使用单独的认证方式。

个人项目早期也可以让 Hono 同时提供 API 和 SPA 静态文件，保持一个 Docker 镜像和一个 Node 进程。

结论

这次技术选型没有确定一个统一管理所有能力的全栈框架，而是把不同类型的页面放回它们更适合的运行模型中。

公开内容使用 SSR 或 SSG
登录后的产品使用 SPA
通用业务能力使用 HTTP API

最终技术栈大致是：

Site
    Astro 或其他 SSR / SSG 方案

Web
    Vite
    React
    TanStack Router
    TanStack Query

API
    Hono
    Drizzle
    PostgreSQL
    Better Auth
    Zod

UI
    Tailwind CSS
    shadcn/ui
    Base UI
    Motion
    Lucide

Tooling
    Vite
    Rolldown
    Oxc
    Oxlint
    Oxfmt
    Vitest
    Playwright

这套结构保留了现代 TypeScript 工具链，也让业务后台继续使用熟悉的 SPA 数据流。

框架能力可以按项目需求增加。对于大多数偏工具型的产品，保持清楚的客户端、API 和数据边界，比在每个页面中同时组合 SSR、Loader、Server Function 和 Query 更容易维护。

Finished reading? Leave a comment

Resolver 是什么?

对于：

import Button from "@/components/Button";

JavaScript 引擎实际上只看到了 这些：

specifier = "@/components/Button"

接下来需要解决的问题是：

specifier
    ↓
真实模块

这个过程称为 Resolution。

Node.js ESM 规范中的入口算法：

ESM_RESOLVE(specifier, parentURL)

本质就是完成这个映射过程。

Node 默认支持哪些 specifier

Node 原生 Resolver 只支持四类：

import "./foo.js"
import "../foo.js"
import "/app/foo.js"

路径模块。

import react from "react"

包模块。

import db from "#db"

Package Imports。

import x from "file:///app/a.js"

URL 模块。

除此之外：

import x from "@/utils"

Node 无法解析。

直接进入：

Module Not Found

异常路径。

为什么 Alias 可以工作

假设存在：

import Button from "@/components/Button"

Webpack 配置：

resolve: {
  alias: {
    "@": "/project/src"
  }
}

Webpack 在执行真正解析前：

@/components/Button

先经过 Alias Resolver：

/project/src/components/Button

随后再进入正常模块解析。

因此 Alias 并不是一种新的模块类型。

而是：

旧 specifier
    ↓
新 specifier

的一次转换。

Vite Alias

Vite：

resolve: {
  alias: {
    "@": path.resolve(__dirname, "src")
  }
}

执行流程与 Webpack 完全一致。

对于：

import x from "@/utils/request"

Vite 首先执行：

@ -> /project/src

得到：

/project/src/utils/request

然后继续执行后续解析。

因此：

Webpack Alias
Vite Alias
Rspack Alias

本质是同一个东西。

区别只是 Resolver 实现不同。

TypeScript Paths 为什么经常失效

配置：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

很多人会发现：

VSCode 正常
TypeScript 正常
Node 运行失败

原因是：

paths

不是运行时 Resolver。

TypeScript 只会在：

类型检查
IDE 跳转
编译阶段

使用 paths。

Node 运行时根本不会读取：

tsconfig.json

因此：

{
  "paths": {}
}

无法让 Node 识别：

import "@/utils"

必须额外配置：

Webpack Alias
Vite Alias
Rspack Alias
Node Loader

其中之一。

Node Loader 如何实现 Alias

Node 提供：

export async function resolve(
  specifier,
  context,
  nextResolve
)

允许接管解析过程。

例如：

export async function resolve(
  specifier,
  context,
  nextResolve
) {
  if (specifier.startsWith("@/")) {
    return {
      url: pathToFileURL(
        path.resolve(
          process.cwd(),
          "src",
          specifier.slice(2)
        )
      ).href,
      shortCircuit: true
    }
  }

  return nextResolve(specifier, context)
}

此时：

import x from "@/utils"

会变成：

file:///project/src/utils.js

然后进入正常加载流程。

Browser Import Map

浏览器没有：

node_modules

因此：

import React from "react"

无法工作。

Import Map 的作用：

<script type="importmap">
{
  "imports": {
    "react": "/vendor/react.js"
  }
}
</script>

执行：

import React from "react"

时。

浏览器先映射：

react
    ↓
/vendor/react.js

再继续加载。

Resolver 的本质

观察：

Webpack Alias
Vite Alias
Rspack Alias
TS Paths
Node Loader
Import Map

会发现它们都在做同一件事：

specifier
    ↓
mapping
    ↓
new specifier
    ↓
real URL

区别仅在于：

映射规则存放的位置不同

模块图的起点

对于：

import App from "./App"

编译器首先执行：

specifier
    ↓
resolver
    ↓
real module

得到：

App.tsx

然后继续递归：

App.tsx
    ↓
Button.tsx
    ↓
request.ts
    ↓
...

最终构建：

Module Graph

Tree Shaking、Code Splitting、HMR、Chunk 拆分全部建立在这个图之上。

因此 Resolver 是整个现代前端工具链真正的入口。

Finished reading? Leave a comment

Node.js ESM 解析算法（Resolution Algorithm）的职责只有两个：

1. 将 import 中的 specifier 解析为最终 URL
2. 判断该 URL 对应的模块格式

例如：

import react from "react";
import util from "./utils.js";
import config from "#config";

Node.js 最终需要得到：

react      -> file:///project/node_modules/react/index.js
./utils.js -> file:///project/src/utils.js
#config    -> file:///project/src/config/index.js

以及：

module
commonjs
json
wasm

等模块格式。

整个 ESM 规范本质上是在描述：

specifier
    ↓
resolved URL
    ↓
module format
    ↓
load
    ↓
execute

一、ESM_RESOLVE 总体流程

Node.js ESM 的入口算法：

ESM_RESOLVE(specifier, parentURL)

可以简化为：

判断 specifier 类型

URL
路径
#imports
裸包名

        ↓

解析得到 URL

        ↓

检查文件是否合法

        ↓

判断模块格式

        ↓

返回给 Loader

整个算法的核心目标：

specifier
      ↓
唯一 URL

而不是像 CommonJS 那样不断猜测。

二、specifier 分类

Node.js 将 specifier 分为四类。

1. URL Specifier

例如：

import x from "file:///app/src/a.js";

或者：

import x from "data:text/javascript,export default 1";

如果本身是合法 URL：

new URL(specifier)

成功。

那么直接返回。

2. Relative Specifier

例如：

import x from "./foo.js";
import y from "../bar.js";

Node.js 根据当前模块位置解析。

假设：

file:///app/src/main.js

执行：

import "./utils.js";

得到：

file:///app/src/utils.js

本质上就是：

new URL("./utils.js", parentURL)

3. Package Imports

例如：

import db from "#db";

或者：

import logger from "#utils/logger";

以：

#

开头。

会进入：

PACKAGE_IMPORTS_RESOLVE()

读取当前包：

{
  "imports": {
    "#db": "./src/db/index.js",
    "#utils/*": "./src/utils/*.js"
  }
}

例如：

import db from "#db";

最终得到：

./src/db/index.js

4. Bare Specifier

例如：

import react from "react";

import lodash from "lodash";

import axios from "axios";

既不是：

URL
路径
#import

就属于裸包名。

进入：

PACKAGE_RESOLVE()

开始查找 node_modules。

三、PACKAGE_RESOLVE

这是 Node.js 查找 npm 包的核心逻辑。

例如：

import react from "react";

当前文件：

/app/src/pages/home/index.js

Node.js 会不断向上查找：

/app/src/pages/home/node_modules/react
/app/src/pages/node_modules/react
/app/src/node_modules/react
/app/node_modules/react
/node_modules/react

直到找到。

等价于：

while(currentDirectory){
    查找 node_modules/packageName
    找不到继续向上
}

四、读取 package.json

找到包以后：

node_modules/react/package.json

Node.js 开始读取配置。

优先级如下：

exports
    ↓
main
    ↓
直接路径

五、exports 机制

现代 Node.js 包解析几乎完全依赖 exports。

例如：

{
  "exports": {
    ".": "./dist/index.js",
    "./jsx-runtime": "./dist/jsx-runtime.js"
  }
}

允许：

import React from "react";

对应：

.

得到：

./dist/index.js

允许：

import jsx from "react/jsx-runtime";

对应：

./jsx-runtime

得到：

./dist/jsx-runtime.js

但是：

import internal from "react/internal";

如果 exports 中不存在：

"./internal"

则报错：

Package Path Not Exported

六、exports 的本质

exports 可以理解为：

包对外暴露的公开 API

例如：

{
  "exports": {
    ".": "./dist/index.js",
    "./api": "./dist/api.js"
  }
}

允许：

import x from "my-lib";
import y from "my-lib/api";

禁止：

import z from "my-lib/dist/internal.js";

即使文件真实存在。

七、Conditional Exports

exports 不一定是字符串。

可以是对象。

例如：

{
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "default": "./dist/index.js"
    }
  }
}

Node.js 会根据条件选择。

ESM：

import x from "lib";

匹配：

"import"

得到：

./dist/index.mjs

CommonJS：

require("lib");

匹配：

"require"

得到：

./dist/index.cjs

八、PACKAGE_SELF_RESOLVE

假设：

{
  "name": "my-lib",
  "exports": {
    ".": "./src/index.js",
    "./core": "./src/core.js"
  }
}

当前代码就在：

my-lib

内部。

那么：

import core from "my-lib/core";

不会去外部 node_modules 查找。

Node.js 会发现：

当前包名就是 my-lib

直接使用当前 package.json 的 exports。

这就是：

PACKAGE_SELF_RESOLVE

九、imports 机制

imports 和 exports 很像。

区别：

exports 给别人用
imports 给自己用

例如：

{
  "imports": {
    "#db": "./src/db/index.js",
    "#utils/*": "./src/utils/*.js"
  }
}

之后：

import db from "#db";

实际解析：

./src/db/index.js

再例如：

import stringUtil from "#utils/string.js";

得到：

./src/utils/string.js

十、Pattern Match

imports 和 exports 支持通配符。

例如：

{
  "exports": {
    "./features/*": "./src/features/*.js"
  }
}

执行：

import user from "pkg/features/user";

匹配：

*

得到：

user

最终：

./src/features/user.js

十一、PACKAGE_TARGET_RESOLVE

这是 exports/imports 真正执行映射的地方。

支持四种类型。

String

{
  "exports": {
    ".": "./dist/index.js"
  }
}

直接解析。

Object

{
  "exports": {
    ".": {
      "node": "./node.js",
      "browser": "./browser.js",
      "default": "./index.js"
    }
  }
}

根据 conditions 选择。

Array

{
  "exports": {
    ".": [
      "./native.js",
      "./fallback.js"
    ]
  }
}

前一个失败。

继续尝试下一个。

null

{
  "exports": {
    "./internal/*": null
  }
}

明确禁止导出。

十二、ESM_FILE_FORMAT

URL 定位完成后。

Node.js 需要判断：

这个文件应该按什么格式加载？

.mjs

module

.cjs

commonjs

.json

json

.wasm

wasm

.node

addon

原生扩展模块。

十三、type 字段的作用

对于：

.js

文件。

Node.js 会查找最近的 package.json。

例如：

{
  "type": "module"
}

那么：

app.js

被解释为：

ESM

如果：

{
  "type": "commonjs"
}

则：

app.js

被解释为：

CommonJS

因此：

.mjs

永远 ESM。

.cjs

永远 CommonJS。

.js

取决于 type。

十四、为什么 ESM 不支持目录导入

CommonJS：

require("./foo");

Node.js 会尝试：

foo.js
foo.json
foo.node
foo/index.js
foo/index.json

ESM：

import "./foo";

不会猜。

如果：

foo

是目录。

直接报错：

Unsupported Directory Import

正确写法：

import "./foo/index.js";

或者：

import "./foo.js";

十五、LOOKUP_PACKAGE_SCOPE

Node.js 如何找到最近的 package.json？

算法：

当前目录
      ↓
父目录
      ↓
继续向上
      ↓
直到根目录

例如：

/app/src/pages/home/index.js

查找：

/app/src/pages/home/package.json
/app/src/pages/package.json
/app/src/package.json
/app/package.json

找到第一个就停止。

十六、自定义 ESM Resolver

Node.js 默认解析：

import x from "./a.js";
import y from "react";

如果想支持：

import x from "@/utils";

怎么办？

答案：

Loader Hook

例如：

import { pathToFileURL } from "node:url";
import path from "node:path";

export async function resolve(
  specifier,
  context,
  nextResolve
) {
  if (specifier.startsWith("@/")) {
    return {
      url: pathToFileURL(
        path.resolve(
          process.cwd(),
          "src",
          specifier.slice(2)
        )
      ).href,
      shortCircuit: true
    };
  }

  return nextResolve(specifier, context);
}

运行：

node --loader ./loader.mjs app.js

之后：

import util from "@/utils.js";

就会自动映射：

src/utils.js

十七、完整解析链路

Node.js ESM 解析可以总结为：

import specifier
        ↓
ESM_RESOLVE
        ↓
判断类型

URL
路径
#imports
裸包名

        ↓

PACKAGE_RESOLVE

        ↓

exports
imports
main

        ↓

得到最终 URL

        ↓

ESM_FILE_FORMAT

        ↓

module
commonjs
json
wasm

        ↓

Loader

        ↓

Execute

总结

Node.js ESM 的核心思想不是“寻找文件”。

而是：

specifier
      ↓
确定 URL
      ↓
确定模块格式
      ↓
加载执行

整个 exports、imports、type、conditional exports、loader 机制，本质上都是围绕这一目标构建的。

ESM 解析模型相比 CommonJS 更严格、更静态、更接近浏览器，也更适合现代工具链（Vite、Webpack、Rspack、Rollup、Turbopack）进行分析和优化。

Finished reading? Leave a comment

最近在看 C++、Rust、Go 的编译过程。

刚开始最容易被一堆名词卡住：

• GCC
• Clang
• LLVM
• AST
• IR
• SSA
• MIR
• GIMPLE
• RTL
• Linker
• Loader

单独看每个词，好像都能理解一点。但把它们放到一张图里，就很容易乱。

后来我发现，问题不在于名词太多，而在于没有从一段真实程序出发。

编译器不是简单地“把源码翻译成汇编”。更准确地说，它是在不断降低程序的抽象层级：

人类写的源码
    ↓
结构化表示
    ↓
语义明确的表示
    ↓
适合优化的表示
    ↓
接近机器的表示
    ↓
机器可以执行的二进制

每一层中间表示，都是为了让某一类问题变得更容易处理。

下面用一段很小的 C++ 程序，把主流编译链路串起来。

extern "C" int printf(const char*, ...);

#define INC(x) ((x) + 1)

int add(int a, int b) {
    return a + b;
}

int main() {
    int x = INC(add(1, 2));
    printf("%d\n", x);
    return 0;
}

这段代码故意保留了几个点：

宏：INC
函数调用：add
外部符号：printf
C++ 符号：add 会发生 name mangling
链接阶段：printf 需要从 C 标准库解析
优化空间：add(1, 2) 和 INC 可以被优化成常量

一个小程序，基本够覆盖主流编译流程。

1. 源码不是编译器真正想要的东西

程序员看到的是：

int x = INC(add(1, 2));

人很容易理解它大概等价于：

int x = ((add(1, 2)) + 1);

但编译器不能一开始就这么理解。

源码只是字符流：

i n t 空格 x 空格 = 空格 I N C ...

编译器必须先把字符处理成更稳定的结构。

这也是为什么现代编译流程不会从源码直接跳到汇编。源码适合人读，不适合机器分析。

2. 预处理：C/C++ 最早的一层文本系统

C/C++ 的第一步通常是预处理。

clang++ -E main.cpp -o main.ii

预处理器主要处理：

#include
#define
#ifdef
#pragma

在这段程序里，最明显的是：

#define INC(x) ((x) + 1)

预处理后，核心代码会变成类似这样：

int main() {
    int x = ((add(1, 2)) + 1);
    printf("%d\n", x);
    return 0;
}

这一步有个很重要的认知：

预处理不是语义分析。

它不理解类型。

它不知道 add 是不是函数。

它也不知道 INC(add(1, 2)) 是否合理。

它只是按照规则展开文本。

这也是 C/C++ 宏容易制造问题的原因。宏不是函数，它不会遵守函数那套类型检查和作用域规则。

例如：

#define SQUARE(x) x * x

如果写：

SQUARE(1 + 2)

会被展开成：

1 + 2 * 1 + 2

而不是：

(1 + 2) * (1 + 2)

很多 C/C++ 的奇怪问题，其实还没进入真正编译阶段，只是在预处理阶段就已经埋雷了。

3. 词法分析：把字符切成 Token

预处理后，编译器开始做词法分析。

源码片段：

int x = ((add(1, 2)) + 1);

会被切成类似：

keyword      int
identifier   x
operator     =
punctuator   (
punctuator   (
identifier   add
punctuator   (
literal      1
punctuator   ,
literal      2
punctuator   )
punctuator   )
operator     +
literal      1
punctuator   )
punctuator   ;

这一步只负责“切词”。

它知道 int 是关键字。

知道 x 是标识符。

知道 1 是数字字面量。

但它还不知道：

x 是局部变量
add 是函数
printf 是外部函数
1 能不能传给 add

这些都不是词法分析负责的。

可以用 Clang 看 Token：

clang++ -Xclang -dump-tokens -fsyntax-only main.cpp

如果编译错误里出现非法字符、字符串没有闭合、数字字面量格式错误，通常就停在这一层附近。

4. 语法分析：从 Token 变成 AST

Token 还是线性的。

编译器需要知道程序结构。

例如：

int x = ((add(1, 2)) + 1);

语法分析后会变成一棵树，简化后大概是：

VarDecl x : int
    └── BinaryOperator +
        ├── CallExpr add
        │   ├── IntegerLiteral 1
        │   └── IntegerLiteral 2
        └── IntegerLiteral 1

这就是 AST，抽象语法树。

AST 的作用不是为了显得高级，而是为了把源码结构稳定下来。

源码是文本。

AST 是结构。

这一步之后，编译器终于知道：

这是一个变量声明
变量名是 x
初始化表达式是一个加法
加法左边是函数调用
加法右边是整数 1

但 AST 仍然不能证明程序正确。

例如：

int x = foo(1, 2);

即使 foo 根本不存在，也可以先构建 AST。

语法上没问题。

语义上才有问题。

可以用 Clang 看 AST：

clang++ -Xclang -ast-dump -fsyntax-only main.cpp

真实 C++ AST 会非常长。模板、重载、隐式转换、构造函数、析构函数都会出现在里面。

这也是 C++ 前端复杂度很高的原因。不是因为 Token 难切，也不是因为语法树难画，而是因为语义太复杂。

5. 语义分析：编译器真正开始理解程序

语义分析会处理这些问题：

add 是否存在
add 参数数量是否正确
add 参数类型是否匹配
printf 是否声明过
int x 的初始化是否合法
函数返回值是否符合声明

对这段代码来说：

int x = INC(add(1, 2));

预处理后是：

int x = ((add(1, 2)) + 1);

语义分析会确认：

add 的类型是 int(int, int)
add(1, 2) 返回 int
返回值可以和 1 做加法
结果可以赋给 int x

如果写成：

int x = add("hello", 2);

语法仍然成立。

AST 也能构建。

但语义分析会报错，因为参数类型不匹配。

很多开发者平时说“编译错误”，其实可以再细分：

语法错误：代码结构不合法
语义错误：结构合法，但意思不合法
链接错误：单个文件能编译，但最终符号找不到

这三个错误发生在完全不同的阶段。

Rust 的 Borrow Checker 也属于这个大范围。

例如：

let r;

{
    let x = 1;
    r = &x;
}

println!("{}", r);

这不是语法错误。

它的结构完全合法。

真正的问题是语义层面的：x 已经离开作用域，r 不能再引用它。

所以 Rust 的所有权、借用、生命周期，不应该理解成语法特性，而应该理解成更强的语义分析。

这也是 Rust 编译器比 Go 编译器复杂很多的原因之一。

6. AST 不适合优化，所以需要 IR

很多人第一次学编译流程，会以为：

源码
  ↓
AST
  ↓
汇编

这个模型太粗糙。

现代编译器不会长期停留在 AST 上做优化。

原因很简单：

AST 太接近源码。

例如：

int x = INC(add(1, 2));

AST 会保留很多源码结构。

但优化器真正关心的是：

这个值从哪里来
这个值被谁使用
这个计算有没有副作用
这个分支是否可达
这个变量能不能放进寄存器
这个函数能不能内联

AST 对这些问题并不友好。

所以编译器会把 AST 降低到 IR。

IR 是 Intermediate Representation，中间表示。

比如这段：

int x = INC(add(1, 2));

可以理解为降低成类似三地址码：

t1 = call add, 1, 2
t2 = t1 + 1
x = t2
call printf, "%d\n", x
return 0

这就比 AST 更适合优化。

表达式树被拆成了简单指令。

数据依赖也更清楚。

LLVM IR 会更像这样，简化后：

define i32 @_Z3addii(i32 %a, i32 %b) {
entry:
  %sum = add nsw i32 %a, %b
  ret i32 %sum
}

define i32 @main() {
entry:
  %call = call i32 @_Z3addii(i32 1, i32 2)
  %add = add nsw i32 %call, 1
  call i32 (ptr, ...) @printf(ptr @.str, i32 %add)
  ret i32 0
}

这里有几个点值得注意。

add 在 C++ 里可能会被编译成：

_Z3addii

这是 C++ name mangling。

因为 C++ 支持函数重载，链接器不能只看到一个名字 add。

例如：

int add(int, int);
double add(double, double);

这两个函数源码里都叫 add，但链接时必须区分。

而 printf 因为声明成：

extern "C" int printf(const char*, ...);

所以不会被 C++ 改名，仍然叫：

printf

这就是 extern "C" 的实际意义之一：控制符号名，方便和 C ABI 对接。

7. 优化：编译器开始改写程序

如果不开优化，编译器会比较忠实地保留程序结构。

如果打开优化：

clang++ -O2 -S -emit-llvm main.cpp -o main.ll

这段代码很可能被优化成类似：

define i32 @main() {
entry:
  call i32 (ptr, ...) @printf(ptr @.str, i32 4)
  ret i32 0
}

add(1, 2) 没了。

INC 展开后的 + 1 也没了。

x 也没了。

最后只剩：

printf("%d\n", 4)

这不是编译器乱改代码。

这是它证明了这些改写不会改变可观察行为。

这里发生了几类典型优化：

函数内联：add(1, 2) 被展开
常量折叠：1 + 2 + 1 变成 4
死代码删除：中间变量 x 不再需要

如果看过 Java JIT、Go SSA、Rust LLVM 优化，会发现这些优化名字经常重复出现。

原因很简单：程序优化的基本问题是相通的。

8. SSA：现代优化器为什么喜欢“变量只赋值一次”

SSA 是理解现代编译器优化的关键。

SSA，全称 Static Single Assignment。

意思是每个变量在静态程序里只赋值一次。

看这个例子：

int f(bool cond) {
    int x = 1;

    if (cond) {
        x = 2;
    }

    return x;
}

普通代码里，x 被赋值两次。

控制流一复杂，优化器就很难判断某个位置的 x 到底来自哪里。

SSA 会把它变成类似：

x1 = 1

if cond goto then else merge

then:
  x2 = 2
  goto merge

merge:
  x3 = phi(x1, x2)
  return x3

这里的：

phi(x1, x2)

表示：

如果从未进入 if 的路径来，x3 = x1
如果从 then 分支来，x3 = x2

SSA 的价值在于，它把“变量会变化”这件事变成了显式的数据流关系。

这对优化非常重要。

例如：

常量传播
死代码删除
公共子表达式消除
循环不变代码外提
值编号
逃逸分析

都会受益于 SSA。

LLVM IR 是 SSA 形式。

Go 编译器内部使用 SSA。

HotSpot C2 也使用接近 SSA 的 Sea of Nodes IR。

很多数据库优化器虽然不叫 SSA，但也会维护类似的数据依赖关系。

这不是某个编译器的小技巧，而是现代优化系统的基础方法。

9. 后端：从平台无关 IR 到机器相关 IR

LLVM IR 仍然是平台无关的。

比如：

%sum = add i32 %a, %b

这句话没有指定：

x86 用哪条指令
ARM 用哪条指令
结果放哪个寄存器
参数从哪里来
调用约定是什么

这些都是后端的问题。

后端要处理：

指令选择
寄存器分配
指令调度
调用约定
栈帧布局
目标平台 ABI

同一个加法，在 x86-64 下可能是：

mov eax, edi
add eax, esi
ret

在 ARM64 下可能是：

add w0, w0, w1
ret

IR 相同，目标机器不同，最终指令就不同。

这也是 LLVM 的价值所在。

语言实现者只要生成 LLVM IR，就可以复用 LLVM 的后端能力。

否则每写一门语言，都要自己支持：

x86-64
ARM64
RISC-V
Windows ABI
Linux ABI
macOS ABI
寄存器分配
指令选择
调试信息
异常处理

这几乎不现实

10. 目标文件：机器码还不是最终程序

后端生成汇编后，汇编器会生成目标文件：

clang++ -c main.cpp -o main.o

main.o 里面有机器码，但它还不是完整程序。

可以用：

nm main.o

看到符号。

可能会看到类似：

0000000000000000 T _Z3addii
0000000000000010 T main
                 U printf

含义大概是：

_Z3addii 已定义
main 已定义
printf 未定义

U printf 不是错误。

它只是说：当前目标文件里没有 printf 的实现，链接阶段需要去别的地方找。

这就是很多人第一次遇到 undefined reference 时容易误解的地方。

它不是语法错误。

也不是类型错误。

它是链接阶段的符号解析失败。

11. 链接：把分散的二进制拼成一个程序

链接器做的事情可以粗略理解为：

main.o
  +
libc
  +
启动代码
  +
运行时库
  ↓
可执行文件

它要解决：

符号解析
地址分配
重定位
静态库选择
动态库记录
入口点设置

如果写 C++，还会涉及：

name mangling
ODR
模板实例化
静态初始化
异常表
RTTI
虚表

比如：

undefined reference to `foo'

说明链接器找不到 foo 的实现。

multiple definition of `foo'

说明多个目标文件都提供了同一个强符号。

undefined reference to `_Z3addii'

说明 C++ 符号名对不上，可能是声明和定义不一致，也可能是 C/C++ ABI 混用出了问题。

链接器是独立于编译器前端的另一个大系统。

很多大型 C++ 工程的构建问题，其实不是编译器问题，而是链接器问题。

12. 加载：程序运行前，操作系统还要接手

执行：

./a.out

也不是 CPU 直接从 main 开始跑。

Linux 下大致会经历：

内核读取 ELF
映射程序段到虚拟内存
加载动态链接器
加载共享库
处理重定位
初始化运行时
调用 main

程序的内存布局大致包括：

.text     代码段
.rodata   只读数据
.data     已初始化全局变量
.bss      未初始化全局变量
heap      堆
stack     栈

所以严格说，完整链路不是：

源码 → 可执行文件

而是：

源码 → 目标文件 → 可执行文件 → 进程

编译器解决“怎么生成程序”。

链接器解决“怎么合成程序”。

加载器解决“怎么把程序变成进程”。

13. Clang、LLVM、GCC 应该怎么放在一张图里

现在再看这些名字，就清楚很多。

Clang + LLVM 是这样：

C++ Source
    ↓
Clang Frontend
    ↓
Clang AST
    ↓
LLVM IR
    ↓
LLVM Optimizer
    ↓
LLVM Backend
    ↓
Object File
    ↓
Linker
    ↓
Executable

GCC 是另一条链路：

C++ Source
    ↓
GCC C++ Frontend
    ↓
GENERIC
    ↓
GIMPLE
    ↓
GIMPLE SSA
    ↓
RTL
    ↓
GCC Backend
    ↓
Object File
    ↓
Linker
    ↓
Executable

这两条链路解决的是同一类问题，但内部表示不同。

Clang 不是 LLVM 的别名。

LLVM 也不是 Clang 的别名。

更准确地说：

Clang 是 C/C++/Objective-C 前端。
LLVM 是中端和后端基础设施。
GCC 是另一套完整编译器系统。

对应关系可以这样记：

Clang 负责读懂 C++。
LLVM 负责优化和生成机器码。
GCC 自己既有前端，也有中端和后端。

14. Rust 为什么有 HIR、MIR，又为什么用 LLVM

Rust 的流程大致是：

Rust Source
    ↓
AST
    ↓
HIR
    ↓
THIR
    ↓
MIR
    ↓
Borrow Check
    ↓
LLVM IR
    ↓
LLVM Backend
    ↓
Machine Code

Rust 这几层不是为了显得复杂。

每层都有明确责任。

AST 接近源码。

HIR 会把一些语法糖和表层结构降下来，让程序形态更稳定。

THIR 更适合类型检查后的表达式分析。

MIR 是 Rust 很关键的一层，适合表达控制流、move、borrow、drop、生命周期等语义。

LLVM IR 则负责进入通用优化和机器码生成阶段。

这里要注意一个区分：

MIR 是 Rust 语义层的 IR。
LLVM IR 是机器代码生成层的 IR。

Borrow Checker 不能直接依赖 LLVM IR。

因为 LLVM IR 已经太低级，Rust 的 ownership、borrow、drop 语义在那一层已经不适合作为主要分析对象。

也不能直接依赖 AST。

因为 AST 太接近语法表面，语法糖太多，不适合做严格的数据流和控制流分析。

所以 Rust 需要 MIR。

这就是中间表示真正的价值：不是多一层抽象，而是为特定分析提供合适的程序形态。

15. Go 为什么看起来简单很多

Go 的编译流程大致是：

Go Source
    ↓
Parser
    ↓
AST
    ↓
Type Check
    ↓
SSA
    ↓
Go Backend
    ↓
Machine Code

Go 默认不走 LLVM。

它有自己的 SSA 和后端。

这和 Go 的设计目标有关。

Go 语言本身刻意保持简单：

没有模板元编程
没有复杂宏系统
没有 Rust 那种 ownership 检查
没有 C++ 那种重载和隐式规则

所以 Go 编译器可以更直接。

这也是 Go 编译速度快的一个重要原因。

当然，“简单”不是说 Go 编译器没有技术含量。

Go 的逃逸分析、内联、SSA 优化、栈增长、GC 相关元数据生成，都有不少工程细节。

但和 C++、Rust 相比，Go 前端语义复杂度确实低很多。

16. 为什么现代编译器总在发明新的 IR

到这里，基本可以回答最初的问题。

为什么 GCC 有 GIMPLE 和 RTL？

为什么 LLVM 有 LLVM IR、SelectionDAG、Machine IR？

为什么 Rust 有 HIR、THIR、MIR？

为什么 Go 有 SSA？

因为没有一种表示适合所有阶段。

AST 适合表示源码结构。

HIR 适合消除表层语法。

MIR 适合表达语言语义和控制流。

LLVM IR 适合做平台无关优化。

Machine IR 适合做寄存器分配和指令调度。

RTL 适合 GCC 后端描述接近机器的操作。

同一段程序，在不同阶段要被看成不同的东西。

对人来说，它是业务逻辑。

对前端来说，它是语法树。

对类型系统来说，它是约束集合。

对优化器来说，它是数据流图。

对后端来说，它是指令选择和寄存器分配问题。

对链接器来说，它是符号和重定位记录。

对加载器来说，它是 ELF 段和动态库依赖。

编译器的复杂性，正是来自这些视角之间的切换。

17. 真正需要记住的主流流程

如果只保留主流路径，不陷入全部细节，可以记成这条线：

源码
  ↓
预处理
  ↓
Token
  ↓
AST
  ↓
语义分析
  ↓
IR
  ↓
SSA
  ↓
优化
  ↓
目标相关 IR
  ↓
汇编 / 目标文件
  ↓
链接
  ↓
可执行文件
  ↓
加载执行

对应到几个主流编译器：

Clang/LLVM:
C++ → Clang AST → LLVM IR → LLVM Backend → Object

GCC:
C++ → GENERIC → GIMPLE SSA → RTL → Object

Rust:
Rust → AST/HIR/THIR → MIR → LLVM IR → Object

Go:
Go → AST → Type Check → SSA → Go Backend → Object

这张图比单独背 AST、IR、SSA 更有用。

因为它告诉你每个系统在同一条工业流水线里的位置。

18. 学这套东西对工程有什么用

这不是纯理论。

遇到宏问题，你知道去看预处理结果：

clang++ -E main.cpp

遇到语法和语义问题，你知道它发生在前端：

clang++ -Xclang -ast-dump -fsyntax-only main.cpp

想看优化前后的差异，你知道去看 LLVM IR：

clang++ -O0 -S -emit-llvm main.cpp -o main_O0.ll
clang++ -O2 -S -emit-llvm main.cpp -o main_O2.ll

遇到符号找不到，你知道看目标文件：

nm main.o

想看 ELF 结构：

readelf -a a.out

想看汇编：

objdump -d a.out

这些工具不是为了炫技。

它们对应的是编译流程中的不同阶段。

能定位阶段，问题就已经解决了一半。

19. 编译器真正有价值的地方

编译器最有价值的地方，不是几个术语，而是一种看复杂系统的方法。

一个复杂输入，不会被直接执行。

它会先变成某种中间表示。

然后被分析、约束、优化、降低，最后才进入执行层。

这个模式不只存在于编译器里。

数据库会把 SQL 变成逻辑计划和物理计划。

JVM 会把字节码变成内部 IR，再交给 JIT 优化。

React 会把 UI 更新组织成 Fiber 结构。

Kubernetes Scheduler 会把调度请求变成资源约束和评分模型。

这些系统看起来不一样，但底层思路很接近：

输入不是直接执行的。
先建立表示。
再基于表示做分析和优化。
最后执行。

编译器只是这个思想最经典、最完整的版本。

如果能把 C++、Rust、Go、GCC、LLVM 这条线看懂，再回头看 JVM、数据库、前端框架、调度系统，很多设计就不再是孤立的名词了。

Finished reading? Leave a comment

Spring 6 循环依赖与早期代理：三级缓存的真实边界

基线：Spring Framework 6、Spring Boot 3。本文解释一个具体代理不一致案例，不把结论推广为所有 Bean 的普遍行为。

1. 问题模型

典型循环依赖：

A -> B -> Repository -> A

如果依赖注入发生在 Bean 完整初始化之前，Spring 可能通过三级缓存提前暴露引用。后续 Bean 初始化还可能经过 BeanPostProcessor 创建代理，于是出现：

Early Reference != Final Bean

2. 三级缓存能做什么

三级缓存中的 ObjectFactory 可以提供早期引用。实现 SmartInstantiationAwareBeanPostProcessor 的后处理器有机会通过 getEarlyBeanReference 参与早期代理。

AbstractAutoProxyCreator 会记录 early proxy reference，避免同一个自动代理在初始化后重复创建。但不是每一个 BeanPostProcessor 都参与 early reference。

普通后处理器若只在 postProcessAfterInitialization 阶段包装 Bean，就可能造成早期引用与最终对象身份不一致。具体是否发生，取决于 Spring 版本、后处理器顺序和代理类型。

3. Spring Boot 3 的处理建议

Spring Boot 2.6 起循环引用默认更严格。Boot 3 项目应优先拆除循环依赖，不要用 spring.main.allow-circular-references=true 作为默认修复。

推荐顺序：

1. 拆分服务和 Repository 的职责；
2. 使用事件或接口反转依赖方向；
3. 对确实需要延迟创建的依赖使用 @Lazy，并评估生命周期；
4. 检查事务、缓存、异步、异常翻译和自定义后处理器是否创建代理。

4. 排障方法

记录实际 Spring Framework 版本；查看 Bean 的代理类型和 Advisor；分别跟踪 getEarlyBeanReference 与 postProcessAfterInitialization；确认是否存在多个后处理器重复包装；检查 allowCircularReferences 和 BeanDefinition 顺序。

三级缓存不是“所有循环依赖都能解决”的保证。它只是容器在特定生命周期阶段提供早期引用的机制，最终仍需要一个清晰且可维护的依赖图。

Finished reading? Leave a comment

很多人学习 Kubernetes 网络时，一上来就接触：

• Pod
• Service
• Ingress
• CNI
• Flannel
• Calico

结果越学越乱。

真正的问题在于：

Kubernetes 网络并不是一个独立体系，而是建立在 Linux 网络之上的一层抽象。

如果不了解 Linux 网络，那么 Pod、Service、VXLAN 这些概念都会变成黑盒。

一、网络世界只有三个核心概念

整个网络可以抽象成三件事：

设备
地址
转发

对应：

设备：
网卡
交换机
路由器

地址：
MAC
IP

转发：
交换
路由
NAT

二、MAC 与 IP

MAC 地址

MAC 是二层地址。

00:11:22:33:44:55

作用是在同一个局域网内定位设备。

IP 地址

IP 是三层地址。

192.168.1.10
10.244.1.2
8.8.8.8

作用是跨网络定位设备。

三、交换机、ARP、路由器

交换机工作在二层，只看 MAC 地址，不看 IP、TCP、HTTP。

ARP 负责：

IP -> MAC

路由器工作在三层：

查看目标 IP
↓
查路由表
↓
决定下一跳

路由表示例：

ip route

192.168.1.0/24 dev eth0
default via 192.168.1.1

含义：

同网段直接发送
其他流量交给默认网关

四、NAT

私网地址不能直接在公网路由：

192.168.x.x
172.16.x.x
10.x.x.x

所以路由器会做 SNAT：

SRC 192.168.1.10
↓
SRC 公网 IP

并通过 conntrack 记录连接映射，用于回包恢复。

五、Linux Network Namespace

Namespace 是 Linux 的隔离机制。

Network Namespace 隔离的是一整套网络栈：

网卡
IP
路由表
ARP 表
iptables
端口空间

所以容器不是虚拟机，而是：

普通 Linux 进程
+
Namespace 隔离
+
Cgroups 限制
+
RootFS 文件系统

六、veth Pair

Namespace 之间需要连接，Linux 提供了 veth pair。

vethA <====> vethB

它像一根虚拟网线：

从 vethA 发出的包，会从 vethB 出来
从 vethB 发出的包，会从 vethA 出来

七、Linux Bridge

Bridge 是软件交换机。

ContainerA
   |
 Bridge
   |
ContainerB

它和物理交换机一样：

学习 MAC
查 MAC 表
转发数据帧

八、Docker 网络

Docker 默认网络结构：

Container
  eth0
    │
veth
    │
docker0
    │
Host

其中 docker0 是 Linux Bridge，同时被 Docker 配置了 IP：

docker0 = 172.17.0.1

所以 docker0 既是交换机，也是容器默认网关。

Docker 自己维护 IPAM：

172.17.0.0/16

容器 IP 通常由 Docker 分配：

172.17.0.2
172.17.0.3
172.17.0.4

九、Pod 是什么

Pod 不是容器。

一个 Pod 里可以有多个容器：

Pod
├── app
└── sidecar

真正持有网络命名空间的是 pause container。

pause container
└── Network Namespace

app
└── 加入 pause 的 Network Namespace

sidecar
└── 加入 pause 的 Network Namespace

所以同一个 Pod 内多个容器共享：

IP
localhost
端口空间

十、Kubernetes 单节点网络

很多 CNI 会在 Node 上创建类似 docker0 的网桥，比如：

cni0

结构：

PodA
  |
veth
  |
cni0
  |
veth
  |
PodB

同节点 Pod 通信时：

PodA ARP 查询 PodB MAC
↓
cni0 广播
↓
PodB 回复
↓
cni0 根据 MAC 表转发

这个过程本质是二层交换。

十一、CNI 是什么

Kubernetes 本身不直接实现网络。

它通过 CNI 插件处理 Pod 网络。

常见 CNI：

Flannel
Calico
Cilium

CNI 负责：

创建 veth
配置 IP
配置路由
接入 Bridge 或其他数据平面
维护跨节点通信

Pod IP 通常由 CNI 的 IPAM 模块分配，不是 Kubernetes 或 Linux 自动分配。

十二、跨节点 Pod 通信

假设：

Node1
PodA = 10.244.1.2

Node2
PodB = 10.244.2.2

PodA 访问 PodB：

10.244.1.2 -> 10.244.2.2

问题是：

Node1 怎么知道 10.244.2.0/24 在 Node2？

这就是 CNI 要解决的问题。

十三、VXLAN

VXLAN 是：

L2 Overlay over L3

意思是：

把二层网络封装到三层 IP 网络里面

原始 Pod 包：

SRC 10.244.1.2
DST 10.244.2.2

经过 VXLAN 封装：

Outer IP:
SRC Node1IP
DST Node2IP

UDP

VXLAN Header

Inner IP:
SRC 10.244.1.2
DST 10.244.2.2

包结构：

Outer Ethernet
Outer IP
UDP
VXLAN
Inner Ethernet
Inner IP
TCP
HTTP

中间物理网络只看到：

Node1IP -> Node2IP

Node2 收到后解 VXLAN，再把原始 Pod 包送给 PodB。

十四、flannel.1 是什么

flannel.1 不是进程。

它是 Linux VXLAN 网络设备。

类似：

eth0
docker0
cni0
vethxxx

路由表里：

10.244.2.0/24 dev flannel.1

意思是：

去 10.244.2.0/24 的流量
交给 flannel.1 这个 VXLAN 设备处理

然后 Linux 内核负责 VXLAN 封装。

flanneld 才是进程，它负责：

创建 flannel.1
写路由表
维护 Node 和 PodCIDR 的映射

十五、Service 的本质

Service 提供稳定访问入口。

例如：

Service IP = 10.96.0.10

但这个 IP 通常不是某张真实网卡上的 IP。

Service 本质是：

虚拟 IP
+
iptables / IPVS 转发规则

十六、kube-proxy

kube-proxy 监听：

Service
Endpoint / EndpointSlice

然后生成转发规则。

例如：

10.96.0.10:8080
↓ DNAT
10.244.1.2:8080

所以访问 Service 时，真实过程是：

访问 Service IP
↓
iptables / IPVS 命中规则
↓
DNAT 到某个后端 Pod IP
↓
通过 CNI 网络转发到目标 Pod

十七、CoreDNS

Pod 内访问服务名：

curl user-service

解析过程：

user-service
↓
CoreDNS
↓
Service ClusterIP
↓
kube-proxy
↓
Pod IP

十八、Ingress

Ingress 是规则，不是真正的网关进程。

真正处理流量的是 Ingress Controller，比如：

Nginx Ingress Controller
Traefik
APISIX
Kong

外部请求链路：

Browser
↓
LoadBalancer / NodePort
↓
Ingress Controller
↓
Service
↓
Pod

Ingress Controller 通常是七层反向代理，会解析：

Host
Path
TLS
HTTP Header

十九、完整链路总结

Linux 网络基础：

MAC
↓
ARP
↓
交换机
↓
路由器
↓
路由表
↓
NAT

容器网络基础：

Namespace
↓
veth
↓
Bridge
↓
IPAM
↓
Docker 网络

Kubernetes 网络：

Pod
↓
CNI
↓
PodCIDR
↓
cni0 / route / eBPF
↓
VXLAN / BGP
↓
Service
↓
CoreDNS
↓
Ingress

二十、最终结论

Kubernetes 网络不是凭空出现的新体系。

它本质是：

Linux 网络能力
+
CNI 自动化
+
Kubernetes 声明式编排

更具体地说：

Kubernetes 网络
=
Namespace
+
veth
+
Bridge
+
Route
+
NAT
+
iptables / IPVS
+
VXLAN / BGP / eBPF
+
CNI

理解 Kubernetes 网络，正确路径不是先背 Pod、Service、Ingress，而是先理解：

Linux 如何转发一个包
容器如何拥有自己的网络栈
Pod 如何通过 CNI 接入网络
跨节点 Pod 如何通过 VXLAN 或路由互通
Service 如何通过 DNAT 找到后端 Pod
Ingress 如何作为七层入口转发流量

Finished reading? Leave a comment