开源AI助手双龙虾接口模块：多上游适配与故障转移实战

之前在做开源AI助手时，最头疼的不是功能设计，而是接口接入层的混乱。项目里往往要对接多个模型服务商，每个上游平台的鉴权方式、请求格式、超时时间都不一样，如果直接散落在业务代码里，后期维护成本会非常高。这篇文章准备围绕开源AI助手开发教程第13期的内容，专门拆解“双龙虾接口模块”的设计与实现，把双上游AI接口的适配、路由、降级思路完整梳理一遍。

本文适合正在做AI助手、机器人、知识库问答等项目的同学阅读。无论你是自己接一个AI平台，还是像本文示例一样需要同时对接双上游供应商，都可以从这套接口模块设计中找到可落地的思路。下面会从概念、环境、核心设计、完整代码、常见问题、最佳实践几个方面依次展开，代码以 Java + Spring Boot 为主，全部可以直接复制改造。

1. 背景与核心概念

1.1 什么是双龙虾接口模块

先解释一下“双龙虾”这个名字。在很多开源项目里，团队会给自己维护的模块起一些形象代号，“双龙虾”就是这类内部命名，它本质上描述的是一种双上游接口适配层。我们平时说的单接口调用，通常只对接一个AI服务商；而“双龙虾”则同时对接两个上游AI服务商，内部通过统一抽象对外提供一致的调用入口。

双龙虾接口模块要解决的核心问题有三个：

• 上游接口差异被屏蔽：不同AI服务商在请求路径、消息格式、鉴权Header、流式返回等方面并不完全一致。接口模块可以在内部完成转换，让业务方不必感知具体上游。
• 单一依赖风险被降低：如果只依赖某一家AI服务商，一旦该平台限流、故障或调整计费策略，整个AI助手都会受影响。双上游部署后，可以在主链路异常时快速切换到备用通道。
• 调用策略可灵活调整：通过模块内的路由策略，可以主动切换当前生效的上游通道，支持主备、轮询、按权重引流等模式。

1.2 枫云AI在模块中的角色

在双龙虾接口模块中，“枫云AI”并不是一个单独的中间件，而是上游AI开放平台的一个示例名称。我们可以把它理解为其中一个Provider，也就是一路“龙虾”。模块会针对枫云AI实现一套适配器，负责完成协议转换、密钥注入、响应解析等动作。

在这个设计里，另外一路Provider可以用任意AI平台替代，比如项目里已有的私有化模型网关，或者另一个云厂商的开放API。代码层面只需要对每一路Provider实现同一个适配接口，就可以被模块统一管理。

1.3 统一适配层与门面模式

双龙虾接口模块的设计本质是“适配器 + 门面”的组合。

• 适配器模式用于屏蔽不同AI平台的差异。
• 门面模式用于对外提供简单稳定的统一调用入口。
• 路由策略在门面内部完成，业务侧只面向门面编程，不关心上游切换逻辑。

这样做还有一个额外的好处：后续要接入第三路、第四路AI服务商时，只需要新增一个适配器实现，并在配置中增加对应信息，不需要改动调用方的代码。

2. 环境准备与版本说明

本文示例使用 Java + Spring Boot 实现，属于开源AI助手开发教程系列，因此环境以本地开发调试为主。具体版本建议如下：

版本需要根据你的项目实际情况调整，本文示例以常见环境为例，重点演示配置思路，不绑定某个具体供应商SDK。

需要强调一点：不同AI平台的SDK和API协议差异较大，本文不会编写某个平台上确定可运行的完整请求代码，而是用一个“示例思路”来演示接口抽象和路由过程。你在实际项目里替换成自己的上游依赖即可。

3. 核心原理与模块设计拆解

3.1 顶层抽象：LobsterAdapter

双龙虾接口模块的各种实现类，最终都需要遵循同一个顶层抽象接口。这个接口就是整条适配链路的契约。

