不造网关，自建适配端点：Java如何无缝兼容OpenAI与Anthropic协议

做对接大模型 API 这种活儿，干多了就会发现，团队里最容易出现的争论不是“用哪个模型”，而是“怎么让所有模型长得一样”。我最近一个项目是典型的 Java 后端：内部推理服务暴露的是 OpenAI 兼容接口，但业务方希望同时支持 Anthropic 的调用风格，让下游用 Anthropic SDK 直接接入。当时组里几乎所有人都提议上一个现成的协议转换网关，把它当基础设施统一管。我坚持没这么干，最后在 Java 服务里写了一个轻量适配端点，把 Anthropic 的请求体转成 OpenAI 语义，再把 OpenAI 响应转回 Anthropic 格式。项目上线后，这个方案被证明成本低得多。这篇就讲讲我为什么反对一上来就造网关，以及“在边界上做协议适配”到底怎么落地。

1. 先把概念掰清楚：协议适配和网关，不是一回事

1.1 建议上网关的理由听着都对，等你部署就变味了

“网关”很诱人。有了它，团队就有一个统一地址，业务不用关心后端是哪个供应商；而且很多现成的网关号称自带路由、密钥管理、限流、日志，看起来是所有 API 团队的标准答案。但如果你只是想把 Anthropic 协议和 OpenAI 协议互相映射，事情就变味了：这个网关需要单独运维、单独监控、单独高可用；它作为一个独立进程出现在调用链里，等于新增了一个天然的故障点。

我见过最典型的场景：网关把上游的错误信息重新包装，下游拿着新的报错去翻日志，日志又在网关里存了一份，两边对不上。排查一个问题要同时打开路由、网关、业务服务三个控制台，最后发现是网关版本升级后把某个响应字段悄悄改了。这种问题不是个例，是网关方案的固有问题——只要中间层不理解业务上下文，它就很难准确传递语义。

1.2 适配器不是网关，是贴在边界上的端点

协议适配的本质不是“转发”，而是“翻译”。转发是网关干的事：请求进来，按规则送到上游，再把响应原样带回来。翻译不一样，翻译需要知道两边的语法和语义，需要把你自己的业务模型作为中间媒介，而不是把字节原封不动地搬来搬去。

所以我的观点是：如果只是给自己的 Java 服务增加一个对外协议入口，那就应该写一个普通的 HTTP 端点。这个端点长在业务进程内部，跟随业务版本一起发布，一起扩缩容，一起打日志。它不是一个独立的系统，而是服务的一个方法。这样做之后，协议转换产生的异常、超时、参数校验全部落到业务自己的监控体系里，不会再有一层绕过你监控的隐形通道。

1.3 两种方案的对比，数据比感受更直白

我习惯把决策依据落到一张表上，这张表后来也成了我劝组里同事放弃网关的主要论据。

这倒不是说网关绝对不能用，而是说，当你只有一个服务需要兼容两种协议时，为它单独立一套网关，性价比非常低。真正的复杂场景是公司里十几个团队、几十个服务都要走统一出口，那时候网关才值得你投入。

2. 协议差异拆解：OpenAI 和 Anthropic 的对话模型差在哪

2.1 请求体：system 参数和 messages 数组的冲突

很多人以为 OpenAI 和 Anthropic 的协议差别只是 URL 和字段名不一样，实际上它们的对话模型设计思路就有区别。OpenAI 把 system 提示塞进 messages 数组里，用 role 区分；Anthropic 则把 system 单独拎出来，作为请求体的一个顶级参数，messages 里只放 user 和 assistant。

这个差异看着小，落到代码里全是坑。如果你直接按照 OpenAI 的 model 类去接 Anthropic 请求，会发现 Anthropic 的 system 字段没法映射到 OpenAI 的 messages 里，必须在适配层做一次“重建 messages”的处理。我当时的做法是把 system 从 Anthropic 请求中提出来，变成 OpenAI messages 数组的第一条 system 消息；反过来，当 OpenAI 响应回来时，我又把 messages 里的 system 内容还原成 Anthropic 的顶层 system 字段。

2.2 工具调用：两套完全不同的结构

协议适配里最容易翻车的是工具调用。OpenAI 的 tool_calls 是在 assistant 消息里平铺一个数组，每个元素有 id、type、function 和 arguments；对应的工具结果放在 role=tool 的消息里。Anthropic 则把工具调用表达成 content block，assistant 回复里的 content 是一个数组，里面混着 text block 和 tool_use block；工具执行结果又变成 user 消息里的 tool_result block。

