用户说「我要订票」，大模型不应凭空编造结果——它应调用 Java 方法改数据库，前端列表随之刷新。本文以 springai_demo 为样本，对照 Spring AI 2.0 源码，说明这套 ReAct 全栈 Demo 怎么搭、亮点在哪，以及 2.0 相对 1.x 到底改了什么。

引言：从聊天框到数据库的一次订票

Spring AI 1.x 时代，很多入门示例把 Tool Calling 写进 ChatModel.call() 的黑盒里：业务代码一行 .call()，中间几轮「模型返回 tool_calls → 执行 Java 方法 → 把结果塞回 Prompt → 再调模型」在模型实现内部悄悄完成，控制台往往只能看到首尾两次 HTTP 请求。

Spring AI 2.0 把这条循环抬进 Advisor 链。ToolCallingAdvisor 在 @since 2.0.0 引入，注释写得很直白：「Recursive Advisor that disables the internal tool execution flow and instead implements the tool calling loop as part of the advisor chain.」¹ 与此同时，各 Provider 的 ChatModel 不再自带内部工具执行循环²。

springai_demo 正是为吃透这一变化而写的 Fullstack 学习项目：React 双栏订票列表 + 自然语言聊天，后端 Spring Boot 4.1 + Spring AI 2.0 + DeepSeek deepseek-chat，用 @Tool 把「订票 / 取消 / 查列表」暴露给大模型，ReAct 循环由框架驱动，业务侧仍只需一行 chatClient.prompt().user().call().content()。

全文脉络：

1. 项目架构 — 前后端分层、写入口收敛、一次聊天的时序
2. 前端设计 — 容器/展示分离、API 封装、聊天后刷新列表
3. 实现亮点 — 业务兜底、PromptLoggingAdvisor 调用链与 before/after 时机、E2E 与 Docker Compose 编排
4. Spring AI 2 核心变动 — 1.x 三种写法回溯、Advisor 链源码走读（nextCall → ChatModel）、Upgrade Notes
5. 变动在项目中的落地 — ChatConfig、PromptLoggingAdvisor、日志如何读 ReAct

一、项目架构：经典三层 + AI 工具层

1.1 技术栈与职责划分

后端 Maven 坐标见 backend/pom.xml：spring-boot-starter-parent 4.1.0，spring-ai-bom 2.0.0。Spring AI 2.0 基于 Spring Boot 4 依赖模型，不能与 Boot 3.x 混用³。

1.2 整体数据流

flowchart TB
  subgraph browser [浏览器 localhost:5173]
    App[App.tsx]
    List[BookingList 双栏]
    Chat[ChatPanel 聊天]
    App --> List
    App --> Chat
  end

  subgraph vite [Vite Dev Server]
    Proxy["/api → :8080"]
  end

  subgraph backend [Spring Boot localhost:8080]
    BC[BookingController]
    CC[ChatController]
    BS[BookingService]
    CS[ChatService]
    BT[BookingTools @Tool]
    BR[BookingRepository]
    CFG[ChatConfig → ChatClient]
    DB[(H2 bookings)]
    BC --> BS
    CC --> CS
    CS --> CFG
    CFG --> ChatModel[DeepSeekChatModel]
    CFG --> BT
    BT --> BS
    BS --> BR
    BR --> DB
  end

  subgraph external [外部]
    DS[DeepSeek API]
  end

  App -->|fetch /api| Proxy
  Proxy --> BC
  Proxy --> CC
  ChatModel --> DS

设计原则：所有写数据库的操作只经过 BookingService。REST 的 BookingController 与 AI 的 BookingTools 都调它——避免「聊天改了一套、列表查另一套」的分叉。

后端包结构可概括为：

1.3 领域模型与状态机

实体 Booking 只有 id、title、status（SUBSCRIBED / UNSUBSCRIBED）。启动时 data.sql 插入 3 条未订阅票；H2 内存库，进程退出即清空。

前端 App.tsx 在挂载时并行拉两栏列表；聊天成功后必须再次 loadBookings()——因为数据库已被 @Tool 修改，React state 不会自动同步。

1.4 一次「我要订票」的时序

sequenceDiagram
  participant User as 用户
  participant FE as React App
  participant CC as ChatController
  participant CS as ChatService
  participant Client as ChatClient
  participant Adv as ToolCallingAdvisor
  participant Log as PromptLoggingAdvisor
  participant DS as DeepSeek
  participant Tools as BookingTools
  participant Svc as BookingService
  participant DB as H2

  User->>FE: 输入「我要订票」
  FE->>CC: POST /api/chat
  CC->>CS: chat(message)
  CS->>Client: prompt().user().call()
  Client->>Adv: adviseCall（TCA 远离 ChatModel，驱动 ReAct）
  Note over Adv,Log: 第 1 轮 copy(this).nextCall()
  Adv->>Log: before() 第1步
  Log->>DS: ChatModel HTTP
  DS-->>Log: tool_call subscribeTicket
  Log->>Adv: after() 第1步
  Adv->>Tools: executeToolCalls subscribeTicket
  Tools->>Svc: subscribeTicket(null)
  Svc->>DB: UPDATE status=SUBSCRIBED
  Note over Adv,Log: 第 2 轮 copy(this).nextCall()
  Adv->>Log: before() 第2步 含 TOOL_RESPONSE
  Log->>DS: ChatModel HTTP
  DS-->>Log: 最终中文 reply
  Log->>Adv: after() 第2步
  Adv-->>CS: content()
  CS-->>FE: JSON reply
  FE->>FE: GET /api/bookings 刷新双栏

用户只说「我要订票」、未指定票名时，BookingService.subscribeTicket(null) 会订第一张未订阅票（按 id 排序）——这是刻意为 AI 传参不准准备的兜底，降低 Tool 调用成功但业务失败的概率。

1.5 前端设计：刻意保持「薄 UI、厚后端」

前端没有引入 Redux、React Router 或 UI 库，目的是把学习成本压在 Spring AI 与 ReAct 上。结构遵循经典的容器组件 / 展示组件分离：

状态设计：App.tsx 用 useState 维护两栏列表（subscribed / unsubscribed）、聊天历史（messages）、加载与错误态。挂载时 Promise.all 并行请求两个 status，减少首屏等待。

与 AI 路径的关键衔接：聊天成功后必须再次 loadBookings()。ReAct 改的是 H2 数据库，React state 不会自动感知 @Tool 的副作用——handleSendMessage 在收到 ChatResponse 后显式刷新双栏，E2E 用例也正是靠「左栏 +1」来验证 Tool 真正执行。

跨域策略：开发态所有请求走相对路径 /api/...，由 Vite dev server 代理到 Spring Boot，浏览器始终认为前后端同源。

// vite.config.ts: 11-19
server: {
  proxy: {
    '/api': {
      target: apiProxyTarget,  // 本地默认 http://localhost:8080
      changeOrigin: true,
    },
  },
},

本地 pnpm dev 时 apiProxyTarget 默认为 http://localhost:8080；Docker Compose 里通过环境变量 VITE_API_PROXY_TARGET=http://backend:8080 把代理目标改成 Compose 网络内的服务名。后端 WebConfig 另配了 CORS，允许 http://localhost:5173 直连 8080——便于 curl、Playwright 或不走代理的调试；日常开发仍以 Vite proxy 为主⁴。

pnpm workspace：根目录 package.json + pnpm-workspace.yaml 统一管理 frontend 与 e2e，根脚本 pnpm dev 等价于 pnpm --dir frontend dev。

二、实现亮点

2.1 单一写入口 + 面向 AI 的业务规则

BookingTools 用 @Tool 暴露四个方法：查未订阅、查已订阅、订票、取消。每个方法只打日志并委托 BookingService，不碰 Repository。

取消逻辑比「模糊匹配 title」更进一步：BookingService.cancelSubscription 支持航班号（G123）、「北京到上海」与「北京-上海 G123」的归一化、用户只说「取消订票」且仅一张已订阅票时的兜底。这些规则对 REST 与 AI 共用，大模型只需选对工具，不必背 SQL。

System Prompt 在 ChatConfig 里用 defaultSystem 约束：禁止未调工具就声称成功、订票/取消/查列表必须走对应 @Tool。配合 temperature: 0.1（application.yml），让模型更稳定地触发 function calling。

2.2 PromptLoggingAdvisor：把 ReAct 从黑盒里拽出来

Spring AI 2.0 的关键收益是：order 大于 ToolCallingAdvisor（+300）的 Advisor，会挂在每一轮 copy(this).nextCall() 子链上、更靠近 ChatModel。PromptLoggingAdvisor 的 getOrder() 返回 HIGHEST_PRECEDENCE + 400，比 +300 更接近 ChatModelCallAdvisor，因此在每一轮「发 Prompt → 收 Response → 执行 Tool → 再发 Prompt」时都能逐步观测。更细的调用链、before/after 时机与日志解读见项目 docs/PROMPT_LOGGING_ADVISOR.md。

2.2.1 核心结论

一句话：before / after 包的是 单次模型 HTTP 往返，不包含工具 Java 执行本身。

2.2.2 注册与入口

// ChatConfig.java: 61-62
.defaultTools(bookingTools)   // 工具 schema 写入 options.toolCallbacks，非 SYSTEM 文本
.defaultAdvisors(new PromptLoggingAdvisor())  // INFO=messages，DEBUG=tools

注意：不要再手动 .advisors(ToolCallingAdvisor.builder()...)，否则会与自动注册的实例 重复，链中出现两个工具 Advisor。

ChatService.chat 在每次用户聊天前调用 PromptLoggingAdvisor.resetSteps()，保证一次 HTTP 请求从 [AI 第1步] 重新计数；业务代码 从不 直接调用 before() / after()：

// ChatService.java: 60-67
PromptLoggingAdvisor.resetSteps();
String reply = chatClient
        .prompt()
        .user(userMessage.trim())
        .call()
        .content();

2.2.3 Spring AI 如何调用 before / after？

PromptLoggingAdvisor 实现 BaseAdvisor。框架对 BaseAdvisor 的默认 adviseCall 模板是：

// BaseAdvisor.java: 47-53
default ChatClientResponse adviseCall(ChatClientRequest chatClientRequest, CallAdvisorChain callAdvisorChain) {
    ChatClientRequest processedChatClientRequest = before(chatClientRequest, callAdvisorChain);
    ChatClientResponse chatClientResponse = callAdvisorChain.nextCall(processedChatClientRequest);
    return after(chatClientResponse, callAdvisorChain);
}

调用链：

ChatService.chat()
    └─ chatClient.prompt().user(...).call()
        └─ DefaultChatClient.doGetObservableChatClientResponse()
            └─ DefaultAroundAdvisorChain.nextCall()     【链调度器】
                └─ advisor.adviseCall(...)              【按 order 逐个 Advisor】
                    └─ PromptLoggingAdvisor
                        ├─ before()   ← 日志
                        ├─ nextCall() → 更靠近 ChatModel
                        └─ after()    ← 日志

DefaultAroundAdvisorChain.nextCall 从 deque 弹出 order 最小（最远离 ChatModel）的 Advisor，执行其 adviseCall；该 Advisor 若继续 nextCall()，则向 更靠近 ChatModel 的方向递进。完整链路见 §3.2.1。

2.2.4 order 与距 ChatModel 远近：为何必须是 +400

速记：在 Advisor 链上，order 数值越大 → 越靠近 ChatModel；order 越小 → 越远离 ChatModel（到达模型前要经过更多 Advisor）。链终点是 ChatModelCallAdvisor（Ordered.LOWEST_PRECEDENCE，order 最大）。

若 PromptLoggingAdvisor 的 order ≤ +300（与 ToolCallingAdvisor 同级或更远离 ChatModel），它不会进入每轮 copy(this).nextCall() 子链，往往 只能看到 ReAct 首尾，看不到中间 [AI 第1步] tool_calls → [AI 第2步] TOOL_RESPONSE 的完整往返。

2.2.5 ReAct 每轮：before / after 的精确时机

ToolCallingAdvisor 不使用 BaseAdvisor 的默认 adviseCall，而是自定义 do { ... } while (isToolCall) 循环。每一轮核心逻辑（简化）：

// ToolCallingAdvisor.java（简化）
do {
    processedChatClientRequest = doBeforeCall(...);
    chatClientResponse = callAdvisorChain.copy(this).nextCall(processedChatClientRequest);
    // ↑ 子链（更靠近 ChatModel）：PromptLoggingAdvisor.before → ChatModel → PromptLoggingAdvisor.after
    chatClientResponse = doAfterCall(...);

    isToolCall = toolExecutionEligibilityChecker.isToolCallResponse(chatResponse);
    if (isToolCall) {
        toolExecutionResult = toolCallingManager.executeToolCalls(...);  // ← BookingTools 在这里
        instructions = doGetNextInstructionsForToolCall(...);
    }
} while (isToolCall);

单轮时序：

ToolCallingAdvisor 第 N 轮
    │
    ├─ PromptLoggingAdvisor.before()          【打 [AI 第N步] 发送 Prompt】
    ├─ ChatModel → DeepSeek HTTP              【真正模型请求】
    ├─ PromptLoggingAdvisor.after()           【打 [AI 第N步] 收到 Response】
    │       （可能是 tool_calls，也可能是最终中文）
    └─ 回到 ToolCallingAdvisor
            ├─ 若 hasToolCalls → executeToolCalls()
            │       └─ MethodToolCallback → BookingTools  【打 [Tool 被调用]】
            └─ 更新 instructions，进入第 N+1 轮

易错点：[Tool 被调用] 不在 before 与 after 之间，而在 after 返回之后。

以「我要订票」为例的完整日志顺序：

一次用户 POST /api/chat 对应 一次 chatClient.call()，但 Advisor 链内可能有 多轮 DeepSeek 请求。

sequenceDiagram
  autonumber
  participant CS as ChatService
  participant TCA as ToolCallingAdvisor
  participant PLA as PromptLoggingAdvisor
  participant DS as DeepSeek
  participant BT as BookingTools

  CS->>CS: resetSteps()
  CS->>TCA: chatClient.call()

  Note over TCA,DS: 第 1 轮
  TCA->>PLA: copy(this).nextCall()
  PLA->>PLA: before() 第1步
  PLA->>DS: ChatModel HTTP
  DS-->>PLA: tool_calls subscribeTicket
  PLA->>PLA: after() 第1步
  PLA-->>TCA: ChatClientResponse

  TCA->>BT: executeToolCalls()
  BT-->>TCA: BookingResponse

  Note over TCA,DS: 第 2 轮
  TCA->>PLA: copy(this).nextCall()
  PLA->>PLA: before() 第2步 含 TOOL_RESPONSE
  PLA->>DS: ChatModel HTTP
  DS-->>PLA: 最终中文
  PLA->>PLA: after() 第2步
  PLA-->>TCA: ChatClientResponse

  TCA-->>CS: content()

2.2.6 before() 与 after() 各打印什么？

before() — 发送前：

after() — 模型返回后：

after() 不修改 request/response，只观测并原样返回。还有一个容易踩坑的细节：@Tool 注册结果不在 INFO 日志的 messages 里，而是进入 ToolCallingChatOptions.toolCallbacks，由 DeepSeekChatModel 转成 HTTP 请求体的 tools 字段——仅看 INFO 会误以为「没注册工具」。

2.2.7 与 ToolCallingAdvisor 的分工

Spring AI 2.0 相对 1.x：ReAct 循环从 ChatModel 内部上移到 Advisor 链，因此 PromptLoggingAdvisor 才能挂在 更靠近 ChatModel 的子链上逐步观测；1.x 路径 A 下，远离 ChatModel 的 Advisor 往往只能看到首尾两次调用（§3.0）。

2.2.8 日志配置与验证关键字

勿在 application.yml 里单独把 PromptLoggingAdvisor 锁为 INFO，否则会覆盖 Docker 的 DEBUG，看不到 inputSchema。

2.2.9 常见误解

2.3 ChatConfig 刻意保持精简

ChatConfig 只做三件事：

// ChatConfig.java: 49-63
return ChatClient.builder(chatModel)
        .defaultSystem(""" ... """)
        .defaultTools(bookingTools)
        .defaultAdvisors(new PromptLoggingAdvisor())
        .build();

• defaultTools(bookingTools) — 注册 @Tool，并触发 ToolCallingAdvisor 自动装配（见第三节）
• 不再手动 new ToolCallAdvisor / ToolCallingAdvisor — 显式再加会导致链中出现两个 ToolAdvisor，DefaultChatClient 会校验并报错
• ToolCallingManager 仍由 Spring Boot 自动配置，业务代码无需注入

2.4 Docker Compose：开发态双容器编排