// 文件路径：src/main/java/com/openai/assistant/lobster/LobsterAdapter.java package com.openai.assistant.lobster; import com.openai.assistant.common.AIRequest; import com.openai.assistant.common.AIResponse; import com.openai.assistant.common.AIProviderType; /** * 双龙虾接口模块统一适配接口。 * 每一路上游AI服务商，都需要实现该接口。 */ public interface LobsterAdapter { /** * 返回当前适配器对应的上游类型。 */ AIProviderType provider(); /** * 统一对话调用入口。 */ AIResponse chat(AIRequest request); /** * 判断当前适配器是否可用，例如密钥缺失、依赖不可用时返回 false。 */ default boolean available() { return true; } }

这个接口定义了三个方法：

• provider()告诉路由层自己是哪一路上游。
• chat()是统一调用方法，内部负责将请求转换成上游API需要的结构，再解析返回结果。
• available()用于探活，比如当上游密钥没有配置或初始化失败时，可以返回 false，路由层会自动跳过该适配器。

3.2 统一请求与响应结构

为了避免业务代码直接和上游响应耦合，需要设计一套内部统一的请求响应结构。

// 文件路径：src/main/java/com/openai/assistant/common/AIRequest.java package com.openai.assistant.common; public class AIRequest { private String model; private String prompt; private Double temperature; private Integer maxTokens; public AIRequest() { } public AIRequest(String model, String prompt) { this.model = model; this.prompt = prompt; } // 省略 getter/setter public String getModel() { return model; } public void setModel(String model) { this.model = model; } public String getPrompt() { return prompt; } public void setPrompt(String prompt) { this.prompt = prompt; } public Double getTemperature() { return temperature; } public void setTemperature(Double temperature) { this.temperature = temperature; } public Integer getMaxTokens() { return maxTokens; } public void setMaxTokens(Integer maxTokens) { this.maxTokens = maxTokens; } }

// 文件路径：src/main/java/com/openai/assistant/common/AIResponse.java package com.openai.assistant.common; public class AIResponse { private String content; private String provider; private long costMs; private boolean success; private String errorMsg; public static AIResponse success(String content, String provider, long costMs) { AIResponse response = new AIResponse(); response.setContent(content); response.setProvider(provider); response.setCostMs(costMs); response.setSuccess(true); return response; } public static AIResponse fail(String provider, String errorMsg) { AIResponse response = new AIResponse(); response.setProvider(provider); response.setSuccess(false); response.setErrorMsg(errorMsg); return response; } // 省略 getter/setter public String getContent() { return content; } public void setContent(String content) { this.content = content; } public String getProvider() { return provider; } public void setProvider(String provider) { this.provider = provider; } public long getCostMs() { return costMs; } public void setCostMs(long costMs) { this.costMs = costMs; } public boolean isSuccess() { return success; } public void setSuccess(boolean success) { this.success = success; } public String getErrorMsg() { return errorMsg; } public void setErrorMsg(String errorMsg) { this.errorMsg = errorMsg; } }

这里推荐使用静态工厂方法来构造AIResponse，调用侧代码会更直观。实际项目中还可以加入requestId、tokensUsed等字段，方便链路追踪和成本统计。

3.3 上游类型枚举

// 文件路径：src/main/java/com/openai/assistant/common/AIProviderType.java package com.openai.assistant.common; public enum AIProviderType { FENGYUN("fengyun"), MAPLE("maple"); private final String code; AIProviderType(String code) { this.code = code; } public String getCode() { return code; } }

枚举值不是固定的。比如你接入的是其他平台，完全可以改成BAIDU、ALIYUN、OPENAI等。关键是代码中要通过枚举而不是字符串散落判断，避免拼写错误。

3.4 路由策略分析

在双龙虾接口模块中，路由层是最核心的部件。常见路由策略有以下几种：

本文示例会重点实现failover策略，并在配置中保留primary策略作为可选。

3.5 为什么需要双上游而不是单上游

有人可能会觉得，既然最终都是调用同一个AI能力，直接在一个适配器里写死切换逻辑不就行了？这种做法短期可以，但长期会有问题：