这两套结构底层语义差不多，但外层包装差异极大。适配的时候如果不小心，最常见的错误就是把 Anthropic 的 tool_use block 当成纯文本拼进 OpenAI 的 content 字段，导致下游大模型收到一堆 JSON 字符串而不是结构化工具调用。我在项目里专门为 content block 设计了一个转换器，逐个判断 block 类型，把 tool_use 翻译成 OpenAI 的 tool_calls，把 tool_result 翻译成 role=tool 的消息。

2.3 响应体：content 字段的形态差异和 stop 原因

非流式响应也有很多细节。OpenAI 的响应里，choices[0].message.content 通常是一个字符串，或者在某些场景下是 null；Anthropic 的响应里，content 永远是数组，里面包含若干个 content block。所以适配响应的第一步，就是把 OpenAI 的字符串 content 包成一个 text block，再把 Anthropic 的 text block 拆回来。

还有一个容易忽略的字段是结束原因。OpenAI 用 finish_reason，取值有 stop、length、tool_calls、content_filter；Anthropic 用 stop_reason，取值有 end_turn、max_tokens、stop_sequence、tool_use。虽然大部分情况下 stop 对应 end_turn、length 对应 max_tokens，但 tool_calls 和 tool_use 的对应关系一旦写错，下游的循环调用逻辑就会出问题。这里我建议不要偷懒，要单独写一个映射函数，把所有组合都覆盖到。

3. Java 里的统一模型：先把两个协议耦合成一套内部结构

3.1 DTO 设计用 record 还是 class

Java 后端做协议适配，第一步不是写 Controller，而是设计一套与具体厂商无关的内部模型。我推荐用 record 来做请求和响应的不可变载体，因为协议转换过程中大多数对象只是传递数据，不需要可变状态。record 自带 equals、hashCode 和 toString，调试打印请求体时非常方便。

当然，如果团队还在用 Java 8，record 用不了，那就退而求其次用 Lombok 的 @Value 或手写不可变类，核心是不想让协议对象变成可以随意修改的“万能类”。在适配层，一旦对象可变，就会出现某个字段在某个分支被悄悄改了值，到下游怎么查都查不出来的局面。

3.2 定义一个 UnifiedRequest 和 UnifiedResponse

我的内部模型大概长这样：

public record ChatMessage( String role, String content, List<ToolCall> toolCalls, String toolCallId ) {} public record ChatRequest( String model, String system, List<ChatMessage> messages, List<ToolDefinition> tools, Double temperature, Integer maxTokens, List<String> stop, boolean stream ) {} public record ChatResponse( String text, String finishReason, TokenUsage usage, List<ToolCall> toolCalls ) {}

这套模型故意做得很朴素，没有直接照搬 OpenAI 或者 Anthropic 的字段命名。它的作用只是桥梁，适配器的方向是：AnthropicRequest -> ChatRequest -> OpenAIRequest，以及 OpenAIResponse -> ChatResponse -> AnthropicResponse。如果以后要接入第三个厂商，也只需要写一个新的转换器，内部模型不用动。

3.3 用 JsonNode 承接协议专用字段，保持边界干净

有一种情况要特别注意：某些字段只在特定协议里存在，或者不同协议对同一字段的嵌套层次不同。这时候不要把所有的字段都展开到内部模型里，否则你的 record 会越来越膨胀，最终变成一个大杂烩。

我在工具调用上就是这么处理的：内部模型的 ToolCall 只保留 id、name、arguments 三个最核心字段，arguments 直接用一个 JsonNode 存原始 JSON 对象，而不是提前解析成 Map。这样无论是 OpenAI 的 JSON 字符串 arguments，还是 Anthropic 的 input 对象，都能统一塞进去，等到转换目标协议时再按需序列化。

4. 核心实操：在 Java 里自建 Anthropic 兼容端点

4.1 端点的路由和鉴权

既然目标是让下游拿 Anthropic SDK 直接接入，端点的路由就要严格贴合 Anthropic 的规范。Anthropic 的聊天接口是 POST /v1/messages，所以我直接用 Spring Boot 的 @RestController 把这个路径暴露出来，并在 header 里校验 x-api-key 和 anthropic-version。

@RestController public class AnthropicCompatibleController { private final LlmProvider provider; private final KeyValidator keyValidator; private final ProtocolMapper mapper; public AnthropicCompatibleController(LlmProvider provider, KeyValidator keyValidator, ProtocolMapper mapper) { this.provider = provider; this.keyValidator = keyValidator; this.mapper = mapper; } @PostMapping(value = "/v1/messages", produces = MediaType.APPLICATION_JSON_VALUE) public ResponseEntity<?> messages( @RequestBody AnthropicRequest request, @RequestHeader(value = "x-api-key", required = false) String apiKey) { if (apiKey == null || !keyValidator.isValid(apiKey)) { return errorResponse(401, "authentication_error", "invalid x-api-key"); } if (request.maxTokens() <= 0) { return errorResponse(400, "invalid_request_error", "max_tokens is required"); } ChatRequest unified = mapper.toUnified(request); ChatResponse response = provider.complete(unified); return ResponseEntity.ok(mapper.toAnthropicResponse(response)); } }