项目刻意不做前端静态资源 + Nginx 的生产打包镜像，而是 Compose 里跑 Vite dev server + Spring Boot JAR——与本地 mvn spring-boot:run + pnpm dev 行为一致，改代码 rebuild 即可，适合 Demo 与学习。

docker-compose.yml 定义两个 service：

flowchart LR
  subgraph host [宿主机]
    Browser[浏览器 :5173]
  end
  subgraph compose [Docker Compose 网络]
    FE[frontend 容器 Vite dev]
    BE[backend 容器 Spring Boot]
  end
  Browser -->|/api 经 Vite proxy| FE
  FE -->|VITE_API_PROXY_TARGET| BE
  BE -->|DEEPSEEK_API_KEY| DS[DeepSeek API]

一键启动：

export DEEPSEEK_API_KEY=your-key-here
docker compose up --build
# 前端 http://localhost:5173  后端 http://localhost:8080

2.5 工程化：E2E 与健康检查

• Playwright（e2e/tests/app.spec.ts）：初始 3 未订阅 / 0 已订阅、聊天订票、聊天取消、健康检查；capture-screenshots 脚本生成 README 效果截图
• API Key 仅通过环境变量注入，仓库内无密钥；跨域与 Proxy 实测见 docs/CORS.md

更细的模块说明见项目 docs/ARCHITECTURE.md。

三、Spring AI 2.0 核心变动（对照源码）

官方 Upgrade Notes 2.0 篇幅很长；对本 Demo 与 Tool Calling 场景，下面几条最关键。先回答一个常见误解：Spring AI 1.x 并非做不了订票 ReAct——@Tool + ChatClient 在 1.x 就能跑通业务；变的是循环放在哪、Advisor 能否插进中间轮次、以及配置要手写多少。

3.0 回溯：1.x 下同一 Demo 怎么写？（已对照 v1.1.8 / v2.0.0 tag 源码）

以下结论来自本地 spring-ai 仓库 tag 比对：v1.1.8（1.x 末版）、v2.0.0（2.0 首发）。1.x 内部仍有版本差：ToolCallAdvisor 自 v1.1.0 才出现；v1.0.x 只有「ChatModel 内部循环」或手写 while，没有 Advisor 链式 ReAct。

本 Demo 的三块能力拆开看：

路径 A：最常见——依赖 ChatModel 内部循环（v1.0.x～v1.1.8 默认）

v1.1.8 中，对带 tools 的 Prompt 调用 chatModel.call() 时，DeepSeekChatModel 在 internalCall 末尾判断 toolExecutionEligibilityPredicate.isToolExecutionRequired(...)，执行 toolCallingManager.executeToolCalls，再递归 internalCall 把 tool 结果塞回 Prompt——循环在模型类内部完成⁵。v2.0.0 的同文件已删掉这段 tool 执行逻辑，internalCall 只返回单次 HTTP 响应²。

因此路径 A 的 ChatConfig 往往比 2.0 更短——不必注册 ToolCallAdvisor：

// Spring AI 1.x + Spring Boot 3.x — 路径 A（v1.1.8 验证）
@Bean
public ChatClient chatClient(ChatModel chatModel, BookingTools bookingTools) {
    return ChatClient.builder(chatModel)
            .defaultSystem(""" ... 订票助手 system prompt ... """)
            .defaultTools(bookingTools)   // v1.0.9+ 已有；亦可用 defaultToolCallbacks
            .build();
    // 无 ToolCallAdvisor；ReAct 在 DeepSeekChatModel.internalCall 内完成
}

ChatService 的 .call().content() 写法可以不变。差别在 .call() 内部：若只加一层 远离 ChatModel 的 BaseAdvisor（如 PromptLoggingAdvisor 但 order ≤ +300），它通常只在整次 .call() 的首尾各执行一次 before/after——中间多轮 internalCall 发生在 ChatModel 黑盒里，看不见 [AI 第1步] … (tool_calls) 与 [AI 第2步] … TOOL_RESPONSE。

路径 B：v1.1.0+ 手动注册 ToolCallAdvisor（Advisor 链 ReAct，2.0 前身）

自 v1.1.0 起，ToolCallAdvisor 与 2.0 的 ToolCallingAdvisor 同类：类注释即写明 Recursive Advisor… implements the tool calling loop as part of the advisor chain，默认 advisorOrder = HIGHEST_PRECEDENCE + 300，do { … callAdvisorChain.copy(this).nextCall(…) … } while (isToolCall)⁶。

与文章旧稿不同、以 v1.1.8 源码为准的几点：

1. 不必手动设 internalToolExecutionEnabled(false)——ToolCallAdvisor.adviseCall 在循环开始前会对 options 副本执行 setInternalToolExecutionEnabled(false)⁸。
2. ToolCallingManager 通常不必注入——ToolCallAdvisor.builder() 默认 ToolCallingManager.builder().build()。
3. 必须手动 .defaultAdvisors(ToolCallAdvisor.builder()...)——1.x 没有 2.0 的 autoRegisterToolCallingAdvisor。

// Spring AI 1.1.x — 路径 B（v1.1.8 验证）
@Bean
public ChatClient chatClient(ChatModel chatModel, BookingTools bookingTools) {
    return ChatClient.builder(chatModel)
            .defaultSystem(""" ... """)
            .defaultTools(bookingTools)
            .defaultAdvisors(ToolCallAdvisor.builder().build())
            .build();
}

PromptLoggingAdvisor 在 1.1.x 并非「根本无法实现」：若像本项目一样再注册一个 order = HIGHEST_PRECEDENCE + 400 的 BaseAdvisor，且其 order 大于 ToolCallAdvisor（+300），则 copy(this).nextCall 重入链时会带上该 Advisor——逐步日志可以做到。难在 1.x 默认走路径 A，且路径 B 需手动组装 ToolCallAdvisor；2.0 则是 defaultTools 即自动启用 ToolCallingAdvisor，本项目只加观测 Advisor 即可。

路径 C：完全手写 while（ChatModel 直调）

对 chatModel.call() 设 internalToolExecutionEnabled(false)（v1.1.8 的 ToolCallingChatOptions 默认 true⁹），再用 ToolCallingManager + while (response.hasToolCalls()) 驱动循环。Upgrade Notes 在 2.0 仍给出等价示例¹⁰；编排代码全在业务里，不适合本 Demo「一行 .call()」的目标。

版本与路径速查

1.x 与 2.0 配置对照（本 Demo 视角）

graph TB
  subgraph v1_default [1.x 路径 A 默认 v1.1.8]
    CS1[ChatService.call]
    CC1[ChatClient + defaultTools]
    CM1[DeepSeekChatModel.internalCall 内 while]
    CS1 --> CC1 --> CM1
  end
  subgraph v1_b [1.x 路径 B v1.1.0+]
    CS1b[ChatService.call]
    CC1b[ChatClient + ToolCallAdvisor +300]
    PLA1[PromptLoggingAdvisor +400 可选]
    CS1b --> CC1b --> PLA1
  end
  subgraph v2 [2.0 本项目 v2.0.0]
    CS2[ChatService.call]
    CC2[ChatClient + defaultTools]
    TCA[ToolCallingAdvisor 自动 +300]
    PLA[PromptLoggingAdvisor +400]
    CS2 --> CC2 --> TCA --> PLA
  end

结论：订票 Demo 的 业务层在 1.x 完全可以实现；2.0 的实质变化是 v2.0.0 移除 ChatModel 内循环，Tool 循环统一由 Advisor 链承担，且 defaultTools 自动注册 ToolCallingAdvisor——因此本项目的 ChatConfig 才能只写 defaultTools + PromptLoggingAdvisor。从 v1.1.8 迁移：去掉手动 ToolCallAdvisor、删除 internalToolExecutionEnabled 配置、升级 Boot 4 + AI 2.0 即可¹¹。

3.1 ChatModel 内部循环被移除

1.x 中，对带 tools 的 Prompt 调用 chatModel.call()，各 Provider 会在实现内部自动执行 tool calls 并循环，直到模型返回纯文本。

2.0 删除了所有 ChatModel 实现中的这一内部循环²。ChatModel.call() / stream() 现在返回原始模型响应——若有 tool_calls，不会自动执行。

迁移路径：改用 ChatClient + 自动注册的 ToolCallingAdvisor（推荐），或自行用 ToolCallingManager 写 while 循环。

3.2 ToolCallingAdvisor 拥有工具执行生命周期

ToolCallingAdvisor.adviseCall 的核心是一个 do { ... } while (isToolCall) 循环：

// ToolCallingAdvisor.java: 141-187
do {
    processedChatClientRequest = this.doBeforeCall(processedChatClientRequest, callAdvisorChain);
    chatClientResponse = callAdvisorChain.copy(this).nextCall(processedChatClientRequest);
    chatClientResponse = this.doAfterCall(chatClientResponse, callAdvisorChain);
    isToolCall = this.toolExecutionEligibilityChecker.isToolCallResponse(chatResponse);
    if (isToolCall) {
        ToolExecutionResult toolExecutionResult = this.toolCallingManager
            .executeToolCalls(processedChatClientRequest.prompt(), chatResponse);
        instructions = this.doGetNextInstructionsForToolCall(...);
    }
} while (isToolCall);

注意 callAdvisorChain.copy(this).nextCall(...)：每一轮 ReAct 重新进入 order 更大（更靠近 ChatModel）的 Advisor 子链——这正是 PromptLoggingAdvisor 能逐步打印的原因；1.x 路径 A 下，中间轮次发生在 ChatModel 内部，远离 ChatModel 的 Advisor 不可见。

默认 order：ToolCallingAdvisor.DEFAULT_ORDER = HIGHEST_PRECEDENCE + 300¹²。MessageChatMemoryAdvisor 默认 order 从 +1000 改为 +200，比 +300 更远离 ChatModel——不参与每一轮 tool 迭代的子链，只存最终 user/assistant 交换，不把 tool_call / tool_response 写进多数 ChatMemoryRepository 不支持的存储¹³。

3.2.1 源码走读：从 nextCall 到 ChatModel.call()（含 handleToolCallRecursion）

先澄清一个常见混淆：handleToolCallRecursion 只出现在流式路径（ToolCallingAdvisor.adviseStream）。本 Demo 的 ChatService 走 .call() 同步路径，ReAct 递归由 adviseCall 里的 do-while 完成（约 141–187 行）。两条路径语义等价：都是「更靠近 ChatModel 的子链调模型 → 检测 tool_calls → 执行工具 → 更新 instructions → 再进子链」，只是流式在 SSE chunk 聚合完毕后才进入 handleToolCallRecursion，再递归调用 internalStream。

链是怎么组出来的？

每次 chatClient.prompt().user(...).call() 时，DefaultChatClient.buildAdvisorChain 做三件事：

1. autoRegisterToolCallingAdvisor() — 若链中尚无 ToolAdvisor，自动加入 ToolCallingAdvisor（+300）
2. 把用户注册的 Advisor（本项目的 PromptLoggingAdvisor +400）与自动注册的 ToolCallingAdvisor 合并
3. 在栈底追加终结 Advisor：ChatModelCallAdvisor（Ordered.LOWEST_PRECEDENCE）与 ChatModelStreamAdvisor（流式用）

DefaultAroundAdvisorChain.Builder.pushAll 按 OrderComparator 排序后装入 双端队列：order 越小，越先被 pop()——即 越远离 ChatModel（请求要先经过它，才能继续 nextCall 靠近模型）。

本 Demo 同步调用链（从远离 ChatModel → 靠近 ChatModel）可概括为：

DefaultAroundAdvisorChain.nextCall：调度器如何「层层递进」？

nextCall 逻辑极简：

var advisor = this.callAdvisors.pop();          // 弹出 order 最小（最远离 ChatModel）的 Advisor
return advisor.adviseCall(chatClientRequest, this);

每个 Advisor 的 adviseCall 决定是否继续向 ChatModel 递进：

copy(CallAdvisor after) 从完整 Advisor 列表里截取 after 之后的剩余节点，构造一条新链。ToolCallingAdvisor 调用 copy(this).nextCall() 时，this 是 +300，剩余子链为 PromptLoggingAdvisor (+400) → ChatModelCallAdvisor——即每一轮 ReAct 都会走一遍 更靠近 ChatModel 的观测链。

同步路径：.call() 如何最终落到 ChatModel？

入口在 DefaultChatClient.doGetObservableChatClientResponse：

// 注释写明：Apply the advisor chain that terminates with the ChatModelCallAdvisor.
var response = advisorChain.nextCall(chatClientRequest);

ChatModelCallAdvisor.adviseCall 是链上唯一真正调用大模型的地方：

ChatResponse chatResponse = this.chatModel.call(formattedChatClientRequest.prompt());
return ChatClientResponse.builder().chatResponse(chatResponse).context(...).build();

对本项目即 DeepSeekChatModel.call(Prompt) → HTTP 请求 DeepSeek API。2.0 下这次 call() 只返回单轮原始响应（含 tool_calls 时也不执行工具），工具执行由 更远离 ChatModel 的 ToolCallingAdvisor 在子链 after 返回后调用 toolCallingManager.executeToolCalls 完成。

流式路径：handleToolCallRecursion 做了什么？

流式时 ToolCallingAdvisor 不走 do-while，而是：

1. internalStream → chainCopy.nextStream() 把 chunk 流式传给客户端
2. streamWithToolCallResponses 在流结束后调用 handleToolCallRecursion
3. 若聚合后的 ChatResponse 含 tool_calls：在 boundedElastic 上 executeToolCalls，再 return internalStream(...) 进入下一轮——与同步的 do-while 同构¹⁴

// ToolCallingAdvisor.java: 343-348（流式递归核心）
List<Message> nextInstructions = this.doGetNextInstructionsForToolCallStream(...);
return this.internalStream(streamAdvisorChain, originalRequest, optionsCopy,
        nextInstructions, usageAccumulator);

Mermaid：本 Demo 同步 .call() 完整时序（第 1 轮 + 工具 + 第 2 轮）

sequenceDiagram
  autonumber
  participant CS as ChatService
  participant DCC as DefaultChatClient
  participant Chain as DefaultAroundAdvisorChain
  participant TCA as ToolCallingAdvisor +300
  participant PLA as PromptLoggingAdvisor +400
  participant CMA as ChatModelCallAdvisor
  participant CM as DeepSeekChatModel
  participant TCM as ToolCallingManager
  participant BT as BookingTools

  CS->>DCC: prompt().user().call()
  DCC->>DCC: buildAdvisorChain()<br/>自动注册 TCA + 栈底 CMA
  DCC->>Chain: nextCall(request)

  Note over Chain,TCA: 先 pop order 最小（远离 ChatModel）→ TCA
  Chain->>TCA: adviseCall(req, chain)

  Note over TCA,CM: 第 1 轮 ReAct
  TCA->>TCA: doBeforeCall()
  TCA->>Chain: copy(TCA).nextCall(req₁)
  Note over Chain: 子链 PLA → CMA（更靠近 ChatModel）

  Chain->>PLA: adviseCall（BaseAdvisor 模板）
  PLA->>PLA: before() 日志第1步
  PLA->>Chain: nextCall(req₁)
  Chain->>CMA: adviseCall
  CMA->>CM: chatModel.call(prompt)
  CM-->>CMA: ChatResponse tool_calls
  CMA-->>PLA: ChatClientResponse
  PLA->>PLA: after() 日志第1步
  PLA-->>TCA: ChatClientResponse

  TCA->>TCA: doAfterCall()
  TCA->>TCM: executeToolCalls(prompt, response)
  TCM->>BT: subscribeTicket @Tool
  BT-->>TCM: BookingResponse
  TCM-->>TCA: ToolExecutionResult + 新 instructions

  Note over TCA,CM: 第 2 轮 ReAct（instructions 含 TOOL_RESPONSE）
  TCA->>Chain: copy(TCA).nextCall(req₂)
  Chain->>PLA: before() 第2步 → CMA → CM.call()
  CM-->>PLA: 最终中文
  PLA->>PLA: after() 第2步
  PLA-->>TCA: ChatClientResponse

  TCA->>TCA: isToolCall=false，退出 do-while
  TCA-->>DCC: ChatClientResponse
  DCC-->>CS: content()

读图要点：

• 第 4–6 步：DefaultChatClient 只调一次 nextCall，首先进入的是 最远离 ChatModel 的 ToolCallingAdvisor（+300），不是 PromptLoggingAdvisor。
• 第 8–9 步：copy(TCA) 是关键——每一轮 ReAct 都重新构造「PLA → CMA」子链（更靠近 ChatModel），因此 PromptLoggingAdvisor 的 before/after 在每一轮都会触发。
• 第 17–18 步：ChatModelCallAdvisor 是链终点（最近）；ToolCallingAdvisor 与 PromptLoggingAdvisor 都不会直接碰 ChatModel。
• 第 20–22 步：工具执行在 PLA.after() 之后、下一轮 copy().nextCall() 之前，与 §2.2.5 日志顺序一致。