• 请求日志中无法区分来源，排障困难。
• 新增上游时，需要改动核心调用方法，容易影响现有逻辑。
• 代码里会出现大量if/else判断，不利于测试。

双龙虾接口模块通过多实现注册 + 路由策略的方式，把“增加上游”这个动作变成“增加一个类 + 增加一段配置”，这是更符合工程化要求的做法。

4. 完整实战案例

4.1 创建项目结构

下面我们以一个名为ai-assistant的Spring Boot工程为例，逐步创建双龙虾接口模块。先看整体结构：

ai-assistant/ ├── pom.xml └── src/main/java/com/openai/assistant/ ├── AssistantApplication.java ├── common/ │ ├── AIProviderType.java │ ├── AIRequest.java │ └── AIResponse.java ├── lobster/ │ ├── DualLobsterRouter.java │ ├── LobsterAdapter.java │ └── impl/ │ ├── FengyunAIAdapter.java │ └── MapleAIAdapter.java └── controller/ └── ChatController.java

如果你使用IDEA，可以直接通过Spring Initializr创建一个Maven工程。如果手动创建，请确保pom.xml至少包含Spring Boot Web依赖。

4.2 添加依赖

<!-- 文件路径：pom.xml --> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.1.5</version> <relativePath/> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> </dependencies>

这里只引入Web依赖，因为示例暂时不需要数据库和消息队列。实际项目中，你可能还需要引入spring-boot-starter-validation、spring-boot-starter-actuator、httpclient5等。

4.3 编写启动类

// 文件路径：src/main/java/com/openai/assistant/AssistantApplication.java package com.openai.assistant; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class AssistantApplication { public static void main(String[] args) { SpringApplication.run(AssistantApplication.class, args); } }

4.4 实现两路上游适配器

首先实现FengyunAIAdapter，它代表枫云AI这一路Provider。

// 文件路径：src/main/java/com/openai/assistant/lobster/impl/FengyunAIAdapter.java package com.openai.assistant.lobster.impl; import com.openai.assistant.common.AIProviderType; import com.openai.assistant.common.AIRequest; import com.openai.assistant.common.AIResponse; import com.openai.assistant.lobster.LobsterAdapter; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; /** * 枫云AI适配器。 * 示例思路：这里只展示统一的适配流程，实际请求需要按上游平台文档调整。 */ @Component public class FengyunAIAdapter implements LobsterAdapter { private static final Logger log = LoggerFactory.getLogger(FengyunAIAdapter.class); @Value("${ai.fengyun.api-key:}") private String apiKey; @Value("${ai.fengyun.base-url:}") private String baseUrl; @Override public AIProviderType provider() { return AIProviderType.FENGYUN; } @Override public AIResponse chat(AIRequest request) { long start = System.currentTimeMillis(); try { if (apiKey.isEmpty() || baseUrl.isEmpty()) { log.warn("[FengyunAI] apiKey 或 baseUrl 未配置，无法调用"); return AIResponse.fail(provider().getCode(), "fenyun config missing"); } // 示例思路：在这里通过 RestTemplate / WebClient 调用枫云AI接口 // String url = baseUrl + "/chat/completions"; // String respBody = restTemplate.postForObject(url, buildBody(request), String.class); // 假设已经拿到上游返回文本 String content = "模拟枫云AI返回值：" + request.getPrompt(); long cost = System.currentTimeMillis() - start; return AIResponse.success(content, provider().getCode(), cost); } catch (Exception e) { log.error("[FengyunAI] 调用失败", e); return AIResponse.fail(provider().getCode(), e.getMessage()); } } }

再实现MapleAIAdapter，代表另一路AI服务商。