鉴权这件事千万别省。即使这个端点只在内网开放，也建议至少校验一个服务级别的密钥，否则公司里的横向扫描可能把你的推理资源变成免费算力。

4.2 非流式请求怎么映射

核心转换逻辑集中在 ProtocolMapper 里。它的内部逻辑很简单：先解析 Anthropic 请求体，按 message role 拆解，把顶层 system 字段放到内部模型的 system 属性里，再把剩余消息映射成 ChatMessage 列表。

OpenAI 请求体的构造也不复杂，但有一个关键点：OpenAI 的 max_tokens 是可选的，Anthropic 则必填。所以在转成 OpenAI 请求时，如果用户没传 max_tokens，我会给一个默认值，避免上游拒绝请求。另外，OpenAI 的 system 消息必须放在 messages 数组第一个位置，如果你把 system 插到中间，有些模型会表现异常。

public OpenAiRequest toOpenAiRequest(ChatRequest unified) { List<OpenAiMessage> messages = new ArrayList<>(); if (unified.system() != null && !unified.system().isBlank()) { messages.add(new OpenAiMessage("system", unified.system(), null, null)); } for (ChatMessage msg : unified.messages()) { messages.add(new OpenAiMessage(msg.role(), msg.content(), msg.toolCalls(), msg.toolCallId())); } return new OpenAiRequest( unified.model(), messages, unified.temperature(), unified.maxTokens() != null ? unified.maxTokens() : 2048, unified.stream() ); }

4.3 参数校验与错误响应映射

协议适配最容易被下游感知到的地方就是错误格式。Anthropic 的错误响应格式是：

{ "type": "error", "error": { "type": "invalid_request_error", "message": "max_tokens is required" } }

OpenAI 则是：

{ "error": { "message": "...", "type": "invalid_request_error", "code": "...", "param": "..." } }

如果直接把 OpenAI 的错误体原样返回给 Anthropic 客户端，SDK 可能解析失败，或者把错误信息当成未知结构。所以我在适配层维护了一张映射表：

这里特别要注意，不要把上游的 404 原样传到下游，Anthropic 客户端看到 404 会以为 endpoint 不存在，从而直接放弃重试。应该把“模型不存在”归为参数错误，返回 400，客户端才会正确处理。

5. 流式适配：协议最容易破功的地方

5.1 两种 SSE 协议的差异

非流式请求只是热身，流式才是真正的坎。OpenAI 的流式响应用的是最朴素的 SSE，每一行 data: 开头，最后以 data: [DONE] 结尾，事件类型完全靠内容里的字段区分。

Anthropic 的流式则更讲究，它定义了明确的 event 类型：message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop。每个 event 后面跟一个 data: 行，携带这个事件的具体数据。

如果你只是简单地把 OpenAI 的 data: 行透传给 Anthropic 客户端，客户端会因为找不到预期的 event 序列而报错。轻则流式截断，重则客户端直接超时断开。

5.2 流式转发的状态机

我在适配层里维护了一个简单的状态机，用来把 OpenAI 的增量内容包装成 Anthropic 的事件序列：

public final class OpenAiToAnthropicStreamAdapter { private boolean started = false; private boolean ended = false; public void accept(String openAiLine) { if (openAiLine.isBlank()) return; if ("data: [DONE]".equals(openAiLine.trim())) { emitStop(); ended = true; return; } if (!started) { emitStart(); started = true; } String deltaText = extractDeltaText(openAiLine); if (!deltaText.isEmpty()) { emitDelta(deltaText); } } }

这个状态机的核心规则是：第一条内容增量到达之前，必须先发 message_start 和 content_block_start；后面每条增量都发 content_block_delta；流结束时发 content_block_stop、message_delta 和 message_stop。顺序一旦错乱，Anthropic SDK 就会抛错。

5.3 处理不完整的 packet：缓冲合并

实际网络环境下，SSE 的行不一定会完整地到达。TCP 分包可能让你在第一次回调里只收到半个 data 行，第二次回调收到剩下的半个。如果直接按行解析，就会产生 JSON parse error。

我的做法是维护一个 StringBuilder 作为缓冲区，每次收到字节都先 append，再尝试按换行符切出完整行处理。处理完的行从缓冲区移除，剩余的留在里面等下一次数据。