三条路径对照

3.3 defaultTools 与自动注册

DefaultChatClient.Spec.autoRegisterToolCallingAdvisor 在每次 call() 前检查：

• 若 AdvisorParams.toolCallingAdvisorAutoRegister(false) 未禁用
• 且链中尚无 ToolAdvisor 实例

则自动加入 ToolCallingAdvisor。全局开关：spring.ai.chat.client.tool-calling.enabled（默认 true）¹⁵。

defaultToolCallbacks 等在 2.0 deprecated；defaultTools(Object...) 在 v1.0.9 已存在¹⁶，2.0 是将其作为唯一推荐入口。

3.4 删除与新增的选项（迁移清单）

若需完全自控循环，可 AdvisorParams.toolCallingAdvisorAutoRegister(false)，配合 ToolCallingManager.executeToolCalls 手写 while——Upgrade Notes 给出了完整示例¹⁰。

3.5 Advisor 链 order 速查（距 ChatModel 远近）

graph LR
  Mem["MessageChatMemoryAdvisor +200<br/>远离 ChatModel"]
  TCA["ToolCallingAdvisor +300"]
  PLA["PromptLoggingAdvisor +400<br/>更靠近 ChatModel"]
  CMA["ChatModelCallAdvisor<br/>最近（链终点）"]
  Mem --> TCA --> PLA --> CMA

速记：order 越大 → 越靠近 ChatModel。要把自定义观测逻辑插进每一轮 tool 迭代，order 必须 > 300（比 ToolCallingAdvisor 更近），这样才会进入 copy(this).nextCall() 子链，在每次 chatModel.call() 前后执行。

四、变动在本项目中的落地

4.1 业务代码几乎不变，可观测性大变

ChatService 仍是一行：

// ChatService.java: 63-67
String reply = chatClient
        .prompt()
        .user(userMessage.trim())
        .call()
        .content();

差异在 .call() 内部：2.0 由自动注册的 ToolCallingAdvisor 驱动多轮 DeepSeek 请求；1.x 路径 A 则在 DeepSeekChatModel.internalCall 内循环（§3.0），远离 ChatModel 的 Advisor 只见首尾——1.1.x 路径 B 手动加 ToolCallAdvisor 后，子链也可多轮靠近 ChatModel。

4.2 配置层：从「手动 Advisor + Manager」到「defaultTools 即可」

1.x 下路径 A/B/C 的代码级对比见 §3.0（已对照 v1.1.8 tag）。本节只保留迁移速查表：

application.yml 无需额外打开 tool-calling 开关——默认已启用。

4.3 如何验证 ReAct 真的发生

按优先级排查：

1. 控制台 [Tool 被调用] subscribeTicket — 工具层日志
2. [AI 第N步] — Advisor 链内每轮 Prompt/Response
3. Hibernate update bookings set status=... — JPA show-sql: true
4. 前端左栏「已订阅」+1 — 聊天后 loadBookings()

若只有 AI 文字、无 Tool 日志、列表不变 → 模型可能未调工具（LLM 常见情况）；可调 system prompt、temperature，或重试。

4.4 与 Spring AI 文档的对应关系

五、快速上手与延伸

export DEEPSEEK_API_KEY=your-key-here
cd backend && mvn spring-boot:run
# 另开终端
pnpm install && pnpm dev

浏览器打开 http://localhost:5173，说「我要订票」或「取消订票 G123」。不启前端也可 curl：

curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"我要订票"}'
curl "http://localhost:8080/api/bookings?status=SUBSCRIBED"

仓库 README 还列出了 SSE 流式、SQLite 持久化、意图规则兜底等扩展方向¹⁷。

References

引言：一个 Resource 类，两个容器

在 RESTEasy 集成 Spring 的项目里，一个典型的 @Path Resource 往往长这样：@Autowired 注入 CustomerService，方法参数用 @QueryParam，类上还有 @Transactional。运行时一切正常——但调试启动顺序、singleton Resource 的 @Context UriInfo 行为，或 prototype Resource 为何「首请求才创建」时，很容易问：实例是谁创建的？路由是谁注册的？请求进来后谁先谁后？

答案并不在一个容器里。Spring 把它当 Bean 管（创建、DI、AOP、销毁），RESTEasy 把它当 HTTP 端点管（路由、取实例、JAX-RS 注入、方法调用）。两者既不合并，也不互相替代；resteasy-spring 通过 SpringBeanProcessor 与 SpringResourceFactory 在启动期与运行期各管一段。

全文脉络：

1. Spring Bean 生命周期 — 所有 scope 共用 doCreateBean 流水线；singleton 在 refresh() 批量创建，prototype 在每次 getBean() 触发
2. RESTEasy Resource 生命周期 — Registry 登记 ResourceFactory（取实例策略）+ ResourceMethodInvoker；registered / createResource / requestFinished
3. resteasy-spring 桥接 — BFPP 扫描 @Path、BPP 做 JAX-RS 字段注入、ContextRefreshedEvent 注册 Registry、运行期 getBean() 取实例
4. 运行期 call chain — 单次 HTTP 请求从 Dispatcher 到 getBean() 的完整路径
5. WAR vs Spring Boot — 启动时序差异，以及 resteasy-spring-boot 的额外编排

术语与缩写

全文反复出现下列缩写；首次出现时尽量给出全称，此处集中对照，便于查阅。

一、两个容器各自管什么

Spring 容器   ≈  对象工厂 + 业务依赖注入 + 生命周期（创建 / 销毁）
RESTEasy 容器 ≈  路由注册表 + ResourceFactory 策略 + Provider 链（不是 BeanFactory）

RESTEasy 故意不做通用 IoC：业务 DI 交给 Spring，自己只管 HTTP 运行时——Registry 登记「怎么拿实例」，ProviderFactory 登记 @Provider 单例，Dispatcher 编排请求链。

JAX-RS 注解：Spring 产出实例，RESTEasy 消费元数据

一个常见的误解是：既然 Resource 类是 Spring Bean，Spring 是否也会处理 @Path、@GET？不会。 Spring 创建出来的 Bean，对 Spring 自身而言就是一个普通 Java 对象（可能被 AOP 代理）；Spring 只关心 @Autowired、@Transactional、scope 等 Spring 语义，不会因为类上挂了 JAX-RS 注解就去注册路由或处理 HTTP。

JAX-RS 注解在这套集成里扮演的是 元数据——挂在类和方法上，解释与执行它们的始终是 RESTEasy：

因此分工可以概括为：

Spring 产出：带 JAX-RS 注解的 Bean 实例（+ 业务 DI / AOP / scope）
RESTEasy 消费：读注解建路由，按请求做 JAX-RS 注入和方法调用

SpringBeanProcessor 在 Spring 启动期 发现 带 @Path 的 Bean 并建立 SpringResourceFactory 映射——这是桥接层的扫描，不是 Spring 框架本身理解 JAX-RS。真正把 Resource 注册进 Registry、在请求进来时匹配 URI 并调用 @GET 方法的，仍是 RESTEasy（见第四节 ContextRefreshedEvent → addResourceFactory）。

二、Spring Bean 生命周期：从 refresh 到 destroy

Spring 容器的 Bean 生命周期是一个经过精心编排的流程，从 BeanDefinition 解析到实例销毁，每个阶段都有明确扩展点。¹

ApplicationContext.refresh() 中的位置

refresh() 结束时发布 ContextRefreshedEvent——Resteasy-Spring 正是在这个事件上把 Resource 注册进 Registry。²

singleton 与 prototype 在启动期的差异从这里开始：

• singleton（及默认 scope）：在 finishBeanFactoryInitialization() → preInstantiateSingletons() 中 批量 getBean()，走完整 doCreateBean，实例写入一级缓存。
• prototype：refresh() 阶段 只注册 BeanDefinition，不创建实例——首次 getBean()（或依赖链触发）才走 doCreateBean。
• Resteasy-Spring 的等待点：SpringBeanProcessor.onApplicationEvent() 注释写明需等 “spring singleton bean creation is completed”³——确保 singleton @Path Resource 及其 @Autowired 依赖在注册进 RESTEasy Registry 前已就绪；prototype Resource 则通常不在此阶段实例化。

refresh()  —  AbstractApplicationContext.refresh() :582-625
├── prepareRefresh() … registerBeanPostProcessors()     :590-606
│     └── SpringBeanProcessor.postProcessBeanFactory()  :235-261  【仅扫描定义，不建实例】
├── finishBeanFactoryInitialization(beanFactory)          :622
│     └── preInstantiateSingletons()                      :1102-1134
│           └── 仅 singleton：getBean() → createBean() → doCreateBean()
│           └── prototype：跳过，等首次 getBean()
└── finishRefresh() → ContextRefreshedEvent               :625
      └── SpringBeanProcessor.onApplicationEvent()        :453-467
            └── Registry.addResourceFactory(SpringResourceFactory)
                  └── SpringResourceFactory.registered()  :44-45

容器关闭时，destroyBeans() 调用 destroySingletons()——只销毁 singleton；prototype 实例 Spring 不跟踪，SpringResourceFactory.unregistered() / requestFinished() 在集成路径下也为空实现。⁴⁵

核心骨架：doCreateBean — 所有 scope 共用，触发时机不同

常见误解：doCreateBean 是 singleton 专属。实际上，无论 singleton 还是 prototype，只要容器要「新建一个 Bean 实例」，都走同一条 doCreateBean → initializeBean 流水线——scope 不改变流水线步骤，只改变 何时触发 以及 完成后是否入缓存。

createBeanInstance → populateBean → initializeBean → 【singleton 收尾：见下节】
  AbstractAutowireCapableBeanFactory.doCreateBean()  :556-603
    createBeanInstance()  :565
    populateBean()        :602   — @Autowired 在此
    initializeBean()      :603   — BPP、@PostConstruct 在此
    └─ prototype: 直接 return exposedObject，容器不登记

注意：addSingleton() 不在 doCreateBean() 内部调用，而在其外层 getSingleton(beanName, ObjectFactory) 中——ObjectFactory lambda 执行 createBean() → doCreateBean()，成功返回后才 addSingleton() 写入 singletonObjects。

Singleton 缓存：DefaultSingletonBeanRegistry 三级结构与 addSingleton

DefaultSingletonBeanRegistry 是 Spring 各 BeanFactory 实现管理 singleton 实例的基类。类注释说明它 “factoring out the common management of singleton bean instances”，与 BeanDefinition、具体创建流程解耦。⁶

三个 Map + 一个注册表

// spring-beans/.../DefaultSingletonBeanRegistry.java:85-98
/** Cache of singleton objects: bean name to bean instance. */
private final Map<String, Object> singletonObjects = new ConcurrentHashMap<>(256);

/** Creation-time registry of singleton factories: bean name to ObjectFactory. */
private final Map<String, ObjectFactory<?>> singletonFactories = new ConcurrentHashMap<>(16);

/** Cache of early singleton objects: bean name to bean instance. */
private final Map<String, Object> earlySingletonObjects = new ConcurrentHashMap<>(16);

/** Set of registered singletons, containing the bean names in registration order. */
private final Set<String> registeredSingletons = Collections.synchronizedSet(new LinkedHashSet<>(256));

创建 singleton 的完整 call chain

AbstractBeanFactory.doGetBean()  :343-356
└─ getSingleton(beanName, () -> createBean(...))     DefaultSingletonBeanRegistry :255
     ├─ singletonObjects 已有 → 直接返回（运行期 RESTEasy getBean 命中此路径）
     └─ 未命中 → singletonFactory.getObject()
          └─ createBean() → doCreateBean()
               ├─ createBeanInstance()
               ├─ addSingletonFactory(...)   :587-596  【仅循环依赖场景，populateBean 之前】
               ├─ populateBean()
               ├─ initializeBean()            — BPP、@PostConstruct
               └─ return exposedObject
          └─ addSingleton(beanName, singletonObject)  :402-404
               — 写入 singletonObjects，清除 singletonFactories / earlySingletonObjects

AbstractBeanFactory.doGetBean() 对 singleton 的入口：

// spring-beans/.../AbstractBeanFactory.java:343-356
if (mbd.isSingleton()) {
    sharedInstance = getSingleton(beanName, () -> {
        try {
            return createBean(beanName, mbd, args);
        }
        catch (BeansException ex) {
            destroySingleton(beanName);  // 创建失败时清理二/三级缓存
            throw ex;
        }
    });
    beanInstance = getObjectForBeanInstance(sharedInstance, requiredType, name, beanName, mbd);
}

doCreateBean 中 循环依赖 的提前暴露（AbstractAutowireCapableBeanFactory.java:587-596）：

// populateBean 之前：允许其他 Bean 在创建完成前先引用
boolean earlySingletonExposure = (mbd.isSingleton() && this.allowCircularReferences &&
        isSingletonCurrentlyInCreation(beanName));
if (earlySingletonExposure) {
    addSingletonFactory(beanName, () -> getEarlyBeanReference(beanName, mbd, bean));
}

getSingleton(beanName, allowEarlyReference) 的查找顺序——先一级，再三级，最后通过二级 ObjectFactory 生成早期引用：

// DefaultSingletonBeanRegistry.java:210-229
Object singletonObject = this.singletonObjects.get(beanName);
if (singletonObject == null && isSingletonCurrentlyInCreation(beanName)) {
    singletonObject = this.earlySingletonObjects.get(beanName);
    if (singletonObject == null && allowEarlyReference) {
        ObjectFactory<?> singletonFactory = this.singletonFactories.get(beanName);
        if (singletonFactory != null) {
            singletonObject = singletonFactory.getObject();
            if (this.singletonFactories.remove(beanName) != null) {
                this.earlySingletonObjects.put(beanName, singletonObject);
            }
        }
    }
}

创建成功后 addSingleton() 将 最终对象 写入一级缓存，并清理二、三级：

// DefaultSingletonBeanRegistry.java:159-167
protected void addSingleton(String beanName, Object singletonObject) {
    Object oldObject = this.singletonObjects.putIfAbsent(beanName, singletonObject);
    if (oldObject != null) {
        throw new IllegalStateException("Could not register object [...] there is already object [...] bound");
    }
    this.singletonFactories.remove(beanName);
    this.earlySingletonObjects.remove(beanName);
    this.registeredSingletons.add(beanName);
}

prototype 完全不进入这三个 Map——doGetBean 的 prototype 分支 直接 createBean() 后 getObjectForBeanInstance() 返回，容器不持有引用。

与 Resteasy-Spring 的关系

• singleton @Path Resource：refresh() 期间 preInstantiateSingletons() → 上述 call chain 走完 → 实例在 singletonObjects；之后 RESTEasy 每次 SpringResourceFactory.createResource() → getBean() 命中一级缓存，不再 doCreateBean。
• prototype Resource：不进入 singletonObjects；每次 createResource() → getBean() 走 prototype 分支，重新 doCreateBean（见第四节）。

容器关闭时 destroySingletons() 清空三个 Map——仅影响 singleton；prototype 实例从未登记，无从销毁。

其中 initializeBean 是生命周期回调最密集的阶段（:1797-1821）——singleton 在 refresh() 走一次，prototype 在每次 getBean() 再走一次：

initializeBean  —  AbstractAutowireCapableBeanFactory.initializeBean()  :1797-1821
├── invokeAwareMethods()                         :1803
├── applyBeanPostProcessorsBeforeInitialization  :1807
├── invokeInitMethods()                            :1811  — @PostConstruct
└── applyBeanPostProcessorsAfterInitialization     :1818
      └── ResteasyBeanPostProcessor.postProcessAfterInitialization()  :114-146
            └── inject() — singleton 启动期；prototype 请求期（有 HttpRequest 时）

源码（AbstractAutowireCapableBeanFactory.java）：

// spring-beans/.../AbstractAutowireCapableBeanFactory.java:556-603
protected Object doCreateBean(String beanName, RootBeanDefinition mbd, @Nullable Object @Nullable [] args) {
    BeanWrapper instanceWrapper = createBeanInstance(beanName, mbd, args);
    Object bean = instanceWrapper.getWrappedInstance();
    // ...
    populateBean(beanName, mbd, instanceWrapper);
    exposedObject = initializeBean(beanName, exposedObject, mbd);
    // ...
}

