XLabs | 技术博客

MCP 工具返回值的两道隐藏边界：10MB 帧上限、outputSchema 校验（1.32.1 实测）

Thu, 08 Oct 2026 16:00:00 GMT

上一篇 MCP 2026-07-28 弃用扫描我 grep 的是 SDK 有没有跟上 spec。这篇 grep 另一件事：我 server 返回的工具结果，在客户端那边会经历什么。

四条结论都不在文档里，也不在类型定义里，跑出来才知道：

stdio 下，结果帧超过 10,485,760 字节 就断连，调用方只看到 MCP error -32000: Connection closed，真实原因只在 transport.onerror 里。
这个上限属于读的一方（客户端）。服务端把 maxBufferSize 调多大都没用。
服务端 outputSchema 校验失败变成一个 isError: true 的正常 result，不是 JSON-RPC error，try/catch 抓不到。
客户端只在调过 tools/list 之后才校验 structuredContent；而且 isError: true 时它照校验不误，会把错误结果整个抛成异常。

环境

@modelcontextprotocol/sdk@1.32.1（npm 当前 latest）+ zod
Node v26.3.0，stdio transport，全部默认配置
每个用例开新客户端进程，避免上一轮的断连污染下一轮
单文件复现脚本在文末，node mcp-result-limits.mjs 直接跑

一、outputSchema：校验失败不是错误

工具声明 outputSchema: { count: z.number() }，handler 返回 { count: 'one' }。服务端 McpServer 确实拦了，但拦下来的处理方式是这样：

// node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:181
catch (error) {
  return this.createToolError(error instanceof Error ? error.message : String(error));
}

createToolError 返回 { content: [{type:'text', text: msg}], isError: true }。抓包确认，线上是一个 result 帧，没有 error 键：

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{ "type": "text", "text": "boom" }],
    "structuredContent": { "count": "one" },
    "isError": true
  }
}

三条失败路径的原话：

no_structured => MCP error -32602: Output validation error: Tool no_structured has an output schema but no structured content was provided
bad_type      => MCP error -32602: Output validation error: Invalid structured content for tool bad_type: Invalid input: expected number, received string at count

对调用方的直接影响是没有异常可捕获：包在 try/catch 里的 callTool 正常返回，业务代码拿到 structuredContent: null、content 是报错文案的结果。下游直接读 structuredContent.count 就是 Cannot read properties of undefined；下游要是把它喂给模型，模型看到的是 “Output validation error: …” 这种它读不懂的字符串，然后开始猜——和我上一篇工具失败回灌实测里 empty_ok 触发幻觉是同一类问题。

唯一可靠的观测点是 isError。但它同时承载了「业务失败」和「我 schema 写错了」两件事，监控上分不开。

客户端校验取决于调没调过 tools/list

同一个工具，客户端 listTools 之前和之后是两个世界：

工具返回值	未 listTools	已 listTools
`no_structured`（有 schema 没给 structuredContent）	isError=true	isError=true
`bad_type`（structuredContent 类型错）	isError=true	isError=true
`extra_field`（多一个诊断字段）	OK，原样返回	抛 -32602
`iserror_bad`（isError + 不合规 structuredContent）	OK，原样返回	抛 -32602
`diverge`（text 说 5，structured 说 7）	OK	OK

客户端在 tools/list 时缓存每个工具的 outputSchema validator（client/index.js 的 cacheToolMetadata），callTool 里再用它校验。所以只 callTool 从不 listTools 的客户端等于完全没有返回值校验。

而正常走 listTools 的客户端会拒绝多出来的字段，因为 Zod 转出来的 JSON Schema 带 additionalProperties: false：

{ "type": "object", "properties": { "count": { "type": "number" } }, "required": ["count"], "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false }

extra_field / 已 listTools =>
MCP error -32602: Structured content does not match the tool's output schema: data must NOT have additional properties

「多给点信息」在这里会打断整个调用。这是最容易踩、也最难自己发现的一条——本地写 server 的调试客户端往往不调 listTools，你测不出来。

isError 是双重标准

服务端遇到 isError: true 就跳过 outputSchema 校验（server/mcp.js:237 的 if (result.isError) return;），好让错误结果不必满足成功时的 schema。客户端不是这样。它的注释写着 // Only validate structured content if present (not when there's an error)（client/index.js:492），但代码只跳过了「structuredContent 缺失」那一种情况——只要 structuredContent 存在就照样校验。

于是：一个上报错误、顺手带了不合规 structuredContent 的工具，服务端放行，客户端抛异常。调用方拿到的是异常，不是那句错误文案。

iserror_bad / 未 listTools => {"isError":true,"structured":{"count":"one"},"text":"上游 502"}
iserror_bad / 已 listTools  => MCP error -32602: Structured content does not match the tool's output schema: data/count must be number

反过来，错误结果里不放 structuredContent，两边都放行。这是错误返回唯一稳妥的形态。

text 和 structuredContent 不一致，没人查

工具返回 content: [{type:'text', text:'count=5'}] 和 structuredContent: {count: 7}，服务端校验通过，客户端校验通过。模型读 text，程序读 structuredContent，拿到两个不同的数，四层实现里没有一层会发现。

同类的还有一个：声明 outputSchema、返回 content: [] + 合法 structuredContent，也一路通过——TS 这个版本的高层 API 不会自动补一份 text 序列化（Python SDK 文档写的是会自动填两个 channel，两者行为不一致）。只吃 text 的客户端拿到空结果，但代码里看不出任何异常。

二、10MB：结果帧超了就断连

真正把连接打死的是这个常量：

// node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js:2
export const STDIO_DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;

ReadBuffer.append 累积超过它就 throw，抛出位置在 transport 的 ondata 回调里，冒泡上去的结果是 transport 关闭。逐个测：

text 9437184B   => OK，318ms
text 10485760B  => -32000: Connection closed / ReadBuffer exceeded maximum size of 10485760 bytes
text 12582912B  => -32000: Connection closed / ReadBuffer exceeded maximum size of 10485760 bytes

断连之后同一个 client 再调任何工具都是 Error: Not connected。Connection closed 这个报错没有任何信息量，真正的原因要去 transport.onerror 里捞；宿主客户端不一定会把它写进日志。

三个被低估的点

1. 上限算字节，不算字符。 换成中文：

cjk 3000000 字  => OK（9,000,000 字节）
cjk 3500000 字  => 断连（10,500,000 字节）

翻成中文以后，同样「三百万字」的摘要、diff、日志片段就撞墙。按字符数估容量必然翻车。

2. base64 让二进制内容再打七五折。 图片/音频走 data 字段 base64，膨胀 4/3：

blob 原始 7340032B => OK（base64 后 9,786,712 字符）
blob 原始 8388608B => 断连（base64 后 11,184,810 字符）

截图类工具实际能返回的图片上限约 7.5 MiB 原始字节，不是 10 MiB。

3. 上限属于读的一方，服务端改不了。 最反直觉的一条：

客户端 maxBuffer=1MiB，返回 1MiB            => 断连（ReadBuffer exceeded maximum size of 1048576 bytes）
客户端 maxBuffer=32MiB，返回 16MiB          => OK，768ms
服务端 maxBuffer=64MiB，客户端默认，返回 12MiB => 仍然断连（10485760 bytes）

服务端把 StdioServerTransport 的 maxBufferSize 调大，只影响它读客户端请求的能力，对「客户端能不能读下我的结果」毫无帮助。这不是服务端单方面能修的：宿主客户端（Claude Desktop 这类）用的就是默认值。

它也不是协议限制。 同一份 server 代码换 InMemory transport，32 MiB 用 1ms 过去；stdio 下连续三次返回 4 MiB 全部成功——上限按单个未结束的帧算，不累积。

为什么会这样

spec 把「谁校验输出」留给实现：server 声明 outputSchema 后 client SHOULD 校验，client 拿到不符的结果 SHOULD/MUST 报错。TS SDK 选了「服务端把失败包成 isError + 客户端校验时抛异常」这套组合，两种策略叠在一起就出现了「同一个错误，取决于是不是调过 tools/list，是异常还是结果」。

10 MiB 则是另一回事：它是 stdio 读取层防 OOM 的工程默认值，写在实现里，不在任何 spec、文档或类型里。没有文档的地方，失败模式就只能是静默。

落地清单

给所有工具结果设自己可控的上限，超了不回原文，回 resource_link 加摘要：

const MAX_INLINE = 1 * 1024 * 1024; // 1 MiB，给 JSON framing 留足余量

function inlineResult(text, uri) {
  const bytes = Buffer.byteLength(text, "utf8"); // 必须按字节，不是 text.length
  if (bytes <= MAX_INLINE) return [{ type: "text", text }];
  return [
    { type: "text", text: `结果 ${bytes} 字节，已截断，完整内容见 resource` },
    { type: "resource_link", uri, name: "full result", mimeType: "text/plain" }
  ];
}

错误结果不要带 structuredContent，只给 text + isError: true（两边都放行的唯一形态）。
outputSchema 只写会稳定返回的字段。额外的诊断信息走 resource 或日志，否则被 additionalProperties: false 拒掉。
返回 structuredContent 时自己再给一份 text 序列化，别指望 SDK 补——只读 text 的客户端拿不到 structuredContent。
自己先校验再返回。服务端失败会变成 isError，客户端失败会变成异常，两种都不是你想看到的报错方式。
客户端侧一定挂 transport.onerror，否则 -32000: Connection closed 等于没信息。
CI 加一条大结果回归：造一个 12 MiB 返回值，断言 callTool 不抛异常、或断言错误文案含 ReadBuffer exceeded。别等用户报「工具偶尔没反应」。

边界

只测 @modelcontextprotocol/sdk@1.32.1 + Node v26.3.0 + stdio + 默认配置。Streamable HTTP 不走 shared/stdio.js 这套 ReadBuffer，上限另说，未测。
Python SDK 未测。它文档里写过「会同时填 content 和 structured_content」，与 TS 高层 API 不一致，不能互相套用结论。
10 MiB 是当前默认值，不是协议承诺，换版本可能就变。要长期依赖就自己定义上限，别依赖这个数。
断连后服务端进程状态未验证（stderr 为空、拿不到 exitCode），只确认客户端侧连接关闭、后续调用 Not connected。

复现脚本

单文件，npm i @modelcontextprotocol/sdk@1.32.1 zod 之后直接跑。

// mcp-result-limits.mjs（节选）
// 1) 子进程 server：一台机器上放 3 类工具
fs.writeFileSync(
  CHILD,
  `
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
const s = new McpServer({ name: 'limits', version: '0.0.1' });
const Cout = { count: z.number() };
const reg = (name, cfg, fn) => s.registerTool(name, { description: name, inputSchema: {}, ...cfg }, fn);
reg('ok',            { outputSchema: Cout }, async () => ({ content: [{ type: 'text', text: 'count=1' }], structuredContent: { count: 1 } }));
reg('no_structured', { outputSchema: Cout }, async () => ({ content: [{ type: 'text', text: 'count=1' }] }));
reg('bad_type',      { outputSchema: Cout }, async () => ({ content: [{ type: 'text', text: 'count=one' }], structuredContent: { count: 'one' } }));
reg('extra_field',   { outputSchema: Cout }, async () => ({ content: [{ type: 'text', text: 'x' }], structuredContent: { count: 1, extra: 'x' } }));
reg('iserror_bad',   { outputSchema: Cout }, async () => ({ isError: true, content: [{ type: 'text', text: '上游 502' }], structuredContent: { count: 'one' } }));
reg('diverge',       { outputSchema: Cout }, async () => ({ content: [{ type: 'text', text: 'count=5' }], structuredContent: { count: 7 } }));
s.registerTool('text', { description: 'text', inputSchema: { bytes: z.number() } }, async (a) => ({ content: [{ type: 'text', text: 'A'.repeat(a.bytes) }] }));
s.registerTool('cjk',  { description: 'cjk',  inputSchema: { chars: z.number() } }, async (a) => ({ content: [{ type: 'text', text: '字'.repeat(a.chars) }] }));
s.registerTool('blob', { description: 'blob', inputSchema: { bytes: z.number() } }, async (a) => ({ content: [{ type: 'image', data: Buffer.alloc(a.bytes, 7).toString('base64'), mimeType: 'image/png' }] }));
await s.connect(new StdioServerTransport(process.env.MAXBUF ? { maxBufferSize: Number(process.env.MAXBUF) } : undefined));
`
);

// 2) 每个用例开新客户端：list 决定校验开关，maxBufferSize 决定帧上限，onerror 留住真实报错
async function call(tool, args, { list = false, clientMaxBuf } = {}) {
  const t = new StdioClientTransport({ command: "node", args: [CHILD], stderr: "pipe", ...(clientMaxBuf ? { maxBufferSize: clientMaxBuf } : {}) });
  const transportErrors = [];
  t.onerror = (e) => transportErrors.push(String(e?.message ?? e));
  const client = new Client({ name: "limits-client", version: "0.0.1" });
  await client.connect(t);
  if (list) await client.listTools();
  try {
    const res = await client.callTool({ name: tool, arguments: args ?? {} });
    return { ok: true, isError: res.isError ?? false, structured: res.structuredContent ?? null, text: res.content?.[0]?.text?.slice(0, 96) ?? null };
  } catch (e) {
    return { ok: false, code: e.code, message: e.message, transportError: transportErrors[0] };
  } finally {
    await client.close();
  }
}

完整文件（含 InMemory 对照与读者侧/服务端侧配置对比）我跑在这台机器上，输出就是上面各节的原始日志。想复用的话，把 call() 直接拿去做回归测试也行——第 7 条清单里的 12 MiB 用例就是这么写的。

MCP 的 server / client 实现和周边工具，可以顺着 awesome-x-ops 的 AI Coding 分类往下翻。同环境同 SDK 的前几篇：版本协商实测、Streamable HTTP 行为、工具失败回灌。

MCP 2026-07-28 弃用 Roots/Sampling/Logging，SDK 还在裸奔（1.32.1 实测）

Tue, 06 Oct 2026 16:00:00 GMT

昨天翻 MCP 2026-07-28 changelog，看到一条以前没注意的：Roots、Sampling、Logging 三个 feature 整体弃用（SEP-2577），且新增了 server/discover 方法和强制 Mcp-Method / Mcp-Name 请求头（SEP-2243）。文档说弃用是 annotation-only，wire protocol 不变，给 12 个月迁移期。

我立刻去看自己的 server 代码——里面正用着 sampling/createMessage 做 Agent 内嵌推理。如果 SDK 已经有 deprecation 警告，我得在升级前看到它。所以拿了 @modelcontextprotocol/sdk@1.32.1（2026-10-05 发布，npm 上当前最新）实测了一把。

结论：SDK 还没跟上 spec。这三个 feature 在 1.32.1 上裸奔，没有任何运行时或类型层警告。

实测环境

@modelcontextprotocol/sdk@1.32.1（npm，2026-10-05）
Node v22
InMemory transport，client 端声明 roots: { listChanged: true } 和 sampling: {} 能力并 stub 了 handler

实测：三个弃用 feature 的当前行为

写了一个 probe server，单个工具内部直发三种「弃用」请求，捕获 console.warn / console.error / process.on('warning')：

// 节选，完整 probe.mjs 在文末
try {
  out.roots = await extra.sendRequest({ method: "roots/list", params: {} }, RootsResultZod);
} catch (e) {
  out.errors.push("roots: " + e.message);
}

try {
  out.sampling = await extra.sendRequest(
    {
      method: "sampling/createMessage",
      params: { messages: [{ role: "user", content: { type: "text", text: "hi" } }], maxTokens: 8 }
    },
    SamplingResultZod
  );
} catch (e) {
  out.errors.push("sampling: " + e.message);
}

try {
  await extra.sendNotification({
    method: "notifications/message",
    params: { level: "info", data: "deprecated-log", logger: "probe" }
  });
  out.log = "sent";
} catch (e) {
  out.errors.push("logging: " + e.message);
}

跑出来的结果：

{
  "roots": { "roots": [{ "uri": "file:///tmp/x", "name": "x" }] },
  "sampling": { "role": "assistant", "model": "stub", "content": { "type": "text", "text": "stub-reply" } },
  "log": null,
  "errors": ["logging: Server does not support logging (required for notifications/message)"]
}
// --- warnings captured ---
// (none)

读出来的事实：

roots/list 工作正常，无任何警告。SDK 不知道也不在乎 spec 已弃用它。
sampling/createMessage 工作正常，无任何警告。同上。
notifications/message 被拦了，但拦它的不是 deprecation——是 SDK 自带的能力协商：server 没声明 logging 能力，sendNotification 直接抛错。也就是说，即使你今天不小心用 logging，得到的提示也不是「这个 API 要没了」，而是「你没声明能力」。

如果只看运行时行为，没人能猜到这三个 feature 已经进入 12 个月倒计时。

类型层也没有 `@deprecated`

SEP-2577 明确说要在 schema/draft/schema.ts 给以下类型加 @deprecated：Root、ListRootsRequest、CreateMessageRequest、SamplingMessage、ModelPreferences、LoggingLevel、LoggingMessageNotification 等等二十多个。

我在 SDK 1.32.1 的 types.d.ts 里搜了一遍：

$ grep -n "@deprecated" node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts

匹配到的全部是无关的旧 API 迁移提示（isJSONRPCResultResponse、ResourceTemplateReferenceSchema 之类），没有任何 Roots/Sampling/Logging 类型被标弃用。

也就是说，IDE 里写 server.createMessage(...) 时，IntelliSense 不会标黄、不会跳删除线。开发者不看 spec 就完全感知不到。

SDK 也没实现 spec 的新增项

spec 2026-07-28 另外引入了几个服务端点：

server/discover：客户端可以问一下服务器的版本、能力、身份，不再依赖 initialize
Mcp-Method / Mcp-Name 请求头：让 CDN/网关可以按方法路由，不解析 body
MRTR（Multi Round-Trip Request）：把 server-initiated 的 roots/list、sampling/createMessage、elicitation/create 改成「result 里嵌 inputRequests + 客户端 retry 时回带 inputResponses」的模式，摆脱长连接

在 1.32.1 的 dist/esm 里 grep：

$ grep -rn "server/discover" node_modules/@modelcontextprotocol/sdk/dist/esm/
$ grep -rn "Mcp-Method\|Mcp-Name" node_modules/@modelcontextprotocol/sdk/dist/esm/
$ grep -rn "input_required\|InputRequiredResult\|inputRequests" node_modules/@modelcontextprotocol/sdk/dist/esm/

前两个零匹配。第三个只命中 TaskStatus = "..." | "input_required" | ...，是 Task 系统的状态枚举，不是 MRTR 的 InputRequiredResult。

也就是说 SDK 1.32.1 还是 2025-11-25 时代的实现，没有接 spec 的新机制。这跟我在 mcp-2026-07-28-version-negotiation 里实测的版本协商一致——SDK 目前默认仍走旧协议。

为什么这是个隐患

如果你今天在写新的 MCP server，看到 types.ts 里 createMessage、listRoots 都是正常的公开 API，IDE 没警告，runtime 没警告，spec 文档里说「annotation-only deprecation」又不会主动跳出来——

你只会写出来一个 12 个月后要重写的 server。

更要命的是 spec 给的迁移路径是结构性的：

弃用	替代方案
Roots	把目录作为工具参数 / resource URI / server 配置传
Sampling	直接调 LLM provider 的 API（让开发者自己持有 API key）
Logging	stderr（stdio）/ OpenTelemetry

这不是改名，是架构调整。Roots 替代方案要求 server 自己管 scope，不再依赖 client 提供；Sampling 替代方案要求 server 直接持有 LLM 凭据，不再是 client 代理。这两种迁移都不能拖到最后一周做。

工程清单

今天就得做的事：

主动 audit server 代码。grep createMessage、listRoots、sendLoggingMessage、logging/setLevel，列出来，对每一处的迁移路径做决定。
不要等 SDK 警告才动。SDK 1.32.1 已经证不会警告你。把 SEP-2577 加进 upgrade checklist。
新代码默认避开这三个 feature。即使他们还能跑，写新代码时也用工具参数传 scope、直接调 LLM、用 stderr/OTel。
盯 SDK 后续版本的 changelog。SDK 团队总会在某个版本加 @deprecated 和 runtime 警告——那一天会是大范围告警的日子，提前一步。
如果非要继续用 Sampling，把 model_preferences 写好。spec 明确说 server hint 是 advisory、client 可以无视。写好 fallback 链路。

边界

只测了 @modelcontextprotocol/sdk@1.32.1 一个版本。Python SDK（py.sdk.modelcontextprotocol.io）从文档看已经在 sampling 函数上加了 deprecation warning（“Deprecated by the 2026-07-28 specification”），跟 TypeScript SDK 节奏不一样。
只测了 InMemory transport。Streamable HTTP 传输层的行为没测。
SEP-2577 的 12 个月期限从「包含该 SEP 的 spec 版本发布日」起算——changelog 上写 spec 2026-07-28 GA，所以最晚 2027-07-28 可能被移除。具体日历看官方 deprecated features registry。
MRTR 我没实测，因为 SDK 还没实现 InputRequiredResult。

probe.mjs 完整源码

放出来给需要自己复现的人：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { ListRootsRequestSchema, CreateMessageRequestSchema } from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";

const warnLog = [];
const origWarn = console.warn;
console.warn = (...a) => {
  warnLog.push(a.join(" "));
  origWarn(...a);
};
process.on("warning", (w) => warnLog.push(w.name + ": " + w.message));

const server = new McpServer({ name: "probe-server", version: "0.0.1" });
server.registerTool(
  "use-deprecated",
  {
    description: "Calls listRoots + createMessage + sendLoggingMessage",
    inputSchema: {}
  },
  async (args, extra) => {
    const out = { roots: null, sampling: null, log: null, errors: [] };
    try {
      out.roots = await extra.sendRequest({ method: "roots/list", params: {} }, z.object({ roots: z.array(z.object({ uri: z.string(), name: z.string().optional() })) }));
    } catch (e) {
      out.errors.push("roots: " + e.message);
    }
    try {
      out.sampling = await extra.sendRequest(
        {
          method: "sampling/createMessage",
          params: { messages: [{ role: "user", content: { type: "text", text: "hi" } }], maxTokens: 8 }
        },
        z.object({ role: z.string(), model: z.string(), content: z.any() })
      );
    } catch (e) {
      out.errors.push("sampling: " + e.message);
    }
    try {
      await extra.sendNotification({
        method: "notifications/message",
        params: { level: "info", data: "deprecated-log", logger: "probe" }
      });
      out.log = "sent";
    } catch (e) {
      out.errors.push("logging: " + e.message);
    }
    return { content: [{ type: "text", text: JSON.stringify(out) }] };
  }
);

const [ct, st] = InMemoryTransport.createLinkedPair();
const client = new Client({ name: "probe-client", version: "0.0.1" }, { capabilities: { roots: { listChanged: true }, sampling: {} } });
client.setRequestHandler(ListRootsRequestSchema, async () => ({
  roots: [{ uri: "file:///tmp/x", name: "x" }]
}));
client.setRequestHandler(CreateMessageRequestSchema, async () => ({
  role: "assistant",
  model: "stub",
  content: { type: "text", text: "stub-reply" }
}));

await server.connect(st);
await client.connect(ct);
const result = await client.callTool({ name: "use-deprecated", arguments: {} });
console.log(result.content[0].text);
console.log("--- warnings ---");
console.log(warnLog.length ? warnLog.join("\n") : "(none)");
await client.close();
await server.close();

MCP 相关的开源 server / client 实现，可以看 awesome-x-ops 的 AI Coding 分类。我前两天写的 MCP 工具失败回灌实测是同环境同 SDK 系列。

MCP 工具挂了之后：empty_ok 比报错更危险，4 个模型实测

Mon, 05 Oct 2026 16:00:00 GMT

MCP 工具调用失败之后，宿主把错误回灌给模型，模型会怎么反应？这个问题的答案决定你的 Agent 在生产环境里是「报错后重试」还是「编一段看似合理的话糊弄过去」。

我搭了一个 12 工具的 MCP server（桩实现），让 4 个模型在真实 MCP 循环里跑失败场景，最多 3 轮，记录每一次调用和最终结局。三种失败回灌方式：

informative：isError=true，content 里带可行动线索（Error: pods "payment-api-9f8e7d6c5-x9zzz" not found in namespace "prod"）
generic：isError=true，但错误信息没线索（Error: upstream request failed）
empty_ok：isError=false，content 为空数组——协议层「成功」，语义层什么都没说

结局表

模型	informative	generic	empty_ok
deepseek-v4-flash	http_error_400（1 轮就断）	http_error_400	http_error_400
qwen3.8-flash	loop_exhausted	loop_exhausted	loop_exhausted
MiniMax-M3	loop_exhausted	loop_exhausted	text_only（编故事）
gemini-3.8-flash	loop_exhausted	loop_exhausted	loop_exhausted

loop_exhausted 的意思是模型在 3 轮内不断换工具重试，没给出最终答案。text_only 的意思是模型放弃调用工具，直接输出文本。

发现一：empty_ok 是幻觉触发器

MiniMax-M3 在 empty_ok 场景下的输出：

以下是 prod 命名空间下 payment-api-9f8e7d6c5-x9zzz 最近 200 行日志的拉取结果：

日志内容为空(0 行)

可能的原因有以下几种：

Pod 刚刚启动，还没有产生任何日志输出 — 如果应用本身没有主动打日志，或者日志都被输出到了 stdout 之外的某些文件，这里就会取不到。

应用把日志重定向到了文件而非 stdout/stderr — Kubernetes kubectl logs 只能拿到容器标准输出流的内容。

日志采集走了 sidecar/agent，容器内 stdout 本身没东西 — 例如日志被 stdout 转发到了某个日志收集器，kubectl logs 取不到。

Pod 处于 CrashLoopBackOff / 已重启过多次 — 当前容器实例的日志为空

这段输出读起来像资深 SRE 的排查思路，但每一个字都是编的。工具协议层返回了 isError=false，content 为空——模型把「空结果」解释成了「日志为空」，然后基于这个虚假前提展开推理。

empty_ok 的问题在于：它不是错误，但没有信息。模型收到的是一个「成功但无内容」的信号，而 LLM 的训练目标让它必须给出有意义的回复，于是它开始脑补。

informative 场景下 MiniMax 没有编故事，而是正经地调了 k8s_list_pods → k8s_list_pods 尝试换路径。有线索的错误反而引导了正确的恢复行为。

发现二：deepseek 的 400 是客户端问题，不是模型问题

deepseek-v4-flash 在三种失败场景下全部 http_error_400，第一轮就断。抓包看请求体：

{
  "error": {
    "message": "The `reasoning_content` in the thinking mode must be passed back to the API.",
    "type": "invalid_request_error"
  }
}

deepseek 的 thinking 模式要求：assistant 消息里的 reasoning_content 必须在后续调用中原样回传。实验代码的 assistant_msg() 做了这个处理，但只在 reasoning_content 非空时才传键——如果某轮 deepseek 返回了空 reasoning（空字符串或 None），下一轮请求就缺了这个字段，直接 400。

这不是 MCP 的问题，是 deepseek thinking 模式 + 工具调用 + 多轮对话的组合坑。如果你的 Agent 框架用 deepseek，遇到工具调用失败后的多轮恢复，必须检查 reasoning_content 是否被正确透传。

发现三：qwen 和 gemini 的「重试」是无效循环

qwen3.8-flash 在 informative 场景下的 trace：

turn 0: k8s_get_pod_logs(namespace=prod, pod=payment-api-9f8e7d6c5-x9zzz, tail=200)
turn 1: k8s_list_pods(namespace=prod, labelSelector=app=payment-api)
turn 2: k8s_list_pods(namespace=prod)

pod 不存在 → 换 list 找 pod → list 没找到（因为 label 不对）→ 再 list 一次不带 label。3 轮用完，没有结论。

gemini-3.8-flash 在 informative 场景下：

turn 0: k8s_get_pod_logs(...)
turn 1: k8s_list_pods(namespace=prod)
turn 2: k8s_list_deployments(namespace=prod)

pod 找不到 → list pods → list deployments。它把「pod 不存在」理解成了「也许 deployment 层面有问题」，方向错了。

两个模型的共同问题：有线索的错误没有触发「放弃当前路径」的决策。它们把「换工具」当成了「解决错误」本身，而不是「验证假设」的手段。

发现四：命名空间猜测——模型的性格差异

多轮实验 MT2：用户问「payment-api-7d9f4c8b6-x2knp 现在 CPU 和内存用了多少」，文本里没有 namespace。

模型	行为	轮数
deepseek-v4-flash	default → payment → payments → prod → production → kube-system → prod	10 轮
qwen3.8-flash	default → production → staging → default → payment	6 轮
MiniMax-M3	直接反问：「请问部署在哪个命名空间？」	0 轮
gemini-3.8-flash	default → payment → production → prod	7 轮

MiniMax 的 0 轮反问是最优策略：它识别出信息缺口，选择不猜。deepseek 和 qwen 的枚举是最劣策略：它们把「猜 namespace」当成了「解决问题」，消耗大量 token 和延迟，最终可能还是错的。

gemini 第 2 轮就试到 prod，但那是运气，不是策略。

工程清单

工具失败时，回灌必须有可行动线索。Error: upstream request failed 是垃圾输入，Error: pods "xxx" not found in namespace "prod" 能帮助模型换路径。
empty_ok（协议层成功但语义为空）必须显式标记。在宿主层把空结果转成 isError=true + 提示文本，或者至少加一条 content: [{"type":"text","text":"查询成功但无结果"}]。否则模型会编原因。
deepseek thinking 模式 + 多轮工具调用，检查 reasoning_content 透传。缺了就是 400，一轮就断。
信息缺口时，「反问」比「枚举」好。如果工具 schema 里 namespace 是必填，而用户没给，好的 Agent 应该问，而不是猜。
3 轮重试上限要配死。qwen 和 gemini 的 loop_exhausted 说明没有上限时模型会一直换工具，消耗 token 不产出结论。

边界

4 个模型、3 种失败形态、12 个工具，样本量小。不同 SDK 版本、不同 gateway 的行为可能不同。
工具是桩实现，返回固定文本。真实 K8s API 的错误格式可能触发不同的模型行为。
没测「empty_ok 但 content 里有空字符串」的变体——那种情况可能更隐蔽。
MiniMax 的「反问」策略只在 s12 工具集下出现；换 s6 或 s24 是否一致，没测。

工具清单见 awesome-x-ops 的 AI Coding 分类，里面有 MCP 相关的开源实现。

AI 写 Playwright 选择器，5 个模型 5 种 DOM 变异实测：i18n 团灭

Wed, 30 Sep 2026 16:00:00 GMT

让 AI 生成 Playwright 用例时，我关心的是它写的选择器在页面前端重构之后还能不能活。上一篇 AI 生成的 E2E 测试能抓到真 bug 吗测的是「能不能抓到注入的功能缺陷」，这篇测另一个维度——选择器本身在 UI 不变语义、只变结构/文案时的存活率。

实验设计

一个用户管理后台的静态 HTML，包含：新建按钮、搜索框、三行用户列表、行内编辑/删除按钮、分页器。把它喂给 5 个模型，让它们为 4 个操作各写一个 Playwright locator 表达式（getByRole(...) 或 page.locator(...)）。

然后做 5 个语义等价的 DOM 变异，让选择器逐一在 6 个页面上跑：

M1 CSS Modules：所有 class 换成 buttonPrimary_a3f9 这种带后缀的形式
M2 i18n 英文：整页文案换成英文（「新建用户」→「Create User」）
M3 包裹一层：按钮外包 <div class="action-area"><div class="action-inner">
M4 动态 id：id="create-user-btn" 变成 id="create-user-btn-a1b2c3"
M5 aria 语义化：button 换成 <a role="button"> 或 <span role="button">，加 aria-label

判定标准：locator 不仅能命中元素，而且命中的必须是语义正确的那一个（防止 click 落到相邻行的编辑按钮上——这种错误比断掉更糟，因为测试还是绿的，bug 已经漏了）。

结果：i18n 团灭

每个模型 4 个选择器 × 6 页面，共 120 个执行格子：

=== deepseek-v4.1-flash
  create_user     ✓ ✓ · ✓ ✓ ✓  <- getByRole('button', { name: '新建用户', exact: true })
  search_user     ✓ ✓ · ✓ ✓ ✓  <- getByPlaceholder('输入用户名搜索', { exact: true })
  edit_zhangwei   ✓ ✓ · ✓ ✓ ·  <- locator('tr[data-user-id="u001"]').getByRole('button', { name: '编辑', exact: true })
  delete_wangfang ✓ ✓ · ✓ ✓ ·  <- locator('tr[data-user-id="u003"]').getByRole('button', { name: '删除', exact: true })

=== MiniMax-M3
  create_user     ✓ ✓ · ✓ ✓ ✓  <- getByRole('button', { name: '新建用户' })
  search_user     ✓ ✓ · ✓ ✓ ✓  <- getByPlaceholder('输入用户名搜索')
  edit_zhangwei   ✓ ✓ · ✓ ✓ ✓  <- page.locator('tr[data-user-id="u001"]').getByRole('button', { name: '编辑' })
  delete_wangfang ✓ ✓ · ✓ ✓ ✓  <- page.locator('tr[data-user-id="u003"]').getByRole('button', { name: '删除' })

=== gpt-5.6-luna
  create_user     ✓ ✓ ✓ ✓ · ✓  <- #create-user-btn
  search_user     ✓ ✓ ✓ ✓ · ✓  <- #search-input
  edit_zhangwei   ✓ ✓ ✓ ✓ ✓ ✓  <- tr[data-user-id="u001"] button.edit-btn
  delete_wangfang ✓ ✓ ✓ ✓ ✓ ✓  <- tr[data-user-id="u003"] button.delete-btn

=== kimi-k3
  create_user     ✓ ✓ · ✓ ✓ ✓  <- getByRole('button', { name: '新建用户' })
  search_user     ✓ ✓ · ✓ ✓ ✓  <- getByPlaceholder('输入用户名搜索')
  edit_zhangwei   ✓ ✓ · ✓ ✓ ✓  <- locator('tr[data-user-id="u001"]').getByRole('button', { name: '编辑' })
  delete_wangfang ✓ ✓ · ✓ ✓ ✓  <- locator('tr[data-user-id="u003"]').getByRole('button', { name: '删除' })

=== doubao-seed-2.0-pro
  create_user     ✓ ✓ · ✓ ✓ ✓  <- getByRole('button', { name: '新建用户' })
  search_user     ✓ ✓ · ✓ ✓ ✓  <- getByPlaceholder('输入用户名搜索')
  edit_zhangwei   ✓ ✓ · ✓ ✓ ✓  <- getByRole('row', { name: '张伟' }).getByRole('button', { name: '编辑' })
  delete_wangfang ✓ ✓ · ✓ ✓ ✓  <- getByRole('row', { name: '王芳' }).getByRole('button', { name: '删除' })

每个变异页面让 20 个选择器活下来几个：

base                 20/20   (基准)
M1 CSS Modules       20/20   (没有人依赖被改的 class)
M2 i18n 英文          4/20   (团灭)
M3 包裹一层          20/20
M4 动态 id            18/20
M5 aria 语义化        18/20

M1 满分有个实验偏差：gpt-5.6-luna 用了 .edit-btn / .delete-btn 这两个 class，而我的 M1 变异里没改它们（只改了 btn-primary 等通用修饰）。如果 CSS Modules 改造是全量的，gpt-5.6-luna 的两个行内按钮选择器会一起断。真实项目里不要把 class 名当稳定契约——它随时可能被构建工具改写。

三个判断

1. 模型写选择器已经普遍按 Playwright 推荐的 getByRole 路线走，但这条路线对文案是硬依赖

deepseek-v4.1-flash、MiniMax-M3、kimi-k3、doubao-seed-2.0-pro 四家全部首选 getByRole('button', { name: '...' })。这是 Playwright 官方推荐、也是社区公认的「最稳」写法。前提是页面文案不变。

M2（换英文文案）一上，这 16 个选择器全灭。只剩 gpt-5.6-luna 的 4 个——它用的是 #id 和 data-user-id。

这不是模型选错了策略，是 「文案稳定」这个假设在 i18n 场景根本不成立。给国内单语言后台写用例时没事；一旦产品要出海或做多语言，所有 getByRole 用例需要成批重写。

2. gpt-5.6-luna 的 #id 风格在 i18n 下活下来，但死在了 M4（动态 id 后缀）

#create-user-btn 在 M4（id="create-user-btn-a1b2c3"）直接找不到元素。这是组件库多次实例化、或者构建工具自动加 hash 时的常态。一个页面只有 1 个新建按钮时没事，同一页面有两个「新建」入口时 id 一定会变。

它反而是 5 个模型里唯一在 i18n 变异下活下来的——以 M4 的死为代价。

3. M5（aria 语义化）只断 deepseek 一家，出乎意料

把编辑按钮从「无 aria-label」改成 aria-label="编辑用户"，text content 不变。结果 deepseek-v4.1-flash 的 getByRole('button', { name: '编辑', exact: true }) 断了——Playwright 的 accessible name 计算优先取 aria-label，取到的是「编辑用户」而不是「编辑」，exact match 失配。

其他四家都没问题：gpt-5.6-luna 用 class selector 完全不在乎 aria-label；MiniMax-M3、kimi-k3、doubao 用 name: '编辑'（不带 exact）substring 命中了「编辑用户」。

讽刺的是：模型里只有 deepseek 加了 exact: true——这是更严谨的写法，却反而更脆。

工程建议

如果让 AI 写回归测试，把这几条塞进 prompt 或 checklist：

如果产品会 i18n：禁止依赖 text content / getByPlaceholder。要求模型优先选 data-testid、data-user-id、aria-* 这类不变量。
如果产品会拆分多语言团队开发：强制 data-testid 是唯一可靠的契约。
不要把 exact: true 当默认值。它确实更严谨，但任何一次文案/aria-label 微调都会断。
拿到 AI 生成的选择器后，至少跑一遍「换文案」「换 div 层级」的变异再入库。

边界

模型只生成一次，temperature=0；换一个 prompt 风格结果可能不同。我用的 prompt 没提「要考虑 i18n」，这是公平的真实场景——真实用户也不会提。
M2 的英文翻译是我手工写的（「Delete this user?」对应「确认删除该用户？」），如果机翻成别的措辞，部分 substring 匹配可能蒙对。
M1 的 CSS class 变异只改了部分 class（btn-primary、btn-danger 等通用修饰），没改 .edit-btn / .delete-btn 这类业务按钮 class，所以 M1 列的满分不能外推到「更激进的 CSS Modules 改造」。
所有 5 个模型都在同一网关下 2026-10-01 实测，模型固化的版本是当时的快照。

复现

关键的判定逻辑是「locator 必须命中语义正确的元素」——只用 count() === 1 不够，因为有些选择器在错误页面上也能命中（比如定位到了相邻行的编辑按钮），那种情况下测试是绿的，bug 已经漏了。我用的是回读 data-user-id / id 前缀这些稳定特征做二次确认。

同领域 AI 工程工具见 awesome-x-ops 的 AI 分类。MCP/Agent 场景的实测在 MCP Streamable HTTP SDK 行为一篇。

Playwright Test Agents 拆包：init-agents 落到磁盘的 3 个 agent 定义文件

Mon, 28 Sep 2026 16:00:00 GMT

Playwright 1.56 引入的 Planner / Generator / Healer 三个测试 agent，文档里只给了 npx playwright init-agents --loop=<client> 一句话。这个命令到底往仓里写了什么、agent 的 prompt 里写了什么硬约束，没人拆开看过。

我把 1.63.0 在空目录里跑了一遍，四个 loop（claude / codex / vscode / opencode）和 --prompts 参数各跑一次。下面是落盘产物对比和原文摘录。

四个 loop 落点不一样

--loop=claude：

.claude/agents/playwright-test-planner.md
.claude/agents/playwright-test-generator.md
.claude/agents/playwright-test-healer.md
.mcp.json
seed.spec.ts
specs/README.md

--loop=codex 把同一批内容写成 TOML，路径换成 .codex/agents/playwright_test_*.toml，且 .mcp.json 里的 server 名变成带 tools: ["*"] 显式白名单的写法。

--loop=vscode 产物最多：.github/agents/*.agent.md + .vscode/mcp.json + 一个 .github/workflows/copilot-setup-steps.yml（Copilot coding agent 在 CI 镜像里跑 npm ci && npx playwright install --with-deps 的引导）。

--loop=opencode 类似 claude，但落到 .opencode/。

公共三件套是 .mcp.json + seed.spec.ts + specs/README.md。.mcp.json 永远只声明一个 server：

{
  "mcpServers": {
    "playwright-test": {
      "command": "npx",
      "args": ["playwright", "run-test-mcp-server"]
    }
  }
}

seed.spec.ts 是 7 行空 test.describe，作用是给 agents 一个「能跑起来」的最小锚点。specs/README.md 一句话：「directory for test plans」—— Planner 的产出落在这里。

--prompts 标志额外多写四个文件，对应四个动作的调用模板（.claude/prompts/playwright-test-plan.md 等），内容是 5-9 行的 front matter + 一句提示词，比如 heal 的就一句「Run all my tests and fix the failing ones」。文件本身没有信息密度，主要价值是把入口参数格式固定在仓里。

Healer 定义里两条值得抄出来的条款

三个 *.agent.md 里最硬的两条都长在 healer（.claude/agents/playwright-test-healer.md）里，原文摘录：

- If the error persists and you have high level of confidence that the test is correct,
  mark this test as test.fixme() so that it is skipped during the execution. Add a comment
  before the failing step explaining what is happening instead of the expected behavior.
- Do not ask user questions, you are not interactive tool, do the most reasonable thing
  possible to pass the test.
- Never wait for networkidle or use other discouraged or deprecated apis

三条各自的含义：

test.fixme() 是合法出口。Healer 修不动时会主动选择「跳过 + 注释说明现象」，而不是继续瞎改。这是把「无法修复」显式编码进产物的条款——比静默改成宽断言要诚实。
「不要问用户」是被写死的。Agent 在无人值守的 CI 循环里跑，遇到歧义自己选最合理解。这意味着同一个 healer 跑两次，第二次的 patch 可能跟第一次不同——它不被要求幂等。
networkidle 被点名禁用。Planner/Generator 的 prompt 里没有这条，Healer 单独提，作者踩过 networkidle 把单页应用卡死的坑。

同时 healer 拿到的工具列表是三个 agent 里唯一带 test_debug/test_run/test_list 的——planner 和 generator 都没有这两个 MCP 工具，意味着它们不能执行已生成的 spec，只能操作浏览器。生成器写完代码没法自己跑一遍验证，这事是 healer 的活。

Generator 强制契约：一个文件一个测试

Generator 的 agent.md 把产出格式钉死了：

- File should contain single test
- File name must be fs-friendly scenario name
- Test must be placed in a describe matching the top-level test plan item
- Test title must match the scenario name
- Includes a comment with the step text before each step execution

外加 generator_read_log + generator_write_test 两个专属工具——生成不是「模型自己写 spec 文件」，而是「模型在浏览器里把每一步重放一遍，把动作日志回收，再让模型对照日志写最终的 .spec.ts」。从设计稿上能看出作者想避免的事：写代码时不查日志、编造没真跑过的选择器。

这同时是一个隐性约束：Generator 每产一个文件就要走一次完整 setup_page → 回放 → read_log → write_test。一个 plan 里 20 个场景就是 20 次完整循环。模型费用、耗时、token 都是线性乘上去的，没有增量压缩机制。

Codex 的差异在 sandbox

Codex 版的 healer 定义开头多了 sandbox_mode = "workspace-write"。

对照我自己的 Codex 记忆（full-auto 沙箱下 git fetch / GitLab API 都不通），这条沙箱声明意味着 healer 在 Codex 里跑时，写文件可以、但网络出仓是受约束的。当 spec 里要命中后端 API 拿数据、test_debug 要拿 trace 时，能不能出得了沙箱要另算。其他三个 loop 的 agent 定义里没有这个声明。

这个实测能带走什么

三个 agent 是不对称的：Planner/Generator 不调 test_run，Healer 不调 generator_write_test。想让 Generator 写完自己跑验证 → 没有，那是 Healer 的职责边界。
init-agents 不会污染你的 playwright.config.ts，所有产物是新建文件，删 .claude/agents/、.mcp.json、specs/、seed.spec.ts 就能干净回滚。
升级 Playwright 后要重跑 init-agents。node_modules/playwright/lib/agents/*.agent.md 是模板源头，1.56 → 1.63 之间模板本身在演化，仓里那份是当时的快照，不会自动跟着 npm 升。
**Healer 的「不问用户」**意味着它不适合放到默认 CI：一个歧义场景它可能选错「最合理动作」，把真 bug 改成 fixme() 跳过。文档把它放到 IDE 循环里是有原因的。

三个 Playwright MCP server 的工具集见 awesome-x-ops AI Coding 分类。MCP 协议本身的握手和会话机制实测见本站 MCP Streamable HTTP 实测。

MCP Streamable HTTP 实测：Accept 少一项就 406，第二次 initialize 会吃掉整个 Server

Tue, 22 Sep 2026 16:00:00 GMT

MCP 把 SSE 改成 Streamable HTTP 之后，文档把 Accept、Mcp-Session-Id、DELETE、405、404 这一整套状态机讲了一遍。我把官方 SDK 1.30.0（Node 26）跑起来实际抓了一遍，结论先放在这里：

Accept 少一项就是 406，错误码 -32000，但消息明确写「Client must accept both application/json and text/event-stream」——这是好事。
Mcp-Session-Id 只在 initialize 响应里下发一次，之后每个请求/每条流都必须带；不带就是 400，带错/带旧就是 404，DELETE 之后也是 404。
会话模式下，McpServer 一个实例只接受一次 initialize。第二个客户端的 initialize 拿到的是 400 + -32600 "Only one initialization request is allowed"——这是 SDK 层面的限制，不是协议的限制。
协议允许 JSON-RPC batch，但 SDK 拒绝「一个 batch 里既有 initialize 又有别的方法」，错误消息是「Only one initialization request is allowed」。先把 initialize 单独发完，后续 batch tools/call 是正常 200 的。
sessionIdGenerator: undefined 是另一个世界：无会话模式下 GET / DELETE 全部 500，连「不支持」都不愿意告诉你。

下面把每一组实验贴出来，curl 形态的你拿去就能复现。

环境

@modelcontextprotocol/sdk@1.30.0，Node 26，node:http 起服务（不占端口时让内核分配，跑完即退）。
客户端就是 fetch，没引 @modelcontextprotocol/client——目的是看裸 HTTP 行为。
服务实现：

const server = new McpServer({ name: "probe", version: "0.1.0" });
server.tool("echo", { text: z.string() }, async ({ text }) => ({
  content: [{ type: "text", text: `echo:${text}` }]
}));

const transport = new StreamableHTTPServerTransport({
  sessionIdGenerator: () => crypto.randomUUID()
});
await server.connect(transport);
createServer((req, res) => transport.handleRequest(req, res)).listen(0, "127.0.0.1");

实验一：Accept 是硬检查，不是建议

POST / 发 initialize，分别给四个不同的 Accept：

Accept	状态码	结果
`application/json, text/event-stream`	200	正常返回 SSE 帧
`application/json`	406	`-32000 Not Acceptable: Client must accept both application/json and text/event-stream`
`text/event-stream`	406	同上
缺省	500	空响应体，没错误消息

GET 同理，只是更狠：GET 只接受 text/event-stream——

GET /
Accept: application/json
Mcp-Session-Id: <sid>

HTTP/1.1 406
{"jsonrpc":"2.0","error":{"code":-32000,
 "message":"Not Acceptable: Client must accept text/event-stream"},
 "id":null}

所以 MCP client 不能写「Accept: application/json 就行」这种代码。两条 accept 都得列上。

Content-Type 也是硬检查：text/plain 拿到 415 Unsupported Media Type: Content-Type must be application/json。这一条符合常识，写出来是因为 500 和 406 的差距只在 SDK 里几行，不要把 500 当成「服务器内部错」。

实验二：`Mcp-Session-Id` 是单 transport 的生死状

initialize 响应：

HTTP/1.1 200
Content-Type: text/event-stream
Mcp-Session-Id: f3952143-bf9e-4507-b3b9-6a769d36b9c3

event: message
data: {"result":{"protocolVersion":"2025-03-26",...},"jsonrpc":"2.0","id":1}

之后每个请求的行为：

请求	状态码	说明
POST 带正确 session	200，SSE 帧	正常
POST 缺 session	400	`-32000 Bad Request: Mcp-Session-Id header is required`
POST 带伪造 session	404	`-32001 Session not found`
POST 带 DELETE 过的 session	404	同上
GET 带 session（Accept: text/event-stream）	200	打开 SSE 流
GET 缺 session	400	同 POST
GET 带伪造 session	404	同上
DELETE 带 session	200	关闭会话
DELETE 缺 session	400	同一个 `-32000`
DELETE 重复一次	404	幂等失败语义

DELETE 是真实的：删完之后 session 立刻失效，再发任何东西都 404。规范里写「server MAY return 405」意思是「可以不支持 DELETE」，但 SDK 是支持 DELETE 的，所以 405 在这个实现里不会出现。

Mcp-Session-Id 的大小写：Node 的 HTTP 头不区分大小写，mcp-session-id 和 Mcp-Session-Id 等价。抓包时看到的是小写。

实验三：一个 `McpServer` 只接受一次 initialize

这是坑。

我用同一个 McpServer 实例、同一个 StreamableHTTPServerTransport，先让客户端 A initialize 拿到 s1，再让客户端 B initialize：

HTTP/1.1 400
{"jsonrpc":"2.0","error":{"code":-32600,
 "message":"Invalid Request: Server already initialized"},
 "id":null}

-32600 是 JSON-RPC 标准的 Invalid Request。文档里没写这一条，但 SDK 就是这么实现的——一个 server 实例只服务一个逻辑客户端。

多客户端的正确姿势是给每个会话建一个 transport，挂到同一个 endpoint 上：

const transports = new Map();

createServer(async (req, res) => {
  const sid = req.headers["mcp-session-id"];
  let transport;

  if (sid && transports.has(sid)) {
    transport = transports.get(sid);
  } else if (!sid && req.method === "POST") {
    // 新会话
    transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: () => crypto.randomUUID(),
      onsessioninitialized: (id) => { transports.set(id, transport); },
    });
    transport.onclose = () => {
      if (transport.sessionId) transports.delete(transport.sessionId);
    };
    await buildServer().connect(transport);   // buildServer() 返回新实例
  } else {
    res.writeHead(400); res.end(/* Bad Request */);
    return;
  }
  await transport.handleRequest(req, res);
}).listen(...);