// 文件路径：src/main/java/com/openai/assistant/lobster/impl/MapleAIAdapter.java package com.openai.assistant.lobster.impl; import com.openai.assistant.common.AIProviderType; import com.openai.assistant.common.AIRequest; import com.openai.assistant.common.AIResponse; import com.openai.assistant.lobster.LobsterAdapter; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; /** * Maple AI 适配器，双龙虾模块中的第二路 Provider。 */ @Component public class MapleAIAdapter implements LobsterAdapter { private static final Logger log = LoggerFactory.getLogger(MapleAIAdapter.class); @Value("${ai.maple.api-key:}") private String apiKey; @Value("${ai.maple.base-url:}") private String baseUrl; @Override public AIProviderType provider() { return AIProviderType.MAPLE; } @Override public AIResponse chat(AIRequest request) { long start = System.currentTimeMillis(); try { if (apiKey.isEmpty() || baseUrl.isEmpty()) { log.warn("[MapleAI] apiKey 或 baseUrl 未配置，无法调用"); return AIResponse.fail(provider().getCode(), "maple config missing"); } // 示例思路：参考上游平台OpenAPI完成调用 String content = "模拟MapleAI返回值：" + request.getPrompt(); long cost = System.currentTimeMillis() - start; return AIResponse.success(content, provider().getCode(), cost); } catch (Exception e) { log.error("[MapleAI] 调用失败", e); return AIResponse.fail(provider().getCode(), e.getMessage()); } } }

这两个适配器类都是@Component，Spring容器启动后会自动收集到LobsterAdapter列表中。这是双龙虾模块能够“自动接入新上游”的关键。

4.5 编写路由门面

DualLobsterRouter是双龙虾接口模块的门面类，负责从Spring容器中找到所有LobsterAdapter实现，再按策略调用。

// 文件路径：src/main/java/com/openai/assistant/lobster/DualLobsterRouter.java package com.openai.assistant.lobster; import com.openai.assistant.common.AIProviderType; import com.openai.assistant.common.AIRequest; import com.openai.assistant.common.AIResponse; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; import java.util.List; import java.util.Map; import java.util.concurrent.atomic.AtomicInteger; import java.util.function.Function; import java.util.stream.Collectors; /** * 双龙虾接口模块路由门面。 * 根据配置的 strategy 选择主备、故障转移或轮询策略。 */ @Component public class DualLobsterRouter { private static final Logger log = LoggerFactory.getLogger(DualLobsterRouter.class); private final Map<AIProviderType, LobsterAdapter> adapterMap; private final AtomicInteger counter = new AtomicInteger(0); @Value("${ai.router.strategy:failover}") private String strategy; @Value("${ai.router.primary:fenyun}") private String primary; public DualLobsterRouter(List<LobsterAdapter> adapters) { // 将 Spring 容器中所有 LobsterAdapter 按 provider 类型建成 Map this.adapterMap = adapters.stream() .collect(Collectors.toMap(LobsterAdapter::provider, Function.identity())); } public AIResponse chat(AIRequest request) { switch (strategy) { case "primary": return chatWithPrimary(request); case "roundrobin": return chatWithRoundRobin(request); case "failover": default: return chatWithFailover(request); } } private AIResponse chatWithPrimary(AIRequest request) { AIProviderType primaryType = AIProviderType.valueOf(primary.toUpperCase()); LobsterAdapter primaryAdapter = adapterMap.get(primaryType); if (primaryAdapter == null || !primaryAdapter.available()) { log.warn("[DualLobster] primary adapter unavailable, try backup"); return callBackup(request); } AIResponse response = primaryAdapter.chat(request); if (response.isSuccess()) { return response; } log.warn("[DualLobster] primary failed: {}", response.getErrorMsg()); return callBackup(request); } private AIResponse chatWithRoundRobin(AIRequest request) { List<LobsterAdapter> adapters = adapterMap.values().stream() .filter(LobsterAdapter::available) .collect(Collectors.toList()); if (adapters.isEmpty()) { return AIResponse.fail("router", "no available adapter"); } int index = Math.abs(counter.getAndIncrement() % adapters.size()); LobsterAdapter adapter = adapters.get(index); return adapter.chat(request); } private AIResponse chatWithFailover(AIRequest request) { AIProviderType primaryType = AIProviderType.valueOf(primary.toUpperCase()); LobsterAdapter primaryAdapter = adapterMap.get(primaryType); if (primaryAdapter != null && primaryAdapter.available()) { AIResponse response = primaryAdapter.chat(request); if (response.isSuccess()) { return response; } log.warn("[DualLobster] failover, primary error: {}", response.getErrorMsg()); } return callBackup(request); } private AIResponse callBackup(AIRequest request) { for (LobsterAdapter adapter : adapterMap.values()) { if (!adapter.provider().getCode().equalsIgnoreCase(primary) && adapter.available()) { AIResponse response = adapter.chat(request); if (response.isSuccess()) { return response; } log.warn("[DualLobster] backup adapter error: {}", response.getErrorMsg()); } } return AIResponse.fail("router", "all adapters failed"); } }