// spring-beans/.../AbstractAutowireCapableBeanFactory.java:1797-1821
protected Object initializeBean(String beanName, Object bean, @Nullable RootBeanDefinition mbd) {
    invokeAwareMethods(beanName, bean);
    wrappedBean = applyBeanPostProcessorsBeforeInitialization(wrappedBean, beanName);
    invokeInitMethods(beanName, wrappedBean, mbd);
    wrappedBean = applyBeanPostProcessorsAfterInitialization(wrappedBean, beanName);
    return wrappedBean;
}

一条完整的 Bean 生命周期时间线

创建流水线（singleton 与 prototype 相同）：

scope 决定「何时走流水线」与「收尾」（Resteasy-Spring 集成下）：

AbstractBeanFactory.doGetBean() 是运行期 scope 分叉点——singleton 命中缓存则 跳过 整条 doCreateBean；prototype 每次进入 createBean()：

// spring-beans/.../AbstractBeanFactory.java:257-268 — singleton：缓存命中，不再 doCreateBean
Object sharedInstance = getSingleton(beanName);
if (sharedInstance != null && args == null) {
    beanInstance = getObjectForBeanInstance(sharedInstance, ...);
}
// :359-364 — prototype：每次 createBean → doCreateBean
else if (mbd.isPrototype()) {
    prototypeInstance = createBean(beanName, mbd, args);
}

下文 RESTEasy 侧用 ResourceFactory 策略表达「取实例」；Spring 集成时 scope 仍由 Spring 决定，第四节详述 singleton / prototype 在 bridge 模式下的差异。

三、RESTEasy Resource 生命周期：Registry 与 ResourceFactory

RESTEasy 对 @Path Resource 的管理精简得多：不解析 @Autowired、不管理 AOP 代理、不处理 @PreDestroy——只关心 每次 HTTP 请求如何拿到 Resource 实例。

这里要先澄清一个常见混淆：RESTEasy 注册的不是 Resource 实例，而是 ResourceFactory——一个「取实例策略」对象。这与 Spring 在容器里登记 BeanDefinition、再按需 createBean() 是不同层级的抽象；理解这一点，是读懂 RESTEasy 与 Spring 分工的基础。

核心模式：一个 Resource 类 → 一个 ResourceFactory → 多个 Invoker

RESTEasy 采用 Strategy 模式：ResourceFactory 接口注释写得很直白——“Implementations of this interface are registered through the Registry class”。每个 @Path Resource 类在 Registry 中对应 一个 Factory 实例；Factory 回答的问题是：「每次请求来了，怎么拿到 Resource 对象？」——而不是「如何初始化一个通用 Bean」。

ResourceMethodRegistry 提供了多种 注册 API，本质是在选择不同的 Factory 实现：

// ResourceMethodRegistry.java — 按创建策略选择 Factory，而非直接注册实例
public void addPerRequestResource(Class clazz) {
    addResourceFactory(new POJOResourceFactory(resourceBuilder, clazz));   // 每请求 new
}

public void addSingletonResource(Object singleton) {
    ResourceClass resourceClass = resourceBuilder.getRootResourceFromAnnotations(singleton.getClass());
    addResourceFactory(new SingletonResource(singleton, resourceClass));   // 固定对象
}

public void addJndiResource(String jndiName) {
    addResourceFactory(new JndiResourceFactory(jndiName));                   // JNDI 查找
}
// Spring 集成：addResourceFactory(new SpringResourceFactory(beanName, beanFactory, scannable))

POJOResourceFactory 的类注释 “Allocates an instance of a class at each invocation” 进一步说明：Factory 的职责是 分配（allocate）实例，不是长期持有实例。

注册期 call chain：Factory 与 Invoker 如何绑定

ResourceMethodRegistry.addResourceFactory() 是 Registry 的核心入口，分两步：⁷

addResourceFactory(ResourceFactory ref, …, Class[] classes)
    ├─ ref.registered(providerFactory)          — 启动期：预建 ConstructorInjector / PropertyInjector
    └─ for each clazz:
         register(ref, base, resourceClass)
             └─ processMethod(rf, base, method)   — 每个 @GET/@POST 方法
                  └─ new ResourceMethodInvoker(method, injectorFactory, rf, providerFactory)
                       — 同一 rf 被所有方法的 Invoker 共享

源码：

// resteasy-core/.../ResourceMethodRegistry.java:200-220
public void addResourceFactory(ResourceFactory ref, ResourceBuilder resourceBuilder, String base, Class[] classes) {
    if (ref != null)
        ref.registered(providerFactory);
    for (Class clazz : classes) {
        ResourceClass resourceClass = resourceBuilder.getRootResourceFromAnnotations(clazz);
        register(ref, base, resourceClass);
    }
}

// :295-310 — 每个 HTTP 方法绑定同一个 ResourceFactory rf
protected void processMethod(ResourceFactory rf, String base, ResourceLocator method) {
    // ...
    ResourceMethodInvoker invoker = new ResourceMethodInvoker((ResourceMethod) method, injectorFactory, rf, providerFactory);
    root.addInvoker(classExpression, fullpath, invoker);
}

要点：

• Registry 的「路由表」存的是 ResourceMethodInvoker（URL → 方法调用器），每个 Invoker 持有 同一个 ResourceFactory 引用（ResourceMethodInvoker 字段 protected ResourceFactory resource）。
• registered() 在 注册期 调用一次，预建注入器；不在此阶段创建 Resource 实例（SingletonResource 除外——实例由调用方在 addSingletonResource(singleton) 时传入，Factory 仅持有引用）。
• 一个 HelloResource 类若有 3 个 @GET 方法 → 1 个 Factory + 3 个 Invoker，Factory 决定 3 个 Invoker 共享的取实例策略。

为何每个端点一个 ResourceMethodInvoker？

需要澄清：不是「每个 Java 方法」一个 Invoker，而是每个 JAX-RS HTTP 端点一个 Invoker——@GET /users 与 @POST /users 在 Registry 路由表里是两个不同叶子节点，ResourceMethodInvoker 就是这个叶子。

1. 路由匹配的目标是一个端点（Resource Method），不是一个类

registry.getResourceInvoker(request) 做的是 URI + HTTP 动词 → 唯一 Invoker，不是「先找到 Resource 类再反射找方法」。JAX-RS 规范（Section 3.7）的匹配粒度就是 Resource Method；Registry 的 URL 树（RootClassNode）在注册期把每个 @Path + @GET/@POST 组合挂到独立 Invoker 上，请求期才能直接命中，而无需每次反射扫描。

2. Invoker 绑定的是「这个方法独有」的运行时上下文

ResourceMethodInvoker 构造函数 在 注册期 为 这一个 端点预建好调用链——这些 metadata 因方法而异，无法多个端点共享：

// resteasy-core/.../ResourceMethodInvoker.java:97-141（节选）
public ResourceMethodInvoker(final ResourceMethod method, final InjectorFactory injector,
        final ResourceFactory resource, final ResteasyProviderFactory providerFactory) {
    this.resource = resource;   // 共享：取实例策略（ResourceFactory）
    this.method = method;       // 独有：这个端点的 metadata

    this.methodInjector = injector.createMethodInjector(method, resourceMethodProviderFactory);

    requestFilters = resourceMethodProviderFactory.getContainerRequestFilterRegistry()
            .postMatch(method.getResourceClass().getClazz(), method.getAnnotatedMethod());
    responseFilters = resourceMethodProviderFactory.getContainerResponseFilterRegistry()
            .postMatch(method.getResourceClass().getClazz(), method.getAnnotatedMethod());
    // … @Produces / 异步 / SSE / Bean Validation 等也按 method 配置
}

3. 共享 Factory，不共享 MethodInjector

运行时 Invoker 的职责拆成两步——取实例与调方法：

// ResourceMethodInvoker.java:348-356 + :555-560
public BuiltResponse invoke(HttpRequest request, HttpResponse response) {
    Object resource = this.resource.createResource(...);  // 共享 ResourceFactory
    return invoke(request, response, resource);
}
private Object internalInvokeOnTarget(..., Object target) {
    return this.methodInjector.invoke(request, response, target);  // 此方法专属
}

• ResourceFactory（一个 Resource 类一个）：回答「怎么拿实例」
• MethodInjector（一个 HTTP 端点一个）：回答「调哪个方法、参数怎么填」

4. 与 Spring 的分工对比

Spring 管到 对象；RESTEasy 还要管 HTTP 路由 + 方法级 JAX-RS 语义，Invoker 粒度自然是端点而非类。

5. 设计收益：注册期预计算，请求期少反射

若在请求期才「找类 → 扫描方法 → 匹配 URI → 解析参数注解」，每次请求都要反射 + 元数据解析。RESTEasy 在 addResourceFactory 时把 Injector、Filter 链、Produces 等 固化进 Invoker；请求路径只做 URL 匹配 + createResource() + methodInjector.invoke()。

请求期 call chain：Invoker 委托 Factory 取实例

SynchronousDispatcher.invoke()
    └─ registry.getResourceInvoker(request)     — URL 匹配，返回 ResourceMethodInvoker
         └─ ResourceMethodInvoker.invoke()
              └─ this.resource.createResource(request, response, factory)  — 委托 Factory 策略
                   ├─ POJOResourceFactory: constructorInjector.construct() + propertyInjector.inject()
                   ├─ SingletonResource:    return obj
                   └─ SpringResourceFactory:  beanFactory.getBean(beanName)
              └─ methodInjector.invoke(request, response, target)  — @QueryParam 等

// resteasy-core/.../ResourceMethodInvoker.java:348-356
public BuiltResponse invoke(HttpRequest request, HttpResponse response) {
    Object resource = this.resource.createResource(request, response, resourceMethodProviderFactory);
    // ...
    return invoke(request, response, resource);
}

RESTEasy 永远通过 ResourceMethodInvoker 调用 createResource() 取实例——无论底层是 per-request new、singleton 固定对象还是 Spring getBean()。这是 RESTEasy 侧 Resource 生命周期的 唯一入口。

设计思想对比：Spring Bean 容器 vs RESTEasy Factory 模式

两者解决不同问题，抽象层级也不同：

Spring 的思路：一切皆 Bean。容器持有 定义（Definition），所有 scope 共用 doCreateBean 流水线；singleton 在 refresh() 批量实例化并缓存，prototype 在每次 getBean() 重新走流水线且不入缓存。AOP/事务/事件都挂在这条流水线上。

RESTEasy 的思路：容器只管 HTTP。Registry 持有 策略（Factory），每次请求问 Factory「给我一个实例」；Factory 可以 new、可以返回已有对象、可以查 JNDI、可以调 Spring getBean()——RESTEasy 不关心 Spring scope，只保证调用链一致（createResource → 注入参数 → 反射调用 → requestFinished）。

用一张图概括两种「登记」：

Spring                          RESTEasy
──────                          ────────
BeanDefinition                  ResourceFactory（策略对象）
  "helloResource"                 SpringResourceFactory(beanName, …)
  scope=singleton|prototype            │
  class=HelloResource                  ├─ registered() → 预建 Injector
       │                               └─ createResource() → getBean() / new
       ▼                                      │
getBean("helloResource")                      ▼
  singleton: 缓存 or prototype: doCreateBean   ResourceMethodInvoker
  （同一 doCreateBean 流水线）                  GET /hello → invoke()
                                           → createResource() → 实例
                                           → MethodInjector → @GET 方法

ResourceFactory 接口把 注册期 与 请求期 拆成五个回调，正是这一策略模式的契约：

// resteasy-core-spi/.../ResourceFactory.java:9-44
public interface ResourceFactory {
    Class<?> getScannableClass();                    // :15
    void registered(ResteasyProviderFactory factory); // :22
    Object createResource(HttpRequest request, HttpResponse response,
            ResteasyProviderFactory factory);         // :32
    void requestFinished(HttpRequest request, HttpResponse response, Object resource); // :41
    void unregistered();                             // :43
}

requestFinished 的接口注释写得很清楚：“usable for things like @PreDestroy if the underlying factory supports it”——Spring 集成里实例销毁归 Spring，RESTEasy 不在此回调里 destroy Bean。⁵

三种内置 ResourceFactory：三种「取实例策略」

以下三种实现 不是 Bean 初始化流程，而是三种不同的 createResource() 策略，由 Registry 注册 API 或集成层（如 SpringBeanProcessor）选择绑定：

1. POJOResourceFactory —— per-request，RESTEasy 自己 new（POJOResourceFactory.java）

// :51-60 registered
public void registered(ResteasyProviderFactory factory) {
    ResourceConstructor constructor = resourceClass.getConstructor();
    // ...
    this.constructorInjector = factory.getInjectorFactory().createConstructor(constructor, factory);
    this.propertyInjector = factory.getInjectorFactory().createPropertyInjector(resourceClass, factory);
}

// :63-77 createResource
public Object createResource(HttpRequest request, HttpResponse response, ResteasyProviderFactory factory) {
    Object obj = constructorInjector.construct(request, response, true);
    CompletionStage<Void> propertyStage = propertyInjector.inject(request, response, obj, true);
    return propertyStage == null ? obj : propertyStage.thenApply(v -> obj);
}

2. SingletonResource —— 固定对象，registered 时注入一次（SingletonResource.java）

addSingletonResource(Object singleton) 要求调用方 先把实例建好 再交给 Registry——RESTEasy 不会在此路径下 new Resource：

// resteasy-core/.../ResourceMethodRegistry.java:95-98
public void addSingletonResource(Object singleton) {
    ResourceClass resourceClass = resourceBuilder.getRootResourceFromAnnotations(singleton.getClass());
    addResourceFactory(new SingletonResource(singleton, resourceClass));
}

SingletonResource 类注释写得很直白：“VERY simple implementation that just returns the instance the SingletonResource was created with”。Factory 用 final 字段 持有 传入的实例引用：

// resteasy-core/.../SingletonResource.java:19-44
public class SingletonResource implements ResourceFactory {
    private final Object obj;
    private final ResourceClass resourceClass;

    public void registered(ResteasyProviderFactory factory) {
        factory.getInjectorFactory().createPropertyInjector(resourceClass, factory).inject(obj, false);
    }

    public Object createResource(HttpRequest request, HttpResponse response, ResteasyProviderFactory factory) {
        return obj;
    }

    public void unregistered() { }
    public void requestFinished(HttpRequest request, HttpResponse response, Object resource) { }
}

• registered()：启动期对 已有 obj 做一次 JAX-RS 字段注入（@Context 等）。
• createResource()：每次请求直接 return obj，不再创建。
• unregistered() / requestFinished()：空实现——RESTEasy 不负责销毁；实例生命周期由 传入实例的调用方 管理。

Singleton 的两种路径：谁维护 instance？

RESTEasy 没有 Spring 那样内建的 scope 框架；「singleton」语义通过 选择不同的 Factory 实现 表达。是否由 RESTEasy 维护 instance，取决于走哪条路径：

纯 RESTEasy singleton：Registry 登记的是 SingletonResource 策略对象，策略对象里 握着 实例引用；RESTEasy 维护的是 引用 + 复用，不是完整的 Bean 生命周期（不 create、不 destroy）。

Spring 集成 singleton：Registry 登记的是 SpringResourceFactory（只存 beanName + beanFactory），不存 instance：

// resteasy-spring/.../SpringResourceFactory.java:35-37
public Object createResource(HttpRequest request, HttpResponse response, ResteasyProviderFactory factory) {
    return beanFactory.getBean(beanName);   // singleton 时命中 Spring 缓存
}

每次 createResource() 向 Spring 要 Bean；RESTEasy 侧每次返回同一对象，是因为 Spring 缓存了 singleton，不是因为 RESTEasy Factory 里有一个 obj 字段。

纯 RESTEasy singleton                    Spring bridge + singleton scope
─────────────────────                    ────────────────────────────────
调用方 new HelloResource()               Spring refresh() → doCreateBean
    │                                        │
    ▼                                        ▼
addSingletonResource(instance)           SpringBeanProcessor 建 SpringResourceFactory
    │                                        │
    ▼                                        ▼
SingletonResource.obj = instance         Registry 登记 Factory（无 instance 字段）
    │                                        │
    ▼                                        ▼
createResource() → return obj            createResource() → getBean() → Spring 缓存

因此，「singleton Resource 是否由 RESTEasy 维护 instance」的准确答案是：纯 SingletonResource 路径下是——RESTEasy Factory 持有引用；Spring 集成路径下否——实例归 Spring 容器，RESTEasy 只维护取实例策略。

3. SpringResourceFactory —— 实例来源外包给 Spring（SpringResourceFactory.java）

RESTEasy 仍只持有一个 Factory 策略对象；createResource() 把取实例委托给 Spring getBean()。singleton / prototype scope 差异见 第四节。

RESTEasy 与 Spring 生命周期对照（Spring 集成，按 scope）