这是 TypeScript SDK examples/ 里的标准模式。要点：

每个 transport 配一个独立的 McpServer 实例，不是共享。
onsessioninitialized 把新 session 注册进 Map，onclose 把它摘掉。
DELETE 触发 onclose，Map 自动清，不需要手动管过期。

实测两个会话同时存在、互不影响：s1 DELETE 之后 s2 还能 tools/call。

实验四：无会话模式（`sessionIdGenerator: undefined`）是半成品

不设 sessionIdGenerator 时：

initialize 200，Mcp-Session-Id 不下发（正确）；
tools/list 200（正确）；
GET 直接 500，没错误消息；
DELETE 直接 500，没错误消息。

规范说 server 可以返回 405 表明不支持 SSE stream / 不支持 DELETE。SDK 没这么做，500 是字面意义的「Internal Server Error」，客户端无法区分「服务器崩了」和「无会话模式不支持」。

如果一定要做无会话 server（比如内部网关只做 tool proxy），GET / DELETE 你自己在 HTTP 框架层面接住，返回 405 + Allow: POST，别放给 SDK。

实验五：JSON-RPC batch 的隐藏约束

标准 JSON-RPC 支持 batch（一个数组里多个请求）。SDK 支持 batch，但initialize 必须单独发：

POST /
Content-Type: application/json
Accept: application/json, text/event-stream

[
  {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}},
  {"jsonrpc":"2.0","id":2,"method":"tools/list"}
]

HTTP/1.1 400
{"jsonrpc":"2.0","error":{"code":-32600,
 "message":"Invalid Request: Only one initialization request is allowed"},
 "id":null}

但同一个会话上，batch 两个 tools/call 是合法的：

HTTP/1.1 200
Content-Type: text/event-stream

event: message
data: {"result":{"content":[{"type":"text","text":"echo:a"}]},...,"id":10}

event: message
data: {"result":{"content":[{"type":"text","text":"echo:b"}]},...,"id":11}

两个 SSE message 事件按序返回。这个行为对 client 有影响：你得同时按 id 分发响应，而不是按行序列化处理。

实验六：协议版本协商——传一个未来版本会怎么样

发 protocolVersion: "2999-01-01" 给 SDK 1.30.0：

HTTP/1.1 200
event: message
data: {"result":{"protocolVersion":"2025-11-25",...}}

不抛错，而是返回 server 支持的最新版本（1.30.0 是 2025-11-25）。客户端要不要再连下去，是它的事——规范允许这么干，但绝大多数 client 拿到不匹配的版本会直接断开。

发老版本 2024-11-05：

HTTP/1.1 200
data: {"result":{"protocolVersion":"2024-11-05",...}}

回的是老版本——server 降级接受了。注意响应头里没有 Mcp-Protocol-Version（这个头只对 2025-03-26 之后的版本才强制，老版本协商时不出现在响应头里）。

给 MCP Client 的五条硬规约

如果你要写一个能连上任意 MCP Server 的 client：

永远发 Accept: application/json, text/event-stream，少一项就 406。
永远单独发 initialize，不要 batch。
initialize 响应里如果有 Mcp-Session-Id，之后每个请求都带上（包括 GET、DELETE、notification）。
protocolVersion 用 client 支持的版本，不要写「最新」。server 可能接受也可能拒绝，看它版本新旧。
DELETE 之后再发请求会 404。client 应该捕获 404 + -32001 自动重新 initialize，不要让用户看见红色的错误。

给 MCP Server 的四条建议

每个会话一个 transport，每个 transport 一个 McpServer 实例——不要共享。
onsessioninitialized / onclose 必须实现，不然 session 表漏泄。
sessionIdGenerator 用 crypto.randomUUID()，不要自增。规范要求密码学安全。
无会话模式自己处理 GET / DELETE。SDK 默认 500 不友好，客户端会当故障处理。

边界