这段路由代码有几个设计点：

• 构造方法中通过List<LobsterAdapter>注入所有适配器，Spring会完成自动收集。
• 配置项ai.router.strategy控制路由策略。
• 配置项ai.router.primary控制主Provider。
• 每个Provider调用失败后，统一返回AIResponse对象，而不是直接抛异常，方便上层做降级。
• Math.abs(counter.getAndIncrement() % adapters.size())用于简单轮询，生产环境可以替换为更平滑的权重算法。

4.6 添加配置项

# 文件路径：src/main/resources/application.yml server: port: 8080 ai: router: strategy: failover primary: fengyun fengyun: api-key: ${FENGYUN_API_KEY:} base-url: https://api.fengyun.example.com/v1 maple: api-key: ${MAPLE_API_KEY:} base-url: https://api.maple.example.com/v1

这里的base-url是示例地址，并不是真实平台地址。实际项目中请改成自己申请到的服务地址。密钥统一通过环境变量注入，不要把明文密钥提交到Git仓库。

4.7 编写测试接口

为了方便验证，写一个简单的ChatController。

// 文件路径：src/main/java/com/openai/assistant/controller/ChatController.java package com.openai.assistant.controller; import com.openai.assistant.common.AIRequest; import com.openai.assistant.common.AIResponse; import com.openai.assistant.lobster.DualLobsterRouter; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController; @RestController public class ChatController { private final DualLobsterRouter router; public ChatController(DualLobsterRouter router) { this.router = router; } @PostMapping("/chat") public AIResponse chat(@RequestBody AIRequest request) { return router.chat(request); } }

如果项目中配置了Spring Security或网关鉴权，这里还需要补充身份认证逻辑。本文示例省略。

4.8 运行与验证

启动Spring Boot应用后，在命令行执行：

curl -X POST http://localhost:8080/chat \ -H "Content-Type: application/json" \ -d '{"model":"text-model","prompt":"你好，枫云AI"}'

如果没有配置真实的API Key，两个适配器会返回失败信息，路由层会自动执行降级。如果配置了密钥，返回内容类似：

{ "content": "模拟枫云AI返回值：你好，枫云AI", "provider": "fengyun", "costMs": 15, "success": true }

如果把ai.router.strategy改成roundrobin，连续调用两次后，两个Provider会交替返回结果。

4.9 增加超时控制

双龙虾接口模块在生产环境最怕的就是上游接口“卡死”。这里建议在适配器内为HTTP客户端配置连接超时和读取超时，避免线程长期阻塞。

// 示例思路：在适配器内部创建 RestTemplate 时配置超时 @Bean public RestTemplate restTemplate(RestTemplateBuilder builder) { return builder .setConnectTimeout(Duration.ofSeconds(5)) .setReadTimeout(Duration.ofSeconds(30)) .build(); }

如果你用的是WebClient，可以配置HttpClient级别的响应超时；如果直接调用SDK，通常SDK本身也有timeout参数。不同平台API差异较大，建议以你实际使用的上游文档为准。

5. 常见问题与排查思路

5.1 问题汇总表

5.2 排查双龙虾模块的推荐顺序

如果线上出现问题，建议按以下顺序排查：