sequenceDiagram
    participant Spring as Spring 容器
    participant RESTEasy as RESTEasy Registry
    participant Resource as @Path Resource

    Note over Spring,Resource: 启动阶段（singleton Resource）
    Spring->>Spring: preInstantiateSingletons → doCreateBean
    Spring->>Spring: ResteasyBeanPostProcessor（JAX-RS 字段注入）
    Spring->>Resource: singleton 实例就绪
    Note over Spring,Resource: prototype Resource：此阶段通常无实例
    Note over Spring,Resource: ContextRefreshedEvent（两种 scope 均注册 Factory）
    Spring->>RESTEasy: addResourceFactory(SpringResourceFactory)
    RESTEasy->>RESTEasy: SpringResourceFactory.registered()

    Note over Spring,Resource: 每次请求
    RESTEasy->>Spring: createResource() → getBean(beanName)
    alt singleton
        Spring-->>RESTEasy: 缓存实例（跳过 doCreateBean）
    else prototype
        Spring->>Spring: doCreateBean 全流程
        Spring-->>RESTEasy: 新实例
    end
    RESTEasy->>Resource: MethodInjector 注入 @QueryParam
    RESTEasy->>Resource: 调用 @GET 方法
    RESTEasy->>RESTEasy: requestFinished()（Spring 路径无操作）

第三节对比了纯 RESTEasy 的三种 ResourceFactory；Spring 集成路径下，桥接逻辑集中在 第四节。

四、resteasy-spring 如何桥接

桥接由两个类分工：SpringBeanProcessor 在 Spring 启动三阶段（BFPP → BPP → ContextRefreshedEvent）扫描 @Path / @Provider、建 SpringResourceFactory 映射并注册 Registry；SpringResourceFactory 在运行期把 RESTEasy 的 createResource() 转译为 getBean()。

SpringBeanProcessor：启动期编排

SpringBeanProcessor 实现 BeanFactoryPostProcessor 与 SmartApplicationListener，在 Spring 启动的三个关键时刻插入逻辑。⁸ 它不会自动出现在 classpath 上——WAR 需 SpringContextLoaderSupport.addBeanFactoryPostProcessor()，Spring MVC 集成 import springmvc-resteasy.xml，Spring Boot 由 ResteasyAutoConfiguration 的 @Bean 注册。⁹

阶段一：Bean 定义期（postProcessBeanFactory :235-261）

// resteasy-spring/.../SpringBeanProcessor.java:235-261
public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) {
    beanFactory.registerResolvableDependency(Registry.class, getRegistry());
    beanFactory.registerResolvableDependency(ResteasyProviderFactory.class, getProviderFactory());
    beanFactory.addBeanPostProcessor(new ResteasyBeanPostProcessor(beanFactory));

    for (String name : beanFactory.getBeanDefinitionNames()) {
        processBean(beanFactory, dependsOnBeans, name, beanDef);
        // @Provider → providerNames (:276-286)
        // 根 @Path → resourceFactories.put(name, new SpringResourceFactory(...)) (:288-289)
    }
    // Resource depends-on 非 MessageBody Reader/Writer 的 @Provider (:256-260)
}

此阶段 只建 SpringResourceFactory 映射，不创建 Bean 实例，也不注册进 Registry。

阶段二：每个 Bean 初始化后（ResteasyBeanPostProcessor.postProcessAfterInitialization :114-146）

类注释写明了 @Path 与 @Provider 的分工（SpringBeanProcessor.java:95-108）。

// resteasy-spring/.../SpringBeanProcessor.java:114-146
public Object postProcessAfterInitialization(Object bean, String beanName) {
    if (providerNames.contains(beanName)) {
        PropertyInjector injector = getInjector(AopUtils.getTargetClass(bean));
        injector.inject(bean, false);
        providerFactory.registerProviderInstance(bean);
    } else {
        SpringResourceFactory resourceFactory = resourceFactories.get(beanName);
        if (resourceFactory != null) {
            inject(beanName, bean, getInjector(resourceFactory.getScannableClass()));
        }
    }
    return bean;
}

阶段三：容器刷新完成（onApplicationEvent :453-467）

// resteasy-spring/.../SpringBeanProcessor.java:453-467
public void onApplicationEvent(ApplicationEvent event) {
    for (SpringResourceFactory resourceFactory : resourceFactories.values()) {
        getRegistry().removeRegistrations(resourceFactory.getScannableClass());
    }
    for (SpringResourceFactory resourceFactory : resourceFactories.values()) {
        getRegistry().addResourceFactory(resourceFactory, resourceFactory.getContext());
    }
}

注释（:446-448）：“Register all of the resources into RESTEasy only when Spring finishes its life-cycle and the spring singleton bean creation is completed.”³——此处强调 singleton 批量创建完毕，以保证 singleton @Path Resource 的 @Autowired 依赖链完整；prototype Resource 的 Factory 映射同样在此时注册进 Registry，只是实例尚未创建。

Registry 侧会回调 ResourceFactory.registered()：

// resteasy-core/.../ResourceMethodRegistry.java:220-222
public void addResourceFactory(ResourceFactory ref, ResourceBuilder resourceBuilder, String base, Class<?>[] classes) {
    if (ref != null)
        ref.registered(providerFactory);
    // ... register(ref, base, resourceClass) 扫描 @Path/@GET 建路由
}

若 Resource 依赖的 CustomerService 尚未创建，过早注册会导致依赖不完整。

sequenceDiagram
    participant Spring as Spring 启动
    participant SBP as SpringBeanProcessor
    participant Registry as RESTEasy Registry

    Note over Spring,Registry: T1 — postProcessBeanFactory
    Spring->>SBP: 扫描 @Path，建 SpringResourceFactory
    Note over Spring,Registry: T2 — 逐 Bean 初始化（主要 singleton）
    loop 每个已实例化的 Bean
        Spring->>SBP: postProcessAfterInitialization
        alt @Provider singleton
            SBP->>Registry: registerProviderInstance
        else @Path singleton
            SBP->>SBP: JAX-RS 字段注入
        else @Path prototype
            Note over SBP: 通常不在此 loop（尚未 getBean）
        end
    end
    Note over Spring,Registry: T3 — ContextRefreshedEvent
    Spring->>SBP: onApplicationEvent
    SBP->>Registry: addResourceFactory + registered()

SpringResourceFactory：从 Startup 映射到 Registry，再到运行期调用

上一小节按 Spring 启动三阶段（T1/T2/T3）编排；本节把 SRF 对象本身 在 RESTEasy runtime 中的位置串成一条线：先进入 SBP 的本地 Map，再进入 Registry，最后被 Invoker 持有并在每次请求调用。

三阶段：SRF 何时「存在」、何时「生效」

T1 扫描逻辑在 processBean()：GetRestful.isRootResource(scannableClass) 为 true 的根 @Path Bean，按 bean 名称 建 SRF，此时既不创建 Resource 实例，也不调用 Registry.addResourceFactory——Registry 里还没有任何与该 Resource 相关的路由。

T2 对 @Path singleton：BPP 用 resourceFactories.get(beanName) 取到 T1 已建好的同一个 SRF，只对 已实例化的 Bean 做 PropertyInjector.inject；prototype Resource 通常尚未 getBean，此 loop 跳过，但 T1 里已为它建好 SRF 映射。

T3 才是 SRF 正式进入 RESTEasy runtime 的时刻：

// resteasy-spring/.../SpringBeanProcessor.java:453-467
for (SpringResourceFactory resourceFactory : resourceFactories.values()) {
    getRegistry().removeRegistrations(resourceFactory.getScannableClass());
}
for (SpringResourceFactory resourceFactory : resourceFactories.values()) {
    getRegistry().addResourceFactory(resourceFactory, resourceFactory.getContext());
}

addResourceFactory 内部链式发生三件事（见第三节 ResourceMethodRegistry.addResourceFactory）：

1. srf.registered(providerFactory) — 为 SRF 关联的类创建 PropertyInjector 等（Spring 路径下主要注入已在 T2 BPP 完成）。
2. register(ref, base, resourceClass) — 扫描 @Path / @GET / @POST，在 URL 树（RootClassNode）上挂叶子。
3. processMethod(...) — 每个 HTTP 端点 生成一个 ResourceMethodInvoker，其 protected ResourceFactory resource 字段 指向同一个 SRF 引用。

因此：Registry 存的不是 HelloResource 实例，而是 SRF 策略 + 若干 Invoker；singleton 与 prototype 在 T3 注册方式相同，差异只在运行期 getBean() 是否命中缓存。

运行期：Invoker → SRF → Spring

HTTP 请求进入后，SRF 的唯一调用入口是 Invoker：

SynchronousDispatcher.invoke()
  → registry.getResourceInvoker(request)     // URI + HTTP 动词 → ResourceMethodInvoker
  → ResourceMethodInvoker.invoke()
       → resource.createResource(...)      // resource 即 SRF
            → beanFactory.getBean(beanName)
       → methodInjector.invoke(...)        // @QueryParam 等
  → resource.requestFinished(...)           // Spring 路径：空实现

SpringResourceFactory.createResource() 不含 scope 分支；singleton 返 Spring 一级缓存，prototype 每次重走 doCreateBean。RESTEasy 侧 始终 认为自己在调 ResourceFactory.createResource()，实例语义完全外包给 Spring。

WAR 与 Boot：Registry 从哪来，SRF 注册时机不变

SRF 的 T1→T3 流程在两种部署下 相同；差别在 Registry / ProviderFactory 何时挂到 ResteasyDeployment 上：

Boot 下可能出现：ContextRefreshedEvent 时 SRF 已进 SBP 持有的 Registry，但 deployment 合并稍晚——合并的是 同一个 Registry 对象引用，故路由不会重复注册。运行期 Dispatcher 使用的仍是合并后的 deployment，Invoker → SRF → getBean() 链路与 WAR 一致。

Startup（两种部署 SRF 路径相同）
────────────────────────────────
T1  SBP.resourceFactories[beanName] = new SpringResourceFactory(...)
T2  BPP：singleton 字段 @Context；prototype 通常跳过
T3  Registry.addResourceFactory(SRF) → registered() + Invoker(srf)

Runtime（两种部署相同）
──────────────────────
HTTP → Invoker.invoke() → SRF.createResource() → getBean(beanName)

SpringResourceFactory：运行期取实例

SpringResourceFactory 实现 ResourceFactory，使 RESTEasy 在 Registry 中登记「向 Spring 要实例」的策略，而不是自己 new。

// resteasy-spring/.../SpringResourceFactory.java:25-29
public SpringResourceFactory(final String beanName, final BeanFactory beanFactory, final Class<?> scannable) {
    this.beanName = beanName;
    this.beanFactory = beanFactory;
    this.scannableClass = scannable;
}

• beanName + beanFactory：运行时 getBean()
• scannableClass：RESTEasy 扫描 @Path / @GET 建路由用（可能与 AOP 代理类不同，故单独保存）

RESTEasy 认为自己在「每次请求创建 Resource」，实际上是在「每次请求从 Spring 取 Bean」——实例的创建、DI、AOP、销毁都由 Spring 决定。

分工要点：

• createResource() 只向 Spring 要 Bean，不做 JAX-RS 字段注入（那是 ResteasyBeanPostProcessor 在 Spring BPP 阶段或 prototype 的 getBean 链路上完成的）。
• registered() 仍会创建 PropertyInjector，但 Spring 路径下主要注入逻辑在 Spring 启动的 BPP 里。
• requestFinished() 空实现——prototype Resource 的销毁靠 Spring scope，不靠 RESTEasy 回调。

Singleton vs Prototype：bridge 模式下 scope 如何改变行为

桥接机制本身不变——无论 singleton 还是 prototype，Registry 里登记的仍是同一个 SpringResourceFactory，每次请求仍走 createResource() → getBean(beanName)。区别在 Spring scope 改变了 getBean() 的返回值与创建路径，进而影响 JAX-RS 字段注入时机、AOP 代理和销毁语义。

createResource 与 getBean：入口相同，分支不同

SpringResourceFactory.createResource() 对两种 scope 不做区分，统一委托 Spring：

// resteasy-spring/.../SpringResourceFactory.java:35-37
public Object createResource(HttpRequest request, HttpResponse response, ResteasyProviderFactory factory) {
    return beanFactory.getBean(beanName);
}

AbstractBeanFactory.doGetBean() 在这里分叉：

// spring-beans/.../AbstractBeanFactory.java:257-268 — singleton 命中一级缓存
Object sharedInstance = getSingleton(beanName);
if (sharedInstance != null && args == null) {
    beanInstance = getObjectForBeanInstance(sharedInstance, requiredType, name, beanName, null);
}

// :359-364 — prototype 每次走完整 createBean → doCreateBean
else if (mbd.isPrototype()) {
    prototypeInstance = createBean(beanName, mbd, args);
    beanInstance = getObjectForBeanInstance(prototypeInstance, requiredType, name, beanName, null);
}

• singleton：直接返回 refresh() 期间 preInstantiateSingletons() 已创建并缓存的实例（可能被 AOP 包装）。
• prototype：每次请求重新走 createBeanInstance → populateBean（@Autowired）→ initializeBean（BPP、@PostConstruct）全流程。

启动期：prototype Resource 通常不在 refresh 时创建

DefaultListableBeanFactory.preInstantiateSingletons() 只 eagerly 初始化 singleton。prototype @Path Resource 在 refresh() 阶段 不会被创建，因此也不会在启动期经过 ResteasyBeanPostProcessor.postProcessAfterInitialization()。

SpringBeanProcessor 在 BFPP 阶段仍会为 prototype Resource 建立 SpringResourceFactory 映射并在 ContextRefreshedEvent 注册进 Registry——路由注册与 scope 无关；但 Bean 实例与 JAX-RS 字段注入推迟到第一次 HTTP 请求、createResource() 首次触发 getBean() 时才发生。

inject() 分支：JAX-RS 字段注入时机的核心开关

ResteasyBeanPostProcessor.inject() 根据 当前线程是否有 HttpRequest 以及 bean 是否为 singleton 决定注入方式：

// resteasy-spring/.../SpringBeanProcessor.java:152-163
public void inject(String beanName, Object bean, PropertyInjector propertyInjector) {
    if (propertyInjector == null) {
        return;
    }
    HttpRequest request = ResteasyContext.getContextData(HttpRequest.class);
    if (request == null || isSingleton(beanName)) {
        propertyInjector.inject(bean, false);
    } else {
        HttpResponse response = ResteasyContext.getContextData(HttpResponse.class);
        propertyInjector.inject(request, response, bean, false);
    }
}

singleton 路径：字段 @Context UriInfo 等在启动期注入一次（此时 HttpRequest == null），之后所有请求复用同一对象——UriInfo 等可能 不是当前请求的值，这是集成里最容易踩坑的点。

prototype 路径：getBean() 发生在 RESTEasy 请求线程内，ResteasyContext 已绑定当前 HttpRequest，字段 @Context 按 当前请求 注入——行为更符合 JAX-RS per-request 语义，代价是每请求完整 Bean 创建。

方法参数上的 @QueryParam / @PathParam 不受此分支影响，始终由 RESTEasy MethodInjector 在方法调用前注入（见第五节）。

singleton vs prototype 完整对照

销毁：bridge 模式下 prototype 的盲区

SpringResourceFactory.requestFinished() 在 Spring 集成路径下 空实现：

// resteasy-spring/.../SpringResourceFactory.java:48-50
public void requestFinished(HttpRequest request, HttpResponse response, Object resource) {
}

对比纯 RESTEasy POJOResourceFactory——每请求 new 实例，RESTEasy 可在 requestFinished() 触发 @PreDestroy 语义；Spring bridge 路径下：

• RESTEasy 不在请求结束时 destroy 实例；
• Spring 对 prototype Bean 默认也不在 getBean() 返回后调 @PreDestroy（调用方负责生命周期）。

若 prototype Resource 持有连接、文件句柄等需释放的资源，不能指望框架自动清理——应在业务方法内显式释放，或避免对 Resource 使用 prototype scope。

与 POJOResourceFactory 对比

sequenceDiagram
    participant HTTP as HTTP 请求
    participant Invoker as ResourceMethodInvoker
    participant SRF as SpringResourceFactory
    participant Spring as BeanFactory
    participant BPP as ResteasyBeanPostProcessor

    Note over HTTP,BPP: prototype Resource — 首次及后续每次请求
    HTTP->>Invoker: invoke()
    Invoker->>SRF: createResource()
    SRF->>Spring: getBean(beanName)
    Spring->>Spring: createBean → doCreateBean
    Spring->>BPP: postProcessAfterInitialization
    BPP->>BPP: inject(request, response, bean) — 字段 @Context
    Spring-->>SRF: 新 prototype 实例
    SRF-->>Invoker: resource
    Invoker->>Invoker: MethodInjector — @QueryParam
    Invoker->>Invoker: 调用 @GET
    Note over SRF: requestFinished() 空实现，无 destroy