实验只测了 @modelcontextprotocol/sdk@1.30.0 的 Node 实现。Python SDK / Rust rmcp 行为不同（比如 rmcp 的 SessionId 是 UUID 类型，校验比 TS 严）。
没有测 SSE 流上的服务器主动推送（notifications/* 那条线）——本轮只用了 request/response，没有模拟 server 推送。
没有测 DNS rebinding / Origin 校验。SDK 有 enableDnsRebindingProtection 选项，默认开，但只在 stdio→HTTP 转发场景有意义。
错误消息可能随 SDK 版本变化。比如 -32001 Session not found 这个码不是 JSON-RPC 标准，是 SDK 自定义的——未来版本可能改。

更多 MCP / AI Agent 工具见 awesome-x-ops 的 AI Infra 分类。站内之前那篇 MCP 2026-07-28 实测：initialize 握手没了是从抓包看协议演进；这篇是从 SDK 行为看会话管理和状态机，两边对着看能拼出一个完整图景。

AI 生成的 E2E 测试能抓到真 bug 吗：5 个模型 41 个用例的变异实测

Sun, 20 Sep 2026 16:00:00 GMT

让模型写 E2E 用例，跑出来一片绿。问题在于「绿」本身不携带信息。我在一个真实的单页应用上注入了 8 个真缺陷，让 5 个模型各自生成 Playwright 用例，然后用变异检测的方式判断哪些用例真的在防回归。

结论先放这里：40 个在正确页面上能通过的用例里，5 个（12%）在整个实验里从未失败过一次；8 个缺陷里有 1 个只有 1 家抓到，其余 4 家全漏；用例数最多的模型花了 1.5 倍的输出 token，只多抓到 1 个缺陷。

环境与实验设计

网关：内网 OpenAI 兼容网关 https://aihub.firstshare.cn/v1，2026-09-21 实测，temperature=0，每个模型只生成一次。
运行：Playwright 1.63.0 + 系统自带的 Chromium 152。不下载 Playwright 自带浏览器，直接 launchOptions.executablePath 指向系统 chromium：

playwright.config.js

module.exports = defineConfig({
  testDir: "./specs",
  use: { headless: true, launchOptions: { executablePath: "/usr/bin/chromium" } }
});

被测页面：单文件 HTML，内联 JS，无框架，5.6 KB。包含登录（空字段时按钮禁用，admin / secret 通过）、成员表（12 条数据、每页 5 条、「共 N 条」计数、点姓名表头切换排序、按姓名搜索且大小写不敏感）、添加成员（新增后清空输入框）。
页面用 file:// 打开，整个实验没有任何常驻进程和监听端口。

8 个变异体，每个只改一行，都是外部可观察行为的改变：

ID	改动	可观察差异
m1	搜索去掉 `toLowerCase()`	搜 `ALICE` 由 1 条变 0 条
m2	`PAGE_SIZE = 5` → `10`	每页行数与「第 1 / 3 页」变化
m3	错误提示文案改掉	断言固定文案的用例失败
m4	添加成员后不清空输入框	输入框 value 变化
m5	排序开关失效，永远升序	首次点击表头不再变降序
m6	登录按钮不再按空字段禁用	`toBeDisabled()` 失败
m7	末页「下一页」不再禁用	边界态变化
m8	「共 N 条」改用全量数据	搜索后计数不更新

变异体和基线页面由脚本从同一份 app.html 做单点字符串替换生成，每个锚点在基线中唯一，改动内容可复核。

协议：把页面源码全文放进 prompt，要求输出单个 @playwright/test 文件，覆盖登录校验、登录成功、搜索、分页、排序、添加成员。生成时告诉模型应用在 http://localhost:3000/，跑之前只做一件事——把 spec 里的这个地址替换成本地 file:// 路径，其他一字不改。

判定：只有「在正确页面上通过、在该变异体上失败」的用例才算真的抓到了缺陷。基线就失败的用例不算击杀——它只是坏的用例碰对了。

结果

模型	用例	断言	击杀	漏掉	输出 token	生成耗时
MiniMax-M3	18	53	8/8	—	8502	44.6s
claude-sonnet-4-6	6	81	7/8	m1	7879	25.2s
deepseek-v4-pro	5	51	7/8	m1	10478	36.2s
deepseek-v4-flash	6	68	7/8	m1	11023	35.8s
qwen3.8-flash	6（5 个基线通过）	51	7/8	m1	5336	75.1s

m2 到 m8 这 7 个缺陷被 5 家全部击杀；唯一活下来的是 m1。5 家合计击杀 36/40。

唯一漏掉的缺陷：搜索的大小写

m1 的改动就是这一行：

// 基线
return m.name.toLowerCase().indexOf(keyword.toLowerCase()) >= 0;
// 变异体
return m.name.indexOf(keyword) >= 0;

只有 MiniMax-M3 写了这条用例，它也是整轮里唯一杀死 m1 的用例：

test("搜索应大小写不敏感", async ({ page }) => {
  await page.locator("#search").fill("ALICE");
  await expect(page.locator("#count-info")).toHaveText("共 1 条");
  await expect(page.locator(".cell-name").first()).toHaveText("alice");
});

另外 4 家都测了搜索，输入全是小写 alice。差异不在工具、不在框架、也不在覆盖率——5 家拿到的是同一份源码，toLowerCase() 就写在第 30 行。差的是模型有没有想到「用户会开着大写锁定敲搜索框，或者直接粘贴一段大写文本」。

这是 AI 生成用例最像人的地方：覆盖面取决于它的联想，而不是取决于被测代码里有什么。指望用覆盖率指标找出这种缺口是不行的，fill('ALICE') 和不写这条用例，行覆盖完全一样。

12% 的用例一个缺陷都没抓到

40 个有效用例里有 5 个在 8 个变异体上全部通过，意思是它们对「有没有被改坏」不敏感。典型例子：

test("两个字段都填写时登录按钮应启用", async ({ page }) => {
  await page.locator("#username").fill("admin");
  await page.locator("#password").fill("secret");
  await expect(page.locator("#login-btn")).toBeEnabled();
});

它断言的是一个从来没有被破坏的状态。这种用例进 CI 唯一的作用是让报告变长。注意它们的通过率是 100%，任何按「通过率」「用例数」来评价生成质量的看板都会给它满分。

基线就挂的用例：模型把数据数错了

qwen3.8-flash 有一条用例在正确页面上就失败：

await page.fill("#search", "a");
await expect(page.locator("#count-info")).toHaveText("共 6 条"); // 实际：共 7 条

页面里 12 个名字中含 a 的是 7 个（alice、carol、dave、frank、grace、ivan、mallory），模型数成 6 个。这条用例永远不可能变绿，但它会被算进「生成成功 / 用例数 +1」的统计里。

所以生成用例的第一道门禁只能是「在正确代码上全绿」，第二道才是「对已知缺陷失败」。顺序反过来，你会把坏用例当覆盖。

用例数量与断言密度

MiniMax-M3 用 18 个用例、8502 输出 token 换到 8 个击杀，其中 5 个用例从未失败。
claude-sonnet-4-6 用 6 个用例、81 个断言换到 7 个击杀，断言密度 13.5/用例；MiniMax 是 2.9/用例。
deepseek-v4-flash 用了 22 次 .nth(0) / .nth(4) 定位表格行。它能杀掉 m5（排序失效）靠的是断言内容，不是定位方式——一旦行序因为功能变化而改动，这 22 处会集体变成等待超时。

「多写用例」和「写深断言」不是同一件事。这一轮里，让击杀数上升的是后者。

为什么通过率不能当质量指标

根因是 test oracle 的位置。模型只能从源码推断「预期行为」，它写下的断言就是它对这份代码的理解。代码是错的，它就照着错的写断言——文献里把这叫「验证 bug 的测试」：一项针对商用与开源生成工具的研究（arXiv 2412.14137）发现，带过滤/自动修复机制的生成工具，最终套件里最多 68.1% 的用例会在错误实现上通过、在正确实现上失败。

另外两个对照，说明这个问题的量级不是本轮实验特有：

ACL 2026 Findings 的 SWE-Mutation 在单元测试上测了 7 个模型，最好的 DeepSeek-V3.1 相对检出率只有 36.15%；而且语义级变异体比规则变异体难杀得多（平均检出率 71.04% → 39.81%）。
本轮 E2E 的 90%（36/40）不能拿去和 36.15% 对比。这里每个变异体都改动了页面上的外部可观察行为，而 m8 那种「只改一句文案/计数」在单元测试里属于最容易杀的一档；而且模型拿到的是完整源码，是白盒。

真正可操作的部分是：用变异检测来验收这批用例。m8 只改了计数文案，覆盖率一点没变，通过率一点没变，只有变异检测能把它标出来。

落地清单

生成完用例先跑一次变异检测——手工注入 8 个一行改动就够，不需要引 Stryker 这类完整工具链。
门禁两条：基线全绿；对已知缺陷失败。两条都不满足的用例退回重写，不要合入。
断言写页面状态（计数、文案、行序、按钮禁用态），不要只写 happy path 的可点击/可见。
静态数据能数清的，让脚本生成期望值（如「共 N 条」按数据源算），不要靠模型心算——qwen 那条 共 6 条 就是这么挂的。
定位器优先 id / role / label；.nth(索引) 定位表格行的地方标记出来，排序或分页一改就是一批超时。

再用哪家的生成能力是次要问题：这一轮 5 家的差距在「有没有想到那条边界」上，而不在能不能写出可运行的 Playwright 代码——5 家的用例都能跑起来。

边界

单个页面、8 个 UI 级变异体、每个模型只生成一次、每个变异体只跑一次，没有做重复与 flaky 统计。
模型拿到完整源码（白盒）。只给需求文档的话，结果只会更差，但差多少没测。
file:// 打开页面，与真实 dev server 的差异在跨域和 fetch 上，本页没有这两类行为。
8 个变异体都至少被一家击杀过，所以集合里没有等价变异体（改行为但不改观察结果的那种）混入。
生成侧还有 2 家在本次调用里没跑通：glm 渠道返回 403 client_not_allowed，kimi-k3 拒绝 temperature=0（要求 temperature=1）。这两个是网关侧的接入约束，不代表模型能力。
m1 只被 1 家击杀，只说明这一次生成里另外 4 家没写这条用例，不代表它们写不出来。

测试与质量工具清单见 awesome-x-ops 的 Testing Tools 分类。站内相关：AI Code Review 横评——CodeRabbit vs PR-Agent vs Copilot Review 讨论的是生成之后谁来看的问题，这篇讨论的是生成出来的东西怎么验。

LLM 可观测性实测：OpenAI 兼容网关的 usage 靠不靠得住

Fri, 18 Sep 2026 16:00:00 GMT

把 LLM 成本看板建在客户端拿到的 usage 上，会错多少？我在这台内网 OpenAI 兼容聚合网关上跑了约 80 次调用，答案不是”有点误差”，而是字段缺失和语义不一致。

环境：一个 /v1/chat/completions 后面挂着多家的模型，2026-09-19 实测，temperature=0。同一个 20 字中文问题，非流式 max_tokens=256 打 5 个模型；流式另有 3 个模型 × 2 种参数 × 2 次重复的配对调用。全部用标准库 urllib 直连，限速 2.3s 避免打限流。

一、usage 里能拿到什么，5 个模型给出 5 套字段

请求模型	prompt_tokens	completion_tokens	其中 reasoning	正文长度	finish_reason
deepseek-v4-flash	55	133	108	35 字	stop
qwen3.8-flash	87	268	251	22 字	stop
glm-5.3	34	256	254	1 字	length
gpt-5.6-luna	29	68	38	33 字	stop
MiniMax-M3	198	256	256	0 字	length

三字段（prompt / completion / total）是唯一的不变量。其余全按供应商各自的习惯：

缓存命中：deepseek 报 prompt_tokens_details.cached_tokens，同时另报一组 prompt_cache_hit_tokens / prompt_cache_miss_tokens；qwen 在 prompt_tokens_details 里给 cached_tokens 和 text_tokens；MiniMax 只有 cached_tokens；gpt-5.6-luna 连 prompt_tokens_details 都没有。
推理 token 全都计入 completion_tokens。所以”输出 token”这个指标跨供应商不可比：同一句话 completion 从 68 到 268，其中 38～256 是推理。
MiniMax 额外回传 input_sensitive / output_sensitive / base_resp，还带一个 total_characters 字段——实测恒为 0，别拿它算字数。

glm-5.3 那一行值得单独看：256 token 预算里 254 个花在推理上，正文只出了 1 个字，finish_reason=length。它在 HTTP 层是 200 成功。

二、同一句话的 prompt_tokens 差 6.8 倍

上表第一列就是答案：gpt-5.6-luna 29，MiniMax-M3 198。

你没法用一个 tokenizer 离线估算全站成本。同一段文本的输入 token 数取决于路由到哪个供应商，还可能包含供应商自己追加的提示词（MiniMax 那 198 里，有 156 是服务端缓存命中，第一轮真实未命中约 42）。这也解释了为什么”按字符数估成本”在聚合网关下必然偏。

三、`stream_options.include_usage` 在这台网关上是个空操作

OpenAI 文档和各家云厂商文档的写法都是：流式下要加 stream_options: {"include_usage": true} 才能拿到 usage。

实测 12 次配对调用（deepseek-v4-flash / glm-5.3 / MiniMax-M3 × 加与不加 × 各 2 次），usage 块的个数、位置、内容完全一致。不加也一样有。

所以这段配置在这台网关上既没有收益也没有副作用。但结论不要外推：换成直连 OpenAI 或别家的网关，行为可能相反。判断方法是抓一次 SSE 流，数一下 usage 非 null 的块有几个，而不是读文档。

四、usage 出现在哪个块，4 种形态

模型	流式块数	前序块	usage 块
deepseek-v4-flash	66	65 块 `usage: null`	第 66 块，与 `finish_reason` 同块，没有独立 usage 块
qwen3.8-flash	31	30 块 `usage: null`	第 31 块，`choices: []`；`finish_reason` 在第 30 块
glm-5.3	19	18 块 `usage: null`	第 19 块，`choices: []`；`finish_reason` 在第 18 块
gpt-5.6-luna	38	37 块连 `usage` 键都没有	第 38 块，`choices: []`；`finish_reason` 在第 37 块
MiniMax-M3	5	4 块 `usage: {"total_tokens":0,"total_characters":0}`	第 5 块是真值，并带 `finish_reason`

同一批条件（max_tokens=64，temperature=0）。块数随生成长度变化，看的是 usage 落在哪里。

deepseek 把 usage 和 finish_reason 挤在同一块；另外三家在 finish_reason 之后再补一个 choices 为空的块。MiniMax 最阴：前面每一块都回传一个非 null、但全为 0 的 usage 对象。

这意味着”取第一个非空 usage”和”见到 usage 就认为请求结束”这两种常见写法，在 MiniMax 这条路径上记录下来的 token 数是 0。同时也不能把多块 usage 累加——那是把一次请求记成多次。

正确写法只有一条：取最后一份非空 usage。

usage, finish, content = None, None, []
for line in resp:                     # SSE 逐行
    if not line.startswith(b"data:"):
        continue
    payload = line[5:].strip()
    if payload == b"[DONE]":
        break
    d = json.loads(payload)
    u = d.get("usage")
    if u and u.get("total_tokens"):    # 跳过 MiniMax 的全 0 占位块
        usage = u                      # 只保留最后一份，不累加
    for ch in d.get("choices") or []:
        finish = ch.get("finish_reason") or finish
        content.append((ch.get("delta") or {}).get("content") or "")

五、客户端断连，这条请求的 token 就消失了

流式下收到 3 个内容块后客户端断开（模拟用户取消、前端切页、超时重试）：

deepseek-v4-flash: content 块 3 个, usage 块 0 个
qwen3.8-flash:     content 块 3 个, usage 块 0 个

本地一行 token 数都拿不到，而网关侧已经消耗了 prompt token 并生成了一部分内容。把成本真源放在应用日志上，误差就和”用户耐心”正相关——取消得越多，你看到的成本越低。

边界说明：我没有网关侧日志权限，无法验证这些断连请求在服务端是否照常计费。要验证得看网关自己的记账。

六、200 成功 + 空正文

把 max_tokens 压到 16：

deepseek-v4-flash: 正文 0 字, completion_tokens=16 (全为 reasoning), finish_reason=length
MiniMax-M3:        正文 0 字, completion_tokens=16 (全为 reasoning), finish_reason=length

MiniMax-M3 在 max_tokens=256 下也给出 content: "" 的 200 响应（推理吃光预算）。如果监控只有 HTTP 状态码和延迟，这一档请求全是”健康”的。

站内上一篇 Prompt 回归测试踩过同一颗雷：content 为空先看 finish_reason，别先怀疑 prompt。那次是回归台，这次是生产网关——同样的判断顺序。

七、前缀缓存按前缀失效，改开头等于全价

长 prompt（约 1122 token），同一模型连发 4 次：

变体	prompt_tokens	cached_tokens
原样第 1 次	1122	896
原样第 2 次	1122	896
只改结尾加一句	1140	896
只改开头加一个标记	1127	0

缓存是服务端自动做的，客户端不需要传任何参数。命中粒度是前缀长度，不是比例。

表里”第 1 次”其实已经不冷了——同一段前缀在前面的调用里出现过，缓存早已建立，所以第一次就是 896 命中。真正有信息量的是最后一行：改开头一个标记，命中归零。

工程含义直接：稳定内容（system prompt、长文档、规则）放前面，变量放后面。把动态内容拼在开头，等于每次全价。

八、响应体里的 model 不是请求的模型

请求 deepseek-v4-flash   → 响应 model: deepseek-flash
请求 deepseek-v4.1-flash → 响应 model: deepseek-flash
请求 deepseek-v4-pro     → 响应 model: deepseek-flash

三个不同价位的请求名，在响应体里合并成同一个字符串。按响应体 model 做成本归因，这条曲线就没有意义了——必须记请求侧的模型名，或者要求网关回传实际路由。

system_fingerprint 只有 deepseek 回传，qwen、glm、gpt-5.6-luna、MiniMax 都没有。想靠它检测”后端静默换版本”，在这台网关上不可行。

落地清单

流式取最后一份非空 usage，不累加、不用第一份，显式跳过全 0 占位块。
usage 缺失记 unknown，不要记 0。0 会把”断连”和”免费”混为一谈。
成本真源放网关或代理侧；应用日志只作参考，用来看影响面而不是算钱。
输出 token 拆成 reasoning / text 两个指标，跨供应商先分组再比。
finish_reason（尤其 length 占比）和空正文率进同一张看板。
成本归因按请求侧模型名，不按响应体。

边界

一台网关、5 个模型、约 80 次调用（含踩到 403 和解析 bug 的重跑）。不同网关的实现差异可能覆盖以上全部结论。
没测非 200 响应（429、超时）是否扣 token。
缓存命中只报了 token 数，没有代入单价，所以算不出省了多少钱。
MiniMax 的 prompt_tokens 偏高一部分来自供应商内部链路，具体构成拆不出来。
全部为单次观测加少量重复，没有做统计检验；上面的差异都是量级差异。

工具清单见 awesome-x-ops 的 LLM and Agent Observability 分类，那里面有采集和评测两端的开源选项。

Prompt 回归测试实测：同一份 prompt 在两个模型上错得不一样

Thu, 17 Sep 2026 16:00:00 GMT

「prompt 改好了」这句话，通常来自一次运行、一个模型、肉眼看输出。

我搭了一个 11 条告警日志的回归台，同一批用例跑 4 个 prompt 版本、2 个模型，共 198 次调用。主表是 deepseek-v4-flash，temperature=0.7，每题 3 次重复：

prompt 版本	调用	裸输出能 `json.loads`	满足契约	四字段全对
v1：只说「提取字段，用 JSON 输出」	33	31	0	0
v1b：v1 + error_type/severity 枚举取值域	11	11	2	2
v1c：v1 + 禁止 markdown 包裹	11	11	0	0
v2：工程化（取值域 + 类型 + 反例 + null 规则）	33	32	32	28（85%）

v1 是最常见的写法：31/33 次输出了合法 JSON，看着挺好。但没有一次满足下游契约——JSON 合法不等于能被消费。

（v1、v2 各 3 次重复；v1b、v1c 是消融版本，单轮 11 个样本。）

实验怎么搭的

任务：从告警日志里抽 4 个字段，契约长这样：

{ "service": "payment-api", "error_type": "OOM", "error_code": 137, "severity": "P1" }

service 是字符串或 null，error_type 限 7 个枚举值，error_code 是 int|null，severity 限 P0–P3。

11 条用例覆盖 OOMKilled exit 137、Metaspace 溢出、MySQL 死锁 1213、JWT 过期 401、上游 429、DNS no such host、gRPC DeadlineExceeded、ENOSPC errno 28、readiness 探针 503 等，期望值都是在日志文本里能定位的客观事实。

断言分三层，分别统计：

格式层：对原始输出做 json.loads，不先剥 markdown 代码块——下游解析器也不会剥。
契约层：字段名、类型、枚举值。
语义层：字段值是否等于期望。

控制变量：v1 与 v2 都是单条 user message，不动 system prompt，温度、max_tokens、模型固定。实验台只用 Python 标准库（urllib + ThreadPoolExecutor），先把数字算出来，再谈要不要上评测平台。

限流是设计的一部分：网关 30 req/min，本地把最小间隔设成 2.3 秒、并发 4，避免 429 重试拿回空输出——这类脏数据会记到 prompt 的账上，必须先按调用层噪声剔除。

发现一：两个模型的头号失败模式完全不同

同一份 v1 prompt 换模型：

	`deepseek-v4-flash`	`glm-5.3-flash`
v1 输出被 markdown 包裹	2/33	11/11
v1 能 parse	31/33	0/11
v1b（只加枚举取值域）能 parse	11/11	0/11
v1c（只禁 markdown 包裹）能 parse	11/11	11/11

glm-5.3-flash 的 v1 输出每一条都以 ```json 开头，deepseek 只有 2/33 这样。加一句「不要用 markdown 代码块包裹」，GLM 从 0/11 变 11/11；同一句话对 deepseek 几乎无事发生——它本来只有 2/33 被包裹，加完规则的 11 次里是 0 次。

反过来，只加枚举取值域（v1b），deepseek 的 error_type 准确率从 0/33 到 11/11；GLM 还是 0/11，因为输出仍被包裹，改的那部分根本没机会生效。

同一句话在两个模型上的边际收益差 100%。所以「优化 prompt」之前先做一件事：按失败模式分类统计现有输出，再决定改哪一句。

顺带一个反例：GLM 的 v1b 有 1 次在 JSON 前加了一行 ## 分析结果（包裹率 10/11，不是 11/11）。用宽松正则清洗模型输出只能对付已知模式；真正的护栏是让模型不产生这类输出。

发现二：修好一处，弄坏另一处

v1b 把 error_type 修到 11/11，同时把 error_code 从 v1 的 13/33 打到 2/11。

原因不在枚举，在类型。契约要求 int|null，v1 的 c01 输出数字 137，v1b 输出字符串 "137"。同一模型、同一用例，只多了一条枚举约束。

v1b 的 11 次 error_code 实际输出：

c01 "137"  c05 "1213"  c06 "401"  c10 "28"  c11 "503"    ← 数字被序列化成字符串
c02 "java.lang.OutOfMemoryError: ..."   c03 "Metaspace"   ← 文本塞进数值字段
c08 "NO_SUCH_HOST"  c09 "DeadlineExceeded"
c04 null   c07 429                                         ← 只有这两次满足契约

契约写的是 int|null，"137" 就是违约。判定在 Python 侧做（isinstance(obj["error_code"], int)），强类型客户端我没跑——但 JSON 契约里的类型不是可以商量的事。

而只看「模型答得对不对」，这 11 次里 service、error_type 几乎全对，很容易签字通过。

这就是 prompt 变更必须过回归的原因：改动的副作用不是局部的。模型的注意力是共享资源，你在「枚举值必须从这 7 个里选」上加了约束，它就可能把这份「照规矩输出」的理解挪到别的字段上，顺手把数字加了引号。单看一遍输出发现不了，因为两边的输出都很「像样」。

发现三：temperature=0 不代表可复现

v2 在 temperature=0 下每题采样 4 次，temperature=0.7 下每题 3 次（P=通过，F=失败）：

用例	T=0（4 次）	T=0.7（3 次）
c04 JDBC 连接失败	P F P P	P F P
c05 MySQL 死锁 1213	F P P F	F P P
c07 上游 429	F F P F	F F F
其余 8 条	4/4 全过	3/3 全过

temperature=0 下依然有 3 题判决翻转，但原因各不相同，不能都算在模型头上：

c04 在 T=0.7 的那次 F 是 content 为空、finish_reason=length——输出被 max_tokens 截断，调用层噪声。
c04 在 T=0 的那次 F 是正常结束（stop），模型把 DB 连接失败判成了 TIMEOUT——模型自身的不确定性，同时暴露用例有歧义：Communications link failure 读成超时也说得通，期望值是按「根因是数据库连接」写死的。
c05 的 F 是漏取 1213，error_code 填了 null。
c07 是我的用例写错了。日志里同时写了 upstream search-api returned 429 和 client search-web 触发限流，两种理解都成立，期望值只认 search-api；默认 max_tokens 下 7 次采样里 6 次判给了 search-web。

处理方式是改用例文本、把服务归属写死，不是放宽断言。放宽断言就是把门禁改成常绿——它从此再也拦不住真的回归。

发现四：推理模型的思维链也算在 max_tokens 里

同一批用例、同一份 v2 prompt，把 max_tokens 从 8192 降到 2048 再跑 11 次：

finish_reason=length  6/11，这 6 次 content 全是空字符串
reasoning token 其中 5 次恰好停在 2048 上限，1 次 2047
通过 5/11：截断的 6 题全挂，没截断的 5 题全过（同批单轮基线 9/11）

不是模型不会答，是思维链把预算吃完了。默认 8192 下的 143 次 deepseek 调用，平均每次 2398 token，其中思维链 2029，占 84.6%，平均延迟 9.6 秒。4 个字段的抽取任务，钱主要花在推理上。

这也直接给出回归频率的算法：一轮 11 题 × 3 次 = 33 次调用、约 7.9 万 token，进 CI 不心疼；用例集涨到 200 条就是 600 次调用、约 144 万 token 一轮，那时要决策的不是跑不跑，是多长时间跑一次。

排错顺序记住一条：content 为空先看 finish_reason，别先怀疑 prompt。

顺带一个观测口径的坑：同一个网关下 glm-5.3-flash 的 44 次调用里 reasoning_tokens 字段完全缺失（不是 0），平均 1352 token。拿 deepseek 的口径去套 GLM 的成本估算会错。

落地：一个最小回归台

prompt-regression-lab/
├── cases.py          # 用例：日志文本 + 期望值（客观事实）
├── prompts/
│   ├── v1.txt        # 每个版本一个文件，Git 就是 prompt 的版本历史
│   └── v2.txt
├── plan.json         # 跑哪些 (model, version, temperature, repeats)
├── run.py            # 执行 + 限流 + 判定
└── analyze.py        # 按层聚合：parse / 契约 / 语义 / 漂移

run.py 判定部分的精简版：

def judge(raw, case):
    r = {"parse_ok": False, "schema_ok": False, "pass": False}
    try:
        json.loads(raw.strip())        # 不剥 markdown 包裹
    except Exception:
        return r                       # 格式层直接判负
    obj = json.loads(raw.strip())
    r["parse_ok"] = True
    r["schema_ok"] = (
        set(obj) == {"service", "error_type", "error_code", "severity"}
        and obj["error_type"] in {"OOM", "DB", "AUTH", "NETWORK", "TIMEOUT", "RATE_LIMIT", "OTHER"}
        and (obj["error_code"] is None or isinstance(obj["error_code"], int))
        and obj["severity"] in {"P0", "P1", "P2", "P3"}
    )
    r["pass"] = r["schema_ok"] and obj["service"] == case["service"] \
        and obj["error_type"] == case["error_type"] and obj["error_code"] == case["error_code"]
    return r

v2 里真正干活的是两段规则（节选，示例部分省略）：

# 取值规则
- service：出错服务的名字。pod 名要去掉 ReplicaSet hash 后缀（payment-api-7d9f4c8b6-x2knp → payment-api）
- error_type 只能取以下之一：OOM | DB | AUTH | NETWORK | TIMEOUT | RATE_LIMIT | OTHER
- error_code：只填日志中明确出现的 HTTP 状态码、进程 exit code 或 errno 数值；没有就填 null
  端口号、耗时毫秒数、行号、重试次数都不是 error_code
- 一条日志里出现多个错误时，填离根因最近的那个

# 硬性约束
- 回复的第一个字符必须是 {，最后一个字符必须是 }
- 不要用 markdown 代码块包裹，不要输出解释、注释或任何前后缀

这些规则不是凑数：v1 的 33 次里 severity 出现过 7 种写法（critical 17 / warning 8 / WARN 3 / ERROR 2 / CRITICAL 1 / error 1 / high 1），0/33 命中 P0–P3；v1 有 2/33 次把 StatefulSet 的 log-collector-0 原样返回；error_code 在 v1 和 v1b 里都出现过用文本填数值字段（GC overhead limit exceeded、no such host、DeadlineExceeded）。规则不写死，模型就按自己的常识补。

v2 是「一次改到位」的版本，我只对枚举取值域、禁 markdown 包裹做了单条消融，其余几段的收益没有单独归因——把它们从 v2 里拆出来再跑一遍才知道谁在干活。

断言分层与门禁

字段类型	断言方式	失败时先改什么
格式层（能否 parse）	严格	prompt：禁 markdown 包裹、禁前后缀
契约层（类型、枚举）	严格	prompt：写死取值域，写明类型
自由文本（`service`）	严格，但期望值必须无歧义	先用例文本，再 prompt
主观字段（`severity`）	只校验枚举，不做精确断言	不进门禁

门禁三条：

单次运行不下结论。 看「k 次重复全过」的题数，不看单次 pass 率。本次 v2 在 T=0 和 T=0.7 下都是 11 题里 8 题全过，两个温度的数字一样，而中间有 3 题在翻转。
锁定子集零容忍。 挑 5–8 条确定性最强的用例，任何一次失败就拦；其余用例看 k 次全过率。规则简单到没人会想去绕过它。
失败分类先于归因。 把 finish_reason=length、空 content、限流失败先归成调用层噪声，再统计 prompt 指标。

边界

只测了两个模型、一类任务（日志字段抽取）。跨任务、跨模型的推广是推测，不是结论。
v1b、v1c 各只跑了 1 轮（11 个样本）；GLM 每个版本也只有 1 轮，只能看模式差异（包裹率 11/11 与 0/11），看不出漂移。但 parse 0/11 与 11/11、error_code 13/33 与 2/11 这种量级的差别，不需要统计检验。
T=0 的 4 次采样跨了两个批次（1 + 3），批次间波动没能单独分离。
没测 seed 参数；没有验证同一模型名背后被换版本造成的漂移。
11 条用例的规模测不出 3 个百分点级别的改进——那需要上百条用例和更多重复次数。
全部调用走同一个 OpenAI 兼容网关，自部署推理栈的数值不确定性未验证。

结论

prompt 变更的风险不在「这次改得对不对」，在「这次改动的影响是不是局部的」。v1b 修好 error_type 的同时打断 error_code，单次目测看不出来——只有 k 次重复的分层回归能把它变成一条红色断言。

站内早前的 AI Code Review 横评有一致的坑：AI 审查输出的格式漂移比判断错误更难发现。prompt 版本管理、评测集与回归门禁的工具清单，见 awesome-x-ops 的 LLM and Agent Observability 分类。

MCP 2026-07-28 实测：initialize 握手没了，老客户端还能连吗

Mon, 14 Sep 2026 16:00:00 GMT

2026-07-28 这一版 MCP 把 initialize 握手删了。协议版本不再是”协商一次、存在连接里”的状态，而是每个请求自己在 _meta 里声明；server 则必须实现 server/discover。

实测下来四件事：

老客户端（官方 v1 SDK @modelcontextprotocol/sdk@1.29.0，LATEST_PROTOCOL_VERSION = '2025-11-25'）不做探测，首包永远是 initialize。
新客户端（mcporter@0.13.10，依赖 v2 的 @modelcontextprotocol/client@2.0.0）先发 server/discover，拿到非 modern 错误就回退 initialize。只认老协议的 server 不用改，照样能被新客户端用。
老客户端撞上只支持 2026-07-28 的 server 会直接失败。它没有”向前兼容”机制，只能人肉改。
最容易翻车的不是版本号，是缓存字段：tools/list 漏 ttlMs / cacheScope，v2 客户端直接判定整个结果非法。

先确认手上的包属于哪一代

# v1 线：还是 initialize 握手
node -p "require('@modelcontextprotocol/sdk/package.json').version"
node -p "require('@modelcontextprotocol/sdk/dist/cjs/types.js').LATEST_PROTOCOL_VERSION"

# v2 线：实现 2026-07-28
node -p "require('@modelcontextprotocol/server/package.json').version"

本机实测值（Node 26.3.0）：

包	版本	协议
`@modelcontextprotocol/sdk`	1.29.0	`LATEST_PROTOCOL_VERSION = '2025-11-25'`，SUPPORTED 一路到 `2024-10-07`
`@modelcontextprotocol/core` / `server` / `client`	2.0.0	2026-07-28，v2 是官方 README 里写明的 stable release line
`mcporter`	0.13.10	依赖 `@modelcontextprotocol/client@^2.0.0`

同一台机器上两代 SDK 并存，这就是断层。

协议到底改了什么

	legacy（≤ 2025-11-25）	modern（2026-07-28）
版本声明	`initialize` 协商一次，结果算连接状态	每个请求 `_meta["io.modelcontextprotocol/protocolVersion"]`
能力	握手时交换一次	每个请求带 `clientCapabilities`（MUST）
开场	`initialize` → `notifications/initialized`	可选 `server/discover`，但 server MUST 实现
结果结构	`{content, isError}`	`resultType: "complete"`，且 `*/list`、`resources/read` 必须带 `ttlMs` + `cacheScope`
版本不匹配	协商降级	`-32022` 附 `data.supported` 列表，客户端换版本重试

为什么要这么改：握手把”我们说的是哪个协议”变成了连接状态，于是任何要水平扩展的部署都得处理会话粘滞——多副本、serverless、中间的负载均衡和代理都得记住”这条连接协商过什么”。改成每请求自带元数据后，请求可以落在任意副本上；规范还明确允许 tools 集合随请求里的授权上下文变化（同一台 server 对不同 token 返回不同工具集），因为授权本来就是请求级输入，不是连接级状态。代价是所有实现方都得改一遍。

抓包：真实客户端到底发什么

MCP Inspector 只能当客户端用，看不到真实客户端的报文。写一个三十行的 stdio 透传代理就能抓：

// tap.mjs —— node tap.mjs --log /tmp/x.ndjson -- <server-cmd> [args...]
import { spawn } from "node:child_process";
import { createWriteStream } from "node:fs";

const argv = process.argv.slice(2);
const log = createWriteStream(argv[argv.indexOf("--log") + 1], { flags: "w" });
const sep = argv.indexOf("--");
const [cmd, ...args] = argv.slice(sep + 1);
const child = spawn(cmd, args, { stdio: ["pipe", "pipe", "inherit"] }); // stderr 透传，别吞
const meta = (dir) => (msg) => log.write(JSON.stringify({ dir, msg }) + "\n");
const safe = (line) => {
  try {
    return JSON.parse(line);
  } catch {
    return { _raw: line };
  }
};

process.stdin.on("data", (c) => {
  c.toString()
    .split("\n")
    .filter(Boolean)
    .forEach((l) => meta("c2s")(safe(l)));
  child.stdin.write(c);
});
process.stdin.on("end", () => child.stdin.end());
child.stdout.on("data", (c) => {
  c.toString()
    .split("\n")
    .filter(Boolean)
    .forEach((l) => meta("s2c")(safe(l)));
  process.stdout.write(c);
});
child.on("exit", (code) => process.exit(code ?? 0));

两个细节：stderr: 'inherit' 让 server 的日志照常输出但不进协议通道；解析不了的行记成 _raw，脏输出不会静默丢掉。

用法是把客户端配置里的 command 指向代理，server 端一行都不用改：

{
  "mcpServers": {
    "era-lab": { "command": "/tmp/mcp-era-lab/tapped-dual.sh" }
  }
}

新客户端连一台只认老协议的 server，抓到的就是这套流程（报文截断显示）：

c2s {"jsonrpc":"2.0","id":"server-discover-probe-1","method":"server/discover",
     "params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28", ...}}}
s2c {"jsonrpc":"2.0","id":"server-discover-probe-1",
     "error":{"code":-32601,"message":"method not found: server/discover"}}
c2s {"method":"initialize","params":{"protocolVersion":"2025-11-25", ...},"jsonrpc":"2.0","id":0}
s2c {"jsonrpc":"2.0","id":0,"result":{"protocolVersion":"2025-11-25",
     "capabilities":{"tools":{}},"serverInfo":{"name":"era-legacy","version":"1.0.0"}}}
c2s {"jsonrpc":"2.0","method":"notifications/initialized"}
c2s {"method":"tools/list","jsonrpc":"2.0","id":1}
s2c {"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"echo", ...}]}}

探测请求的 id 是 server-discover-probe-1，回退规则照规范实现：DiscoverResult → 认定 modern；-32022 这类已定义的 modern 错误 → 认定 modern，用 supported 里的版本重试，不回退 initialize；其他错误或超时 → 认定 legacy，回退握手。

这里最反直觉的是回退判据：不能只认某个错误码。老 server 对未知方法回的是实现自定义的错误（常见 -32601 / -32602），也可能干脆不回复。判错一次，你就把”版本不匹配”误当成”这是一台老 server”，然后在一个只支持新协议的 server 上反复发 initialize。

同一台新客户端连 dual-era server，initialize 在抓包里出现 0 次：

c2s server/discover  (_meta: 2026-07-28)
s2c result {resultType:"complete", supportedVersions:["2026-07-28"],
            capabilities:{tools:{}}, ttlMs:3600000, cacheScope:"public"}
c2s tools/list       (_meta: 2026-07-28)
s2c result {resultType:"complete", tools:[...], ttlMs:3600000, cacheScope:"public"}

而 v1 SDK 写的客户端连同一台 server，首包永远是 initialize，没有任何探测：

c2s {"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},
     "clientInfo":{"name":"legacy-client","version":"1.0.0"}},"jsonrpc":"2.0","id":0}
s2c {"jsonrpc":"2.0","id":0,"result":{"protocolVersion":"2025-11-25","capabilities":{"tools":{}},
     "serverInfo":{"name":"era-dual","version":"1.2.0"}}}
c2s {"method":"notifications/initialized","jsonrpc":"2.0"}
c2s {"method":"tools/list","jsonrpc":"2.0","id":1}
s2c {"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"echo", ...}]}}   ← 注意：没有 resultType

两代客户端的开场方式不同，server 端必须两种都认。

dual-era Server 的分流规则

只有一条规则：客户端怎么开场，就按哪一代语义服务。

if (method === "initialize") {
  // legacy 开场：协商出协议版本，本进程后续按 legacy 语义回复
  // （结果不带 resultType，也不带缓存字段）
  return legacyResult(id, {
    protocolVersion: pick(params.protocolVersion),
    capabilities: { tools: {} },
    serverInfo: SERVER
  });
}

const metaVersion = params._meta?.["io.modelcontextprotocol/protocolVersion"];
if (metaVersion !== undefined) {
  if (!MODERN_SUPPORTED.includes(metaVersion)) {
    return fail(id, -32022, "Unsupported protocol version", { supported: MODERN_SUPPORTED, requested: metaVersion });
  }
  if (params._meta["io.modelcontextprotocol/clientCapabilities"] === undefined) {
    return fail(id, -32602, "missing required _meta field: io.modelcontextprotocol/clientCapabilities");
  }
}

两个我实际写错过的地方：

clientCapabilities 是 MUST。 第一版我只校验了 protocolVersion，一个只有版本字段的请求本该被拒：

{"jsonrpc":"2.0","id":2,"error":{"code":-32602,
 "message":"missing required _meta field: io.modelcontextprotocol/clientCapabilities"}}

legacy 分支的结果别带 modern 字段。 我实测老客户端对多余字段是宽容的：在 legacy 结果里混入 resultType，v1 SDK 照常解析出 callTool = {"content":[...],"isError":false}。但那是运气不是保证，按分支给对应结构更省事。

initialize 的拒绝方式也有讲究。modern-only server 收到 initialize，规范建议把支持的版本写进错误信息——老客户端没有 fall-forward 机制，错误文本是用户唯一能看到的诊断：

{"jsonrpc":"2.0","id":3,"error":{"code":-32601,
 "message":"initialize is not supported by this server; supported protocol versions: 2026-07-28"}}

v1 SDK 客户端拿到后原样抛出：

FAILED: McpError | MCP error -32601: initialize is not supported by this server; supported protocol versions: 2026-07-28

真正会卡住你的坑：`*/list` 必须带缓存字段

dual-era server 跑通了，但 v2 客户端一上来就把 tools/list 判成非法：

"error": "Invalid result for tools/list: [
  {\"expected\":\"number\",\"code\":\"invalid_type\",\"path\":[\"ttlMs\"],
   \"message\":\"Invalid input: expected number, received undefined\"},
  {\"code\":\"invalid_value\",\"values\":[\"public\",\"private\"],\"path\":[\"cacheScope\"],
   \"message\":\"Invalid option: expected one of \\\"public\\\"|\\\"private\\\"\"}
]"

规范原文的要求是：server/discover、tools/list、prompts/list、resources/list、resources/templates/list、resources/read 返回的 resultType: "complete" 结果 MUST 带 ttlMs 和 cacheScope，后者只能是 "public" 或 "private"。

我一开始只在 server/discover 里带了这两个字段——它们语义上属于”缓存协商”，直觉上只跟发现阶段有关。补到每个 list 结果之后，v2 客户端立刻 "status": "ok"，tools/call 也正常返回。

这里没有渐进降级：字段缺失等于整个结果被拒，现象是”客户端拿不到工具列表”，而 server 日志里一行错误都没有。要定位这种问题，只能从客户端侧看原始错误。

顺带一句，cacheScope 不是随手填的值。"public" 意味着结果可能被客户端或共享网关跨授权上下文复用。tools/list 如果按调用者权限过滤过，必须 "private"——否则不同 token 之间会互相看到工具集。

一个被说反了的常识：脏 stdout

“MCP server 往 stdout 写一行日志就会崩”——我实测没崩。让 server 启动时先 console.log("era-legacy 启动中，正在加载配置...")，v1 SDK 客户端和 mcporter（v2 客户端）都忽略了这行脏数据，照常连接、列工具、调用工具。在 tap 的原始记录里它就是一条解析失败的行：

{"dir":"s2c","msg":{"_raw":"era-legacy 启动中，正在加载配置..."}}

正确的结论不是”可以往 stdout 写日志”，而是别指望客户端替你兜住。规范写得很直白：stdout 只允许出现合法的 MCP 消息，stderr 才是日志通道（MAY write UTF-8 strings to stderr for any logging purposes）。我这台机器上的两代 SDK 恰好都跳过了脏行，但社区里已经有宿主因为 server 的 stdout 噪音直接报 Invalid JSON-RPC messages。把日志写 stderr，成本是零。

边界

全部在 stdio 传输下实测。Streamable HTTP 的版本协商走 MCP-Protocol-Version 请求头，回退判据是 400 Bad Request 响应体里有没有 modern 错误——我没有部署 HTTP server，这部分只读了规范，未实测。
客户端侧只覆盖了官方 v1/v2 SDK 和 mcporter 0.13.10。Claude Code、Claude Desktop 这类宿主没在本机验证；规范对探测与回退用的是 SHOULD / RECOMMENDED，不是 MUST，各家实现可能有差异。
缓存字段我按规范填的是保守值，没有做缓存命中率或 TTL 的实测。

所以现在怎么做

server 端写 dual-era：initialize 和每请求 _meta 都认，直到确认所有客户端都能说 modern。分流成本就是一次判断，不需要维护会话状态。
升级 SDK 前先抓一次真实流量：一个透传代理比读文档快得多——你的客户端发不发 server/discover、协商到哪个版本，抓一次就有答案。
别依赖会话状态：modern 语义下版本、能力、授权上下文都随请求走。任何”握手时记住的东西”，在切到 modern 的那天都会失效。

MCP 的分层结构与三大原语见站内早前的 MCP 协议深度解析；MCP Server 与 Agent 工作流相关工具清单在 awesome-x-ops。

K8S 集群平滑迁移：Service + 手工 EndpointSlice 跨集群引流

Sun, 02 Aug 2026 03:00:00 GMT

背景

多集群迁移（机房搬迁、集群升级）的难点在于：新集群是从零搭的，Pod 不会一下子全就绪。要是直接把流量切过去，没就绪的服务会把调用全打失败。微服务之间靠 Service 做服务发现，迁移期间整条调用链不能断。

思路

Service 是流量入口（ClusterIP + DNS），EndpointSlice 决定流量转发到哪。流量并不要求转发目标一定在本集群——EndpointSlice 里写任何可达的 IP:Port 都行。

所以做法是：新集群的 Service 先通过手工 EndpointSlice 把流量导到老集群，等服务逐个就绪再切回来。

调用方 Pod (新集群)
   │  order-service.default.svc.cluster.local
   ▼
Service ClusterIP ─▶ EndpointSlice(手工) ─▶ 老集群 NodeIP:NodePort ─▶ 老集群 Service ─▶ 老集群 Pod

比 ExternalName（DNS CNAME，有缓存，同一个 Service 没法同时指两个集群）和改调用方配置（要发版）都省事。

Step 1：老集群 Service 开 NodePort

ClusterIP 只在本集群内可达，跨集群要用 NodePort。

apiVersion: v1
kind: Service
metadata:
  name: order-service
  namespace: default
spec:
  selector:
    app: order-service
  type: NodePort
  ports:
    - name: http
      port: 8080
      targetPort: 8080
      nodePort: 30080

两个注意点：

保持默认 externalTrafficPolicy: Cluster，请求可以转发到集群内任意 Node 上的 Pod，不用管 Pod 落在哪个节点。
新集群的节点要能访问老集群节点的 内网IP:30080（内网/专线/VPN，安全组放行），迁移期间这条链路不能断。

Step 2：新集群建同名 Service，不带 selector

name 和 namespace 跟老集群保持一致，调用方域名不变，代码不用动。

apiVersion: v1
kind: Service
metadata:
  name: order-service
  namespace: default
spec:
  type: ClusterIP
  ports:
    - name: http
      port: 8080
      targetPort: 8080
  # 故意不写 selector。带 selector 的 Service 会被 kube-controller-manager
  # 自动生成并接管 EndpointSlice（带 ownerReference），手工创建的同名 EndpointSlice 会被覆盖。

不带 selector，controller 就不介入，EndpointSlice 完全由我们控制。

Step 3：手工创建 EndpointSlice 指到老集群

apiVersion: discovery.k8s.io/v1
kind: EndpointSlice
metadata:
  name: order-service-proxy-old-cluster
  namespace: default
  labels:
    kubernetes.io/service-name: order-service
addressType: IPv4
ports:
  - name: http
    protocol: TCP
    port: 30080
endpoints:
  - addresses: ["10.1.2.3", "10.1.2.4"]
    conditions:
      ready: true

kubernetes.io/service-name 这个 label 必须和 Service 同名，Service 靠它关联 EndpointSlice。
没有 ownerReference，controller 不会自动删，直到我们手动删。
Node IP 全写上，kube-proxy 会做负载均衡；只写一个也行，挂了会自动重试。

Step 4：验证

kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- \
  curl -v http://order-service.default.svc.cluster.local:8080/health

在新集群里能跑通这个，说明引流成功，这时新集群的调用方流量全走老集群。

Step 5：切流量

新集群 Pod 全部 ready 之后：

给 Service 补上 selector，controller 生成指向新 Pod 的 EndpointSlice。新旧两套并存，流量被分流。

kubectl patch svc order-service --type=json \
  -p='[{"op":"add","path":"/spec/selector","value":{"app":"order-service"}}]'

看新 Pod 的日志和监控，确认正常处理流量。
删掉指向老集群的 EndpointSlice，流量全切过来。

kubectl delete endpointslices order-service-proxy-old-cluster

Step 5 全程没有断点：切之前流量全在老集群，切的时候有一段两边并存的窗口，出问题随时补回手工 EndpointSlice 就能回滚。

Step 6：收尾

老集群把 NodePort 撤掉（改回 ClusterIP 或直接删），迁移完成。

灰度

EndpointSlice 本来就能同时写老集群和新集群的地址。不靠 selector，把新集群 Pod IP 按比例加进手工 EndpointSlice 也行，观察指标再全量。缺点是 Pod IP 会随重启变化，得手动维护，所以一般还是用 selector 那套。上面 Step 5 借 selector 做了一次现成的全量切换。

注意事项

Service 别带 selector，最容易踩的坑。
迁移是逐步的，老集群的调用方不受影响，老集群服务在撤 NodePort 前一直正常。
这只解决流量层，数据/存储要单独迁。
调用方如果缓存了 Service 地址，切完要重建；正常情况 ClusterIP 和 DNS 全程不变。

AI Code Review 横评——CodeRabbit vs PR-Agent vs Copilot Review

Mon, 13 Jul 2026 14:00:00 GMT

AI 写代码是热点，AI 审代码才是刚需。人工 Code Review 三个痛点：响应慢（等同事有空）、质量不稳（看人看心情）、覆盖率低（只审改动的 30%）。AI Code Review 解决的不是”替代人审”，是每次 PR 都有一致标准的先行审查——人等会累，机器不会。

更多 AI 开发工具见 awesome-x-ops AI Coding 分类。

三款工具一句话

工具	定位	一句话
CodeRabbit	全托管 SaaS	「AI 审查 + 对话式修正 + 自动摘要」的无脑一体化方案
PR-Agent	开源可自托管	「各种 AI Provider 随便换」的审查框架，Codium 出品
Copilot Review	GitHub 原生	「点一下就有」的零配置审查，但能力还在长

维度 1：集成方式

CodeRabbit：GitHub App + SaaS

CodeRabbit 是托管服务。安装 GitHub App → 授权仓库 → 开 PR → 自动审。不需要 CI runner，不需要管理 token。

# .coderabbit.yaml — 唯一的配置入口
reviews:
  auto_review:
    enabled: true
    drafts: false
  poem: false # 关掉那个烦人的诗
  path_instructions:
    - path: "**.go"
      instructions: "检查 error 是否被正确处理，context 是否正确传递"
    - path: "db/migrations/**"
      instructions: "检查是否有破坏性变更，reviewers: @dba-team"

优点：零运维，摘要生成（PR Summary）质量好。缺点：数据离仓，内部代码谨慎用。

PR-Agent：CLI + GitHub Action

PR-Agent 本质上是一个命令行工具 pr-agent，提供两种使用方式：

# 方式 1：CLI 主动调用
pr-agent --pr_url=https://github.com/org/repo/pull/42 review

# 方式 2：GitHub Action 自动触发

.github/workflows/pr-agent.yml

name: PR-Agent Review
on:
  pull_request:
    types: [opened, synchronize]
permissions:
  pull-requests: write
  contents: read
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: Codium-ai/pr-agent@v0.26
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CONFIG.MODEL: "gpt-5"
          PR_REVIEWER.EXTRA_INSTRUCTIONS: |
            重点关注：SQL 注入风险、N+1 查询、未处理的 error
          PR_DESCRIPTION.ENABLE: true
          PR_REVIEW.INLINE_CODE_COMMENTS: true

优点：可自托管，Provider 随便换（OpenAI / Azure / Bedrock / 本地 Ollama）。缺点：需要自己维护 runner 和 API key。

Copilot Code Review：GitHub 原生按钮

GitHub Copilot Code Review 目前提供两种模式：

PR 页面点击「Copilot Review」按钮 — 手动触发
Copilot Workspace — 自动触发（需 waitlist）

没有 yaml 配置，没有自定义指令，就是点一下。审完输出评论列表。

优点：零配置，GitHub 原生。缺点：控制力最弱，只支持 GitHub，功能还在快速迭代中。

维度 2：审查深度实测

我拿同一个 PR（包含 SQL 注入风险、N+1 查询、未处理的 error、拼写错误）分别让三款工具审，结果如下：

发现项	CodeRabbit	PR-Agent	Copilot Review
SQL 注入风险	✅ 指出 + 修复建议 + CWE 编号	✅ 指出 + 修复建议	⚠️ 只提示「拼接 SQL」
N+1 查询	✅ 识别循环内查询	✅ 识别并给出批量查询方案	❌ 未发现
未处理 error	✅ 指出	✅ 指出	✅ 指出
拼写错误	✅	❌	❌
代码风格不一致	✅ 指出	✅ 指出 + 建议	❌
误报	1 处（误判 dead code）	0	0

CodeRabbit：最全面但有噪音

CodeRabbit 审得最细——拼写检查、许可证声明检查、CWE 安全映射都做了。但也产生了误报：把一个条件编译的 fallback 路径标为「可能不可达」，需要人工忽略。

它的 path_instructions 机制是杀手功能：你可以针对不同目录、不同文件类型给 AI 不同的审查重点。比如 db/migrations/** 检查破坏性变更，**.go 检查 error handling。

PR-Agent：精准但依赖模型质量

PR-Agent 换不同模型结果差异明显。用 GPT-5 审出来 5 个有效问题，换 DeepSeek-V3 只审出来 3 个，SQL 注入风险漏了。结论：PR-Agent 的上限取决于你用什么模型。

它的 PR_REVIEWER.EXTRA_INSTRUCTIONS 等价于 CodeRabbit 的 path_instructions，但粒度更粗——只能给全局指令，不能按文件路径区分。

Copilot Code Review：能用但不够深

Copilot Code Review 能发现明显问题——未处理的 error、拼接 SQL。但 N+1 查询、代码风格这类需要上下文理解的问题，它目前覆盖不到。

维度 3：审查速度

工具	小型 PR（<100 行）	中型 PR（100-500 行）	大型 PR（>500 行）
CodeRabbit	30s-1min	1-3min	3-8min
PR-Agent (GPT-5)	20s-40s	1-2min	3-5min
Copilot Review	10s-30s	30s-1min	1-3min

Copilot 最快但审得最浅。CodeRabbit 最慢但最全。PR-Agent 速度受模型 API 延迟影响——用 Azure OpenAI 比用 OpenAI 直连快 30%。

维度 4：审查结果交互

CodeRabbit：对话式

CodeRabbit 的审查结果是对话线程——每条评论你都可以回复追问。比如它标记了一个「潜在 SQL 注入」，你可以回复「给出修复代码」，它会在同一线程下给完整修复。

CodeRabbit Bot: ⚠️ 第 42 行：使用字符串拼接构造 SQL 查询（CWE-89）
                建议：使用参数化查询

你: @coderabbitai 给出修复方案

CodeRabbit Bot: 替换为：
                db.Query("SELECT * FROM users WHERE id = ?", userID)

PR-Agent：评论式

PR-Agent 默认输出一份汇总评论，包含所有发现（PR_REVIEW.INLINE_CODE_COMMENTS: true 可改为行内评论）。不支持对话交互——问题发现就是发现，没有追问机制。

Copilot Code Review：只读评论

Copilot Code Review 输出标准 PR 评论列表。同样不支持对话式交互。

维度 5：成本

工具	免费额度	付费方案	大型团队月成本估算
CodeRabbit	开源项目免费	Pro $12/月/人	~$500/月（40人）
PR-Agent	完全开源免费	只有 API 费用（自己出）	~$100-300/月（API）
Copilot Review	Copilot 订阅内含	Copilot Business $19/月/人	~$760/月（40人）

隐藏成本：CodeRabbit 的付费是按「审查的代码行数」计费（Pro plan），不是人头。如果你的团队 PR 频繁且改动量大，成本会显著上升。PR-Agent 的 API 费用取决于模型选择——用 GPT-5 每次中型 PR 审查约 $0.15-0.30，用 DeepSeek 约 $0.02-0.05。

维度 6：支持语言

三款工具都对主流语言（Python、JavaScript/TypeScript、Go、Java、Rust、C#）支持良好。差异在于小众语言：

CodeRabbit：声称支持所有语言，但非主流语言审查质量明显下降（用了通用 prompt）
PR-Agent：依赖底层模型能力，GPT-5 系对 50+ 语言有不错理解
Copilot Review：GitHub 自家产品，copilot-language-support 列表内的质量最好

维度 7：安全与合规

关注点	CodeRabbit	PR-Agent	Copilot Review
代码是否离仓	✅ 是（SaaS）	✅ 是（默认用 OpenAI）	✅ 是
自托管选项	❌	✅	❌
SOC 2	✅	不适用（自托管）	✅
支持私有部署	❌	✅ 可配 Azure/AWS Bedrock	❌

如果你的代码不能出公司网络：只有 PR-Agent 配合私有 LLM 部署（Ollama / vLLM / 内部 Azure OpenAI）能满足。CodeRabbit 有 Enterprise plan 提供数据隔离，但本质上还是 SaaS。

维度 8：自动摘要和描述生成

CodeRabbit 和 PR-Agent 都支持自动生成 PR 描述和摘要（walkthrough），Copilot Review 不支持。

CodeRabbit 的摘要质量更高——它把改动按文件分组，标注影响范围：

## Summary by CodeRabbit

### Walkthrough
- **auth/middleware.go**: 重构认证中间件，从 JWT 改为 session-based
  - 新增 session store 初始化
  - 移除 JWT 签名验证逻辑
- **db/migrations/042_sessions.sql**: 新增 sessions 表
  - 注意：包含 DROP TABLE IF EXISTS（破坏性）

PR-Agent 的 PR_DESCRIPTION.ENABLE: true 也能生成摘要，但格式更简单，不标注风险项。

选型决策

你的代码能离开公司网络吗？
  │
  NO ──▶ PR-Agent + 私有 LLM（Ollama/Azure OpenAI）
  │
  YES
  │
你愿意为「开箱即用」付费吗？
  │
  YES ──▶ CodeRabbit（全托管，开箱即用）
  │
  NO
  │
你需要 GitHub 原生体验吗？
  │
  YES ──▶ Copilot Code Review（如果你已有 Copilot 订阅）
  │
  NO ──▶ PR-Agent（灵活度最高，成本最低）

一个实际的工作流配置

以下是我们团队使用的 PR-Agent 配置，覆盖 80% 的审查场景：

.github/workflows/pr-agent.yml

name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]
permissions:
  pull-requests: write
  contents: read
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: Codium-ai/pr-agent@v0.26
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CONFIG.MODEL: "gpt-5"
          PR_REVIEWER.EXTRA_INSTRUCTIONS: |
            审查重点（按优先级）：
            1. 安全问题：注入、XSS、认证绕过、敏感信息泄露
            2. 性能问题：N+1 查询、无索引查询、大对象加载
            3. 错误处理：未处理的 error、panic 风险、超时设置
            4. 代码质量：重复代码、过长函数（>50行）、过度嵌套（>3层）
            请忽略：测试文件中的命名风格、注释的措辞
          PR_REVIEW.INLINE_CODE_COMMENTS: true
          PR_REVIEW.NUM_OF_SUGGESTIONS: 5
          PR_DESCRIPTION.ENABLE: true

在这个配置下跑了一个月，数据如下：

平均每个 PR 发现 3.2 个有效问题
误报率 < 5%
人工 Review 时间从平均 45 分钟降到 25 分钟（AI 先筛掉低级问题）

最后

AI Code Review 不是替代人工审查，是把人从「找拼写错误」「检查 SQL 注入」「对代码规范」中解放出来，让人专注于架构设计、业务逻辑正确性、长期可维护性——这些 AI 做不好的事。

选择工具前先想清楚一个问题：你最烦人工 Code Review 的哪个环节？ 如果烦的是低级错误检查 → CodeRabbit；烦的是审查速度 → PR-Agent（最快模型）；烦的是同事从来不做 Review → 先解决文化问题，工具帮不了。

更多 AI 开发工具：awesome-x-ops AI Coding 分类 · xlabs.club 技术博客

MCP 协议深度解析——AI 工具互联的 USB-C 时刻

Thu, 09 Jul 2026 15:00:00 GMT

2024 年底，Anthropic 发布了 MCP（Model Context Protocol）——一个让 AI 模型安全、标准化地访问外部工具和数据源的开放协议。用 Anthropic 的话说：MCP 是 AI 应用的 USB-C 接口。

六个月过去，MCP 已经从 Anthropic 的实验变成了整个 AI 生态的基础设施：OpenAI 发布了自己的 MCP 支持，Google 的 Gemini 接入，微软在 Copilot 生态中推广，开源社区贡献了 500+ MCP Server。

这篇文章不是翻译官方文档，而是我们从实现 MCP Server 和 Client 的过程中，对协议设计哲学的理解。

问题：Function Calling 不够吗？

在 MCP 之前，LLM 调用外部工具的标准方式是 Function Calling：

// OpenAI 风格 Function Calling
{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_database",
        "description": "查询用户数据库",
        "parameters": {
          "type": "object",
          "properties": {
            "query": { "type": "string" },
            "limit": { "type": "integer" }
          }
        }
      }
    }
  ]
}

这个模式的三个致命缺陷：

1. Context Window 污染

每个工具的定义（名称、描述、参数 schema）都要塞进 System Prompt。10 个工具 = 500+ tokens。100 个工具 = 5000+ tokens。而这些 tokens 在每一轮对话中都占据上下文窗口——即使用户这次只用了其中 2 个工具。

用户问："今天天气怎么样？"

LLM 实际收到的 Prompt：
"你是 AI 助手。你可以使用以下工具：
  1. search_database — 查询数据库 ...
  2. create_ticket — 创建工单 ...
  3. deploy_service — 部署服务 ...
  ... (95 个无关工具定义)

  用户：今天天气怎么样？"

浪费了 4500+ tokens 在无关工具上。

2. 工具发现是静态的

Function Calling 的工具列表在对话开始时就固定了。如果对话中间新增了一个数据源或工具——比如用户说「查一下我 GitHub 上的 PR 状态」——你只能让 LLM 返回「我没有这个工具」，然后应用层重新发起一次带新工具的调用。

3. 安全和权限是「调用前」的

Function Calling 只有「能调用」和「不能调用」两个状态。如果 LLM 可以调用 deploy_service，它就能部署任何服务。没有「需要用户确认」或「只读」的粒度。

MCP 的设计哲学

MCP 不是 Function Calling 的替代品，它是一个更高层次的抽象。核心差异：

维度	Function Calling	MCP
工具注册	静态列表，全量注入 Prompt	动态发现，按需加载
工具描述	文本参数 schema	结构化 Resource/Tool/Prompt
上下文管理	LLM 负责	MCP Client 负责
权限模型	调用前二态	资源级 + 操作级 + 人机审查
传输层	HTTP/SSE	stdio / Streamable HTTP / WebSocket
状态	无状态	有状态（Resource 订阅）

MCP 把工具抽象成三个原语（Primitive）：

原语一：Resource（资源）

Resource 是 LLM 可以读取的数据。 它不只是「文件」，而是任何结构化或非结构化的数据源。

// MCP Server 暴露的资源
{
  "resources": [
    {
      "uri": "db://users/active",
      "name": "活跃用户列表",
      "description": "过去 30 天内登录过的用户",
      "mimeType": "application/json"
    },
    {
      "uri": "docs://internal/security-policy",
      "name": "安全策略文档",
      "mimeType": "text/markdown"
    }
  ]
}

关键设计：Resource 的 URI 是标准化的——protocol://path。这让 LLM 可以用统一的语义引用任何数据源，而不是记住「用户列表是 get_users()，文档是 read_file()」。

原语二：Tool（工具）

Tool 是 LLM 可以执行的操作。 和 Function Calling 的 function 类似，但多了服务器端描述——Tool 的能力由 MCP Server 声明，Client 不需要硬编码。

{
  "tools": [
    {
      "name": "create_issue",
      "description": "在 GitHub 仓库中创建 Issue",
      "inputSchema": {
        "type": "object",
        "properties": {
          "repo": { "type": "string" },
          "title": { "type": "string" },
          "body": { "type": "string" }
        }
      }
    }
  ]
}

和 Function Calling 的核心差异：Tool 列表不在 Prompt 中，在 MCP Client 的内存中。Client 负责在 LLM 需要时动态注入相关 Tool 的 schema，而不是全部塞进去。

原语三：Prompt（提示模板）

Prompt 是预定义的交互模板。 比如「帮我 Review 这个 PR」或「为这个函数写单元测试」。这些模板由 MCP Server 提供，确保 LLM 以正确的格式理解用户意图。

{
  "prompts": [
    {
      "name": "code_review",
      "description": "审查 Pull Request",
      "arguments": [{ "name": "pr_url", "description": "PR 链接", "required": true }]
    }
  ]
}

Prompt 模板的好处：你不需要在每次对话中都告诉 LLM「请以这种格式审查代码，关注 1)安全性 2)性能 3)可读性」——这些规则被封装在 MCP Server 的 Prompt 模板中。

MCP 的架构

┌──────────────────────────────────────────┐
│              MCP Host (应用)               │
│  ┌────────────────────────────────────┐   │
│  │        MCP Client (协议层)          │   │
│  │  • 管理多个 MCP Server 连接          │   │
│  │  • 动态发现 Resource/Tool/Prompt    │   │
│  │  • 按需注入上下文到 LLM             │   │
│  └──────┬──────────┬──────────┬───────┘   │
│         │          │          │           │
│    ┌────▼───┐ ┌───▼────┐ ┌──▼──────┐     │
│    │Server A│ │Server B│ │Server C │     │
│    │(GitHub)│ │(Slack) │ │(Database)│    │
│    └────────┘ └────────┘ └─────────┘     │
└──────────────────────────────────────────┘

Client 是核心。它不是简单的 proxy，而是上下文管理器：

收到用户消息 → 分析意图
从所有连接 Server 的 Tool 列表中匹配相关工具
只将匹配的 Tool schema 注入 LLM 上下文
LLM 返回 Tool Call → Client 路由到对应 Server 执行
结果返回 LLM → 生成最终回复

MCP 的传输层

MCP 支持三种传输方式：

stdio（标准输入输出）

claude_desktop_config.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"]
    }
  }
}

MCP Client 以子进程方式启动 Server，通过 stdin/stdout 通信。适合本地工具。

Streamable HTTP

MCP Server 作为 HTTP 服务运行，Client 通过 HTTP 请求获取工具列表、调用工具。支持 Server-Sent Events（SSE）推送。

Client ──GET /mcp/tools──▶ Server
Client ◀──200 [{tool1}, {tool2}]── Server

Client ──POST /mcp/call──▶ Server
         {tool: "create_issue", args: {...}}
Client ◀──200 {result}── Server

适合公共服务，任何支持 HTTP 的环境都可以对接。

WebSocket（实验性）

双向实时通信，适合需要推送通知的场景。

实战：写一个 MCP Server

以下是一个完整的 MCP Server 示例——暴露一个「天气查询」工具：

weather_server.py

from mcp.server import Server, NotificationOptions
from mcp.server.models import InitializationCapabilities
import httpx

server = Server("weather-server")

@server.list_tools()
async def list_tools():
    return [
        {
            "name": "get_weather",
            "description": "获取指定城市的当前天气",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名称（中文，如 '北京'）"
                    }
                },
                "required": ["city"]
            }
        }
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_weather":
        city = arguments["city"]
        async with httpx.AsyncClient() as client:
            resp = await client.get(
                f"https://api.weather.com/v1/current?city={city}",
                params={"apiKey": "YOUR_KEY"}
            )
            data = resp.json()
            return {
                "content": [
                    {
                        "type": "text",
                        "text": f"{city}当前温度 {data['temp']}°C，{data['condition']}"
                    }
                ]
            }

if __name__ == "__main__":
    server.run(transport="stdio")

启动：

python weather_server.py

然后在 Claude Desktop 的 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["weather_server.py"]
    }
  }
}

Claude 就能查询天气了。

注意：MCP Python SDK 仍在快速迭代。截至 2026 年 7 月，建议固定 SDK 版本。Server 端的异常处理要完善——任何未捕获的异常都会导致 stdio 连接断开。

MCP vs Function Calling vs Plugin

维度	Function Calling	ChatGPT Plugin	MCP
标准化	OpenAI 专有	OpenAI 专有	开放标准
模型无关	❌ OpenAI only	❌	✅
动态发现	❌ 静态列表	❌	✅ Resource/Tool/Prompt
权限粒度	二态	二态	资源级 + 操作级
传输层	API 注入	HTTP	stdio / HTTP / WS
生态	OpenAI 生态	已弃用	开放生态（500+ Server）

ChatGPT Plugin 被 MCP 取代几乎是必然——Plugin 是封闭生态，MCP 是开放标准。类似 W3C 和 Flash 的关系。

MCP 的问题与陷阱

陷阱 1：Schema 膨胀

MCP Server 可以提供任意数量的 Tool。但如果你把 200 个 Tool 都注册到同一个 Server，Client 的匹配逻辑反而会退化——它不知道哪个 Tool 是相关的，只能把所有 Tool 的描述发给 LLM。

最佳实践：一个 MCP Server 暴露 5-15 个 Tool。超过 20 个就拆分成多个 Server。

陷阱 2：Tool 描述的语言差异

如果你的 MCP Client 是中文应用，但 Server 的 Tool 描述是英文——LLM 在匹配用户中文意图和英文 Tool 描述时会出现理解偏差。

最佳实践：Tool 描述和用户 prompt 使用同一语言。如果用户是中文，Tool 描述也用中文。

陷阱 3：资源泄露

MCP 使用 stdio 传输时，Server 是子进程。如果 Client 没有正确管理进程生命周期，每个对话都 spawn 一个新的 Server 进程 → 进程泄漏 → 内存耗尽。

最佳实践：Client 使用进程池，复用 Server 进程。

陷阱 4：Tool 调用依赖链

用户："部署最新版本到生产环境"
  → LLM 调用 list_services → 返回 50 个服务
  → LLM 调用 get_version("user-service") → 返回 v2.3.1
  → LLM 调用 deploy("user-service", "v2.3.1")

这个链路需要 3 次 Tool 调用。如果 list_services 返回超时，整个链路失败。MCP 目前没有内置的 retry 或 fallback 机制——这些需要应用层处理。

MCP 的未来方向

资源订阅（Resource Subscription）：Server 推送资源变化（如「数据库有新记录」），Client 主动通知 LLM，而不是 LLM 每次轮询。
Tool 组合（Tool Composition）：声明式组合多个 Tool 为一个工作流——「部署」= build → test → deploy → health check，LLM 不再需要知道这 4 步的细节。
跨会话记忆：MCP Server 维护跨会话的状态，让 LLM 能「记住上次我们做到哪了」。
MCP 网关：统一的 MCP Server 管理和路由层，处理认证、限流、监控、多租户——企业 IAM 的典型能力。

MCP 正在成为 AI Agent 基础设施的事实标准——就像 HTTP 成为 Web 的标准、USB-C 成为设备的接口标准。它不是最完美的协议，但它在一个关键时间点出现：当所有人都开始把 LLM 连接到外部工具，但每个人都用不同的方式连接。

协议需要实践检验。参考 awesome-x-ops MCP 生态获取更多 MCP Server 和 Client 实现。

AI Coding 工具横评——Aider vs Continue vs Cline 谁更适合你

Thu, 09 Jul 2026 14:00:00 GMT

2026 年的 AI Coding 工具已经不再是「玩具」或「自动补全」那么简单。Aider、Continue、Cline 代表了三种不同的设计哲学：终端原生的结对编程、IDE 内嵌的上下文感知、VS Code 插件的 Agent 自动化。

本文从 12 个维度对比这三款工具，帮你选型——不是看谁功能多，是看谁的设计哲学契合你的工作流。

更多 AI 基础设施工具参见 awesome-x-ops AI 分类。

一句话定位

工具	定位	核心哲学
Aider	终端原生 AI 结对编程	“AI 是你的 Pair，Git 是真相来源”
Continue	IDE 内嵌 AI 助手	“AI 应该像 Tab 补全一样自然，不打断心流”
Cline	VS Code AI Agent	“AI 应该能自己读代码、写代码、执行命令”

维度 1：工作流适配

Aider：终端原生

Aider 在终端运行，和 Git 深度集成。你不需要离开终端——aider 启动，AI 自动理解 Git 仓库的上下文。

$ aider
Aider v0.75.0
Models: claude-sonnet-4-5 with diff edit format
Git repo: .git with 1,234 files
Repo map: using 1024 tokens
──────────────────────────────────────────
> 把这个函数的错误处理改成 Result 类型

# AI 直接在终端中输出 diff，你可以 /add、/drop、/undo

适合：Vim/Neovim/终端重度用户、Git 工作流驱动的开发。

Continue：IDE 内嵌

Continue 安装为 VS Code / JetBrains 插件。它通过 @ 命令引入上下文：

@file 引用文件
@folder 引用目录
@docs 引用文档
@terminal 引入终端输出
@git 引入 Git diff

适合：IDE 重度用户，希望 AI 不离开编辑器。

Cline：Agent 模式

Cline 的运行模式更像「自主 Agent」：你描述目标，它自己读代码 → 写代码 → 执行命令 → 检查输出 → 修正错误。

你：把这个 Express 后端迁移到 Hono

Cline：
  1. 读取 package.json → 理解依赖
  2. 读取 src/ → 理解路由结构
  3. 安装 hono → npm install
  4. 重写路由文件 → 逐个文件替换
  5. 运行测试 → npm test
  6. 发现 1 个失败 → 读取错误日志 → 修复 → 重新测试
  7. 全部通过 ✓

适合：希望 AI 自己完成多步骤任务，而不是每次对话都要手动描述上下文。

维度 2：代码编辑能力

能力	Aider	Continue	Cline
单文件编辑	✅	✅	✅
多文件编辑	✅ 强	✅	✅ 强
搜索替换模式	✅ SEARCH/REPLACE	✅ Diff 模式	✅
自动格式化	✅ `--lint`	✅ 依赖 IDE	✅
Git 提交	✅ 自动 `git commit`	❌ 手动	✅
Undo/回滚	✅ `/undo`	❌ IDE 原生 Undo	✅ Checkpoint
测试驱动修复	✅ `--test-cmd`	⚠️ 手动	⚠️ 半自动

Aider 最独特的能力：理解 Git 仓库的 Map（Repo Map）——它能自动生成仓库结构摘要发给 LLM，让 LLM 知道哪个文件干什么。这意味着当你问「修改认证逻辑」，Aider 不需要你手动 @file auth.ts，它自己知道应该改哪些文件。

Cline 最独特的能力：Plan → Act 模式。在修改代码前，Cline 会先输出一个执行计划（Plan Mode），你同意后它才执行（Act Mode）。这在改生产代码时特别有用。

维度 3：上下文与内存

维度	Aider	Continue	Cline
上下文来源	Git 仓库 + 对话历史	手动 @ 引用	自动读取项目文件
上下文大小	仓库 Map + 当前文件	用户选择	自动裁剪
跨会话记忆	✅ `.aider.conf.yml` 缓存	⚠️ 对话无持久	❌
自定义规则	✅ `CONVENTIONS.md`	✅ `.continuerc.json`	✅ `.clinerules`

Aider 的 Repo Map 是差异化优势——它持续分析整个仓库的代码结构，LLM 调用时附上摘要。如果你有 500 个源文件，LLM 不需要读 500 个文件，只需要读 1KB 的 Map 摘要。

Continue 的上下文方式更「手动但精确」——你控制 LLM 看到什么。好处是 Token 成本可控，坏处是每次都要手动选择上下文。

维度 4：模型支持

模型	Aider	Continue	Cline
Claude Sonnet 4.5	✅ 优秀	✅	✅
GPT-5	✅	✅	✅
DeepSeek	✅	✅	✅
本地模型（Ollama）	✅	✅	✅
自定义 Provider	✅ `--openai-api-base`	✅ 配置	✅

三款工具都支持自定义 API endpoint，可以对接任何 OpenAI 兼容接口（含自建代理）。这意味着你可以使用公司内部的 LLM 网关或成本更低的第三方 API。

维度 5：学习曲线与上手成本

Aider：    ████████░░  需要理解 Git 工作流 + Map 概念，但上手后极快
Continue： ████░░░░░░  和 Tab 补全一样自然， 5 分钟上手
Cline：    ██████░░░░  需要理解 Agent 模式，但 UI 引导清楚

实战场景推荐

重构遗留代码 → Aider

$ aider --model claude-sonnet-4-5
> 把 src/legacy/ 下的所有函数签名从 callback 模式改成 async/await
> 用 /run npm test 验证

Aider 的 Repo Map 天然适合大规模重构——它自己知道所有受影响文件。

日常开发 + 代码审查 → Continue

在 VS Code 中选中代码 → Cmd+L → “这段代码有什么问题？” → AI 在侧边栏回答。不需要离开编辑器，不需要复制粘贴。

从零搭建新项目 → Cline

"用 Hono + Drizzle + SQLite 搭一个 REST API，包含用户注册/登录/CRUD"

Cline 会自动：创建项目结构 → 安装依赖 → 写代码 → 运行测试 → 修复问题。你只需要在关键步骤确认。

成本和性能

工具	单次任务平均 Token	月成本（轻度使用）	月成本（重度使用）
Aider	5K-20K	$10-30	$50-150
Continue	2K-10K	$5-20	$30-80
Cline	10K-50K	$20-50	$100-300

Cline 的 Agent 模式每次任务消耗更多 Token（因为自己读文件+执行命令+读取输出），但完成的任务也更多。

选择决策树

你是终端/Vim 用户？ ──YES──▶ Aider
    │
    NO
    │
你喜欢 IDE 内嵌、低打扰？ ──YES──▶ Continue
    │
    NO
    │
你想 AI 自己完成多步骤任务？ ──YES──▶ Cline
    │
    ALL → 三个都装，不同场景用不同工具

实际上很多开发者三个都装了——Aider 做重构、Continue 做日常、Cline 做自动化任务。它们不互斥。

总结

你的画像	首选工具
Vim/Terminal 党，Git 工作流驱动	Aider
IDE 党，希望 AI 像 Tab 一样自然	Continue
想要 AI Agent 自主完成任务	Cline
「我全都要」	三个都装

AI Coding 工具的选择不是技术问题，是工作流哲学问题。选那个不打断你心流的工具。

更多 AI 开发工具：awesome-x-ops AI Coding 分类 · xlabs.club 技术博客

Keycloak 生产环境避坑指南——从单实例到高可用集群

Thu, 09 Jul 2026 13:00:00 GMT

Keycloak 的开发环境只需 docker run，但生产环境远没有这么简单。本文整理了我们在多个项目中踩过的 7 个坑，每个都有可复制的配置。

如果你还不熟悉 Keycloak 的基本概念（Realm、Client、Identity Provider），建议先阅读 Keycloak 完全指南。

坑 1：默认 H2 数据库

Keycloak 默认使用 H2 嵌入式数据库。开发环境没问题，生产环境绝对不能碰。

症状：重启后所有 Realm 配置消失、并发写入时数据损坏、无法做数据库级别备份。

解决方案：

docker-compose.yml

keycloak:
  image: quay.io/keycloak/keycloak:26.1
  environment:
    KC_DB: postgres
    KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
    KC_DB_USERNAME: keycloak
    KC_DB_PASSWORD: <secure-password>
  depends_on:
    postgres:
      condition: service_healthy

教训：生产环境第一天就切到 PostgreSQL。H2 → PostgreSQL 的迁移比想象中痛苦（用户密码哈希格式不同、自定义 SPI 数据表结构不兼容）。

坑 2：会话不共享——多实例的噩梦

Keycloak 26.x 默认使用 Infinispan 做分布式缓存，但单播发现模式（PING）在生产环境中不可靠。

症状：登录后刷新页面回到登录页、不同 Pod 之间 Session 不共享、偶尔出现 user session not found 错误。

根本原因：Keycloak Pod 之间没有发现彼此，每个 Pod 维护独立的 Infinispan 缓存。

解决方案——Kubernetes DNS 发现模式：

# Keycloak 启动参数
--cache=ispn
--cache-stack=kubernetes
--spi-connections-infinispan-quarkus-site=<site-name>

配合 Headless Service：

keycloak-headless.yaml

apiVersion: v1
kind: Service
metadata:
  name: keycloak-discovery
spec:
  clusterIP: None
  selector:
    app: keycloak
  ports:
    - port: 7800
      name: jgroups-tcp

验证集群是否正常：

# 进入 Keycloak Pod
kubectl exec -it keycloak-0 -- /opt/keycloak/bin/kcadm.sh config credentials \
  --server http://localhost:8080 --realm master --user admin

# 检查集群节点
kubectl exec -it keycloak-0 -- /opt/keycloak/bin/kcadm.sh get \
  --server http://localhost:8080 serverinfo | jq '.clusterInfo'

深入理解 Keycloak 的 Infinispan 缓存和用户会话管理，参考 IAM 会话管理深度解析。

坑 3：反向代理配置——混合端口噩梦

Keycloak 默认监听 8080（HTTP），但生产环境必须用 TLS。NGINX/Traefik 反向代理是标配，但配置不当会导致：

redirect_uri 不匹配：Keycloak 以为自己是 http://localhost:8080，实际用户在访问 https://auth.example.com
混合内容：HTML 通过 HTTPS，但 JS/CSS 引用的是 HTTP 地址
WebSocket 断开：Keycloak Admin Console 使用 WebSocket，反向代理必须支持升级

正确配置：

# Keycloak 启动参数
--hostname=https://auth.example.com
--http-enabled=false
--proxy-headers=xforwarded

# Traefik IngressRoute
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: keycloak
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`auth.example.com`)
      kind: Rule
      services:
        - name: keycloak
          port: 8080
  tls:
    secretName: keycloak-tls

关键点：--hostname 和反向代理的 Host 头必须一致。任何不一致都会导致 OpenID Connect Discovery 端点（/.well-known/openid-configuration）返回错误的 URL，所有依赖 OIDC 的应用都会故障。

坑 4：数据库连接池耗尽

Keycloak 使用 HikariCP 连接池，默认最大连接数 20。当 Realm 配置的 Identity Provider 数量多、或 User Federation 查询频繁时，20 个连接很快耗尽。

症状：Admin Console 卡住、登录延迟飙升、HikariPool-1 - Connection is not available 日志。

调优：

# 根据实际负载调整
--db-pool-initial-size=5
--db-pool-min-size=5
--db-pool-max-size=50
--db-pool-idle-timeout=300000

同时确保 PostgreSQL 的 max_connections 远大于 Keycloak 的 pool size（建议 max_connections = keycloak_instances × pool_max_size + 50）。

坑 5：会话持久化——Pod 重启后用户不掉线

Kubernetes 默认使 Pod 变成「牲畜」，随时可以被杀死。Keycloak 如果只依赖内存缓存（--cache=local），Pod 重启后所有在线用户的 Session 丢失。

解决方案——启用持久会话（Persistent User Sessions）：

--spi-user-sessions-infinispan-offline-session-preload=true
--spi-user-sessions-infinispan-offline-preload-entry-size=10000

生产验证：执行 kubectl delete pod keycloak-0，观察是否有活跃用户掉线。

完整的 Keycloak 高可用 + 灾备方案，参考 Keycloak 高可用与灾备部署。

坑 6：健康检查——存活探针不当导致脑裂

Kubernetes 的健康检查（Liveness Probe）如果配置不当，可能会在 Keycloak 启动慢或 Infinispan 集群重组时误杀 Pod。

推荐配置：

livenessProbe:
  httpGet:
    path: /health/live
    port: 9000
  initialDelaySeconds: 60
  periodSeconds: 30
  failureThreshold: 5 # 连续 5 次失败才重启
readinessProbe:
  httpGet:
    path: /health/ready
    port: 9000
  initialDelaySeconds: 30
  periodSeconds: 10
  failureThreshold: 3
startupProbe:
  httpGet:
    path: /health/started
    port: 9000
  initialDelaySeconds: 10
  periodSeconds: 10
  failureThreshold: 30 # 给足 5 分钟启动时间

关键：/health/live 端点依赖 Infinispan 集群状态。在集群重组时，/health/live 会返回 DOWN。如果 failureThreshold 太小（默认 3），3 × 30 = 90 秒内 Keycloak 集群还没重组完成，Pod 就会被杀——导致重组永远完不成。failureThreshold: 5 甚至 10 都不为过。

坑 7：优雅停机——拒绝新请求 + 排空存量

Keycloak 的关闭不是瞬时的。直接 kill -9 或 kubectl delete pod --grace-period=0 会导致：

正在处理的登录请求丢失
正在写入的会话数据损坏
Infinispan 集群成员突然消失 → 整个集群短暂不稳定

正确配置：

# Kubernetes
spec:
  terminationGracePeriodSeconds: 120 # 给足 2 分钟
  containers:
    lifecycle:
      preStop:
        exec:
          command:
            - /bin/sh
            - -c
            - |
              # 1. 从负载均衡摘除自己（如调用 Traefik API）
              # 2. 等待存量请求排空
              sleep 30
              # 3. Keycloak 自身关闭（SIGTERM）

Keycloak 收到 SIGTERM 后会：

停止接受新连接
等待活跃事务完成
刷新 Infinispan 缓存到持久存储
优雅退出

terminationGracePeriodSeconds 必须大于 Keycloak 的实际关闭时间。建议在测试环境实测后 + 30 秒安全边界。

总结

坑	症状	关键修复
H2 数据库	重启数据丢失	`KC_DB=postgres`
会话不共享	登录状态丢失	`--cache-stack=kubernetes` + Headless Service
反向代理	redirect_uri 不匹配	`--hostname=https://...` + `--proxy-headers=xforwarded`
连接池耗尽	Admin Console 卡住	`--db-pool-max-size=50`
会话丢失	Pod 重启用户掉线	`--spi-user-sessions-infinispan-offline-session-preload=true`
健康检查误杀	集群重组时 Pod 被杀	`failureThreshold: 5+` + `startupProbe`
强制重启	数据损坏	`terminationGracePeriodSeconds: 120`