StringBuilder buffer = new StringBuilder(); void onBytes(String chunk) { buffer.append(chunk); String raw = buffer.toString(); List<String> lines = raw.lines().toList(); int lastNewline = raw.lastIndexOf("\n"); buffer.delete(0, lastNewline + 1); for (String line : lines) { streamAdapter.accept(line); } }

这里有个细节：如果最后一行没换行符，那它很可能是不完整的，不能立刻处理，必须留在缓冲区里继续等。很多新手在这里踩坑，把最后半个消息直接丢了解析，流式就莫名其妙少一段文字。

5.4 网络中断与取消

流式适配还有一层容易被忽略：调用方的连接随时可能断开。客户端点开页面刷一下，或者模型生成到一半用户取消了请求，你的代码就得立刻感知并释放相关资源。

在 Spring Boot 的 SseEmitter 里，我会注册 onCompletion 和 onTimeout 回调，手动关闭上游的 HTTP 连接。如果不主动关闭，上游的推理服务会继续把整段内容推完，白白浪费算力。更严重的是，连接池里的连接可能被半开状态的响应占住，时间一长就把线程池拖垮。

6. 真实工程踩坑清单，每条都是血泪

6.1 不要把 Provider 全塞进一个 HttpClient

刚开始我图省事，把所有厂商的请求共用一个 HttpClient，觉得连接池复用可以提高效率。后来发现问题很大：OpenAI 和 Anthropic 的超时策略、连接复用、证书策略都不一样，混在一起之后，一个厂商的慢请求会占光连接池的配额，另一个厂商的请求全部排队。

正确做法是给每个上游单独建一个 HttpClient，单独配置 connectTimeout、readTimeout 和连接池大小。最好再按厂商隔离线程池，避免某个厂商整体变慢时拖垮整个服务。

6.2 错误信息不能只透传

这里的坑和错误码映射类似，但更隐蔽。上游的 OpenAI 兼容服务经常会在 error.message 里写一些内部细节，比如“model xxx not found”或者带了内网地址的日志，直接透传给下游既不美观也不安全。

我在适配层增加了一个 sanitize 方法，把错误信息里的敏感信息替换掉，同时保留对用户有用的关键部分。比如把“model not found: gpt-xxx”保留，但把内部的 request id 和 hostname 摘掉。

6.3 Jackson 反序列化要小心 content 的多态结构

Anthropic 的 content 是数组，里面可能是 text block，也可能是 tool_use block。如果只用普通 POJO 去反序列化，强转类型时很容易出问题。我建议直接用 JsonNode 接住 content 字段，再按 type 字段分发处理，而不是硬写一层多态注解。

因为 Anthropic 未来大概率还会加新的 block 类型，硬编码多态意味着每次上游新增类型你都要发版，直接用 JsonNode 则能天然兼容未知类型，最多是少处理一种而已。

6.4 编码问题比你想的更常见

SSE 流式传输时，中文和 emoji 都可能被拆到两个 chunk 里。如果你用 String.getBytes(StandardCharsets.UTF_8) 之后按 byte 去切分，很容易把多字节字符切成半个，导致乱码。

我的建议是始终用字符流处理，不要用字节流切分。Java 的 BufferedReader 可以按行读，读出来的一定是完整字符。配合缓冲区按换行切行，处理中文和特殊符号都很稳。

7. 我个人的取舍标准：什么时候真的需要独立网关

7.1 一个服务的场景，不要直接上网关

如果只是你所在的服务需要兼容多协议，那就老老实实写适配端点。它就在你的进程里，随业务一起测试、一起发布、一起监控。出了任何问题，你可以直接用断点在本地调试，不用去翻另一套系统的日志。

7.2 什么时候我才会考虑网关

当协议兼容成为公司级需求，需要十几个团队共同使用的时候，独立的协议转换网关才值得考虑。判断标准有三条：是否有多个团队需要复用；是否需要对所有请求做统一审计或计费；是否需要一个独立的流量出口来屏蔽后端拓扑变化。三条只要中了一条，麻烦点也还能接受；一条都不占，那就别折腾了。

还有一个折中方案：把适配端点做成一个独立的 Java 模块，通过依赖的方式嵌入各业务服务，代码只维护一份，但运行时仍然在每个服务内部。这种方案兼顾了复用和隔离，是我现在更倾向的做法。

最后分享一个小经验：协议适配最容易翻车的地方往往不是“看不懂协议”，而是“以为看懂了两边协议”，结果漏掉了 system 字段的位置、stream 事件的顺序、tool_use block 的多态结构这些细节。如果你也在做类似的事，建议先把两边的官方示例请求和响应打印出来，逐字段对照着写转换器，比直接看 SDK 源码快得多。这套适配端点跑上线之后，我最大的体会是：别为了让代码看起来“更高级”就多加一层，很多时候最简单的方式，反而最省心。