启动期桥接就绪后，下面看 运行期 单次请求的完整 call chain。

五、运行期：RESTEasy 主控，Spring 供实例

运行期 Call Chain（单次 HTTP 请求）

SynchronousDispatcher / AsynchronousDispatcher
  → ResourceMethodInvoker.invoke(request, response)           :348-356
      → ResourceFactory.createResource(...)                     SpringResourceFactory :35-37
          → BeanFactory.getBean(beanName)                       AbstractBeanFactory :197-198
              → doGetBean(name, ...)                          :249-396
                  ├─ singleton: getSingleton() 命中缓存        :257-268
                  └─ prototype: createBean() → doCreateBean() :359-364 → :556-603
      → ResourceMethodInvoker.invoke(request, response, target) :370-378
          → invokeOnTarget()                                    :403-417
              → internalInvokeOnTarget()                        :555-560
                  → MethodInjector.invoke(request, response, target)  :560

ResourceMethodInvoker：每次请求先 createResource

// resteasy-core/.../ResourceMethodInvoker.java:348-356
public BuiltResponse invoke(HttpRequest request, HttpResponse response) {
    Object resource = this.resource.createResource(request, response, resourceMethodProviderFactory);
    // ...
    return invoke(request, response, resource);
}

// :555-560 — JAX-RS 方法参数注入 + 反射调用
private Object internalInvokeOnTarget(HttpRequest request, HttpResponse response, Object target) {
    Object methodResponse = this.methodInjector.invoke(request, response, target);
    // ...
}

getBean 分支（singleton vs prototype）

与第二节相同，doGetBean() 在运行期按 scope 分叉——singleton 命中缓存则不再进入 doCreateBean，prototype 每次进入：

// spring-beans/.../AbstractBeanFactory.java:257-268 — singleton 命中缓存
Object sharedInstance = getSingleton(beanName);
if (sharedInstance != null && args == null) {
    beanInstance = getObjectForBeanInstance(sharedInstance, requiredType, name, beanName, null);
}

// :359-364 — prototype 每次 createBean
else if (mbd.isPrototype()) {
    prototypeInstance = createBean(beanName, mbd, args);  // → doCreateBean
}

运行期注入分工

RESTEasy 不重新做 Spring DI；Spring 不解析 JAX-RS 方法参数。

Spring 能力在运行时是否保留

Resource / Service 仍是 Spring Bean（可能是 CGLIB/JDK 代理）：

sequenceDiagram
    participant HTTP as HTTP 请求
    participant Invoker as ResourceMethodInvoker
    participant SRF as SpringResourceFactory
    participant Spring as BeanFactory
    participant Resource as @Path Bean

    HTTP->>Invoker: invoke()
    Invoker->>SRF: createResource()
    SRF->>Spring: getBean(beanName)
    alt singleton
        Spring-->>SRF: 缓存实例
    else prototype
        Spring->>Spring: doCreateBean 全流程
        Spring-->>SRF: 新实例
    end
    SRF-->>Invoker: resource
    Invoker->>Resource: 注入 @QueryParam，调用 @GET
    Resource->>Spring: 调用 @Autowired Service（可能 @Transactional）

运行期桥接逻辑在 WAR 与 Boot 下相同；差异在 启动编排——第六节对比两种部署方式。

六、传统 Spring 与 Spring Boot：启动差异与 resteasy-spring-boot

运行期桥接逻辑不变——仍是 SpringResourceFactory.createResource() → getBean()。resteasy-spring-boot 解决的是 嵌入式 Tomcat 没有 ServletContainerInitializer 时，如何把 RESTEasy deployment 与 Spring 容器按正确时序拼起来。⁹

传统 WAR / Spring MVC 启动时序

WAR 部署下，RESTEasy 常通过 ServletContainerInitializer 先于 Spring 完成 deployment 初始化：

ServletContainerInitializer（RESTEasy）
    └─ ResteasyDeployment 创建
         └─ new SpringBeanProcessor(deployment)  :177-179
              └─ ContextLoaderListener 启动 WebApplicationContext
                   └─ refresh()
                        ├─ BFPP / BPP（同第四节）
                        └─ ContextRefreshedEvent → Registry.addResourceFactory

此时 SpringBeanProcessor 构造函数接收 已存在的 ResteasyDeployment，Registry 与 ProviderFactory 来自 servlet 层；Spring 的 refresh() 只负责 Bean 创建与 Resource 注册，不再创建 deployment。

Spring Boot 嵌入式 Tomcat 启动时序

Boot 路径下 Spring 容器先起，Servlet 后注册：

SpringApplication.run()
    └─ ResteasyAutoConfiguration @Bean SpringBeanProcessor()  :85-88
    └─ refresh()
         ├─ BFPP / BPP（同第四节）
         └─ ContextRefreshedEvent → Registry.addResourceFactory
    └─ Tomcat 启动
         └─ ResteasyBeanProcessorTomcat：扫描 @ApplicationPath  :36-44
         └─ ServletRegistrationBean 注册 HttpServletDispatcher
         └─ resteasyBootstrapListener()  :50-56
              └─ DeploymentCustomizer.customizeRestEasyDeployment()  :29-47
                   └─ 把 SpringBeanProcessor 的 Registry/ProviderFactory 写回 ResteasyDeployment
                   └─ deployment.start()

Boot 先建 空的 SpringBeanProcessor，Servlet 启动后 DeploymentCustomizer 再把 Registry / ProviderFactory 合并进 ResteasyDeployment。Resource 等到 ContextRefreshedEvent 才进 Registry——这一点 WAR 与 Boot 一致。

resteasy-spring-boot 额外组件

七、总结：两个生命周期的分界

启动期

Spring refresh()
├── BFPP: SpringBeanProcessor 扫描 @Path → SpringResourceFactory（singleton / prototype 均建映射）
├── preInstantiateSingletons → doCreateBean（仅 singleton）
│     ResteasyBeanPostProcessor: @Provider 注册；singleton @Path 做 JAX-RS 字段注入
│     prototype @Path：通常不在此阶段实例化
└── finishRefresh → ContextRefreshedEvent
      → Registry.addResourceFactory → registered()（scope 无关，均注册路由）

Spring 管： 实例创建（doCreateBean，scope 决定时机）、@Autowired、AOP、@PostConstruct / @PreDestroy（prototype 无自动 destroy）。
RESTEasy 管： 路由元数据、@Provider 链、JAX-RS 字段 / 方法参数注入策略。

运行期

RESTEasy 管： URI 匹配、createResource()、Filter/Interceptor 链、方法调用。
Spring 管： getBean() — singleton 返缓存，prototype 再走 doCreateBean；业务依赖、事务与 AOP 随实例而来。

一句话

Spring：所有 scope 共用 doCreateBean 流水线；singleton 启动期入缓存，prototype 每次 getBean 重走
RESTEasy：Registry 登记 ResourceFactory 策略 + 每端点 ResourceMethodInvoker
SpringResourceFactory：createResource() → getBean()，scope 由 Spring 定义

References

对照源码仓库：

经过一年多的日常实践，AI 辅助编程在我的工作流中从”辅助工具”演变成了”核心协作伙伴”。这个过程沉淀出了一些认知——它们不追求新奇，只追求准确。这篇文章记录的是截至 2026 年中，我个人认知框架中的六个核心洞见。

引言：认知的演化路径

过去一年半，我在 AI 辅助编程中的角色经历了三次转变：

1. 工具使用阶段：把 AI 当成更聪明的搜索引擎和代码补全¹
2. 流程重构阶段：围绕 AI 重新设计自己的工作流，从”写代码”转向”引导 AI 写代码”²
3. 范式反思阶段：开始区分不同场景下 AI 的最佳使用模式，意识到”单人”和”多人”模式下 AI 的角色截然不同

这篇文章属于第三阶段的产物。它不是操作指南，而是一个仍在演进中的认知框架——关于 LLM 能力边界、协作模式选择，以及技术和人的关系。

洞见一：LLM 能力是地基，但上下文窗口同样关键

模型本身的能力决定了理解和生成的天花板——这是一个常识，但在实践中容易被低估。不同模型在同一任务上的表现差距是系统性的，prompt 工程能优化但无法跨越这个差距。

但真正影响日常工程体验的，还有另一个因素：稳定且足够长的上下文窗口。

一个在单项得分上略低但能稳定处理 200K token 上下文的模型，在跨项目重构场景中的实际体验，往往优于一个单项得分更高但上下文窗口受限的模型。原因在于：多项目重构的决策不是孤立的——修改包 A 的接口时，需要同时理解它在包 B、C、D 中的调用模式。只有能一次性消化这些关联代码，才能做出不”短视”的方案。

这涉及到 LLM 的一项基础能力——长上下文中的”注意力持久性”。相关研究表明，模型在长上下文中的信息检索和推理能力会随位置衰减³。稳定的大上下文窗口意味着这种衰减被控制在了可接受的范围内，使得跨文件的语义理解成为可能。

所以更准确的表述是：模型能力决定上限，上下文窗口决定这个上限在真实工程中能被兑现多少。

洞见二：Plan 的核心价值是理清人的思路

在 AI 辅助编程的讨论中，”Plan”经常被理解成”让 AI 按步骤执行”的手段。但我逐渐发现，Plan 的最大受益者不是 AI，而是人自己。

原因有两点：

第一，Plan 是外挂工作记忆。 复杂任务涉及大量上下文——文件依赖关系、接口契约、状态迁移路径。把这些结构化成 Plan 写在 prompt 里，相当于给思考过程加了一个”外挂存储区”。这与人脑的工作记忆限制有关——我们同时能追踪的信息量是有限的⁴，Plan 把这个限制放大了。

第二，Plan 是人和 AI 之间唯一的可追溯沟通证据。 在长对话中，AI 的行为可能因为上下文压缩、模型更新等因素产生漂移。一份结构化的 Plan 是判断”AI 是否偏离了原定方向”的锚点。当 AI 生成的代码和预期不符时，不是凭感觉重来，而是对照 Plan 指出”你在第 3 步偏离了方向”。这让调试协作过程变得可操作。

这个概念和 Chain-of-Thought Prompting⁵ 有相似之处——显式的推理步骤能显著降低模型在长上下文中的错误率。但 Plan 在工程中的意义不止于此：它从”推理工具”变成了 “通信协议” ，让人和 AI 共享一个可参照的路线图。

洞见三：Monorepo 让 AI 跨项目整体提交成为可能

这是实践中沉淀出的一个很具体的观察：单仓库（Monorepo）结构天然适合 AI 主导的跨项目修改。

Google 在 2016 年发表的论文中详细阐述了 Monorepo 的优势——统一的依赖管理、原子化的跨项目变更、简化的分支策略⁶。这些优势在传统开发中体现为”减少沟通成本”，在 AI 辅助开发中则体现为“让 AI 能看见全局”。

举个例子：当你修改一个共享库的接口时，在 Monorepo 中，AI 可以同时看到：

• 这个接口的定义（共享库中的源码）
• 所有调用方的使用模式（同一仓库中的其他项目）
• 对应的测试代码如何 mock 这个接口

然后 AI 可以一次性完成：修改接口定义 → 更新所有调用方 → 调整测试用例 → 验证编译通过。这个完整的原子提交在 Monorepo 中是一个自然的操作，在多仓库（Polyrepo）中则需要跨仓库协调，AI 目前难以胜任。

sequenceDiagram
    participant Human as 开发者
    participant AI as AI Agent
    participant Repo as Monorepo

    Human->>AI: 重构共享库接口
    AI->>Repo: 读取接口定义（包 A）
    AI->>Repo: 扫描所有调用方（包 B、C、D）
    AI->>Repo: 读取对应测试代码
    AI->>AI: 制定修改方案
    AI->>Repo: 修改接口定义
    AI->>Repo: 更新包 B 调用
    AI->>Repo: 更新包 C 调用
    AI->>Repo: 更新包 D 调用
    AI->>Repo: 调整测试用例
    AI->>Repo: 编译验证
    AI-->>Human: 提交完整变更

这个模式在多仓库环境下很难复制——AI 需要同时打开多个仓库、理解它们的依赖关系、协调跨仓库的提交顺序，目前的主流工具链对此支持有限。

洞见四：TAO 模式的关键在于可验证的闭环

“TAO”指的是 Thought（推理）→ Action（执行）→ Observation（反馈观察） 的结构化提示范式。它直接源于 ReAct（Reasoning + Acting）模式⁷——让 AI 不是一次性输出最终结果，而是在”推理 → 行动 → 观察结果”的循环中逐步逼近目标。其中 Thought（推理步骤）是 ReAct 论文中的标准术语，在工程实践中常具体化为 Task Decomposition（任务分解），但其概念源头是 Thought。

但在工程实践中，TAO 的关键不在于 T 和 A，而在于 O——Observation（观察）。

graph LR
    T["Thought<br/>推理"] --> A["Action<br/>执行"]
    A --> O["Observation<br/>观察反馈"]
    O -->|"未达到预期"| T
    O -->|"达到预期"| D["Done<br/>完成"]

    style T fill:#87CEEB
    style A fill:#90EE90
    style O fill:#FFD700
    style D fill:#90EE90

为什么 O 是最关键的？因为没有 Observation 的闭环，TAO 就退化成了”让 AI 一步一步做”的简单链式调用，和普通的 prompt 没有本质区别。TAO 的真正价值在于让 AI 每一步的产出都被检验——检验结果反馈到下一步的推理中，形成一个可验证的闭环。

这和软件工程中的闭环反馈原则是一致的：每次修改都应该有对应的验证手段（测试、lint、类型检查），验证结果决定下一步方向。TAO 只是把这个原则应用到了和 AI 的协作过程中。

在单人高效模式下，这个闭环可以非常紧凑：AI 执行 → 人肉眼验证 → 反馈修正 → AI 再执行。但在多人场景下，这个闭环需要被编码为更正式的流程——代码评审、CI 门禁、契约检查——每一个都是 Observation 环节的工程化实现。

Observation 环节的数据基础设施

要让 Observation 真正可操作，需要建设一套覆盖 AI 全链路的数据基础设施。仅仅依赖”看 AI 的输出”是不够的——因为很多错误的根因不在最终输出，而在中间某个环节的状态。具体来说，需要关注以下数据源：

• 日志数据：AI 的每次输入输出、每次工具调用、每次决策路径都需要可追溯的结构化日志。这是最基础的观测手段——没有日志，无法定位 AI 行为异常的原因。这在之前的文章中曾作为”埋点驱动迭代”的核心组件展开过⁸。
• 数据库状态：AI 执行的变更会体现在数据库状态中。当 AI 操作涉及数据迁移、批处理任务或状态变更时，能查询和对比执行前后的数据库状态是定位问题的关键手段。
• 1:1 可复刻的测试环境：AI 行为与运行环境强相关——同一个 prompt 在不同依赖版本、不同数据分布下的输出可能不同。拥有一个可随时重建、与生产环境配置一致的测试环境，是隔离 AI 行为变量的前提。否则你无法判断”这次输出不对”是因为 prompt 有问题，还是因为环境中的数据状态与上次不同。
• 页面层的多模态可观测性：当 AI 的操作涉及用户界面时（无论是生成前端代码、模拟用户操作、还是验证 UI 行为），传统日志无法覆盖”视觉语义”层面的信息。需要组合使用 Playwright 等工具采集 UI 截图、通过 OCR 提取界面文本内容、再借助多模态大模型理解页面状态。这一层观测正在成为 AI 协作中不可或缺的一环——它能捕捉到”按钮没渲染出来”、”布局错位”等日志完全无法反映的问题。

从 TAO 到 Harness Engineering

当 Observation 环节从”人眼看一下”升级为上述这套数据基础设施时，TAO 模式就超越了 prompt 技巧的范畴，进入了工程化的层面。我把建设这套基础设施的实践称为 Harness Engineering——它关注的不是”怎么写 prompt”，而是”如何构建支撑 AI 稳定运行的工程体系”。

这套体系的关键组件包括：

• 可观测性管道：采集 AI 全链路的日志、状态、产出，形成可检索、可回溯的观测数据湖
• 可复现环境：保证 AI 的每次执行都在一致的上下文和数据状态下进行，行为偏差可归因
• 门禁系统：在 AI 的每个产出节点设置自动检查（类型校验、契约验证、测试覆盖）
• 回滚与补偿机制：当 AI 行为不符合预期时，能快速回滚并补偿受影响的下游