生产环境的 Keycloak 不是一个 docker run 的事。但填完上述 7 个坑后，它可以稳定运行数年。

更多 Keycloak 深度内容：Keycloak 完全指南 · Keycloak 高可用与灾备 · IDaaS Book

企业级智能代码重构探索：大规模自动化迁移实践与工具选型

Tue, 09 Dec 2025 14:08:54 GMT

作为一个以 Java 和 Spring 为主要技术栈的团队，在日常的软件开发中，我们经常会遇到一系列的组件升级和代码重构需求，在此过程我们期望能做到几个效果：

项目级升级：整个项目（注此项目指 Maven Project）升级，而不是基于某个 Java 类或片段。
不同版本跨度变更：比如从 Spring 项目迁移到 Spring Boot，从 Spring Boot 2.x 升级到 3.x，从 Java 8 升级到 Java 21。
代码安全可靠：变更的代码一定是正确的，至少是逻辑正确的，至少不能像某 AI 助手一样设置一些根本不存在的属性。
经验产品化：最佳实践就是产品，比如我并不（想）了解 Spring Boot 3.2 具体有哪些变更，但希望能一键从 3.0 自动升级到 3.2，直接告诉有哪些变更。
自定义重构：对于某些自研代码，希望能自定义重构逻辑，一键自动重构。

