用几十行代码搞定 Chat 接口透明转发：跨环境轻量级网关实战

在企业级应用开发中，经常遇到这样的场景：测试环境入口要访问生产数据，但不能改客户端配置，也不想动 Nginx 。 我用几十行代码实现了一个基于 YML 配置开关的透明转发机制 ------OpenAPI Chat Forward ，支持 SSE 流式响应、Header 白名单过滤，并且完全可控。

下面我将从场景背景、技术架构、核心实现、部署实战、监控排查完整拆解，并附实战示例和可视化图表，让你看到我能做什么、怎么做。

---

1️⃣ 背景故事：测试环境要用生产数据

真实项目中，我们遇到这样的需求：

• 客户端（H5/企业微信 Bot）入口固定指向测试环境
• 数据必须来自生产环境
• 不允许改客户端或域名配置
• 支持 SSE 实时流式推送

换句话说，我们需要一个**"壳是测试环境，料是生产环境"的透明代理"**。

💡 实战价值：

• 灰度验证新模型
• 并行对比服务版本
• 平滑迁移接口

传统做法是通过复杂 Nginx 配置或多套接口方案，但我用YML 配置 + 几十行 Java 代码就搞定了。

---

2️⃣ 技术架构设计

架构概览

flowchart LR A[客户端请求 H5/企业微信 Bot] --> B{检查 forward.enabled?} B -->|true| C[构建目标 URL] B -->|false| D[本地业务处理] C --> E[创建 OkHttpClient] E --> F[序列化请求体 JSON] F --> G[过滤并复制请求头] G --> H[HTTP POST 请求 -> 目标服务] H --> I[复制响应状态码和响应头] I --> J[流式写入 SSE 输出流] J --> K[客户端实时接收数据] D --> L[验证请求参数] L --> M[验证账户余额] M --> N[构建 ChainContext] N --> O[记录追踪信息] O --> P[BotAgent 处理并返回 SSE 流]

核心组件结构

com.example.openapi
├── config
│   └── OpenApiChatForwardProperties.java  # 配置属性绑定
├── service
│   └── OpenApiChatForwardService.java     # 转发实现
└── web
    └── OpenChatAppController.java        # 控制器入口

---

3️⃣ 配置驱动，让环境切换简单

openapi:
  chat:
    forward:
      enabled: ${OPENAPI_CHAT_FORWARD_ENABLED:false}
      targetBaseUrl: ${OPENAPI_CHAT_FORWARD_TARGET_BASE_URL:http://prod-service:8080}
      path: ${OPENAPI_CHAT_FORWARD_PATH:/chat/completions}
      connectTimeoutMs: 3000
      readTimeoutMs: 600000
      writeTimeoutMs: 30000
      headerWhitelist:
        - authorization
        - content-type
        - accept

• 优先级：环境变量 > application.yml > 默认值
• 优势：无代码改动即可切换环境，支持多环境部署（开发/测试/生产）

💡 案例截图建议 ：IDE 中 application-test.yml 与 application-prod.yml 对比图，让读者一眼看懂差异。

---

4️⃣ 核心实现亮点

4.1 OkHttpClient + SSE 流式响应

OkHttpClient client = new OkHttpClient.Builder()
        .connectTimeout(connectTimeoutMs, TimeUnit.MILLISECONDS)
        .readTimeout(readTimeoutMs, TimeUnit.MILLISECONDS)
        .writeTimeout(writeTimeoutMs, TimeUnit.MILLISECONDS)
        .retryOnConnectionFailure(false)
        .build();

✅ 原生支持 SSE 流式响应 ✅ 禁用自动重试，避免重复请求

---

4.2 直接写入 HttpServletResponse 输出流

try (InputStream input = body.byteStream();
     OutputStream output = response.getOutputStream()) {
    byte[] buffer = new byte[8192];
    int len;
    while ((len = input.read(buffer)) != -1) {
        output.write(buffer, 0, len);
        output.flush(); // 实时推送 SSE
    }
}

• return null 仍能返回数据
• 完全绕过 Spring MVC 返回值机制
• 支持实时 SSE 推送，适合聊天、日志流场景

💡 实战截图建议：展示控制台 SSE 数据流，凸显实时推送效果。

---

4.3 白名单控制请求头

• 防止敏感信息泄露
• 避免头部冲突导致转发失败
• 可控性强，易于维护

---

5️⃣ 部署实战示例

测试环境

openapi:
  chat:
    forward:
      enabled: true
      targetBaseUrl: http://test-forward-service:8080
      readTimeoutMs: 300000

生产环境

openapi:
  chat:
    forward:
      enabled: ${OPENAPI_CHAT_FORWARD_ENABLED:false}
      targetBaseUrl: ${OPENAPI_CHAT_FORWARD_TARGET_BASE_URL}
      connectTimeoutMs: 5000
      readTimeoutMs: 600000
      writeTimeoutMs: 60000

环境变量控制

export OPENAPI_CHAT_FORWARD_ENABLED=true
export OPENAPI_CHAT_FORWARD_TARGET_BASE_URL=http://prod-service:8080
export OPENAPI_CHAT_FORWARD_READ_TIMEOUT_MS=300000

---

6️⃣ 故障排查

问题	可能原因	解决方案
转发超时	目标服务响应慢	调整 readTimeoutMs 或优化目标服务
连接拒绝	URL 或网络不可达	检查 targetBaseUrl 与网络
401 Unauthorized	未转发 authorization	确认白名单配置
SSE 响应不完整	网络不稳定	增加缓冲区或优化网络

---

7️⃣ 成果展示

1. 配置驱动：无需代码改动即可切换环境
2. 透明代理：客户端完全无感知
3. 安全可控：Header 白名单机制
4. 高性能：SSE 流式响应 + 8KB 缓冲区
5. 易监控：日志完善、指标易追踪

💡 图示建议：绘制"请求流向图"+"SSE 时序图"，直观展示数据流动。

---

8️⃣ 我的能力 & 可承接项目

• 精通 Java、Spring Boot、SSE、OkHttpClient
• 擅长接口转发、透明代理、流式响应设计
• 可独立设计跨环境网关与配置驱动方案
• 可承接企业接口开发、微服务网关、实时数据推送等私活项目

📬 联系我 ：如果你需要类似解决方案，我可以提供 接口转发、微服务优化、实时推送架构设计落地服务。