Harness Engineering 的核心思想是：不要依赖 AI 的可靠性，而要通过工程手段把 AI 的不可靠性控制在可接受的范围内。 这和传统软件工程中防御式编程的逻辑相通——你不能假设输入永远合法，所以用类型系统、契约测试、降级策略来兜底。Harness Engineering 就是对 AI 的”防御式工程”。

这套思路也与之前文章中讨论的”LLM 工程化的自举迭代框架”⁹一脉相承——两者都强调用系统能力而非人工干预来管理 AI 行为的不确定性。

洞见五：AI 拉平了技术壁垒，但拉不平决策与责任

AI 确实在拉平一些长期以来区分小团队和大团队的壁垒：

1. 知识壁垒被拉平了——以前大团队才养得起专门研究 Monorepo、形式化验证、性能分析等领域的专家，现在小团队一个人 + AI 就能达到相当的高度
2. 执行力差距被拉平了——大团队靠人多并行推进，但 AI 可以让小团队的单人具备”伪并行”能力（一个上午同时在多个方向上推进）
3. 规范落地难度被拉平了——大团队靠制度强制统一风格，小团队靠 AI 自动遵循规范，甚至比人更一致

但”拉平”不等于”消失”。拉平的是技术实现层面的壁垒，拉不平的是三个更本质的东西：

技术壁垒的降低，反而让剩余竞争点——人的判断力——变得更加重要。 AI 可以写代码，但”这个接口要不要这样设计”、”这个依赖该不该升级”、”这个功能现在做还是以后做”——这些决策依赖的是人对业务逻辑、系统边界和长期成本的理解，不是 prompt 技巧。

这个观察和 Frederick Brooks 在《人月神话》中的观点有跨越时空的呼应：软件工程的本质困难不是”写代码”，而是”理解要写什么”¹⁰。AI 降低了”写”的成本，但”理解”的成本仍然由人承担。

与此相关但容易被忽视的另一面是：具体落地的技术细节和实现仍然需要人去把控。 AI 擅长生成”看起来正确”的代码，但边界条件、错误处理、并发安全、性能敏感路径——这些需要结合具体运行环境做判断的细节，往往是 AI 输出中最薄弱也最隐蔽的地方。一个模式正确的实现，可能因为遗漏了某个 NULL 检查、搞错了锁的粒度、或忽略了跨平台的文件路径差异，在生产环境中引发严重问题。这些细节不会在架构图和接口定义中体现，但恰恰是决定系统能否稳定运行的关键。人在这里的角色不是”写”这些细节，而是知道哪些细节需要被关注、在什么场景下需要特殊处理——这仍然是经验驱动的判断力，不属于 AI 能可靠替代的范畴。

前端与用户界面是上述判断压力最集中的地带之一。 后端背景的开发者借助 AI 调整 UI 时，常出现一种反差：接口或业务逻辑的小幅改动往往几轮对话即可收敛，而一旦涉及布局、间距、响应式或视觉细节，同样的协作方式却可能消耗整天仍达不到预期——不是因为 prompt 不够精确，而是因为「看起来对不对」缺乏像编译错误那样可机器判定的反馈信号。个人项目里，界面与参考稿达到约七成视觉相似往往已是可接受的上限；前端人力被压缩的团队则更常明确退化为「AI 产出什么样就用什么样，能用即可」。这不是对质量的放弃，而是在 Observation 无法工程化闭环的前提下，对 UI craft 这道仍未被拉平的壁垒所做的理性妥协——也解释了洞见四中「页面层多模态可观测性」为何不是锦上添花，而是 UI 场景下 TAO 闭环能否成立的前置条件。

洞见六：AI 作为执行者与辅助者的模式切换

这是所有认知中最根本的一个二分法。经过反复实践，我意识到 AI 和人协作存在两种截然不同的模式，它们对流程、信任和团队结构的要求完全不同：

这两种模式对技术能力、流程、信任机制的要求不仅不同，甚至互斥——在执行者模式下建立的自动化流程，在辅助者模式下会变成噪音和负担。

团队规模的约束不是偶然的。Robin Dunbar 在 1992 年的研究中提出了一个认知上限：人类的社交网络规模受限于新皮层容量，稳定协作的群体层级从核心信任圈（约 5 人）到氏族（约 50 人）再到熟人网络（约 150 人）¹¹。软件团队中的”认知开销”同样存在规模效应——当团队超过 5-8 人，成员之间需要同步的协作协议、依赖关系和变更影响信息量就会超出个人能有效追踪的范围。

graph TD
    subgraph "执行者模式（≤5人）"
        A1["人定方向"] --> A2["AI 自主执行"]
        A2 --> A3["人审查结果"]
        A3 --> A1
    end

    subgraph "辅助者模式（大团队）"
        B1["人定方向"] --> B2["人写需求/设计"]
        B2 --> B3["AI 局部辅助"]
        B3 --> B4["人工评审/集成"]
        B4 --> B1
    end

    style A1 fill:#90EE90
    style A2 fill:#87CEEB
    style A3 fill:#FFD700
    style B1 fill:#90EE90
    style B2 fill:#FFD700
    style B3 fill:#87CEEB
    style B4 fill:#FFD700

这两种模式之间的切换成本，是很多关于 AI 生产力的讨论中被忽略的因素。单人场景下的高效模式（AI 接管、整体提交）一旦进入多人场景，就必须切换回更传统的辅助模式，而之前建立的那套自动化流程并不能平滑迁移。

没有银弹：认知闭环的终点

Fred Brooks 在 1986 年的经典文章《No Silver Bullet》中提出，软件工程中没有能够”在一个数量级上提升生产率”的单一技术突破¹²。这个判断在近四十年后被重新审视——LLM 带来的变化可能确实超出了 Brooks 当年的预测框架。但 Brooks 的另一句话在今天依然成立：软件的本质困难在于”概念结构”的复杂性，而不是”实现”的复杂性。

AI 解决了实现层面的复杂性，但概念结构的复杂性——需要做什么、为什么这么做、什么时候不做——仍然需要人的判断。

这六个洞见最终指向同一个结论：AI 不会消除软件工程的困难，它只是把这些困难重新分配到不同的位置。 知识壁垒被拉平了，决策质量的门槛变高了；写代码变快了，但搞清楚”该写什么”变得更关键了。人和 AI 之间没有最优的协作模式，只有最适合当前场景的协作模式。

没有银弹，但有清晰的认知框架——这就够了。

References

在前面的 tokio 系列文章中，我们提到了 Linux 内核的 hrtimer 能为 epoll_wait(timeout) 提供纳秒精度的定时中断。这个说法引出了一个追问：内核里的 hrtimer 如何实现纳秒级别的精度？

引言

“纳秒精度”这个表述很容易被误解。说 hrtimer 精度纳秒，到底是什么意思？

一个 nanosleep(&ts) 系统调用，传入的 timespec 确实是以纳秒为单位的。但内核真的能保证在恰好那个纳秒点唤醒你的进程吗？

答案是否定的。但”纳秒精度”也不是一个营销话术——它是内核在数据结构、时钟硬件和中断机制三层协作下，确实能达到的能力。理解这个协作过程，就能同时理解精度的来源和它的边界。

概念先行：精度来自三层协作

hrtimer 的纳秒精度是三层协作的结果：

1. 数据结构层：hrtimer 的到期时间用 ktime_t（纳秒）表示，用红黑树（Red-Black Tree）按到期时间排序——这是”纳秒”作为数据精度的入口
2. 时钟源层：CPU 内部的 TSC（Time Stamp Counter）在每个 cycle 递增——现代 CPU 上相邻两次递增的时间间隔在 0.3-0.5ns 之间，这是”纳秒”在硬件上能被读取到的来源
3. 中断触发层：LAPIC 的 TSC Deadline 模式允许内核写入一个绝对 TSC 值，硬件在该 TSC 值到达时直接触发中断——这是”纳秒”的硬实时出口

把这三层串起来，就是 hrtimer 从用户注册到期时间到实际触发中断的完整链路：

用户态: clock_nanosleep(&ts)  // ts = 100ns
    ↓ 系统调用
内核态: ktime_t expires = timespec_to_ktime(ts)  // 纳秒存为 ktime_t
    ↓ 插入红黑树
       hrtimer 红黑树按 expires 排序
    ↓ 如果是当前最早到期
       hrtimer_reprogram() → tick_program_event(expires)
    ↓ 转到时钟事件设备
       clockevents_program_event(dev, expires, force)
    ↓ TSC Deadline 模式
       lapic_next_deadline():
         tsc = rdtsc()
         native_wrmsrq(MSR_IA32_TSC_DEADLINE, tsc + delta)
    ↓ 硬件层
       LAPIC 监视 TSC 寄存器，到达指定值时触发中断

从这条链路可以看到，”纳秒精度”是数据结构精度（ktime_t）、硬件读时精度（TSC）、和中断编程精度（TSC Deadline）三者叠加的结果。下面逐层展开。

一、数据结构层：hrtimer 的红黑树

1.1 ktime_t：纳秒级的时间表示

hrtimer 的核心数据结构没有使用内核传统的 jiffies（基于定时器中断周期，通常是 1ms/4ms），而是使用 ktime_t——一个专门设计的高精度时间类型¹：

// include/linux/ktime.h
typedef s64 ktime_t;

ktime_t 就是一个 64 位有符号整数，单位是纳秒。取值范围从 -292 年 到 +292 年。所有 hrtimer 的到期时间、剩余时间、间隔值都以此为单位。

这也直接体现在 hrtimer 源码顶部的宏定义上²：

// kernel/time/hrtimer.c: 61-62
// HIGH_RES_NSEC = 1 表示 hrtimer 在高精度模式下分辨率为 1ns
#define HIGH_RES_NSEC		1

对比传统 timer_list（基于 jiffies 的时间轮），hrtimer 的优势在于”到期时间”和”现在时间”的比较不需要经过 jiffies 这个中间层：

1.2 红黑树：按到期时间排序

每个 CPU 有 8 个 hrtimer_clock_base，分别对应不同的时钟源（CLOCK_MONOTONIC、CLOCK_REALTIME、CLOCK_BOOTTIME 等，每个时钟分 hard 和 soft 两种模式）。每个 base 内部用一棵红黑树管理所有活跃的 hrtimer³：

// include/linux/hrtimer_defs.h: 28-43
struct hrtimer_clock_base {
    struct hrtimer_cpu_base    *cpu_base;
    const unsigned int         index;
    const clockid_t            clockid;
    seqcount_raw_spinlock_t    seq;
    ktime_t                    expires_next;   // 此 base 最早到期时间
    struct hrtimer             *running;       // 正在执行回调的 timer
    struct timerqueue_linked_head  active;     // 红黑树根节点
    ktime_t                    offset;         // 相对于 MONOTONIC 的偏移
};

每个 CPU 的 8 个 clock base 打包在 hrtimer_cpu_base 中³：

// include/linux/hrtimer_defs.h: 82-108
struct hrtimer_cpu_base {
    raw_spinlock_t              lock;
    unsigned int                cpu;
    unsigned int                active_bases;     // 哪些 base 有活跃 timer
    bool                        hres_active;      // 高精度模式已启用
    // ...
    ktime_t                     expires_next;     // 本 CPU 最早到期时间
    struct hrtimer              *next_timer;      // 最早到期的 timer 指针
    struct hrtimer_clock_base   clock_base[HRTIMER_MAX_CLOCK_BASES];  // 8 个 base
};

当一个 hrtimer 被插入时，它被放入对应 clock base 的红黑树，按 expires（到期时间）排序。插入操作的时间复杂度是 O(log n)⁴：

// kernel/time/hrtimer.c: 640-660
static bool enqueue_hrtimer(struct hrtimer *timer, struct hrtimer_clock_base *base,
                            enum hrtimer_mode mode, bool was_armed)
{
    base->cpu_base->active_bases |= 1 << base->index;
    WRITE_ONCE(timer->is_queued, HRTIMER_STATE_ENQUEUED);

    // 如果新插入的 timer 是当前 base 中最左的（最早到期），返回 true
    if (!timerqueue_linked_add(&base->active, &timer->node))
        return false;

    base->expires_next = hrtimer_get_expires(timer);
    return true;
}

timerqueue_linked_add 返回 true 表示新插入的节点成为了红黑树的最左节点——也就是最早到期的那个。这种情况下，内核需要重新编程时钟事件设备。

1.3 什么时候编程硬件？

从红黑树到硬件只差一步：每插入一个 timer，都检查它是不是当前最早的；如果是，重新编程时钟事件设备⁵：

// kernel/time/hrtimer.c: 732-760
static void hrtimer_reprogram(struct hrtimer *timer, bool reprogram)
{
    struct hrtimer_cpu_base *cpu_base = this_cpu_ptr(&hrtimer_bases);
    ktime_t expires = hrtimer_get_expires(timer);
    expires = ktime_sub(expires, base->offset);
    // ...

    // 如果到期时间在当前最早之后，什么都不做
    if (expires >= cpu_base->expires_next)
        return;

    cpu_base->next_timer = timer;
    __hrtimer_reprogram(cpu_base, timer, expires);
}

__hrtimer_reprogram 最终调用 tick_program_event(expires_next, 1)，进入时钟事件设备层⁶：

// kernel/time/hrtimer.c: 700-708
static inline void hrtimer_rearm_event(ktime_t expires_next, bool deferred)
{
    trace_hrtimer_rearm(expires_next, deferred);
    tick_program_event(expires_next, 1);
}

1.4 中断到来后：批量收割

当硬件中断到来时，hrtimer_interrupt() 被调用。它遍历红黑树，收割所有已到期的 timer，执行回调²：

// kernel/time/hrtimer.c: 2083-2138
void hrtimer_interrupt(struct clock_event_device *dev)
{
    struct hrtimer_cpu_base *cpu_base = this_cpu_ptr(&hrtimer_bases);

    raw_spin_lock_irqsave(&cpu_base->lock, flags);
    entry_time = now = hrtimer_update_base(cpu_base);

retry:
    // 将最早到期时间设为 KTIME_MAX（阻止远程 CPU 插入新 timer）
    cpu_base->expires_next = KTIME_MAX;

    // 收割所有到期的 hard hrtimer
    __hrtimer_run_queues(cpu_base, now, flags, HRTIMER_ACTIVE_HARD);

    // 重新计算下一个到期时间
    now = hrtimer_update_base(cpu_base);
    expires_next = hrtimer_update_next_event(cpu_base);

    // 如果还有 timer 已到期（更新 now 后发现的），重试
    if (expires_next < now) {
        if (++retries < 3)
            goto retry;
        // 超过 3 次仍到期 → 判定为 hang，设定 max_hang_time
        cpu_base->hang_detected = true;
    }

    // 重新编程硬件到下一个到期时间
    hrtimer_interrupt_rearm(cpu_base, expires_next);
    raw_spin_unlock_irqrestore(&cpu_base->lock, flags);
}

__hrtimer_run_queues 遍历每个有活跃 timer 的 clock base，从红黑树中取出第一个到期时间在 basenow 之前的 timer，执行其回调函数，然后取下下一个，直到遇到还没到期的为止⁷：

// kernel/time/hrtimer.c: 1968-1992
static void __hrtimer_run_queues(struct hrtimer_cpu_base *cpu_base, ktime_t now,
                                 unsigned long flags, unsigned int active_mask)
{
    unsigned int active = cpu_base->active_bases & active_mask;

    for_each_active_base(base, cpu_base, active) {
        ktime_t basenow = ktime_add(now, base->offset);
        struct hrtimer *timer;

        while ((timer = clock_base_next_timer(base))) {
            if (basenow < hrtimer_get_softexpires(timer))
                break;
            __run_hrtimer(cpu_base, base, timer, basenow, flags);
        }
    }
}

遍历从 Red-Black Tree 取最左节点（最早到期），如果到期时间（softexpires）还在 basenow 之后则停止。注意这里用了 softexpires（soft expiration）而不是硬到期时间——这是 hrtimer 的”软到期”特性，允许 timer 在软到期后、硬到期前的任意时刻触发，目的是减少中断次数，将多个接近到期的 timer 合并为一次中断⁴。

二、硬件时钟源层：TSC 如何提供纳秒级读数

数据结构层用 ktime_t（纳秒）做比较和存储。但内核从哪里拿到”当前纳秒时间”？答案是时钟源（clocksource）层。

2.1 clocksource 抽象

内核有一个 clocksource 抽象层，每种计时硬件注册为一个 clocksource 实例，启动时自动选择精度最高的那个⁸：