基于以上背景，我们探索了 OpenRewrite、Spring Boot Migrator、Redhat Windup、emt4j 和一众不便具名的 AI 代码助手，本文将分享我们使用 OpenRewrite、Spring Boot Migrator 进行代码重构和升级的一些使用经验和体验。

OpenRewrite

OpenRewrite 是一个开源的代码重写工具，旨在帮助开发人员自动化大规模重构代码。

它提供了一套强大的 API 和插件系统，可以通过静态分析和代码转换技术来解析、修改和生成代码。OpenRewrite 支持多种编程语言，包括 Java、C#、 TypeScript、Python、Kubernetes 等。通过使用 OpenRewrite，开发人员可以轻松地进行代码重构、性能优化、代码风格调整和代码迁移等操作，从而提高代码质量和可维护性。OpenRewrite 的开源性质使得开发人员可以自由地定制和扩展其功能，以满足特定项目的需求。

比如 Java 领域一些热门的应用场景：

Java 版本升级：从 Java 8 到 Java 21，从 Java EE 到 Jakarta EE 。
Spring 框架迁移：从 Spring 5 到 Spring 6，从 Spring Boot 2 到 Spring Boot 3。
测试框架迁移：从 Junit 4 到 Junit 5。
依赖管理：自动更新 Java 项目的 Maven 或 Gradle 依赖，确保使用最新和最安全的库版本。
代码清理和格式化：自动清理和格式化 Java 代码，确保符合项目或组织的编码标准和风格指南。
修复安全漏洞：自动识别和修复 Java 代码中的已知安全漏洞，如使用了有安全问题的库或方法。
代码异味检测和修复：识别并自动重构 Java 代码中的“代码异味”，以提高代码可维护性。

相比于时下火热的 AI 代码工具，比如 GitHub Copilot、Amazon CodeWhisperer，我认为 OpenRewrite 的优势主要有以下几点：

可以直接处理大型项目，截止我写此文的今天还没一个成熟的 AI 助手能将整个项目一次性迁移或重构。
准确度较高，它通过预定义的规则来实现代码的精确修改，目前很多 AI 代码助手还在一本正经的瞎扯，尤其是凭空创造让人防不胜防。
可自定义扩展，对于自研代码不可能经过自动学习达到精确的效果，此时可自定义实现。
免费，可离线使用，便于 CI 集成。

值得一提的是，AWS 最近推出了 Amazon Q Code Transformation 专门做代码迁移和重构，需要开通 Amazon CodeWhisperer 企业版才能使用，可惜我没有钱去试用。

更新：AWS 2025 年底推出了 AWS Transform Custom，这其实就是我想要的，比 Q Code 已经有质的提升，只是没有深度测试，有用过的小伙伴欢迎交流反馈。

快速入门

OpenRewrite 一个最核心的概念是 Recipe，由于我是国内首个翻译这个单词的人，以下将直译为食谱。一个 Recipe 可以理解为是一套声明好的规则，OpenRewrite 按照固定规则进行重构。

一个 Recipe 可以包含多个 Recipe，可以层级累加，比如 UpgradeSpringBoot_3_2可能包含对 pom.xml、application.properties、java main source、java test source 的升级改动。

初次使用 OpenRewrite，可通过官方提供的热门指导找到自己感兴趣的按步骤操作。

另外就是食谱很多，一个一个用很麻烦，可优先考虑 best practices 系列，里面聚合了多个食谱。

更多功能可通过食谱分类搜索，也可通过官网右上方的搜索按钮按照关键字搜索，也可通过 mvn rewrite:discover 列出可用的食谱。

运行方式

友情提示：运行前请把代码交给 Git 管理，并 checkout 一个全新的分支，便于比对自动修改了哪些代码。

OpenRewrite 支持使用 maven、gradle 以及使用 SaaS 服务 Moderne cli mod 这三种方法。

使用 maven、gradle 文件定制比较方便，dependency 管理也比较灵活，另外某些食谱只有 maven、gradle 支持，缺点则是需要修改 pom、gradle 文件。

使用 maven 命令行直接执行插件任务并指定属性，不用改 pom.xml 更方便，缺点是不方便管理 dependencies。

mvn -U org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE -Drewrite.activeRecipes=org.openrewrite.java.migrate.jakarta.JakartaEE10 -Drewrite.exportDatatables=true

使用 SaaS 服务提供的 Moderne CLI 最方便，比如 mod run . --recipe JakartaEE10, 需要注册 license。

最佳实践和定制

OpenRewrite 对不同类型分别内置了一些最佳实践，可通过 best practices 关键字搜索。

最佳实践包含了哪些规则呢，以 Spring Boot 3.x best practices 为例，在文档中能看到对应的食谱列表如下：

---
type: specs.openrewrite.org/v1beta/recipe
name: org.openrewrite.java.spring.boot3.SpringBoot3BestPractices
displayName: Spring Boot 3.x best practices
description: Applies best practices to Spring Boot 3 applications.
tags:
  - spring
  - boot
recipeList:
  - org.openrewrite.java.spring.boot2.SpringBoot2BestPractices
  - org.openrewrite.java.migrate.UpgradeToJava21
  - org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_2

而其中每个食谱又可能包含多个，比如上面的 org.openrewrite.java.spring.boot2.SpringBoot2BestPractices 又包含以下列表：

---
type: specs.openrewrite.org/v1beta/recipe
name: org.openrewrite.java.spring.boot2.SpringBoot2BestPractices
displayName: Spring Boot 2.x best practices
description: Applies best practices to Spring Boot 2 applications.
tags:
  - spring
  - boot
recipeList:
  - org.openrewrite.java.spring.NoRequestMappingAnnotation
  - org.openrewrite.java.spring.ImplicitWebAnnotationNames
  - org.openrewrite.java.spring.boot2.UnnecessarySpringExtension
  - org.openrewrite.java.spring.NoAutowiredOnConstructor
  - org.openrewrite.java.spring.boot2.RestTemplateBuilderRequestFactory
  - org.openrewrite.java.spring.boot2.ReplaceDeprecatedEnvironmentTestUtils

如果官方的某个食谱不和你的胃口，比如想在最佳实践中去掉或新增某个自定义食谱怎么办，可以自己定义一个 rewrite.yml 文件，类似上面的 yaml 文件，在文件中自行组合食谱。注意 rewrite.yml 文件要放到 maven 项目的根目录下，更多关于文件的说明参考 Refactoring with declarative YAML recipes。

CI 集成

通过 mvn rewrite:run 命令执行后，会直接修改代码。但是大部分 CI 场景下，我们可能只想做分析，不想真正改动代码。那么就可以把命令换成 mvn rewrite:dryRun，dryRun 会在控制台输出 warning 结果，并生成一个 rewrite.patch 文件。

如果 dryRun 向控制台日志发出任何警告，或者生成了 rewrite.patch 文件，证明此次有需要变更的地方，则可视为 CI 失败。

Spring Boot Migrator

OpenRewrite 功能很强悍，但是仍缺失一项功能：将传统 Spring 项目一键迁移到 Spring Boot。

Spring Boot Migrator 基于 OpenRewrite，是一个专门用于协助将传统的 Spring 应用迁移到基于 Spring Boot 的工具，同时也提供 Spring Boot 的升级。

Spring Boot Migrator 程序运行起来后，通过 list 命令可以看到提供的 OpenRewrite recipes，其中主要关注的有：

initialize-spring-boot-migration: 将项目初始化为 Spring Boot 应用。
migrate-spring-xml-to-java-config：将 Spring xml 转换为 Java 注解。
spring-context-xml-import：使用 Import xml 文件的形式初始化 Bean。
boot-2.7-3.0-dependency-version-update：Spring Boot 2 升级到 Spring Boot 3。

migrator:> list
Found these recipes:

  1) remove-redundant-maven-compiler-plugin
     -> Remove standard maven-compiler plugin for applications with boot parent.
  2) initialize-spring-boot-migration
     -> Initialize an application as Spring Boot application.
  3) migrate-jndi-lookup
     -> Migrate JNDI lookup using InitialContext to Spring Boot
  4) migrate-jpa-to-spring-boot
     -> Migrate JPA to Spring Boot
  5) migrate-ejb-jar-deployment-descriptor
     -> Add or overrides @Stateless annotation as defined in ejb deployment descriptor
  6) migrate-weblogic-ejb-deployment-descriptor
     -> Migrate weblogic-ejb-jar.xml deployment descriptor
  7) mark-and-clean-remote-ejbs
     -> Search @Stateless EJBs implementing a @Remote interface
  8) migrate-stateless-ejb
     -> Migration of stateless EJB to Spring components.
  9) migrate-annotated-servlets
     -> Allow Spring Boot to deploy servlets annotated with @WebServlet
  10) migrate-jax-ws
     -> Migrate Jax Web-Service implementation to Spring Boot bases Web-Service
  11) migrate-jax-rs
     -> Any class has import starting with javax.ws.rs
  12) migrate-mule-to-boot
     -> Migrate Mulesoft 3.9 to Spring Boot.
  13) migrate-tx-to-spring-boot
     -> Migration of @TransactionAttribute to @Transactionsl
  14) spring-context-xml-import
     -> Import Spring Framework xml bean configuration into Java configuration without converting them.
  15) migrate-spring-xml-to-java-config
     -> Migrate Spring Framework xml bean configuration to Java configuration.
  16) migrate-jms
     -> Convert JEE JMS app into Spring Boot JMS app
  17) documentation-actions
     -> Create Documentation for Actions
  18) migrate-jsf-2.x-to-spring-boot
     -> Use joinfaces to integrate JSF 2.x with Spring Boot.
  19) cn-spring-cloud-config-server
     -> Externalize properties to Spring Cloud Config Server
  20) boot-2.4-2.5-upgrade-report
     -> Create Upgrade Report for a Spring Boot 2.4 Application
  21) boot-2.7-3.0-dependency-version-update
     -> Bump spring-boot-starter-parent from 2.7.x to 3.0.0
  22) boot-autoconfiguration-update
     -> Create org.springframework.boot.autoconfigure.AutoConfiguration.imports file for new spring 2.7
  23) boot-2.4-2.5-datasource-initializer
     -> Replace deprecated spring.datasource.* properties
  24) boot-2.4-2.5-spring-data-jpa
     -> Rename JpaRepository methods getId() and calls to getOne()
  25) boot-2.4-2.5-dependency-version-update
     -> Update Spring Boot dependencies from 2.4 to 2.5
  26) boot-2.7-3.0-upgrade-report
     -> Create a report for Spring Boot Upgrade from 2.7.x to 3.0.0-M3
  27) boot-2.4-2.5-sql-init-properties
     -> Replace deprecated spring.datasource.* properties
  28) sbu30-report
     -> Create a report for Spring Boot Upgrade from 2.7.x to 3.0.x
  29) sbu30-upgrade-dependencies
     -> Spring boot 3.0 Upgrade - Upgrade dependencies
  30) sbu30-set-java-version
     -> Spring boot 3.0 Upgrade - Set java version property in build file
  31) sbu30-add-milestone-repositories
     -> Spring boot 3.0 Upgrade - Add milestone repository for dependencies and plugins
  32) sbu30-migrate-spring-data-properties
     -> Spring boot 3.0 Upgrade - Migrate 'spring.data' properties to new property names
  33) sbu30-remove-construtor-binding
     -> Spring boot 3.0 Upgrade - Remove redundant @ConstructorBinding annotations
  34) sbu30-migrate-to-jakarta-packages
     -> Spring boot 3.0 Upgrade - Migrate javax packages to new jakarta packages
  35) sbu30-johnzon-dependency-update
     -> Spring boot 3.0 Upgrade - Specify version number for johnzon-core
  36) sbu30-225-logging-date-format
     -> Spring boot 3.0 Upgrade - Logging Date Format
  37) sbu30-auto-configuration
     -> Move EnableAutoConfiguration Property from spring.factories to AutoConfiguration.imports
  38) sbu30-upgrade-spring-cloud-dependency
     -> Upgrade Spring Cloud Dependencies
  39) sbu30-upgrade-boot-version
     -> Spring boot 3.0 Upgrade - Upgrade Spring Boot version
  40) sbu30-remove-image-banner
     -> Spring boot 3.0 Upgrade - Remove the image banner at src/main/resources
  41) sbu30-paging-and-sorting-repository
     -> Spring boot 3.0 Upgrade - Add CrudRepository interface extension additionally to PagingAndSortingRepository
  42) migrate-raml-to-spring-mvc
     -> Create Spring Boot @RestController from .raml files.
  43) migrate-boot-2.3-2.4
     -> Migrate from Spring Boot 2.3 to 2.4
  44) upgrade-boot-1x-to-2x
     -> Migrate applications built on previous versions of Spring Boot to the latest Spring Boot 2.7 release.

OpenRewrite 使用示例

下面使用 maven 方式演示几个例子，注意如果是 maven 多模块项目，请在父模块下执行，否则运行可能出错，参考官方说明：Running Rewrite on a multi-module Maven project。

友情提醒：初次使用会下载很多依赖 jar 包，速度可能比较慢，切换到你最快的 maven 仓库。

升级到 Java 21

从任意版本升级到 Java 21。

mvn -U org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE -Drewrite.activeRecipes=org.openrewrite.java.migrate.UpgradeToJava21

# 或者手动指定版本
mvn -U org.openrewrite.maven:rewrite-maven-plugin:5.31.0:run -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:2.14.0 -Drewrite.activeRecipes=org.openrewrite.java.migrate.UpgradeToJava21

OpenRewrite 会自动替换一些 Java 21 支持的新特性，如：

大文本块 JEP 378: Text Blocks，自动优化格式化。
模式匹配增强：支持在执行 instanceof 操作时同时定义指定类型的新变量，省却了类型转换的过程。
String 类增加的新格式化方法： formatted(Object… args)。
排序性集合：可以直接使用 getFirst() 和 getLast() 来获取第一个和最后一个集合元素了。参考： JEP 431: Sequenced Collections。

Base64 方法替换

Base64 常用的实现有：

Apache Common Codec，依然可用，可以选择是否转换成 java.util.Base64。
sun.misc 包下提供的实现类，从 Java 9 开始，已经不再对外提供，需要替换。
从 Java 1.8 开始提供的标准库 java.util.Base64。