1. 确认Spring启动日志中是否正常加载了所有适配器Bean。
2. 查看请求日志，确认当前请求命中了哪个Provider。
3. 单独调用上游API，判断问题在双龙虾模块还是上游平台。
4. 检查路由策略配置是否与预期一致。
5. 检查是否有大量报错日志，确认是否为超时、限流或密钥过期。

这五步下来，80%的问题都能定位到根因。

6. 最佳实践与工程建议

6.1 密钥管理与配置隔离

双龙虾接口模块涉及多个上游密钥，最忌讳把密钥写在application.yml中提交到Git仓库。推荐做法：

• 本地开发使用环境变量或.env文件。
• 测试环境使用配置中心管理，例如Apollo或Nacos。
• 生产环境使用KMS、Vault等密钥管理服务。
• 每个环境的配置通过不同Profile隔离。

6.2 统一异常与降级规范

在双龙虾模块中，不建议把上游异常直接抛给调用方。统一做法是：

• 适配器内部捕获所有异常。
• 返回包含success=false和errorMsg的AIResponse。
• 路由层根据isSuccess()判断是否需要切换。
• Controller层只负责把AIResponse返回给前端。

这样即使两个上游都挂了，前端仍然能收到结构一致的错误响应。

6.3 超时、重试与幂等

重复请求AI接口时，需要关注幂等性。比如用户点击发送按钮后网络抖动，可能导致同一请求被重复提交。双龙虾模块的建议是：

• 调用上游前生成requestId。
• 在业务层对requestId做幂等校验。
• 重试只重试“连接超时”等瞬时错误，不要对上游已正常响应的请求盲目重试。
• 设置最大重试次数，避免下游故障时导致雪崩。

6.4 日志与链路追踪

多上游接入后，日志字段必须统一。推荐在请求入口生成traceId，并在整个调用链中传递。日志至少包含：

traceId provider model prompt长度 costMs success errorMsg

这样后续排查问题、统计成本和观测服务质量都会有数据支撑。

6.5 配置中心与灰度发布

双龙虾接口模块的配置项很适合放在配置中心中管理。比如你要把枫云AI的流量从10%逐步提升到100%，可以在配置中心动态调整ai.router.strategy和权重参数，而不需要发布新代码。

生产环境变更路由策略时，建议先在小流量灰度，观察日志和监控指标后再全量切换。

6.6 性能与线程池隔离

AI接口通常是IO密集型调用，不要在Controller线程中同步阻塞等待过长时间。如果QPS较高，可以考虑：

• 使用异步返回CompletableFuture。
• 为不同Provider配置独立线程池。
• 监控线程池队列长度，避免任务堆积。
• 使用bulkhead舱壁模式隔离不同Provider的错误影响。

6.7 安全边界

在AI助手场景中，用户输入的提示词可能包含恶意内容。双龙虾模块的上游调用应在网关或业务层完成输入过滤，不要直接把未校验的用户输入发送给模型。另外，输出内容也要做适当的内容安全和信息泄露检测。

7. 总结与学习路线

这篇文章从开源AI助手的双龙虾接口模块出发，梳理了双上游AI接口适配层的主要设计思路。核心内容包括：

• 定义统一的LobsterAdapter接口，让不同AI服务商按统一契约接入。
• 通过DualLobsterRouter门面实现主备、故障转移、轮询等策略。
• 通过AIRequest和AIResponse统一内部请求响应，隔离上游差异。
• 通过配置项动态调整路由策略，支持灰度与降级。

如果你要把它应用到自己的项目中，下一步可以尝试补齐这些能力：

• 接入一个真实的AI开放平台SDK，替换掉示例中的模拟返回。
• 增加流式响应支持，让AI助手在打字机模式下使用。
• 增加tokens统计和成本核算，为后续精细化运营做准备。
• 引入配置中心和监控面板，把上游状态可视化。

双龙虾接口模块只是一个起点。真正让AI助手稳定运行的关键，是围绕上游适配、路由降级、观测能力和成本控制建立一套完整的工程体系。希望这篇文章能帮你少踩一些适配层的坑，在接入双上游或多上游时快速搭建出一套干净、可靠、可扩展的接口模块。