// include/linux/clocksource.h: 35-135
struct clocksource {
    u64     (*read)(struct clocksource *cs);  // 读取当前计数值
    u64     mask;                              // 计数值的位掩码
    u32     mult;                              // 计数值 → 纳秒 的乘数
    u32     shift;                             // 计数值 → 纳秒 的位移
    u64     max_idle_ns;                       // 最大无中断安全闲置时间
    int     rating;                            // 精度评级（选源依据）
    // ...
};

每种平台的可用时钟源不同，内核按 rating 择优选取：

现代 x86 平台上 TSC 是默认首选。一个 3GHz 的 CPU 上，TSC 每 0.33ns 递增一次。

2.2 TSC 的演进：为什么它可信

早期 TSC 有不稳定的问题（不同步、频率可变）。现代 CPU 上这些问题已经解决：

• Invariant TSC：所有内核的 TSC 在启动时同步，之后不受频率变化（P-state、C-state）影响
• ARAT（Always Running APIC Timer）：即使 CPU 进入 C-state 休眠，TSC 仍然递增
• TSC_ADJUST MSR：允许管理程序修正不同 CPU 核之间的 TSC 偏差

三、中断触发层：从 TSC 到硬件中断

有了 ktime_t 做数据结构、TSC 做纳秒级读数，最后一步是：”如何在恰好那个纳秒点触发中断？”

3.1 时钟事件设备（clock_event_device）

和 clocksource（只读，告诉内核”现在几点”）配对的是一套 clock_event_device 层（可写，告诉硬件”什么时候触发中断”）。每个 CPU 有一个本地时钟事件设备，在 x86 上就是 Local APIC Timer⁹：

// arch/x86/kernel/apic/apic.c: 495-509
static struct clock_event_device lapic_clockevent = {
    .name               = "lapic",
    .features           = CLOCK_EVT_FEAT_PERIODIC | CLOCK_EVT_FEAT_ONESHOT,
    .shift              = 32,
    .set_state_shutdown = lapic_timer_shutdown,
    .set_state_oneshot  = lapic_timer_set_oneshot,
    .set_next_event     = lapic_next_event,       // 传统模式
    .rating             = 100,
};

3.2 传统模式 vs TSC Deadline 模式

这里有一个关键的区别，决定了 hrtimer 精度的登顶：

传统 LAPIC 模式（lapic_next_event）⁹：

// arch/x86/kernel/apic/apic.c: 415-419
static int lapic_next_event(unsigned long delta, struct clock_event_device *evt)
{
    apic_write(APIC_TMICT, delta);  // 写入 cycle 数，递减到 0 时中断
    return 0;
}

向 LAPIC 的 TMICT 寄存器写入一个相对值，LAPIC 以总线时钟频率递减，到 0 时触发中断。这里有一个重要限制：写入的值需要换算成 APIC 总线周期，而 APIC 总线频率和 CPU 频率不同，存在换算误差。

TSC Deadline 模式（lapic_next_deadline）⁹：

// arch/x86/kernel/apic/apic.c: 421-428
static int lapic_next_deadline(unsigned long delta, struct clock_event_device *evt)
{
    u64 tsc = rdtsc();       // 读当前 TSC 值
    native_wrmsrq(MSR_IA32_TSC_DEADLINE, tsc + (((u64) delta) * TSC_DIVISOR));
    return 0;
}

向 MSR_IA32_TSC_DEADLINE 写入一个绝对 TSC 值。LAPIC 内部监视 TSC 寄存器，当 TSC 到达该值时直接触发 LVTT 定时器中断。

TSC Deadline 模式的优势：

TSC Deadline 模式在 CPUID 中通过 X86_FEATURE_TSC_DEADLINE_TIMER 标识¹⁰：

// arch/x86/include/asm/cpufeatures.h: 129
#define X86_FEATURE_TSC_DEADLINE_TIMER  ( 4*32+24) /* "tsc_deadline_timer" */

内核启用它时，把 LAPIC 时钟事件设备的 set_next_event 指针替换为 lapic_next_deadline⁹：

// arch/x86/kernel/apic/apic.c: 581-598
static void setup_APIC_timer(void)
{
    // ...
    if (this_cpu_has(X86_FEATURE_TSC_DEADLINE_TIMER)) {
        levt->name = "lapic-deadline";
        levt->features |= CLOCK_EVT_FEAT_CLOCKSOURCE_COUPLED;
        levt->cs_id = CSID_X86_TSC;
        levt->set_next_event = lapic_next_deadline;  // ← 关键替换
        clockevents_config_and_register(
            levt, tsc_khz * (1000 / TSC_DIVISOR), 0xF, ~0UL);
    } else {
        clockevents_register_device(levt);  // 传统模式
    }
}

CLOCK_EVT_FEAT_CLOCKSOURCE_COUPLED 表示这个时钟事件设备”绑定”到了 TSC 时钟源。clockevents_program_event 识别到这个标志后，走 ktime_t → TSC 的直接转换路径，跳过中间换算¹¹：

// kernel/time/clockevents.c: 360-380
int clockevents_program_event(struct clock_event_device *dev, ktime_t expires, bool force)
{
    // ...
    // 如果设备支持 COUPLED 模式，走 ktime → TSC 直接路径
    if (likely(clockevent_set_next_coupled(dev, expires)))
        return 0;

    // 否则：传统路径，ktime → delta ns → 换算 → 写入
    delta = ktime_to_ns(ktime_sub(expires, ktime_get()));
    cycles = ((u64)delta * dev->mult) >> dev->shift;
    dev->set_next_event((unsigned long) cycles, dev);
}

传统路径多了一步从 delta-ns 到设备 tick 的换算（mult/shift），可能引入误差。Coupled 路径直接使用 TSC 值，无换算。

当然，使用 lapic_next_deadline 也有注意事项：由于历史原因，一些 CPU 型号（如部分 Haswell/Broadwell/Skylake X）存在 TSC Deadline 的 bug，需要在特定 microcode 版本后才能启用。内核维护了一张 bug 型号表⁹：

// arch/x86/kernel/apic/apic.c: 514-545
static const struct x86_cpu_id deadline_match[] __initconst = {
    X86_MATCH_VFM_STEPS(INTEL_HASWELL_X,   0x2, 0x2, 0x3a),
    X86_MATCH_VFM_STEPS(INTEL_BROADWELL_D, 0x5, 0x5, 0x0e000003),
    X86_MATCH_VFM_STEPS(INTEL_SKYLAKE_X,   0x5, 0xf, 0),
    // ...
};

如果 microcode 不满足，内核会自动禁用 TSC Deadline 模式，回退到传统 LAPIC 定时器。

3.3 完整链路图

将三层串起来，hrtimer 从注册到触发的完整链路是：

sequenceDiagram
    participant User as 用户程序
    participant HR as hrtimer 框架
    participant RB as 红黑树
    participant CE as 时钟事件设备
    participant LAPIC as LAPIC (TSC Deadline)
    participant TSC as TSC 寄存器

    User->>HR: clock_nanosleep(100ns)
    HR->>HR: ktime_t expires = now + 100
    HR->>RB: 插入红黑树 (O(log n))
    Note over RB: 如果是最早到期
    HR->>CE: hrtimer_reprogram(expires)
    CE->>CE: clockevents_program_event(expires)
    CE->>LAPIC: lapic_next_deadline(delta)
    LAPIC->>TSC: rdtsc() + delta → MSR_IA32_TSC_DEADLINE
    Note over LAPIC,TSC: 硬件监视 TSC<br/>到达目标值时触发中断
    TSC-->>LAPIC: TSC == deadline
    LAPIC-->>CE: LVTT 定时器中断
    CE-->>HR: hrtimer_interrupt()
    HR->>RB: 收割到期 timer
    RB-->>HR: 回调函数
    HR-->>User: 进程被唤醒

四、精度 vs 准确性：一个重要的区分

让很多人困惑的一件事是：hrtimer 的”纳秒精度”和”实际中断是否能准时在纳秒级触发”是两回事。

• 精度（precision）：hrtimer 的 ktime_t 确实是纳秒粒度的，红黑树按到期时间排序，比较的单位就是纳秒。时钟源（TSC）读出的值分辨率也在亚纳秒级。这是数据层面的精度。
• 准确性（accuracy）：中断实际触发时间到理论到期时间的偏差，受中断延迟（interrupt latency）影响。

中断延迟的来源：

理想路径：
  t=0ns:    注册 hrtimer(deadline = t + 100ns)
  t=100ns:  TSC deadline 到达 → LAPIC 拉高 IRQ 线 → CPU 响应 → handler

实际路径：
  t=0ns:    注册 hrtimer(deadline = t + 100ns)
  t=50ns:   CPU 进入 spin_lock_irqsave 临界区（关中断）
  t=100ns:  TSC deadline 到达 → LAPIC 拉高 IRQ 线
            但 CPU 关中断 → IRQ 在 CPU 的 INTR 引脚等待
  t=300ns:  退出临界区 → 开中断 → CPU 从 IDT 读取中断向量
            → 跳转到 hrtimer_interrupt → handler 执行
            晚了 200ns

这个偏差在普通 Linux 内核上通常在 1-10μs 级别，在 PREEMPT_RT（实时内核）上可以压到亚微秒级。

但即便是普通内核，hrtimer 和老的时间轮(timer_list)也有本质区别：

传统 timer_list (jiffies):
  到期间隔: t=0 注册 5ms 的 timer
  下一个 jiffies tick 在 3ms 后
  再下一个 jiffies tick 在 7ms 后
  → 实际触发在 7ms，偏差 ~2ms

hrtimer (TSC Deadline):
  到期间隔: t=0 注册 5ms 的 hrtimer
  → TSC deadline 写入 t + 5ms 对应的 TSC 值
  → 即使关中断导致延迟，但 5ms+300ns 比 7ms 精确得多
  → 且 hrtimer 不会因为 jiffies 的周期而被延迟

五、NOHZ + hrtimer：为什么 tickless 需要 hrtimer

hrtimer 的纳秒精度还有一个关键的应用场景：tickless 模式（NOHZ）。

在没有 NOHZ 的传统内核上，即使 CPU 空闲，每个 tick（1ms/4ms）都会触发一次定时器中断，唤醒 CPU 检查是否需要调度。这浪费了功耗。

在 NOHZ 模式下（桌面和服务器内核默认启用），空闲 CPU 可以完全关闭 tick 中断，靠 hrtimer 在真正有事情需要做时才唤醒它。

这个过程是这样的⁶：

CPU 进入 idle:
  1. 检查所有 hrtimer 的下一个到期时间
  2. 如果没有任何即将到期的 hrtimer → 无限期 idle（可被外部中断唤醒）
  3. 如果有 hrtimer 在 50ms 后到期
     → tick_program_event(50ms 后的 TSC)
     → LAPIC 在 TSC deadline 触发时唤醒 CPU

CPU 从 idle 被 hrtimer 中断唤醒:
  1. hrtimer_interrupt() 收割到期的 hrtimer
  2. 重新编程下一个到期时间
  3. 执行可能由于被阻塞的 RCU 回调等
  4. 如果没有更多工作，再次进入 idle

// kernel/time/tick-sched.c: 892
// NOHZ 模式下，tick 被 hrtimer 替代
tick_program_event(expires, 1);

这里 hrtimer 替代了传统的 tick 定时器，实现了”没有工作时完全不打扰 CPU”的效果。

总结

回到最初的问题：hrtimer 的纳秒精度来自三个层次：

1. 数据结构层（纳秒的”意愿”）：ktime_t 以纳秒为单位存储和比较到期时间，红黑树 O(log n) 管理
2. 时钟源层（纳秒的”眼见”）：TSC 以 ~0.3ns 的粒度提供当前时间读数
3. 中断触发层（纳秒的”手到”）：TSC Deadline 模式写入绝对 TSC 值，硬件在确切时刻触发中断

三层叠加，实现了 clock_nanosleep() 在数据层面、读时层面、触发层面均能达到纳秒级精度。但实际触发时间受关中断影响，在普通内核上通常有 1-10μs 的偏差——这是准确性受限，而非精度受限。

hrtimer 和传统 timer_list（jiffies 时间轮）的区别，不仅仅在于分辨率从毫秒级降到纳秒级——更在于hrtimer 的触发完全不依赖 tick，它按需编程时钟事件设备，在 NOHZ 模式下实现了真正的 tickless 空闲。如果把内核时钟系统比作一个厨房：

• jiffies 时间轮像一个每隔固定时间响一次的闹钟——无论有没有事，它都响
• hrtimer像一个贴在墙上的倒计时器列表——每个 timer 指定了精确的到期时间，CPU 按需设置最近的一个，到期后响一次，然后设置下一个最近的一个。没事的时候，所有计时器静默，CPU 可以安心睡觉

References

上篇文章跟踪了 tokio::time::sleep 从 Future::poll 到哈希时间轮的完整链路。那篇文章的核心是一个问题：时间怎么做到异步等待的？本文要回答另一个问题：网络 I/O又是怎么做到异步等待的？它们共享同一个 runtime 主循环，但背后是两种完全不同的驱动模型。

引言：为什么需要第二篇？

上篇文章¹中，我们看到了 tokio::time::sleep 的实现链条：

Future::poll → TimerEntry → Wheel(哈希时间轮) → Driver::park_timeout → epoll_wait

那条链路的核心架构是：用户态维护时间轮，只向内核注册一个「最早 deadline」的定时器。当线程从 epoll_wait 返回后，驱动去时间轮里收割所有到期 timer，批量唤醒对应的任务。

但这里有一个容易被忽略的细节：park_timeout 最终调用的 epoll_wait，本身就是 Linux 上最核心的 I/O 事件通知机制。时间驱动把 I/O 驱动的 park_timeout 当成了「闹钟」来用——它只是顺路借用了 epoll 的超时功能。真正的主角是I/O 驱动自己。

当你写下下面这行代码时，背后发生的事情和 sleep 有着本质区别：

let mut stream = TcpStream::connect("127.0.0.1:8080").await?;
stream.read(&mut buf).await?;

sleep 只关心”时间到了没”；TcpStream::read 关心的是”数据到了没”。前者在用户态就能判断（查时间轮），后者必须由内核通知——因为只有内核知道网卡上有没有新数据包到达。

这篇文章就从 TcpStream 注册到 I/O 驱动的完整流程讲起，拆开 ScheduledIo、Registration、PollEvented、I/O Driver 的事件循环，然后和上篇的 Timer 驱动做横向对比，看看它们在同一套 runtime 主循环里是如何共存并各自工作的。

先看一段代码

和上一篇文章一样，先从一个可运行的程序建立直觉。下面是一个简单的 TCP echo 服务，用 Tokio 同时处理多个连接：

// tokio_echo.rs
use tokio::net::TcpListener;
use tokio::io::{AsyncReadExt, AsyncWriteExt};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let listener = TcpListener::bind("127.0.0.1:8080").await?;

    loop {
        // 等待新连接（异步）
        let (mut socket, addr) = listener.accept().await?;

        // 每个连接 spawn 一个独立的任务
        tokio::spawn(async move {
            let mut buf = [0; 1024];

            // 在一个连接上循环读写（异步）
            loop {
                match socket.read(&mut buf).await {
                    Ok(0) => break,            // 连接关闭
                    Ok(n) => {
                        // 把读到的内容原样写回去
                        let _ = socket.write_all(&buf[..n]).await;
                    }
                    Err(_) => break,
                }
            }

            println!("连接 {} 关闭", addr);
        });
    }
}

用一条线程跑上面的服务，它就可以同时接受成千上万个连接。每个连接上的 accept、read、write 都是异步的——调用时不会阻塞线程，线程会去服务其他连接。

对比一下同步阻塞版本的多线程实现：

// sync_echo.rs（多线程阻塞版）
use std::net::TcpListener;
use std::thread;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let listener = TcpListener::bind("127.0.0.1:8080")?;

    loop {
        let (mut socket, addr) = listener.accept()?;

        // 每个连接启动一条新线程
        thread::spawn(move || {
            let mut buf = [0; 1024];

            loop {
                let n = socket.read(&mut buf).unwrap();
                if n == 0 { break; }
                socket.write_all(&buf[..n]).unwrap();
            }

            println!("连接 {} 关闭", addr);
        });
    }
}

同步版本也能处理多连接，但代价是每条连接一条 OS 线程。每个 thread::spawn 都涉及内核态的线程创建、栈分配（默认 2MB）、以及调度器的上下文切换。几千个连接就需要几千条线程——OS 调度器很快就不堪重负。

而 Tokio 版本却用一条线程做到了同步版本需要几千条线程才能做到的事。秘密就藏在这三个 .await 背后：它们不会阻塞线程，只会把任务挂起，把线程还给调度器去服务其他连接。