# UseJavaUtilBase64
mvn -U org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE -Drewrite.activeRecipes=org.openrewrite.java.migrate.UseJavaUtilBase64 -Drewrite.exportDatatables=true

# ApacheBase64ToJavaBase64
mvn -U org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-apache:RELEASE -Drewrite.activeRecipes=org.openrewrite.apache.commons.codec.ApacheBase64ToJavaBase64 -Drewrite.exportDatatables=true

另外更多关于 Apache 包升级、使用 Java 自带方法代替 Apache Utils 的方法，请参考 OpenRewrite 官网 apache 下的食谱。

升级到 JakartaEE

从 javax 到 jakarta，在 maven 项目父（根）模块下执行以下命令即可，注意命令可能随着版本变化，请去官网查看最新版本示例。

mvn -U org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE -Drewrite.activeRecipes=org.openrewrite.java.migrate.jakarta.JakartaEE10 -Drewrite.exportDatatables=true

执行完成后可根据 git diff 查看修改效果。

代码清理

先试一下 CodeCleanup 效果。

pom.xml 文件中增加以下配置，然后执行 mvn rewrite:run。

  <build>
    <plugins>
      <plugin>
        <groupId>org.openrewrite.maven</groupId>
        <artifactId>rewrite-maven-plugin</artifactId>
        <version>5.23.1</version>
        <configuration>
          <activeRecipes>
            <recipe>org.openrewrite.staticanalysis.CodeCleanup</recipe>
          </activeRecipes>
        </configuration>
        <dependencies>
          <dependency>
            <groupId>org.openrewrite.recipe</groupId>
            <artifactId>rewrite-static-analysis</artifactId>
            <version>1.3.1</version>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>

我的某个项目执行效果：

删除了一些多余的空格、空行、多括号。
代码格式化，比如多个参数间缺少空格的加了空格。
颠倒了一个 equals 比较： method.equals("CONNECT") -> "CONNECT".equals(method)。
长代码换行归整，三元运算格式化。

静态分析、查找、重构

支持以下功能，不一一列举，请参考官方文档。

分析依赖关系。
查找某个方法是否被使用。
将某个方法替换为某个方法。
批量修改方法名字，修改参数类型等。
排序 imports ，删除未使用的 imports。

通用代码格式化

无用空行、空白符、前后空白符、方法参数前后空白符、Tab 转 space 等一些常用格式化方式。

日志优化

Parameterize logging statements：把字符串拼接自动转为参数类型。
用 logger 代替 System.err、System.out、printStackTrace。
把 JUL、log4j、logback 都转为 slf4j API。

Spring 到 Spring Boot

下面介绍下我们将 Spring 项目迁移到 Spring Boot 的过程，以及中间遇到的一些问题。

升级项	迁移前	迁移后
Runtime	Spring + Tomcat	Spring Boot 3.2
Spring	Spring 4	Spring 6
Junit	Junit 4	Junit 5
okhttp	okhttp 3	okhttp 4
Java	Java 8	Java 21
Java EE	Java EE	Jakarta EE

基本步骤：

使用 Spring Boot Migrator 将 Spring 项目转换成 Spring Boot，使用 Java 17 启动 spring-boot-migrator 程序并根据提示一步一步操作，如果某个步骤出错，根据 stacktrace 命令查看错误信息，修复后继续 apply <recipe-number>。

# 注意在执行 spring-boot-migrator 前，先在你要升级的项目中执行 mvn clean package install，拉取和安装依赖包，避免下面的 scan 步骤中下载依赖包失败

# 使用 Java 17 启动 spring-boot-migrator 程序
$ java -jar spring-boot-migrator.jar

Get Started:
------------
Type

"help" - to display a list all of the available commands.
"scan <dir>" - to scan an application

--------------------------------------------------------------------------------------------------

migrator:> scan my-spring-project-dir

[ok] Found pom.xml.
[ok] 'sbm.gitSupportEnabled' is 'true', changes will be committed to branch [springboot] after each recipe.
[ok] Found required source dir 'src/main/java'.

Maven        100% │██████████████████████████████████│ 2/2 (0:00:00 / 0:00:00)

Applicable recipes:

1) remove-redundant-maven-compiler-plugin
   -> Remove standard maven-compiler plugin for applications with boot parent.
2) initialize-spring-boot-migration
   -> Initialize an application as Spring Boot application.
3) spring-context-xml-import
   -> Import Spring Framework xml bean configuration into Java configuration without converting them.
4) migrate-spring-xml-to-java-config
   -> Migrate Spring Framework xml bean configuration to Java configuration.
5) cn-spring-cloud-config-server
   -> Externalize properties to Spring Cloud Config Server
6) sbu30-set-java-version
   -> Spring boot 3.0 Upgrade - Set java version property in build file
7) sbu30-add-milestone-repositories
   -> Spring boot 3.0 Upgrade - Add milestone repository for dependencies and plugins
8) sbu30-225-logging-date-format
   -> Spring boot 3.0 Upgrade - Logging Date Format

Run command '> apply <recipe-number>' to apply a recipe.

ibss-site-dc:> apply remove-redundant-maven-compiler-plugin
Applying recipe 'remove-redundant-maven-compiler-plugin'
[ok] Clean up redundant properties for maven compiler plugin.
[ok] Clean up redundant maven compiler plugin.

remove-redundant-maven-compiler-plugin successfully applied the following actions:
(x) Clean up redundant properties for maven compiler plugin.
(x) Clean up redundant maven compiler plugin.

Applicable recipes:

1) initialize-spring-boot-migration
   -> Initialize an application as Spring Boot application.
2) spring-context-xml-import
   -> Import Spring Framework xml bean configuration into Java configuration without converting them.
3) migrate-spring-xml-to-java-config
   -> Migrate Spring Framework xml bean configuration to Java configuration.
4) cn-spring-cloud-config-server
   -> Externalize properties to Spring Cloud Config Server
5) sbu30-set-java-version
   -> Spring boot 3.0 Upgrade - Set java version property in build file
6) sbu30-add-milestone-repositories
   -> Spring boot 3.0 Upgrade - Add milestone repository for dependencies and plugins
7) sbu30-225-logging-date-format
   -> Spring boot 3.0 Upgrade - Logging Date Format

Run command '> apply <recipe-number>' to apply a recipe.

ibss-site-dc:> apply initialize-spring-boot-migration
Applying recipe 'initialize-spring-boot-migration'
[ok] Add Spring Boot dependency management section to buildfile.
[ok] Add Spring Boot starter class.
[ok] Add initial unit test class to test Spring Boot Application Context startup.
[ok] Set packaging to 'jar' type if different

initialize-spring-boot-migration successfully applied the following actions:
(x) Add Spring Boot dependency management section to buildfile.
(x) Add spring dependencies 'spring-boot-starter' and 'spring-boot-starter-test'.
(x) Delete dependencies to artifacts transitively managed by Spring Boot.
(x) Add Spring Boot Maven plugin.
(x) Add Spring Boot starter class.
(x) Add initial unit test class to test Spring Boot Application Context startup.
(x) Set packaging to 'jar' type if different

Applicable recipes:

1) spring-context-xml-import
   -> Import Spring Framework xml bean configuration into Java configuration without converting them.
2) migrate-spring-xml-to-java-config
   -> Migrate Spring Framework xml bean configuration to Java configuration.
3) cn-spring-cloud-config-server
   -> Externalize properties to Spring Cloud Config Server
4) boot-2.7-3.0-dependency-version-update
   -> Bump spring-boot-starter-parent from 2.7.x to 3.0.0
5) boot-2.7-3.0-upgrade-report
   -> Create a report for Spring Boot Upgrade from 2.7.x to 3.0.0-M3
6) sbu30-report
   -> Create a report for Spring Boot Upgrade from 2.7.x to 3.0.x
7) sbu30-upgrade-dependencies
   -> Spring boot 3.0 Upgrade - Upgrade dependencies
8) sbu30-set-java-version
   -> Spring boot 3.0 Upgrade - Set java version property in build file
9) sbu30-add-milestone-repositories
   -> Spring boot 3.0 Upgrade - Add milestone repository for dependencies and plugins
10) sbu30-remove-construtor-binding
   -> Spring boot 3.0 Upgrade - Remove redundant @ConstructorBinding annotations
11) sbu30-225-logging-date-format
   -> Spring boot 3.0 Upgrade - Logging Date Format
12) sbu30-upgrade-spring-cloud-dependency
   -> Upgrade Spring Cloud Dependencies
13) sbu30-upgrade-boot-version
   -> Spring boot 3.0 Upgrade - Upgrade Spring Boot version

Spring Boot Migrator 目前还并不成熟，以上步骤中很多 recipe 可能出错，所以我只用 Spring Boot Migrator 做一些基础初始化，其他任务使用 rewrite-maven-plugin，交给 openrewrite 执行。在 maven pom.xml 中增加以下配置后，执行 mvn rewrite:run。

   <plugin>
      <groupId>org.openrewrite.maven</groupId>
      <artifactId>rewrite-maven-plugin</artifactId>
      <version>5.19.0</version>
      <configuration>
         <activeRecipes>
            <recipe>org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_7</recipe>
            <recipe>org.openrewrite.java.testing.junit5.JUnit4to5Migration</recipe>
            <recipe>org.openrewrite.okhttp.UpgradeOkHttp4</recipe>
            <recipe>org.openrewrite.okhttp.ReorderRequestBodyCreateArguments</recipe>
            <recipe>org.openrewrite.java.migrate.UpgradeToJava17</recipe>
         </activeRecipes>
      </configuration>
      <dependencies>
         <dependency>
            <groupId>org.openrewrite.recipe</groupId>
            <artifactId>rewrite-spring</artifactId>
            <version>5.2.0</version>
         </dependency>
         <dependency>
            <groupId>org.openrewrite.recipe</groupId>
            <artifactId>rewrite-testing-frameworks</artifactId>
            <version>2.2.0</version>
         </dependency>
         <dependency>
            <groupId>org.openrewrite.recipe</groupId>
            <artifactId>rewrite-okhttp</artifactId>
            <version>0.1.0</version>
         </dependency>
         <dependency>
            <groupId>org.openrewrite.recipe</groupId>
            <artifactId>rewrite-migrate-java</artifactId>
            <version>2.5.0</version>
         </dependency>
      </dependencies>
   </plugin>

[INFO] Using active recipe(s) [org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_7, org.openrewrite.java.testing.junit5.JUnit4to5Migration]
[INFO] Using active styles(s) []
[INFO] Validating active recipes...
[INFO] Project [ibss-site-dc] Resolving Poms...
[INFO] Project [ibss-site-dc] Parsing source files
[INFO] Running recipe(s)...
[WARNING] Changes have been made to pom.xml by:
[WARNING]     org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_7
[WARNING]         org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_6
[WARNING]             org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_5
[WARNING]                 org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_4
[WARNING]                     org.openrewrite.java.spring.boot2.SpringBoot2JUnit4to5Migration
[WARNING]                         org.openrewrite.java.testing.junit5.JUnit4to5Migration
[WARNING]                             org.openrewrite.maven.ExcludeDependency: {groupId=junit, artifactId=junit}
[WARNING]         org.openrewrite.java.dependencies.UpgradeDependencyVersion: {groupId=org.springframework.boot, artifactId=*, newVersion=2.7.x, overrideManagedVersion=false}
[WARNING] Changes have been made to src/main/java/com/fsde/ibss/dc/controller/ClientController.java by:
[WARNING]     org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_7
[WARNING]         org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_6
[WARNING]             org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_5
[WARNING]                 org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_4
[WARNING]                     org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_3
[WARNING]                         org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_2
[WARNING]                             org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_1
[WARNING]                                 org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_0
[WARNING]                                     org.openrewrite.java.spring.boot2.SpringBoot2BestPractices
[WARNING]                                         org.openrewrite.java.spring.NoRequestMappingAnnotation
[WARNING]                                         org.openrewrite.java.spring.ImplicitWebAnnotationNames
[WARNING] Changes have been made to src/test/java/com/fsde/ibss/dc/service/FileSaveTest.java by:
[WARNING]     org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_7
[WARNING]         org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_6
[WARNING]             org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_5
[WARNING]                 org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_4
[WARNING]                     org.openrewrite.java.spring.boot2.SpringBoot2JUnit4to5Migration
[WARNING]                         org.openrewrite.java.testing.junit5.JUnit4to5Migration
[WARNING]                             org.openrewrite.java.testing.junit5.UpdateTestAnnotation
[WARNING]                         org.openrewrite.java.spring.boot2.RemoveObsoleteSpringRunners
[WARNING]                             org.openrewrite.java.testing.junit5.JUnit5BestPractices
[WARNING]                                 org.openrewrite.java.testing.cleanup.RemoveTestPrefix
[WARNING]                                 org.openrewrite.java.testing.cleanup.TestsShouldNotBePublic
[WARNING] Please review and commit the results.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

在上面步骤我是先升级到了 Spring Boot 2，然后再执行升级 Spring Boot 3 和 Jakarta EE。实际上直接升级到 Spring Boot 3 也是可以的。
执行完成后可从 maven 中删除 rewrite-maven-plugin，也可留着下次做其他变更。

试用总结

注意事项：

我们项目配置都是通过远程配置中心管理的，所以升级过程中配置文件无法响应变更，解决办法是将配置从远端拷贝到本地 applicaiton.properties 中，执行完任务后根据变化再更新远程配置中心。
执行过程中可能会报错，比如 maven 插件升级后某些属性可能变更或失效，需要手动解决错误后，再执行 mvn rewrite:run，
可重复执行 mvn rewrite:run 命令，可随时加入新的 recipe 再执行，所以为了观察变更和保证执行成功，可分批次加入 recipe 多次执行。
OpenRewrite 不解析依赖的第三方 jar 包内容，所以第三方 jar 的问题需要自行识别，比如从 Java EE 到 Jakarta EE，只是替换规则中知道的 jar 包版本和当前项目的源代码，不会自动把 jar 包内的 javax. 替换为 jakarta.。

Spring Boot 3 到 4 迁移完全指南：新特性、废弃功能与实战踩坑经验

Tue, 25 Nov 2025 15:20:22 GMT

2025 年 11 月，Spring Boot 4.0 正式发布，这次升级被业界称为爆炸性升级。同时对于云原生应用而言，这是一次不可错过的性能与效率跃迁：

🐳 容器化友好：模块化架构减少 30-50% 运行时占用，镜像更小、启动更快
⚡ 启动速度提升 30-50%：多线程异步启动机制，容器冷启动时间显著缩短，更适合 Kubernetes 快速扩缩容
🚀 2-3 倍吞吐量提升：虚拟线程原生支持，I/O 密集型微服务资源利用率大幅提升，单实例可承载更高并发
🎯 云原生特性增强：内置弹性功能（重试、限流）、HTTP 接口客户端自动配置，简化微服务间通信

但这次升级也带来了 36 个废弃 API 移除、模块化架构重构、Tomcat 11 变更等挑战。本文基于 Spring Boot 官方文档和生产环境迁移经验，从原理到踩坑，提供完整、实用的迁移指南，助你平稳完成云原生应用的升级。

Spring Boot 4.0 核心新特性

作为 Spring Boot 3.x 之后的首个大版本更新，Spring Boot 4.0 基于 Spring Framework 7.0、Jakarta EE 11 和 Java 17+（推荐 Java 21 或 25），带来了模块化架构重构、虚拟线程原生支持、HTTP 服务客户端自动配置等重大变化。

Spring Boot 4.0 配套使用 Spring Cloud 2025.1.x。虽然版本号看起来只是中号版本变更，但实际上这是一次大版本变更，包含了大量破坏性变更和重要更新。

模块化架构

Spring Boot 4 将 spring-boot-autoconfigure 拆分为多个专注的模块，每个技术都有独立的 starter 和对应的测试 starter。

主要变化：

模块命名：spring-boot-<technology>，包路径：org.springframework.boot.<technology>
Starter 命名：spring-boot-starter-<technology> 和 spring-boot-starter-<technology>-test
之前没有 starter 的技术（如 Flyway、Liquibase）现在需要显式添加对应的 starter

模块化的优势：

减少 IDE 干扰：IDE 自动完成只显示你实际使用的技术相关的类和配置属性，不再出现无关的代码提示。例如，如果你不使用 GraphQL，IDE 不会提示 GraphQL 相关的配置属性
更小的运行时占用：只引入实际使用的模块，减少类路径开销和启动扫描成本。Spring Boot 3.5 的 spring-boot-autoconfigure 是 2 MiB，模块化后只引入需要的模块，显著减少占用
避免意外自动配置：模块化后，Spring Boot 能更准确地判断你的意图。例如，如果只使用 WebClient（通过 spring-boot-starter-webclient），不会意外启用 Web 服务器自动配置，不再需要调用 SpringApplication.setWebApplicationType(WebApplicationType.NONE)
启用新用例：例如，现在可以独立使用 Micrometer 指标（spring-boot-starter-micrometer-metrics），而不需要完整的 Actuator 依赖链
更好的维护性：模块边界成为明确的契约，而不是软约定，便于团队协作和代码维护

测试支持的模块化：

spring-boot-test-autoconfigure 也被模块化了。测试相关的注解现在位于对应的测试模块中。例如，@AutoConfigureDataJdbc 注解现在位于 spring-boot-starter-data-jdbc-test 模块中，与 spring-boot-starter-data-jdbc 对齐。

测试 Starter 的传递性：

所有 test starter 都会传递性地引入 spring-boot-starter-test，因此不需要再单独声明 spring-boot-starter-test。只需要列出被测试技术对应的 test starter 即可。

主要废弃 Starter 和替代方案：

废弃 Starter	替代
`spring-boot-starter-web`	`spring-boot-starter-webmvc`
`spring-boot-starter-aop`	`spring-boot-starter-aspectj`
`spring-boot-starter-oauth2-authorization-server`	`spring-boot-starter-security-oauth2-authorization-server`
`spring-boot-starter-oauth2-client`	`spring-boot-starter-security-oauth2-client`
`spring-boot-starter-oauth2-resource-server`	`spring-boot-starter-security-oauth2-resource-server`
`spring-boot-starter-web-services`	`spring-boot-starter-webservices`

其他迁移要点：

测试依赖需要添加对应的 -test starter，如 spring-boot-starter-security-test
之前没有 starter 的技术（如 Flyway、Liquibase）现在需要显式添加对应的 starter

完整的 Starter 列表：

Spring Boot 4.0 统一了 starter 的使用方式：大多数技术都有专门的 starter，每个 starter 都有对应的 test starter。以下是完整的列表（参考官方迁移指南）：

Technology	Main Dependency	Test Dependency
Core Starters
AspectJ	`spring-boot-starter-aspectj`	`spring-boot-starter-aspectj-test`
Cloud Foundry Support	`spring-boot-starter-cloudfoundry`	`spring-boot-starter-cloudfoundry-test`
Jakarta Validation	`spring-boot-starter-validation`	`spring-boot-starter-validation-test`
Kotlin Serialization	`spring-boot-starter-kotlin-serialization`	`spring-boot-starter-kotlin-serialization-test`
Reactor	`spring-boot-starter-reactor`	`spring-boot-starter-reactor-test`
Web Server Starters
Jetty	`spring-boot-starter-jetty`	none
Reactor Netty	`spring-boot-starter-reactor-netty`	none
Tomcat	`spring-boot-starter-tomcat`	none
Web Client Starters
Spring’s Imperative `RestClient` and `RestTemplate`	`spring-boot-starter-restclient`	`spring-boot-starter-restclient-test`
Spring’s Reactive `WebClient`	`spring-boot-starter-webclient`	`spring-boot-starter-webclient-test`
Web Starters
Jersey	`spring-boot-starter-jersey`	`spring-boot-starter-jersey-test`
Spring GraphQL	`spring-boot-starter-graphql`	`spring-boot-starter-graphql-test`
Spring HATEOAS	`spring-boot-starter-hateoas`	`spring-boot-starter-hateoas-test`
Spring Session Data Redis	`spring-boot-starter-session-data-redis`	`spring-boot-starter-session-data-redis-test`
Spring Session JDBC	`spring-boot-starter-session-jdbc`	`spring-boot-starter-session-jdbc-test`
Spring Web MVC	`spring-boot-starter-webmvc`	`spring-boot-starter-webmvc-test`
Spring WebFlux	`spring-boot-starter-webflux`	`spring-boot-starter-webflux-test`
Spring Webservices	`spring-boot-starter-webservices`	`spring-boot-starter-webservices-test`
Database Starters
Cassandra	`spring-boot-starter-cassandra`	`spring-boot-starter-cassandra-test`
Couchbase	`spring-boot-starter-couchbase`	`spring-boot-starter-couchbase-test`
Elasticsearch	`spring-boot-starter-elasticsearch`	`spring-boot-starter-elasticsearch-test`
Flyway	`spring-boot-starter-flyway`	`spring-boot-starter-flyway-test`
JDBC	`spring-boot-starter-jdbc`	`spring-boot-starter-jdbc-test`
jOOQ	`spring-boot-starter-jooq`	`spring-boot-starter-jooq-test`
Liquibase	`spring-boot-starter-liquibase`	`spring-boot-starter-liquibase-test`
LDAP	`spring-boot-starter-ldap`	`spring-boot-starter-ldap-test`
MongoDB	`spring-boot-starter-mongodb`	`spring-boot-starter-mongodb-test`
Neo4J	`spring-boot-starter-neo4j`	`spring-boot-starter-neo4j-test`
R2DBC	`spring-boot-starter-r2dbc`	`spring-boot-starter-r2dbc-test`
Spring Data Starters
Spring Data Cassandra	`spring-boot-starter-data-cassandra` 或 `spring-boot-starter-data-cassandra-reactive`	`spring-boot-starter-data-cassandra-test` 或 `spring-boot-starter-data-cassandra-reactive-test`
Spring Data Couchbase	`spring-boot-starter-data-couchbase` 或 `spring-boot-starter-data-couchbase-reactive`	`spring-boot-starter-data-couchbase-test` 或 `spring-boot-starter-data-couchbase-reactive-test`
Spring Data Elasticsearch	`spring-boot-starter-data-elasticsearch`	`spring-boot-starter-data-elasticsearch-test`
Spring Data JDBC	`spring-boot-starter-data-jdbc`	`spring-boot-starter-data-jdbc-test`
Spring Data JPA (using Hibernate)	`spring-boot-starter-data-jpa`	`spring-boot-starter-data-jpa-test`
Spring Data LDAP	`spring-boot-starter-data-ldap`	`spring-boot-starter-data-ldap-test`
Spring Data MongoDB	`spring-boot-starter-data-mongodb` 或 `spring-boot-starter-data-mongodb-reactive`	`spring-boot-starter-data-mongodb-test` 或 `spring-boot-starter-data-mongodb-reactive-test`
Spring Data Neo4J	`spring-boot-starter-data-neo4j`	`spring-boot-starter-data-neo4j-test`
Spring Data R2DBC	`spring-boot-starter-data-r2dbc`	`spring-boot-starter-data-r2dbc-test`
Spring Data Redis	`spring-boot-starter-data-redis` 或 `spring-boot-starter-data-redis-reactive`	`spring-boot-starter-data-redis-test` 或 `spring-boot-starter-data-redis-reactive-test`
Spring Data REST	`spring-boot-starter-data-rest`	`spring-boot-starter-data-rest-test`
IO Starters
Hazelcast	`spring-boot-starter-hazelcast`	`spring-boot-starter-hazelcast-test`
Mail	`spring-boot-starter-mail`	`spring-boot-starter-mail-test`
Quartz	`spring-boot-starter-quartz`	`spring-boot-starter-quartz-test`
SendGrid	`spring-boot-starter-sendgrid`	`spring-boot-starter-sendgrid-test`
Spring Caching Support	`spring-boot-starter-cache`	`spring-boot-starter-cache-test`
Spring Batch (with JDBC)	`spring-boot-starter-batch-jdbc`	`spring-boot-starter-batch-jdbc-test`
Spring Batch (without JDBC)	`spring-boot-starter-batch`	`spring-boot-starter-batch-test`
JSON Starters
GSON	`spring-boot-starter-gson`	`spring-boot-starter-gson-test`
Jackson	`spring-boot-starter-jackson`	`spring-boot-starter-jackson-test`
JSONB	`spring-boot-starter-jsonb`	`spring-boot-starter-jsonb-test`
Messaging Starters
ActiveMQ	`spring-boot-starter-activemq`	`spring-boot-starter-activemq-test`
Artemis	`spring-boot-starter-artemis`	`spring-boot-starter-artemis-test`
JMS	`spring-boot-starter-jms`	`spring-boot-starter-jms-test`
RSocket	`spring-boot-starter-rsocket`	`spring-boot-starter-rsocket-test`
Spring AMQP	`spring-boot-starter-amqp`	`spring-boot-starter-amqp-test`
Spring Integration	`spring-boot-starter-integration`	`spring-boot-starter-integration-test`
Spring for Apache Kafka	`spring-boot-starter-kafka`	`spring-boot-starter-kafka-test`
Spring for Apache Pulsar	`spring-boot-starter-pulsar`	`spring-boot-starter-pulsar-test`
Websockets	`spring-boot-starter-websocket`	`spring-boot-starter-websocket-test`
Security Starters
Spring Security	`spring-boot-starter-security`	`spring-boot-starter-security-test`
Spring Security OAuth Authorization Server	`spring-boot-starter-security-oauth2-authorization-server`	`spring-boot-starter-security-oauth2-authorization-server-test`
Spring Security OAuth Client	`spring-boot-starter-security-oauth2-client`	`spring-boot-starter-security-oauth2-client-test`
Spring Security OAuth Resource Server	`spring-boot-starter-security-oauth2-resource-server`	`spring-boot-starter-security-oauth2-resource-server-test`
Spring Security SAML	`spring-boot-starter-security-saml2`	`spring-boot-starter-security-saml2-test`
Templating Starters
Freemarker	`spring-boot-starter-freemarker`	`spring-boot-starter-freemarker-test`
Groovy Templates	`spring-boot-starter-groovy-templates`	`spring-boot-starter-groovy-templates-test`
Mustache	`spring-boot-starter-mustache`	`spring-boot-starter-mustache-test`
Thymeleaf	`spring-boot-starter-thymeleaf`	`spring-boot-starter-thymeleaf-test`
Production-Ready Starters
Actuator	`spring-boot-starter-actuator`	`spring-boot-starter-actuator-test`
Micrometer Metrics	`spring-boot-starter-micrometer-metrics`	`spring-boot-starter-micrometer-metrics-test`
OpenTelemetry	`spring-boot-starter-opentelemetry`	`spring-boot-starter-opentelemetry-test`
Zipkin	`spring-boot-starter-zipkin`	`spring-boot-starter-zipkin-test`

提示： 所有 test starter 都会传递性地引入 spring-boot-starter-test，因此不需要再单独声明 spring-boot-starter-test。只需要列出被测试技术对应的 test starter 即可。

Classic Starters（快速迁移方案）：

如果需要快速迁移，可以使用 Classic Starters，它们提供了类似 Spring Boot 3.x 的 classpath，让你可以快速恢复所有基础设施的可用性：

<!-- 替代 spring-boot-starter -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-classic</artifactId>
</dependency>

<!-- 替代 spring-boot-starter-test -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test-classic</artifactId>
    <scope>test</scope>
</dependency>

使用 Classic Starters 的好处：

快速恢复应用功能，无需立即处理所有 starter 替换
修复导入错误，验证应用能正常工作
作为过渡方案，降低迁移风险

迁移建议（官方推荐的两步法）：

第一步：使用 Classic Starters 快速迁移，修复编译错误，确保应用运行正常
第二步：逐步移除 Classic Starters，根据更新后的导入语句识别缺失的 starter，添加对应的模块化 starter

注意： 官方建议最终还是要迁移到模块化的 starter，Classic Starters 只是过渡方案。完整的 starter 列表和对应关系请参考官方迁移指南。

增强的配置属性元数据

Spring Boot 4 引入了新的注解 @ConfigurationPropertiesSource，允许 Spring Boot 读取外部模块中定义的 @ConfigurationProperties 类型，这在之前是不可能的。

使用场景：

@ConfigurationPropertiesSource("com.example.config")
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;
    // getters and setters
}

优势：

更清晰的模块化设计
改进工具支持（IDE 自动完成、配置提示等）
支持跨模块的配置属性定义

任务调度增强

Spring Boot 4 现在支持配置多个 TaskDecorator Bean，允许你组合多个装饰器来增强任务执行行为。

使用示例：

@Configuration
public class TaskConfig {

    @Bean
    public TaskDecorator loggingTaskDecorator() {
        return runnable -> {
            return () -> {
                System.out.println("Task started: " + Thread.currentThread().getName());
                try {
                    runnable.run();
                } finally {
                    System.out.println("Task completed");
                }
            };
        };
    }

    @Bean
    public TaskDecorator mdcTaskDecorator() {
        return runnable -> {
            String traceId = MDC.get("traceId");
            return () -> {
                MDC.put("traceId", traceId);
                try {
                    runnable.run();
                } finally {
                    MDC.clear();
                }
            };
        };
    }
}

多个 TaskDecorator 会按顺序应用，提供更灵活的任务执行增强能力。

包结构变化

模块化架构对包结构也有影响。每个模块现在都有独立的 org.springframework.boot.<module> 包路径。根据模块的职责范围，可能包含 API、自动配置、Actuator 相关支持等。

示例：

// Spring Boot 3.x
import org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration;

// Spring Boot 4.0
import org.springframework.boot.webmvc.autoconfigure.WebMvcAutoConfiguration;

主要变化：

每个技术模块都有独立的包路径：org.springframework.boot.<technology>
测试模块包路径：org.springframework.boot.<technology>.test
自动配置类、Actuator 支持等都位于对应的模块包下
如果你有自定义 starter，大概率都需要适配新的包路径，尤其是使用 class 字符名字，而不是 class 类的。

Spring Framework 7.0 带来的增强

Spring Boot 4 基于 Spring Framework 7.0 构建，继承了以下特性。

API 版本控制

Spring Framework 7 原生支持 API 版本管理，这是首次在 Spring 框架中提供官方支持。之前虽然可以通过 @RequestMapping 实现，但需要大量手动工作。

配置方式：

Java 配置：

@Configuration
public class WebConfiguration implements WebMvcConfigurer {
    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        configurer.useRequestHeader("API-Version");
        // 或使用其他策略：
        // configurer.useQueryParameter("version");
        // configurer.usePathPattern("/api/{version}");
        // configurer.useMediaType("application/vnd.api.v1+json");
    }
}

Spring Boot 配置属性：

spring:
  mvc:
    apiversion:
      use:
        header: API-Version
        # 或使用：
        # query-parameter: version
        # path-pattern: /api/{version}

使用示例：

@RestController
@RequestMapping("/api")
public class UserController {

    @GetMapping(value = "/users", version = "1")
    public List<UserV1> getUsersV1() {
        return userService.getUsersV1();
    }

    @GetMapping(value = "/users", version = "2")
    public List<UserV2> getUsersV2() {
        return userService.getUsersV2();
    }
}

功能式端点支持：

RouterFunction<ServerResponse> route = RouterFunctions.route()
    .GET("/hello-world", version("1.2"),
        request -> ServerResponse.ok().body("Hello World"))
    .build();

支持的版本控制策略：

路径版本控制：/v1/users、/v2/users（需要在路径中声明 URI 变量）
请求头版本控制：X-API-Version: 1 或自定义 header 名称
查询参数版本控制：/users?version=1
媒体类型版本控制：Accept: application/vnd.api.v1+json

版本格式：

默认使用语义化版本（Semantic Versioning），支持 major.minor.patch 格式。如果未指定 minor 和 patch，默认为 0。版本解析器可以自定义，支持日期格式或其他格式。

废弃处理：

API 版本控制支持 RFC 9745 标准的废弃处理，可以在响应中发送废弃提示。

JSpecify 空安全注解

Spring Framework 7 迁移到 JSpecify 注解，这是 Spring 生态系统中空安全支持的重大里程碑。JSpecify 是一个由 OpenJDK、Broadcom、Google、JetBrains、Sonar 等组织共同参与的标准项目。

已支持 JSpecify 的 Spring 项目：

Spring Boot 4.0
Spring Framework 7.0
Spring Data 4.0
Spring Security 7.0
Spring Batch 6.0
Spring Kafka 4.0
Spring Integration 7.0
Spring GraphQL 2.0
Spring Web Services 5.0
Spring AMQP 4.0
Spring Shell 4.0
Spring Plugin 4.0
Spring HATEOAS 3.0
Spring Modulith 2.0
Spring Vault 4.0
Spring Cloud Commons 5.0
Spring Cloud Gateway 5.0
Micrometer 1.16
Micrometer Tracing 1.6
Context Propagation 1.2
Reactor 2025.0

使用示例：

import org.jspecify.annotations.Nullable;
import org.jspecify.annotations.NonNull;

public class UserService {

    public @NonNull User getUser(@NonNull String userId) {
        return userRepository.findById(userId)
            .orElseThrow(() -> new UserNotFoundException(userId));
    }

    public @Nullable User findUser(@NonNull String email) {
        return userRepository.findByEmail(email).orElse(null);
    }
}

IDE 支持：

IntelliJ IDEA 2025.3+：提供完整的 JSpecify 支持，包括复杂的数据流分析
Kotlin 2.2：自动将 JSpecify 注解转换为 Kotlin 空安全类型，告别平台类型（platform types）
NullAway：构建时检查工具，需要 JDK 21+（JDK 17 支持可能在后续版本提供）

Kotlin 项目注意事项：

JSpecify 注解会明确标记可空性，Kotlin 编译器会自动识别并转换。如果 Java 接口使用 @Nullable 注解，Kotlin 实现必须返回可空类型；如果使用 @NonNull，则必须返回非空类型。IntelliJ IDEA 会提供相应的编译错误提示和修复建议。

多线程异步启动

Spring Framework 7.0 引入了多线程异步启动机制，可以并行初始化 ApplicationContext，显著加快应用启动速度。

工作原理：

ApplicationContext 启动时，可以并行初始化多个 Bean
利用多核 CPU 资源，将串行的 Bean 初始化改为并行执行
自动处理 Bean 之间的依赖关系，确保初始化顺序正确

配置方式：

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(Application.class);
        // 启用异步启动
        app.setApplicationStartup(new BufferingApplicationStartup(1000));
        app.run(args);
    }
}

或者通过配置属性：

spring:
  application:
    startup:
      enabled: true

性能提升：

大型应用启动时间可减少 30-50%
特别适合 Bean 数量多、初始化耗时的应用
充分利用多核 CPU，提升资源利用率

注意事项：

需要确保 Bean 初始化是线程安全的
某些单例 Bean 可能仍需要串行初始化
建议在测试环境先验证，确保无并发问题

HTTP 接口客户端

Spring Framework 7 和 Spring Boot 4 大幅简化了 HTTP 接口客户端的配置。之前需要手动创建 HttpServiceProxyFactory 和配置每个客户端，现在可以通过声明式方式自动注册。

建议： 虽然 RestTemplate 仍可使用，但推荐使用 RestClient 或 HTTP 接口客户端（@HttpExchange）作为替代方案。

旧方式（Spring Framework 6 / Spring Boot 3）：

@HttpExchange(url = "/api/users")
public interface UserClient {
    @GetExchange("/{id}")
    User getUser(@PathVariable String id);

    @PostExchange
    User createUser(@RequestBody UserRequest request);
}

// 需要手动配置每个客户端
@Configuration
public class HttpClientConfig {
    @Bean
    public UserClient userClient(RestClient.Builder builder) {
        RestClient restClient = builder.baseUrl("https://api.example.com").build();
        HttpServiceProxyFactory factory = HttpServiceProxyFactory
            .builderFor(RestClientAdapter.create(restClient)).build();
        return factory.createClient(UserClient.class);
    }

    // 如果有多个客户端，需要重复配置。..
}

新方式（Spring Framework 7 / Spring Boot 4）：

使用 @ImportHttpServices 注解：

@HttpExchange(url = "/api/users")
public interface UserClient {
    @GetExchange("/{id}")
    User getUser(@PathVariable String id);

    @PostExchange
    User createUser(@RequestBody UserRequest request);
}

@Configuration
@ImportHttpServices(group = "api", types = {UserClient.class})
public class HttpClientConfig {
}

配置 application.yml：

spring:
  http:
    client:
      service:
        read-timeout: 2s
        group:
          api:
            base-url: https://api.example.com

或使用包扫描自动发现：

@Configuration
@ImportHttpServices(group = "api", basePackages = "com.example.client")
public class HttpClientConfig {
}

多组配置示例：

如果应用需要集成多个 REST API，可以为每个 API 配置不同的组：

@Configuration
@ImportHttpServices(group = "github", basePackages = "com.example.client.github")
@ImportHttpServices(group = "stackoverflow", basePackages = "com.example.client.stackoverflow")
public class HttpClientConfig {
}

对应的配置：

spring:
  http:
    client:
      service:
        group:
          github:
            base-url: https://api.github.com
            read-timeout: 5s
          stackoverflow:
            base-url: https://api.stackexchange.com
            read-timeout: 10s

使用 WebClient（响应式）：

默认使用 RestClient，如需使用 WebClient，可通过配置切换：

@Configuration
@ImportHttpServices(
    group = "api",
    basePackages = "com.example.client",
    clientType = ClientType.WEB_CLIENT
)
public class HttpClientConfig {
}

优势：

配置简化：不再需要为每个客户端手动创建 HttpServiceProxyFactory 和 Bean
自动注册：所有 HTTP 接口自动注册为 Spring Bean，可直接注入使用
统一管理：通过组（group）概念统一管理同一 API 的所有客户端
灵活配置：支持为不同组配置不同的超时、重试等策略

这样 com.example.client 包下所有带 @HttpExchange 的接口都会自动注册为 Spring Bean，可以直接注入使用：

@Service
public class UserService {
    private final UserClient userClient;  // 直接注入，无需手动配置

    public UserService(UserClient userClient) {
        this.userClient = userClient;
    }

    public User getUser(String id) {
        return userClient.getUser(id);  // 直接使用
    }
}

内置弹性功能（Resilience）

Spring Framework 7 引入了强大的弹性工具，直接集成到核心框架中：

@Retryable：自动重试失败的方法调用，支持配置最大尝试次数、延迟、抖动和退避策略，也支持响应式返回类型
@ConcurrencyLimit：限制并发方法调用数量，保护服务和资源（例如限制为单线程访问）

配置方式：

@Configuration
@EnableResilientMethods
public class ApplicationConfig {
}

@Service
public class PaymentService {

    @Retryable(
        maxAttempts = 3,
        backoff = @Retryable.Backoff(delay = 2000, multiplier = 2.0)
    )
    @ConcurrencyLimit(value = 2)  // 只允许 2 个并发调用
    public void processPayment(String paymentId) {
        // 处理支付逻辑
    }
}

优势：

无需引入第三方库（如 Resilience4j）
与 Spring 生态深度集成
支持响应式编程模型
配置简单，开箱即用

流式 JMS 客户端 API（JmsClient）

Spring Framework 7 引入了 JmsClient，类似于 JdbcClient 和 RestClient，提供流畅的构建器风格 API。这是对传统 JMS 模板的更优雅和可读的替代方案。

使用示例：

@Service
public class MessageService {

    private final JmsClient jmsClient;

    public MessageService(JmsClient jmsClient) {
        this.jmsClient = jmsClient;
    }

    public void sendMessage(String destination, String message) {
        jmsClient.create()
            .queue(destination)
            .body(message)
            .send();
    }

    public String receiveMessage(String destination) {
        return jmsClient.create()
            .queue(destination)
            .receive(String.class);
    }
}

优势：

流畅的 API 设计，代码更易读
与 JdbcClient、RestClient 保持一致的风格
Spring Boot 4 提供自动配置支持

统一消息转换（Unified Message Conversion）

Spring Framework 7 简化了消息转换，引入了新的 HttpMessageConverters 配置类。这种统一方法借鉴了响应式编解码器的设计，简化了 HTTP 消息的序列化和反序列化。

Jakarta EE 11 升级

Spring Framework 7 采用 Jakarta EE 11 规范：

Servlet 6.1
JPA 3.2
Bean Validation 3.1
WebSocket 2.2

JPA 3.2 重要变化：

之前，EntityManager 只能通过 @PersistenceContext 注解注入。现在，EntityManagerFactory 和共享的 EntityManager 都可以使用 @Inject 或 @Autowired 注入，并支持使用限定符来选择特定的持久化单元（当配置了多个持久化单元时）。

// 旧方式（仍然支持）
@PersistenceContext
private EntityManager entityManager;

// 新方式（Spring Framework 7 / JPA 3.2）
@Autowired
private EntityManager entityManager;

// 多个持久化单元时使用限定符
@Autowired
@Qualifier("primaryEntityManager")
private EntityManager primaryEntityManager;

这里要提醒一下：javax.* 到 jakarta.* 的迁移应该在 Spring Boot 3.0 的时候就已经完成了。如果你还在用 Spring Boot 2.x，那得先升级到 3.x，然后再考虑 4.0。

JUnit 4 和 Jackson 2.x 弃用

JUnit 4：官方推荐迁移到 JUnit 5
Jackson 2.x：Spring Boot 4 使用 Jackson 3.x

Jackson 3.x 的破坏性变更：

部分注解被移除
更严格的类型处理
模块整合
ObjectMapper 行为变更

迁移示例：

// Jackson 2.x
@JsonInclude(JsonInclude.Include.NON_NULL)
public class User {
    private String name;
    // ...
}

// Jackson 3.x （同样的语法，但内部行为可能不同）
@JsonInclude(JsonInclude.Include.NON_NULL)
public class User {
    private String name;
    // ...
}

测试上下文暂停机制

Spring Framework 7 引入了一个挺有意思的测试上下文管理机制：

测试上下文在不使用的时候会自动暂停（stopped）
下次用的时候会自动重启
这样能显著降低测试套件的内存占用

该机制可显著降低测试套件的内存占用。

SpEL 增强

支持 Optional 类型和 Elvis 操作符：

@Value("#{userService.findUser('123')?.name ?: 'Unknown'}")
private String userName;

程序化 Bean 注册（BeanRegistrar）

Spring Framework 7 引入了 BeanRegistrar 接口，允许在 @ConditionalOn... 注解族不够用时进行动态 Bean 注册。

Java 实现：

import org.springframework.context.bean.BeanRegistrar;
import org.springframework.context.bean.BeanRegistry;

public class QuoteProviderRegistrar implements BeanRegistrar {
    @Override
    public void register(BeanRegistry registry, Environment env) {
        registry.registerBean("quoteProviderDb", QuoteProviderDb.class);
        registry.registerBean("quoteProviderFallback",
                QuoteProviderFallback.class,
                spec -> {
                    spec.fallback();
                    spec.order(1);
                });
    }
}

Kotlin DSL 实现（更优雅）：

Kotlin 2.2 提供了 BeanRegistrarDsl，让 Bean 注册更加简洁：

import org.springframework.context.bean.BeanRegistrarDsl

class QuoteProviderRegistrar : BeanRegistrarDsl({
    registerBean<QuoteProviderDb>("quoteProviderDb")
    registerBean<QuoteProviderFallback>(
        name = "quoteProviderFallback",
        fallback = true,
        order = 1
    )
})

使用场景：

根据环境变量或配置动态注册 Bean
实现复杂的条件逻辑，超出 @ConditionalOn... 注解的能力范围
需要根据运行时信息决定注册哪些 Bean

Tomcat 11 核心变更

Tomcat 11 是 Apache Tomcat 项目第九个主要版本，标志着从传统 Java EE 向现代 Jakarta EE 框架的重要转变。本次升级支持 Jakarta EE 11，实现了：

Servlet 6.1 - 改进异步请求处理，提升长运行任务的性能
JSP 4.0
EL 6.0
WebSocket 2.2 - 性能和可扩展性显著提升，特别适合实时双向通信场景（如聊天应用、协作工具）
Authentication 3.1

虚拟线程支持（Java 21+）

重要特性： Tomcat 11 原生支持 Java 21 的 Project Loom 虚拟线程，这是本次升级的核心亮点之一。

性能数据（基于实际测试）：

根据 Fast Thread 和 Java Code Geeks 的性能基准测试：

场景	平台线程	虚拟线程	性能提升
I/O 密集型应用（数据库查询、HTTP 调用）	基准	2-3x 吞吐量	+100-200%
高并发 Web 请求（1000+ 并发）	基准	2-3x 吞吐量	+100-200%
CPU 密集型应用	基准	无明显提升	0%
内存占用	基准	-30-50%（线程栈）	-30-50%
响应时间（P99）	基准	-20-40%	-20-40%

适用场景：

✅ 推荐使用：REST API、数据库查询、HTTP 客户端调用、文件 I/O、消息队列消费
❌ 不推荐使用：CPU 密集型计算、图像处理、加密解密、复杂算法

实际案例：

一个典型的 Spring Boot Web 应用（处理 REST 请求，调用数据库和外部 API）：

使用平台线程：1000 并发请求，吞吐量约 500 req/s，P99 延迟 200ms
使用虚拟线程：1000 并发请求，吞吐量约 1200-1500 req/s，P99 延迟 120ms
性能提升：吞吐量提升 2-3 倍，延迟降低 40%

优势：

轻量级并发模型，简化线程管理
相比传统线程模型，提供更好的可扩展性
特别适合 I/O 密集型应用，可以处理大量并发连接

配置方式：

在 Spring Boot 4 中，虚拟线程支持通过配置属性启用：

spring:
  threads:
    virtual:
      enabled: true

适用场景：

Web 请求处理
WebSocket 连接管理
高并发 I/O 操作

WebSocket 2.2 性能提升

重要变化： Tomcat 11 升级到 Jakarta WebSocket 2.2，带来显著的性能和可扩展性提升。

主要改进：

更高效的实时双向通信处理
改进的流式数据传输能力
更好的并发连接管理
特别适合需要实时更新的应用（如聊天、协作工具、实时数据流）

与 HTTP/2 和异步处理的协同：

Tomcat 11 的 WebSocket 改进与 HTTP/2 支持和异步处理能力协同工作，确保更响应式和可扩展的 Web 应用。

Servlet 6.1 异步处理改进

重要变化： Jakarta Servlet 6.1 改进了 Web 应用处理 HTTP 请求的方式，特别是异步请求处理。

主要改进：

更高效的异步请求处理机制
提升长运行任务的性能
更好的资源利用率

安全增强

重要变化： Tomcat 11 引入了多项安全增强。

主要改进：

更好的 TLS/SSL 默认配置 - 使管理员更容易建立安全的 HTTPS 连接，开箱即用
改进的安全实践和默认设置

最低 Java 版本要求

Tomcat 11 要求至少 Java SE 17，这个和 Spring Boot 4 的要求一致。

影响：

确保 Tomcat 能够利用最新的 Java 语言特性和性能改进
包括增强的内存管理、Records、更高效的 switch 表达式等
需要从旧版本 Java 升级的应用需要特别注意

OpenSSL 支持（Java 22+）

如果你用的是 Java 22+，Tomcat 11 支持通过 FFM（Foreign Function & Memory API）使用 OpenSSL，性能会更好。

javax. 到 jakarta. 命名空间迁移

重要提醒： 迁移到 Tomcat 11 的一个挑战性方面是需要重构应用以适应从 javax.* 到 jakarta.* 命名空间的切换。

影响：

这是从早期 Tomcat 版本迁移的基础性变更
特别是使用 Java EE 的应用需要特别注意
Tomcat 11 提供了迁移工具来支持这一转换
需要仔细测试以确保应用在新命名空间下继续正常工作

注意： 如果你还在使用 Spring Boot 2.x，需要先升级到 Spring Boot 3.x（已完成 javax.* 到 jakarta.* 迁移），然后再考虑升级到 Spring Boot 4.0。

HTTP Header 大小写处理变化

Tomcat 11 使用 header name 的原始大小写来存储 HTTP/1.1 request headers，而不是强制将其转换为小写。以前 Tomcat 会自动转小写，现在不会了。

主要影响：

取 Header 时一定要关注大小写
建议按照 RFC 7230 建议，全链路都统一使用小写
如果代码中直接比较 header 名称字符串，可能因为大小写不匹配而失败
Spring Framework 7.0 的 HttpHeaders API 也有相应变化

废弃功能与破坏性变更

移除的废弃 API

Spring Boot 4.0 这次移除了 36 个废弃类，大概占了所有废弃 API 的 88%。迁移的时候这些地方需要特别注意：

MockBean 和 SpyBean 移除

影响： 测试代码中广泛使用。旧写法：

// Spring Boot 3.x （已废弃，4.0 移除）
@SpringBootTest
class UserServiceTest {
    @MockBean
    private UserRepository userRepository;
}

新写法：

// Spring Boot 4.0 （使用 Spring 官方支持）
@SpringBootTest
class UserServiceTest {
    @MockitoBean
    private UserRepository userRepository;
}

MockitoTestExecutionListener 移除

Spring Boot 4.0 移除了该监听器，使用 Spring 的原生 Mockito 支持。

WebSecurityConfigurerAdapter 移除

该改动在 Spring Boot 3.x 时已废弃，4.0 正式移除。

旧写法：

// Spring Boot 2.x/3.x （已废弃）
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/public/**").permitAll()
            .anyRequest().authenticated();
    }
}

需要改成新的方式：

// Spring Boot 4.0
@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/public/**").permitAll()
                .anyRequest().authenticated()
            )
            .build();
    }
}

该改动在 Spring Boot 3.x 时已废弃，4.0 正式移除。

Undertow 支持移除

Undertow 目前不兼容 Servlet 6.1，Spring Boot 4.0 移除了对它的支持：

<!-- Spring Boot 4.0 不再支持 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-undertow</artifactId>
</dependency>

替代方案：

切换到 Tomcat 11（推荐）
使用 Jetty 12.1+
等待 Undertow 支持 Servlet 6.1

Spring Batch 默认行为变更

Spring Batch 现在默认在内存中存储元数据，不再使用数据库。这可能导致 Job 执行历史丢失：

<!-- 如果需要持久化元数据，显式添加 JDBC 支持 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-batch-jdbc</artifactId>
</dependency>

Reactive Pulsar 支持移除

Spring Pulsar 移除了 Reactor 支持，所以 Spring Boot 4.0 也相应移除了响应式 Pulsar 客户端的自动配置。

Embedded Executable Uber Jar Launch Scripts 移除

Spring Boot 4.0 移除了用于创建”完全可执行” jar 文件的嵌入式启动脚本支持。该功能仅适用于类 Unix 系统，且与高效部署建议冲突。

如果需要类似功能，可以使用 Gradle 的 application plugin 等替代方案。你仍然可以使用 Spring Boot 的构建插件创建 uber jar，并通过 java -jar 运行。

Spring Session Hazelcast/MongoDB 移除

Spring Session Hazelcast 和 Spring Session MongoDB 现在分别由 Hazelcast 团队和 MongoDB 团队维护，Spring Boot 4.0 移除了对它们的直接支持。如需使用，请直接使用对应的 starter。

常见问题与解决方案

HTTP Header 大小写问题

问题：Header 访问失败或行为不一致

升级到 Tomcat 11.0.12+ 和 Spring Framework 7.0 后，某些 header 访问可能出现问题。这是 Spring Boot 4 迁移中必须关注的坑。

原因：

Tomcat 11.0.12+：HTTP 请求头名称会保留原始大小写，而不是强制转换为小写（以前 Tomcat 会自动转小写，现在不会了）
Spring Framework 7.0：HttpHeaders API 不再继承 MultiValueMap
Header 名称大小写不敏感，但某些代码可能依赖特定的大小写格式或直接比较 header 名称

建议： 按照 RFC 7230 建议，全链路都统一使用小写 header 名称。

解决方案：

更新 HttpHeaders 的使用方式：

// 旧代码（Spring Framework 6.x）
HttpHeaders headers = new HttpHeaders();
headers.add("Content-Type", "application/json");
String contentType = headers.getFirst("Content-Type");

// 新代码（Spring Framework 7.0）
HttpHeaders headers = new HttpHeaders();
headers.add("Content-Type", "application/json");
String contentType = headers.getFirst("Content-Type"); // 仍然可用
// 或使用
boolean hasContentType = headers.contains("Content-Type"); // 大小写不敏感

统一使用标准格式的 header 名称：

// 推荐：使用标准格式
headers.add("Content-Type", "application/json");
headers.add("Authorization", "Bearer token");
headers.add("X-Custom-Header", "value");

更新 header 名称比较的代码：

// 问题代码：直接字符串比较可能失败
Enumeration<String> headerNames = request.getHeaderNames();
while (headerNames.hasMoreElements()) {
    String name = headerNames.nextElement();
    if (name.equals("content-type")) { // 可能失败，name 可能是 "Content-Type"
        // ...
    }
}

// 推荐：使用大小写不敏感比较
if (name.equalsIgnoreCase("content-type")) {
    // ...
}

更新测试代码：

// MockHttpServletRequest 的行为已更新
MockHttpServletRequest request = new MockHttpServletRequest();
request.addHeader("Content-Type", "application/json");

// 以下都能正常工作（大小写不敏感）
assertThat(request.getHeader("Content-Type")).isNotNull();
assertThat(request.getHeader("content-type")).isNotNull();
assertThat(request.getHeader("CONTENT-TYPE")).isNotNull();

// 但遍历时需要注意原始大小写
Enumeration<String> names = request.getHeaderNames();
while (names.hasMoreElements()) {
    String name = names.nextElement();
    // name 可能是 "Content-Type" 而不是 "content-type"
    assertThat(name).isEqualTo("Content-Type"); // 使用原始大小写
}

编译时 Nullability 错误

问题：JSpecify 注解导致 Kotlin 或空值检查工具报错

Kotlin 项目可能遇到以下错误：

error: [nullness] incompatible types in return.
  required: @NonNull String
  found:    @Nullable String

解决方案：

// Kotlin 中处理可空类型
val user: User? = userService.findUser("123")
val name: String = user?.name ?: "Unknown"

或者临时禁用严格空值检查：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <compilerArgs>
            <arg>-Xlint:-nullness</arg>
        </compilerArgs>
    </configuration>
</plugin>

Jackson 3.x 序列化问题

问题：JSON 序列化/反序列化行为变更

Jackson 3.x 的行为和 2.x 有些不一样，可能会导致一些序列化问题。

解决方案：

@Configuration
public class JacksonConfig {

    @Bean
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        // 恢复 Jackson 2.x 的兼容性行为
        mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
        mapper.configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false);
        mapper.registerModule(new JavaTimeModule());
        return mapper;
    }
}

第三方库不兼容

问题：某些库依赖旧版本的 Spring 或 Jakarta API

部分第三方库可能尚未适配 Spring Boot 4.0。

解决方案：

检查库的最新版本
使用依赖排除和强制版本：

<dependency>
    <groupId>com.example</groupId>
    <artifactId>legacy-library</artifactId>
    <version>1.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>*</artifactId>
        </exclusion>
    </exclusions>
</dependency>

考虑替换为兼容的库

Spring Batch 元数据丢失

问题：升级后找不到 Job 执行历史

升级后 Job 执行历史丢失，原因是 Spring Batch 默认行为变更。

解决方案：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-batch-jdbc</artifactId>
</dependency>

spring:
  batch:
    jdbc:
      initialize-schema: always

Undertow 无法使用

问题：spring-boot-starter-undertow 不再可用

解决方案：切换到 Tomcat：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <!-- 默认使用 Tomcat，无需额外配置 -->
</dependency>

如果需要 Jetty：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jetty</artifactId>
</dependency>

虚拟线程性能未达预期

问题：启用虚拟线程后性能无明显提升

可能原因：

应用是 CPU 密集型的（虚拟线程对这种情况没用）
数据库连接池配置不当
用了同步的阻塞代码（比如 synchronized）

解决方案：

# 优化数据库连接池
spring:
  datasource:
    hikari:
      maximum-pool-size: 50 # 虚拟线程环境可适当增加
      minimum-idle: 10

# 确保启用虚拟线程
spring:
  threads:
    virtual:
      enabled: true

使用 JFR (Java Flight Recorder) 分析：

java -XX:StartFlightRecording=filename=recording.jfr -jar app.jar

测试上下文缓存问题

问题：测试上下文自动暂停导致测试变慢

Spring Framework 7 的测试上下文暂停机制可能导致测试变慢。

解决方案：

调整测试上下文缓存配置：

@SpringBootTest
@TestPropertySource(properties = {
    "spring.test.context.cache.maxSize=10"
})
class MyTest {
    // ...
}

升级顺序与验收门禁

不要把“依赖能解析”当成迁移完成。更稳妥的顺序是：先在 Spring Boot 3.x 升到当前维护线并清理废弃 API，再切换 Boot 4；这样能把问题拆成两批，回滚也更简单。具体版本以官方迁移指南和 Spring Boot 4 发布说明为准。

建议把下面几项设为合并门禁：

依赖收敛：检查 spring-*、jakarta.*、Servlet、Jackson、数据库驱动是否被第三方库拉入旧版本；Maven 使用 dependency:tree，Gradle 使用 dependencies/dependencyInsight。
先 dry run 再改代码：OpenRewrite 只负责机械变更，运行后必须人工检查安全配置、序列化配置和自定义自动配置，不能把自动修复当成测试替代品。
测试分层执行：先编译和单元测试，再跑 @SpringBootTest、MockMvc/WebTestClient、数据库迁移、消息消费和真实容器集成测试；重点覆盖鉴权、异常响应、Header、日期/数字序列化。
上线前可回滚：保留 Boot 3 构建产物和数据库回滚方案，灰度期间同时观察启动失败率、5xx、P95 延迟、线程/连接池和 GC；不要在同一个发布窗口同时升级 JDK、数据库和中间件。

判断标准：构建通过只是起点；依赖树无冲突、关键链路测试通过、指标没有回归，并且能切回旧产物，才算迁移完成。

自动化迁移工具

OpenRewrite

OpenRewrite 是开源的自动化代码重构工具，支持 Spring Boot 迁移。

Maven 集成：

<build>
    <plugins>
        <plugin>
            <groupId>org.openrewrite.maven</groupId>
            <artifactId>rewrite-maven-plugin</artifactId>
            <version>5.40.0</version>
            <configuration>
                <activeRecipes>
                    <recipe>org.openrewrite.java.spring.boot4.UpgradeSpringBoot_4_0</recipe>
                </activeRecipes>
            </configuration>
            <dependencies>
                <dependency>
                    <groupId>org.openrewrite.recipe</groupId>
                    <artifactId>rewrite-spring</artifactId>
                    <version>5.22.0</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

Gradle 集成：

plugins {
    id 'org.openrewrite.rewrite' version '6.25.0'
}

rewrite {
    activeRecipe('org.openrewrite.java.spring.boot4.UpgradeSpringBoot_4_0')
}

dependencies {
    rewrite 'org.openrewrite.recipe:rewrite-spring:5.22.0'
}

运行迁移：

# Maven: 预览变更
mvn rewrite:dryRun

# Maven: 应用变更
mvn rewrite:run

# Gradle: 预览变更
./gradlew rewriteDryRun

# Gradle: 应用变更
./gradlew rewriteRun

主要功能：

自动升级 Spring Boot 版本号
替换废弃的 API（如 @MockBean → @MockitoBean）
更新 import 语句
修复依赖冲突
调整配置文件格式
重构安全配置（移除 WebSecurityConfigurerAdapter）

示例：迁移安全配置

OpenRewrite 会自动将：

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests().anyRequest().authenticated();
    }
}

重构为：

@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http.authorizeHttpRequests(auth ->
            auth.anyRequest().authenticated()
        ).build();
    }
}

Spring Boot Migrator

Spring Boot Migrator 是 Spring 官方的实验性工具，基于 OpenRewrite，专门用于将传统 Spring 应用迁移到 Spring Boot，同时提供 Spring Boot 版本升级。

主要功能：

将传统 Spring 项目初始化为 Spring Boot 应用
将 Spring XML 配置转换为 Java 配置
Spring Boot 版本升级

# 安装
git clone https://github.com/spring-projects-experimental/spring-boot-migrator.git
cd spring-boot-migrator
./mvnw clean install

# 扫描项目
java -jar applications/cli/target/spring-boot-migrator.jar scan /path/to/project

# 应用迁移
java -jar applications/cli/target/spring-boot-migrator.jar migrate /path/to/project

Windup (Red Hat)

Windup 是 Red Hat 提供的 Java 应用现代化和迁移工具，支持大规模 Java 应用迁移。

主要功能：

代码分析和迁移评估
支持多种迁移场景（Java 版本升级、框架迁移、云迁移等）
生成迁移报告和评估工作量

适用场景：

大型企业级应用迁移
多项目批量迁移
云原生应用迁移

IntelliJ IDEA 迁移助手

IntelliJ IDEA 2025.3+ 内置了 Spring Boot 4 迁移支持：

打开项目
右键点击 pom.xml 或 build.gradle
选择 Refactor → Migrate to Spring Boot 4.0
按照向导完成迁移

Eclipse Transformer

从 Spring Boot 2.x 迁移时，可使用 Eclipse Transformer 批量转换 javax.* 到 jakarta.*：

java -jar transformer.jar /path/to/project /path/to/output

参考资料

迁移工具

OpenRewrite: Migrate to Spring Boot 4.0 - OpenRewrite 官方文档
Spring Boot Migrator - Spring 官方迁移工具
Windup - Red Hat 应用现代化工具
EMT4J - Eclipse Java 版本迁移工具
Moderne.ai - 企业级 OpenRewrite 托管服务

Awesome Alternatives Bitnami：寻找 Bitnami Charts 的替代方案

Mon, 03 Nov 2025 14:03:42 GMT

Bitnami 曾是最受欢迎的 Helm Charts 和容器镜像提供商之一，但其维护策略调整后，很多 Charts 已停止更新或更新严重滞后。本文整理了常用中间件的替代 Helm Charts 和镜像来源，供团队迁移参考。

为什么要从 Bitnami 迁移

更新滞后：部分 Charts 长期未更新，Kubernetes 新版 API 不兼容。
镜像安全：老旧镜像可能存在已知 CVE 漏洞。
社区活跃度：官方维护的资源更有保障。

替代方案汇总

数据库

中间件	Bitnami Chart	推荐替代
PostgreSQL	`bitnami/postgresql`	CrunchyData Postgres Operator 或 CloudNativePG
MySQL	`bitnami/mysql`	mysql-operator 或官方 Docker 镜像
Redis	`bitnami/redis`	redis-operator 或直接使用官方 Helm Chart
MongoDB	`bitnami/mongodb`	MongoDB Community Operator
ClickHouse	`bitnami/clickhouse`	clickhouse-operator（Altinity 维护）

消息队列

中间件	Bitnami Chart	推荐替代
Kafka	`bitnami/kafka`	Strimzi Operator
RabbitMQ	`bitnami/rabbitmq`	RabbitMQ Cluster Operator
NATS	—	官方 nats-io/k8s Helm Chart

基础组件

中间件	Bitnami Chart	推荐替代
Nginx	`bitnami/nginx`	官方 Docker 镜像 + 自编 Helm Chart，或用 ingress-nginx
cert-manager	—	官方 jetstack/cert-manager Helm Chart
Keycloak	`bitnami/keycloak`	官方 keycloak/keycloak Helm Chart（Quarkus 版）
Harbor	`bitnami/harbor`	官方 goharbor/harbor-helm

容器镜像替代来源

如果仅使用 Bitnami 的容器镜像（而非完整 Chart），可考虑的替代来源：

Docker Official Images：docker.io/library/*，最权威可靠的基础镜像。
Chainguard Images：专注于安全的最小化、无发行版镜像，CVE 极低。
linuxserver.io：维护了大量流行应用的容器镜像，社区活跃。
官方项目镜像：如 docker.io/envoyproxy/envoy、quay.io/prometheus/prometheus 等。

迁移建议

优先级排序

安全优先：先迁移存在已知 CVE 且无法更新的组件。
依赖关系：从底层依赖（数据库、消息队列）开始，再到上层应用。
灰度迁移：在新环境（如新 namespace）部署替代方案，DNS/Service 切换后再清理旧资源。

迁移检查清单

确认替代方案的功能覆盖度（监控指标、备份恢复、持久化存储等）
导出并验证数据备份
在测试环境完整验证一次迁移流程
准备回滚方案（保留原有 PV 和配置，必要时可快速切换回去）
更新监控和告警规则（指标名称可能有变化）
更新 CI/CD 中的 Helm 仓库引用

自编 Helm Chart 模板

对于简单的无状态服务，自编一个简洁的 Helm Chart 替代 Bitnami Chart 往往更可控：

templates/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ .Release.Name }}
  template:
    metadata:
      labels:
        app: {{ .Release.Name }}
    spec:
      containers:
        - name: {{ .Release.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports:
            - containerPort: {{ .Values.service.port }}
          {{- with .Values.resources }}
          resources:
            {{- toYaml . | nindent 12 }}
          {{- end }}

总结

Bitnami Charts 的替代并非一刀切——对于仍正常维护的 Chart 可继续使用。重点关注已停止更新或存在安全漏洞的组件，优先迁移到官方 Operator 或活跃社区维护的方案。

Javax 和 Jakarta 过渡期兼容方案

Sun, 14 Sep 2025 06:33:23 GMT

什么是 Jakarta EE，为什么要切换

Jakarta EE 就是 Java EE 的新名词。这里的 EE 全称是 Enterprise Edition，它是专门为企业级 Java 应用定义的一套规范，与 Java SE (Java Platform, Standard Edition) 相对应。

Java EE 是从 Java 1.2 版本开始推出的 Java 企业级开发平台，最初的名称是 J2EE (Java 2 Platform, Enterprise Edition)。随着 Java 的发展，它的名称于 Java 1.5 版本时更改为 Java EE (Java Platform, Enterprise Edition)。2009 年 Oracle 收购了 Sun，Java EE 开始由 Oracle 通过 JCP (Java Community Process) 开发和维护。

直到 2017 年，Oracle 将 Java EE 提交给了 Eclipse 基金会，并命名为 Eclipse Enterprise for Java。然而，由于”Java”这个名字的商标归 Oracle 所有，Eclipse 基金会无法继续使用 javax.* 和 java.*，因此，项目名称改为 Jakarta EE。

Jakarta EE 包含了许多技术规范和 API，涵盖了 Web 应用、数据库访问、消息传递、事务处理、安全性等方面的功能，其中包括但不限于下列规范：

Jakarta Servlet：前身是 J2EE Servlet，定义了如何管理 HTTP 请求的规范。这应该是大部分 Java Web 开发者最熟悉的，同时也是许多其它规范的基础。
Jakarta Server Page (JSP)：服务端动态生成网页的技术，可以看作 Java 版本的 PHP 和 ASP。
Jakarta Websocket：定义了一套 WebSocket 连接相关的 API，用于实现全双工通信。
Jakarta RESTful Web Services：开发符合 REST 原则的 Web 服务的一套规范。
Jakarta JSON Binding：Java 类和 JSON 字符串互相转换的规范。
Jakarta XML Binding：Java 类和 XML 的映射规范。
Jakarta Enterprise Beans (EJB)：这个规范比较复杂，包括 EJB 容器，RMI（远程过程调用），并发控制，依赖注入等。
Jakarta Persistent (JPA)：ORM 规范，定义了 Java 类和数据库表直接的映射规范。
Jakarta Transactions (JTA)：包含了事务相关的接口和注解类，也用于管理分布式事务。
Jakarta Messaging (JMS)：消息系统的规范，用于实现异步消息传递，比如 Apache 的 ActiveMQ 就实现了这套规范。

对研发的影响

依赖包坐标和版本号变更

比如常见的 servlet-api：

<!-- 老版本 -->
<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>3.1.0</version>
</dependency>

<!-- 新版本 -->
<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <version>6.1.0</version>
</dependency>

package namespace 变更

比如：

// 老版本
import javax.servlet.Filter;

// 新版本
import jakarta.servlet.Filter;

兼容性问题

如果不兼容会发生什么，比如：

Servlet 运行期错误

javax.servlet.ServletRequest can not cast to jakarta.servlet.ServletRequest

数据库扫描失败映射错误

比如下面定义是 javax.persistence.Table，开源或者自定义的数据库中间件件一般习惯按注解 jakarta.persistence.Table 进行扫描：

import javax.persistence.Id;
import javax.persistence.Table;

@Table(name = "mt_field_extra")
public class FieldExtra {
    @Id
    String id;
}

private static void scanTableName(Class<?> clazz, PersistMeta meta, boolean mapCamelCaseToUnderscore) {
    jakarta.persistence.Table table = clazz.getAnnotation(jakarta.persistence.Table.class);
    String tableName;
    if (null != table) {
        tableName = table.name();
    } else {
        tableName = nameConvert(clazz.getSimpleName(), mapCamelCaseToUnderscore);
    }
}

如果项目能直接升级到最新版本当然更好，但是作为中间件团队提供的组件，往往需要在过渡期间提供一种兼容两种模式的方案，既能让原有老服务正常使用，又兼容 Spring Boot 3+ Jakarta EE 9+新服务。

Jakarta EE 兼容是一个复杂的课题，当前只记录 package namespace 差异解决方法。

Maven 本身特性说明

父子 POM 依赖继承

假设父 POM 使用 dependencyManagement 定义如下：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tester</groupId>
            <artifactId>rocketmq-support</artifactId>
            <version>1.0.0</version>
        </dependency>
        <dependency>
            <groupId>com.tester</groupId>
            <artifactId>rocketmq-support</artifactId>
            <version>2.0.0</version>
        </dependency>
        <dependency>
            <groupId>com.tester</groupId>
            <artifactId>rocketmq-support</artifactId>
            <version>3.0.0</version>
            <classifier>jakarta</classifier>
        </dependency>
        <dependency>
            <groupId>com.tester</groupId>
            <artifactId>rocketmq-support</artifactId>
            <version>3.0.0</version>
            <classifier>jakarta-java21</classifier>
        </dependency>
        <dependency>
            <groupId>com.tester</groupId>
            <artifactId>rocketmq-support</artifactId>
            <version>3.0.0</version>
            <classifier>jakarta-java23</classifier>
        </dependency>
    </dependencies>
</dependencyManagement>

Maven 官方文档说明：

NOTE: In two of these dependency references, we had to specify the <type/> element. This is because the minimal set of information for matching a dependency reference against a dependencyManagement section is actually {groupId, artifactId, type, classifier}. In many cases, these dependencies will refer to jar artifacts with no classifier. This allows us to shorthand the identity set to {groupId, artifactId}, since the default for the type field is jar, and the default classifier is null.

基于以上说明，假设子模块，依次按以下方式填写 dependency，实际生效的是哪个：

<dependencies>
    <!-- 方式 1 -->
    <dependency>
        <groupId>com.tester</groupId>
        <artifactId>rocketmq-support</artifactId>
    </dependency>

    <!-- 方式 2 -->
    <dependency>
        <groupId>com.tester</groupId>
        <artifactId>rocketmq-support</artifactId>
        <version>5.0.0</version>
    </dependency>

    <!-- 方式 3 -->
    <dependency>
        <groupId>com.tester</groupId>
        <artifactId>rocketmq-support</artifactId>
        <classifier>jakarta</classifier>
    </dependency>

    <!-- 方式 4，同时引入 2 个 -->
    <dependency>
        <groupId>com.tester</groupId>
        <artifactId>rocketmq-support</artifactId>
    </dependency>
    <dependency>
        <groupId>com.tester</groupId>
        <artifactId>rocketmq-support</artifactId>
        <classifier>jakarta-java23</classifier>
    </dependency>
</dependencies>

Profile 继承和传递

假设有个第三方组件，比如 rocketmq-support，他定义了一个 profile 叫 jakarta，独立加了 dependencies，deploy 到中央仓库。

<profile>
    <id>jakarta</id>
    <dependencies>
        <dependency>
            <groupId>jakarta.servlet</groupId>
            <artifactId>jakarta.servlet-api</artifactId>
            <version>5.0.0</version>
        </dependency>
    </dependencies>
</profile>

有另外一个组件 B 依赖了 rocketmq-support，并且也定义了一个 jakarta profile 激活。那么这个组件 B 会自动依赖 jakarta.servlet-api 吗？

不会。profile 为自身编译期服务，deploy 后失效。

如果 deploy 后还能依赖传递的话，那某些人定义写一些恶意代码和插件然后定义一堆通用的 profile，比如大家喜欢叫 dev，然后 deploy 就能变相投毒了。

如果父 pom 定义了 profile，子模块直接引用，是会继承生效的。

主流的辅助工具

Tomcat Migration Tool

Tomcat Migration Tool 是 Apache Tomcat 提供的迁移工具。

java -jar jakartaee-migration-*-shaded.jar <source> <destination>

The source should be a path to a compressed archive, a folder or an individual file. The destination will be created at the specified path as a resource of the same type as the source.

用途：

字节码转换
已有项目，甚至无源码项目，直接转换。只负责转换制品，要想给别人用需自己手动 deploy
一个 javax war 转换后放到 Tomcat 10，理论上可运行

缺陷：

解决不了本地开发 Debug 期间编译、运行的问题，如果不兼容本地启动、Test 失败

另外 Tomcat 10 提供了一种自动转换的方法，参考文档：https://tomcat.apache.org/migration-10.html 将 war 放到 webapps-javaee 目录下，就会自动转换后放到 webapp 下运行。然而这种方案最大的问题在于：

必须是基于外置 Tomcat，不支持 Spring Boot Jar 形式运行。
转换需要时间，这是时间基本上都是 1~10 分钟之间，对应用重启、快速扩缩容都有很大的副作用。

maven-shade-plugin

用途：

字节码转换
需要配置详细的转换规则

缺陷：

解决不了本地开发 Debug 期间编译、运行的问题，本地启动、Test 失败

maven-assembly-plugin

上面我们都是假设只有 javax 和 jakarta namespace 差异，只需要转换字节码。但是，

如果有某个 Java 方法不兼容需要重写一个版本怎么办
配置文件比如 xml 有差异怎么办

assembly-plugin 就可以帮助我们通过 include、exclude 不同的源码、resource、依赖项，重组编译发布不同的包。

这是适合复杂不兼容的代码，但是对于多模块项目，需要某个模块开发指定 assembly xml，会非常痛苦。

目前其他几种工具只处理 javax 和 jakarta package 差异，后续肯定会遇到除了 package 不同，接口或使用方式也不兼容的情况，等遇到了再单独处理。

OpenRewrite

OpenRewrite 迁移菜谱 Migrate to Jakarta EE 9。

# 命令行运行
mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE \
  -Drewrite.activeRecipes=org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta \
  -Drewrite.exportDatatables=false

用途：

源码级别转换，直接自动改代码
除了代码，还能自动改写 pom 依赖

缺陷：

多模块目前适配还不完善，对于多模块，需要每个模块处理一次
复杂代码可能转换失败，失败后可能导致编译失败，无法一键编译，需要人工介入
改 pom 时，他会自己强制指定版本号，实际上我们希望用父 pom 管理版本号
速度稍慢，遍历并修改文件源码，然后编译

transformer-maven-plugin

transformer-maven-plugin 是 eclipse 出的字节码和配置文件转换工具，默认内置了一些 jakarta 的替换规则。

它能帮我们实现：

同时打包（或发布）出 javax 和 jakarta 两个包，通过 classifier 区分，比如设置 javax 默认 classifier 为 null，转换后的版本设置 classifier 为 jakarta。
只打包（或发布）javax 和 jakarta 任意一个版本。
web.xml 或 web-fragment.xml 等相关 xml 定义转换。

<plugin>
    <!-- 这个插件自动把 javax 转为 jakarta，打包出 javax 和 jakarta 两个包，通过 classifier 区分 -->
    <groupId>org.eclipse.transformer</groupId>
    <artifactId>transformer-maven-plugin</artifactId>
    <version>1.0.0</version>
    <extensions>true</extensions>
    <executions>
        <execution>
            <!-- javax 替换成 jakarta -->
            <id>jakarta-jar</id>
            <phase>package</phase>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <rules>
                    <jakartaDefaults>true</jakartaDefaults>
                </rules>
                <artifact>
                    <groupId>${project.groupId}</groupId>
                    <artifactId>${project.artifactId}</artifactId>
                </artifact>
            </configuration>
        </execution>
    </executions>
</plugin>

用途：

字节码转换
支持 web 相关 xml 定义自动替换，比如 web-fragment.xml xmlns="http://xmlns.jcp.org/xml/ns/javaee"
转换和 deploy 可以一步到位，速度快很方便
如果是多模块，可以在根父模块声明一次，一键全部编译

缺陷：

不处理 pom 依赖关系，发布出的 Jakarta 版本依赖项都遵循原 pom 声明

此插件运行需要 Java 21 版本，发布业务包的时候，必须使用 Java 21 编译，编译目标 release 版本可以是 Java 8，在 pom 中增加以下设置：

<properties>
    <java.version>21</java.version>
    <maven.compiler.release>8</maven.compiler.release>
</properties>

web-fragment.xml 适配

一般咱们典型的 web-fragment 定义有如下两个版本，3.0 和 3.1：

3.0 版本：

<?xml version="1.0" encoding="UTF-8"?>
<web-fragment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://java.sun.com/xml/ns/javaee"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
        http://java.sun.com/xml/ns/javaee/web-fragment_3_0.xsd"
    version="3.0" metadata-complete="true">
</web-fragment>

3.1 版本：

<?xml version="1.0" encoding="UTF-8"?>
<web-fragment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
        http://xmlns.jcp.org/xml/ns/javaee/web-fragment_3_1.xsd"
    version="3.1" metadata-complete="true">
</web-fragment>

其中涉及 jakarta 修改的替换的是其中的 xmlns、xsi、version 字段。

Tomcat 8 以后支持 3.1 版本并兼容 3.0 版本，Tomcat 7 对应 3.0 版本。

transformer-maven-plugin 已经不支持 3.0 版本的替换，所以如果还在用 3.0 的需要咱们手动改成以上 3.1 版本的定义，transformer-maven-plugin 在转换的过程中才能自动升级到 jakarta，自动升级后，升级到 5.0 后的结果如下：

<?xml version="1.0" encoding="UTF-8"?>
<web-fragment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="https://jakarta.ee/xml/ns/jakartaee"
    xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
        https://jakarta.ee/xml/ns/jakartaee/web-fragment_5_0.xsd"
    version="5.0" metadata-complete="true">
</web-fragment>

跳过转换

我们的 maven 项目大部分都是多模块，对于打包成 war 自运行不需要发布给别人用的项目，一般都不需要转换，可以设置 properties transform.skip=true 跳过。

<properties>
    <!-- 不发布 -->
    <maven.deploy.skip>true</maven.deploy.skip>
    <!-- 不转换 -->
    <transform.skip>true</transform.skip>
</properties>

实施方案

Classifier vs Version

业界主流方案就是用版本号区分或者用 classifier 区分这两种方案。

classifier 最主要的问题是无法通过父 pom 继承，这样将导致各个业务方需要大量改 pom.xml 文件。

假设一个项目依赖了 app-a，而 app-a 又依赖 b、c、d.

首先因为父 pom 定义 classifier 并不会继承。那么，我是不是指定 app-a 的 classifier 就行了。

不是，除非 app-a 的特定 classifier 自身 pom 里已经为给个模块指定了 classifier，否则 app-a 依赖的各个都要重新指定一遍，这就使用 pom 文件长得又长又臭。如果哪天 app-a 又新增依赖 e, 但是使用者漏掉了 e classifier 声明的，就可能带来问题，这是很危险的动作。

所以我们最终选择用版本号来区分。

使用特定版本

版本号规则，在原版本基础上增加固定前缀：9999.${project.version}，如原 9.6.0 对应的 jakarta 版本号是 9999.9.6.0。

父 pom 区分版本号，Spring Boot 3.x 版本依赖，重申版本号。

这样各个使用者，只需要选择不同的父 pom，遵循父 pom 版本定义，dependency 可以原样不变。

如何打包发布

目前暂定选择 transformer-maven-plugin，他不完美，但是足够快，相对稳定。

发布目标：两次发布，第一次发布常规版本，第二次发布自动转换后的版本，版本号增加前缀。

发布步骤：

在公司级父 pom 增加如下 profile：

<profiles>
    <profile>
        <id>jakarta-transformer</id>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.eclipse.transformer</groupId>
                    <artifactId>transformer-maven-plugin</artifactId>
                    <version>1.0.0</version>
                    <extensions>true</extensions>
                    <executions>
                        <execution>
                            <!-- 此处配置 javax 替换成 jakarta，artifactId 不变，无 classifier -->
                            <id>jakarta-jar</id>
                            <phase>package</phase>
                            <goals>
                                <goal>jar</goal>
                            </goals>
                            <configuration>
                                <rules>
                                    <jakartaDefaults>true</jakartaDefaults>
                                </rules>
                                <artifact>
                                    <groupId>${project.groupId}</groupId>
                                    <artifactId>${project.artifactId}</artifactId>
                                </artifact>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

发布 jakarta 版本时，先改版本号增加前缀，再指定 profile 发布：

# 获取当前版本号
mvn help:evaluate -Dexpression=project.version -q -DforceStdout

# 如果项目都是自己写版本号的，使用 version 插件设置新版本号，增加前缀
mvn versions:set -DnewVersion=9999.9.6.0 -DgenerateBackupPoms=false

# 重新发布，指定 -Pjakarta profile，父 pom 里的插件自动转换 javax
mvn deploy -Pjakarta-transformer

# 如果使用 flatten-maven-plugin 插件管理版本号的，设置 revision
mvn deploy -Drevision=9999.9.6.0 -Pjakarta-transformer

预防和消灭技术债：Maven CI 如何在编译时禁止调用某些特定 API

Tue, 09 Sep 2025 14:18:59 GMT

在日常开发中，我们经常遇到类似如下需求：

项目组提供了 SDK，某个 API 已经被标记为废弃，但是大家迟迟不升级，项目组还需要花费时间维护已经废弃的 API。
有些项目在使用 JDK 已经废弃的 API，这些废弃 API 在更高版本 JDK 中已经删除，导致推动升级 JDK 比较困难。
有些项目会跨版本混合编译，比如用 Java 8 编译运行在 Java 21 上，常见的错误比如 javafx.util 在 Java 21 默认已经去掉了，就会出现编译成功却运行时失败。

所以我们想提供一种方案，能不能在编译期就强制禁用某些 API，主动阻止让编译不通过，提前报错及早发现及早处理。

实现方案

当前我们使用 maven forbiddenapis 插件，结合 CI 流程来实现。

执行效果，如果有使用禁用的 API，能看到类似如下错误提示，编译失败并给出原因。

12:40:30.647 [INFO]
12:40:30.648 [INFO] --- forbiddenapis:3.9:check (check-forbidden-apis) @ app-biz ---
12:40:30.657 [INFO] Scanning for classes to check...
12:40:30.661 [INFO] Reading bundled API signatures: jdk-deprecated-1.8
12:40:30.694 [INFO] Reading API signatures: /usr/share/maven/conf/forbidden-apis.txt
12:40:30.694 [INFO] Loading classes to check...
12:40:30.695 [INFO] Scanning classes for violations...
12:40:30.849 [ERROR] Forbidden class/interface use: javafx.util.Pair [禁止使用 JavaFX 相关类]
12:40:30.850 [ERROR]   in com.tester.HomeController (HomeController.java:11)
12:40:30.865 [ERROR] Scanned 13 class file(s) for forbidden API invocations (in 0.21s), 1 error(s).
12:40:30.872 [INFO] ------------------------------------------------------------------------

24784 [INFO] --- forbiddenapis:3.9:check (check-forbidden-apis) @ app-api ---
24812 [INFO] Scanning for classes to check...
24884 [INFO] Reading bundled API signatures: jdk-deprecated-1.8
25016 [INFO] Reading API signatures: /usr/share/maven/conf/forbidden-apis.txt
25017 [INFO] Loading classes to check...
25106 [INFO] Scanning classes for violations...
25984 [ERROR] Forbidden method invocation: java.net.URLEncoder#encode(java.lang.String) [Deprecated in Java 1.8]
25984 [ERROR]   in com.tester.FormBody$FormBodyBuilder (FormBody.java:60)
26110 [ERROR] Scanned 660 class file(s) for forbidden API invocations (in 1.31s), 2 error(s).
26113 [INFO]

Maven 核心配置

首先，在父 pom 里增加了以下片段，此内容主要含义：

在存在 ${env.MAVEN_HOME}/conf/forbidden-apis.txt 文件时激活此 profile，以便确保缺少 txt 文件时不会报错。
默认激活了 forbiddenapis 插件的 jdk-deprecated 规则。
增加了我们定制的 forbidden-apis.txt 规则，此文件放在 maven 的基础镜像里。

<profile>
      <id>forbidden</id>
      <activation>
        <file>
          <exists>${env.MAVEN_HOME}/conf/forbidden-apis.txt</exists>
        </file>
      </activation>
      <build>
        <plugins>
          <plugin>
            <groupId>de.thetaphi</groupId>
            <artifactId>forbiddenapis</artifactId>
            <version>3.9</version>
            <configuration>
              <detail>true</detail>
              <failOnUnsupportedJava>false</failOnUnsupportedJava>
              <ignoreSignaturesOfMissingClasses>true</ignoreSignaturesOfMissingClasses>
              <bundledSignatures>
                <bundledSignature>jdk-deprecated</bundledSignature>
              </bundledSignatures>
              <signaturesFiles>
                <signaturesFile>${env.MAVEN_HOME}/conf/forbidden-apis.txt</signaturesFile>
              </signaturesFiles>
            </configuration>
            <executions>
              <execution>
                <id>check-forbidden-apis</id>
                <phase>process-classes</phase>
                <goals>
                  <goal>check</goal>
                </goals>
              </execution>
              <execution>
                <id>test-check-forbidden-apis</id>
                <phase>process-test-classes</phase>
                <goals>
                  <goal>testCheck</goal>
                </goals>
              </execution>
            </executions>
          </plugin>
        </plugins>
      </build>
</profile>

我的项目需要紧急发版，来不及改代码，如何禁用以上插件，在 pom.xml 中增加以下属性，或通过 mvn 命令行 -Dforbiddenapis.skip=true 传递此参数：

    <properties>
      <forbiddenapis.skip>true</forbiddenapis.skip>
    </properties>

forbiddenapis 规则详解

forbiddenapis 插件有内置规则和自定义规则，规则名字叫 signatures。

forbiddenapis 插件默认已经内置了一些规则 signatures，参考：bundled-signatures。

主要默认规则：

jdk-unsafe-*: Signatures of “unsafe” methods that use default charset, default locale, or default timezone. For server applications it is very stupid to call those methods, as the results will definitely not what the user wants (for Java* = 1.7, 1.8, 9,…, 24; Ant / Maven / Gradle automatically add the compile Java version).
jdk-deprecated-*: This disallows all deprecated methods from the JDK (for Java*= 1.7, 1.8, 9,…, 24; Ant / Maven / Gradle automatically add the compile Java version).
jdk-internal-*: Lists all internal packages of the JDK as of Security.getProperty(“package.access”). Calling those methods will always trigger security manager and is completely forbidden from Java 9 on (for Java*= 1.7, 1.8, 9,…, 24; Ant / Maven / Gradle automatically add the compile Java version, since forbiddenapis v2.1).
jdk-non-portable: Signatures of all non-portable (like com.sun.management.HotSpotDiagnosticMXBean) or internal runtime APIs (like sun.misc.Unsafe). This is a superset of jdk-internal. Internally this is implemented using heuristics: Any reference to an API that is part of the Java runtime (rt.jar, extensions, Java 9+ java./ jdk. core modules) and is not part of the Java SE specification packages (mainly java, javax, but also org.ietf.jgss, org.omg, org.w3c.dom, and org.xml.sax) is forbidden (any java version, no specific JDK version, since forbiddenapis v2.1).
jdk-system-out: On server-side applications or libraries used by other programs, printing to System.out or System.err is discouraged and should be avoided (any java version, no specific JDK version).
jdk-reflection: Reflection usage to work around access flags fails with SecurityManagers and likely will not work anymore on runtime classes in Java 9 or later (any java version, no specific JDK version, since forbiddenapis v2.1).
commons-io-unsafe-*: If your application uses the famous Apache Common-IO library, this adds signatures of all methods that depend on default charset (for versions* = 1.0, 1.1, 1.2, 1.3, 1.4, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8.0, 2.9.0, 2.10.0, 2.11.0, 2.12.0, 2.13.0, 2.14.0, 2.15.0, 2.15.1, 2.16.0, 2.16.1, 2.17.0, 2.18.0).

通过 txt 文件自定义规则，规则语法：signatures-syntax。

Class reference: A binary/fully-qualified class name (including package). You may use the output of Class.getName(). Be sure to use correct name for inner classes! Example: java.lang.String
A package/class glob pattern: To forbid all classes from a package, you may use glob patterns, like sun.misc.**(** matches against package boundaries).
A field of a class: package.Class#fieldName
A method signature: It consists of a binary class name, followed by # and a method name including method parameters: java.lang.String#concat(java.lang.String) – All method parameters need to use fully qualified class names! Instead of method parameters, the special wildcard string ** may be used to add all variants of a method, regardless of their parameter types. To refer to instance constructors, use the method name <init>, e.g. java.lang.Integer#<init>(int).

The error message displayed when the signature matches can be given at the end of each signature line using ”@” as separator:

java.lang.String @ You are crazy that you disallow strings

To not repeat the same message after each signature, you can prepend signatures with a default message. Use a line starting with “@defaultMessage”.

@defaultMessage You are crazy that you disallow substrings
java.lang.String#substring(int)
java.lang.String#substring(int,int)

这里着重需要注意：

按方法名定义时，一定要定义好参数类型，否则不生效。
按包名定义时，一定要区分好一个 * 和两个 **，一个*只能匹配一级，两个**能匹配 N 级。

XLabs | 技术博客

MCP 工具返回值的两道隐藏边界：10MB 帧上限、outputSchema 校验（1.32.1 实测）

环境

一、outputSchema：校验失败不是错误

客户端校验取决于调没调过 tools/list

isError 是双重标准

text 和 structuredContent 不一致，没人查

二、10MB：结果帧超了就断连

三个被低估的点

为什么会这样

落地清单

边界

复现脚本

MCP 2026-07-28 弃用 Roots/Sampling/Logging，SDK 还在裸奔（1.32.1 实测）

实测环境

实测：三个弃用 feature 的当前行为

类型层也没有 @deprecated

SDK 也没实现 spec 的新增项

为什么这是个隐患

工程清单

边界

probe.mjs 完整源码

MCP 工具挂了之后：empty_ok 比报错更危险，4 个模型实测

结局表

发现一：empty_ok 是幻觉触发器

发现二：deepseek 的 400 是客户端问题，不是模型问题

发现三：qwen 和 gemini 的「重试」是无效循环

发现四：命名空间猜测——模型的性格差异

工程清单

边界

AI 写 Playwright 选择器，5 个模型 5 种 DOM 变异实测：i18n 团灭

实验设计

结果：i18n 团灭

三个判断

工程建议

边界

复现

Playwright Test Agents 拆包：init-agents 落到磁盘的 3 个 agent 定义文件

四个 loop 落点不一样

Healer 定义里两条值得抄出来的条款

Generator 强制契约：一个文件一个测试

Codex 的差异在 sandbox

这个实测能带走什么

MCP Streamable HTTP 实测：Accept 少一项就 406，第二次 initialize 会吃掉整个 Server

环境

实验一：Accept 是硬检查，不是建议

实验二：Mcp-Session-Id 是单 transport 的生死状

实验三：一个 McpServer 只接受一次 initialize

实验四：无会话模式（sessionIdGenerator: undefined）是半成品

实验五：JSON-RPC batch 的隐藏约束

实验六：协议版本协商——传一个未来版本会怎么样

给 MCP Client 的五条硬规约

给 MCP Server 的四条建议

边界

AI 生成的 E2E 测试能抓到真 bug 吗：5 个模型 41 个用例的变异实测

环境与实验设计

结果

唯一漏掉的缺陷：搜索的大小写

12% 的用例一个缺陷都没抓到

基线就挂的用例：模型把数据数错了

用例数量与断言密度

为什么通过率不能当质量指标

落地清单

边界

LLM 可观测性实测：OpenAI 兼容网关的 usage 靠不靠得住

一、usage 里能拿到什么，5 个模型给出 5 套字段

二、同一句话的 prompt_tokens 差 6.8 倍

三、stream_options.include_usage 在这台网关上是个空操作

四、usage 出现在哪个块，4 种形态

五、客户端断连，这条请求的 token 就消失了

六、200 成功 + 空正文

七、前缀缓存按前缀失效，改开头等于全价

八、响应体里的 model 不是请求的模型

落地清单

边界

Prompt 回归测试实测：同一份 prompt 在两个模型上错得不一样

实验怎么搭的

发现一：两个模型的头号失败模式完全不同

发现二：修好一处，弄坏另一处

发现三：temperature=0 不代表可复现

类型层也没有 `@deprecated`

实验二：`Mcp-Session-Id` 是单 transport 的生死状

实验三：一个 `McpServer` 只接受一次 initialize

实验四：无会话模式（`sessionIdGenerator: undefined`）是半成品

三、`stream_options.include_usage` 在这台网关上是个空操作

真正会卡住你的坑：`*/list` 必须带缓存字段