1. 为什么要在 Spring Boot 里自己接一套 AI 对话服务先把结论摆在前面Spring Boot 集成 OpenAI API 这件事本质上不是“调个接口”那么简单而是要在 Java 生态里补齐一整套对话上下文管理、流式输出、异常兜底、密钥安全、成本控制的能力。我见过太多团队一开始觉得“不就是发个 HTTP 请求吗”结果上线两周就被超时、上下文丢失、Token 爆表和密钥泄露轮番教育。这套东西适合谁如果你是有 Spring Boot 基础、想给自己的管理系统、客服系统、内部工具加一个 AI 对话入口的 Java 开发者那这篇就是写给你的。如果你只是想快速验证一个想法那用现成的 SDK 或平台也行但只要你想把 AI 对话能力真正嵌进业务系统自己掌控请求链路、上下文策略和降级逻辑那自己搭一层服务几乎是必经之路。我这次做的场景很典型一个内部知识助手前端一个对话框后端 Spring Boot 提供/chat和/chat/stream两个接口底层对接 OpenAI 的对话模型。整个链路我踩过的坑包括同步阻塞导致 Tomcat 线程被占满、SSE 流式输出中文乱码、多轮对话把历史全塞进去导致 Token 爆炸、以及 API Key 被硬编码进配置文件后差点提交到仓库。下面我把整套设计思路、核心实现和排查经验完整拆开讲你可以直接照着复现。需要先说明一点OpenAI API 的 Key 获取、模型名称、计费规则这些会随时间变化我下面提到的具体模型名和参数是基于我实操时的常见实践你落地时以官方控制台当前说明为准。另外任何密钥都不要写进代码或提交到版本库这是底线。2. 整体架构设计与技术选型思路2.1 为什么不用现成 SDK 而选择自己封装 HTTP 层Java 生态里对接 OpenAI 有几条路官方或社区的 Java SDK、Spring AI 这类框架、以及自己用RestTemplate/WebClient封装。我最后选了自己封装 HTTP 层原因有三个。第一可控性。SDK 版本迭代快接口签名经常变一旦底层行为不符合预期比如超时策略、重试逻辑你很难插手。自己封装的话超时、重试、日志、熔断全在自己手里。第二依赖轻。引入一个 SDK 往往带进来一堆传递依赖跟项目里已有的 Jackson、OkHttp 版本打架是常事。第三学习成本反而更低——你只需要理解 OpenAI 的 REST 接口契约不用去啃某个框架的抽象层。那 Spring AI 呢它确实是个不错的选择尤其是你想快速接入多家模型、用统一的ChatClient抽象时。但在我这个场景里需求很聚焦就是对接一家、做多轮对话和流式输出自己封装反而更透明。如果你团队后续要接多家模型做对比那 Spring AI 的抽象价值就体现出来了这个取舍看你自己的规划。2.2 同步接口与流式接口为什么要分开设计对话服务我设计了两个入口/chat走同步返回/chat/stream走 SSE 流式返回。很多人会问既然有流式了还要同步干嘛同步接口的价值在于简单场景和内部调用。比如后台任务、定时脚本、或者某些不需要实时展示的批处理直接拿完整结果最省事。而流式接口的价值在于用户体验——大模型生成一段几百字的回答可能要好几秒如果等全部生成完再返回用户盯着转圈会以为卡死了。SSE 让首字延迟从几秒降到几百毫秒体感完全不同。这里有个关键决策流式接口必须用异步非阻塞的方式实现。如果你在 Spring MVC 里用同步方式写 SSE每个连接都会占住一个 Tomcat 线程并发一上来线程池直接耗尽。我一开始就踩了这个坑压测到 50 并发时接口开始大面积超时。后来改用WebClientFlux返回text/event-stream线程占用问题才解决。2.3 上下文管理的核心策略多轮对话的本质是把历史消息按顺序拼成一个数组发给模型。但历史不能无限增长否则 Token 消耗会指数级上升而且超出模型上下文窗口后请求直接报错。我的策略是滑动窗口 系统提示词固定。系统提示词system message永远放在最前面不参与裁剪用户和助手的对话历史保留最近 N 轮N 根据模型上下文窗口和单轮平均长度动态估算。具体来说我按“总 Token 预算的 70% 留给历史30% 留给本次输入和输出”来分配然后用一个粗略的字符数估算中文约 1 字符 ≈ 1 Token英文约 4 字符 ≈ 1 Token做裁剪判断。这个估算不精确但足够实用真要精确可以用分词库但会引入额外依赖和性能开销。提示上下文裁剪一定要保留完整的“用户-助手”配对不能只删用户消息或只删助手消息否则模型会收到语义不完整的对话回答质量明显下降。3. 核心实现细节与关键参数解析3.1 项目依赖与基础配置先看依赖。核心就三个spring-boot-starter-web提供 Web 能力、spring-boot-starter-webflux提供 WebClient 和响应式流、spring-boot-starter-validation参数校验。注意 web 和 webflux 同时引入时Spring Boot 默认还是以 MVC 为主WebClient 可以正常使用这个组合是安全的。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-validation/artifactId /dependency配置文件里密钥绝对不能硬编码。我用环境变量注入openai: api-key: ${OPENAI_API_KEY} base-url: https://api.openai.com/v1 model: gpt-4o-mini connect-timeout: 5000 read-timeout: 60000 max-history-rounds: 10这里几个参数值得说清楚。connect-timeout设 5 秒因为建连本身很快超过说明网络有问题没必要等。read-timeout设 60 秒因为流式生成长回答可能持续几十秒设太短会中途断开。max-history-rounds设 10是我实测下来在成本和体验之间的平衡点——大部分对话 10 轮内能解决问题再长的话用户自己也该开新会话了。3.2 请求体的构造与消息角色OpenAI 对话接口的请求体结构是固定的model、messages、temperature、stream等字段。messages是一个数组每个元素有role和content。role有三种system设定助手行为、user用户输入、assistant模型回复。我封装了一个ChatMessage记录类用 Java 的 record 特性简洁且不可变public record ChatMessage(String role, String content) { public static ChatMessage system(String content) { return new ChatMessage(system, content); } public static ChatMessage user(String content) { return new ChatMessage(user, content); } public static ChatMessage assistant(String content) { return new ChatMessage(assistant, content); } }temperature这个参数控制输出的随机性范围 0 到 2。做知识问答、客服这类需要稳定准确的场景我设 0.2 到 0.5做创意写作、头脑风暴可以设 0.8 以上。我默认用 0.3因为内部助手更看重准确性。3.3 流式响应的解析难点流式接口返回的是 SSE 格式每一行以data:开头内容是一个 JSON 片段最后以data: [DONE]结束。解析时有两个坑。第一个坑是数据可能跨行或粘包。网络传输不保证一次onNext就给你一个完整的data:行可能半行就来了。所以不能简单按行切分要维护一个缓冲区遇到换行符才处理完整行。第二个坑是空行和心跳。SSE 规范里空行是消息分隔符有些实现还会发注释行以:开头做心跳这些都要跳过。我用 WebClient 的bodyToFlux(String.class)拿到的是已经按 SSE 事件切分好的字符串省去了手动处理粘包的麻烦但每个字符串里可能包含多个data:行还是要逐行解析。解析逻辑是去掉data:前缀如果是[DONE]就结束否则反序列化成对象取出choices[0].delta.content这个字段在流式响应里是增量内容可能为空比如第一个 chunk 只有 role 信息。3.4 密钥安全与请求头设置API Key 通过请求头Authorization: Bearer key传递。这里的安全要点密钥只从环境变量或配置中心读取日志里绝对不能打印完整密钥我一般只打印前 4 位和后 4 位用于排查异常信息里也要过滤掉请求头。private String maskKey(String key) { if (key null || key.length() 8) return ****; return key.substring(0, 4) **** key.substring(key.length() - 4); }另外base-url也做成可配置的方便你在测试环境和生产环境之间切换或者对接兼容 OpenAI 协议的其他服务端点。这个设计让整套代码的复用性大大提升。4. 完整实操流程与核心代码实现4.1 服务层同步对话的完整实现先看同步对话。核心是用WebClient发 POST 请求拿到完整响应后解析出choices[0].message.content。Service public class ChatService { private final WebClient webClient; private final OpenAiProperties props; private final ObjectMapper objectMapper; public ChatService(WebClient.Builder builder, OpenAiProperties props, ObjectMapper objectMapper) { this.props props; this.objectMapper objectMapper; this.webClient builder .baseUrl(props.getBaseUrl()) .defaultHeader(HttpHeaders.AUTHORIZATION, Bearer props.getApiKey()) .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE) .build(); } public String chat(ListChatMessage messages) { MapString, Object body Map.of( model, props.getModel(), messages, messages, temperature, 0.3 ); String response webClient.post() .uri(/chat/completions) .bodyValue(body) .retrieve() .bodyToMono(String.class) .block(Duration.ofSeconds(60)); return extractContent(response); } }extractContent用 Jackson 解析 JSON取choices数组第一个元素的message.content。这里要处理choices为空的情况虽然正常不会发生但防御性编程能避免线上 NPE。4.2 服务层流式对话的实现流式对话返回FluxString每个元素是一段增量文本。Controller 层把它包装成 SSE。public FluxString chatStream(ListChatMessage messages) { MapString, Object body Map.of( model, props.getModel(), messages, messages, temperature, 0.3, stream, true ); return webClient.post() .uri(/chat/completions) .bodyValue(body) .retrieve() .bodyToFlux(String.class) .flatMap(this::parseSseLine) .filter(s - !s.isEmpty()); } private FluxString parseSseLine(String raw) { return Flux.fromArray(raw.split(\n)) .filter(line - line.startsWith(data: )) .map(line - line.substring(6).trim()) .filter(data - !data.equals([DONE])) .map(this::extractDelta) .filter(s - s ! null !s.isEmpty()); }extractDelta解析 JSON 取choices[0].delta.content这个字段可能不存在比如首个 chunk所以要判空。4.3 Controller 层SSE 接口的正确写法Controller 返回FluxServerSentEventString或直接FluxString配合produces MediaType.TEXT_EVENT_STREAM_VALUE。PostMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString chatStream(RequestBody Valid ChatRequest request) { ListChatMessage messages buildMessages(request); return chatService.chatStream(messages); }这里有个细节SSE 默认的字符编码要确认是 UTF-8否则中文会乱码。Spring 的TEXT_EVENT_STREAM_VALUE默认就是 UTF-8但如果你手动设置了produces为其他编码就会出问题。我实测下来只要用这个常量中文没问题。4.4 上下文构建与裁剪的落地代码buildMessages负责把系统提示词、历史消息、本次用户输入拼起来并做裁剪。private ListChatMessage buildMessages(ChatRequest request) { ListChatMessage result new ArrayList(); result.add(ChatMessage.system(props.getSystemPrompt())); ListChatMessage history request.getHistory(); int maxRounds props.getMaxHistoryRounds(); if (history ! null history.size() maxRounds * 2) { history history.subList(history.size() - maxRounds * 2, history.size()); } if (history ! null) { result.addAll(history); } result.add(ChatMessage.user(request.getMessage())); return result; }注意maxRounds * 2是因为一轮对话包含一条用户消息和一条助手消息。裁剪时从尾部取保证最近的对话优先保留。4.5 超时、重试与降级处理网络请求必须配超时否则线程会被无限期挂住。WebClient的超时通过HttpClient配置HttpClient httpClient HttpClient.create() .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, props.getConnectTimeout()) .responseTimeout(Duration.ofMillis(props.getReadTimeout())); this.webClient builder .baseUrl(props.getBaseUrl()) .clientConnector(new ReactorClientHttpConnector(httpClient)) .defaultHeader(HttpHeaders.AUTHORIZATION, Bearer props.getApiKey()) .build();重试要谨慎。对话接口不是幂等的吗其实对于同样的输入模型输出可能不同但重试在“请求失败”场景下是安全的——失败意味着没拿到结果重试不会产生副作用。我用retryWhen对 5xx 和超时做最多 2 次重试间隔 1 秒。但 4xx比如 401 密钥错误、429 限流不重试因为重试也没用反而浪费配额。降级方面如果模型服务不可用我返回一个友好的提示而不是把原始异常抛给前端。同时记录错误日志方便排查。5. 常见问题与排查技巧实录5.1 高频问题速查表问题现象可能原因排查方向解决方法401 Unauthorized密钥错误或未生效检查环境变量是否注入、密钥是否过期重新生成密钥确认maskKey日志429 Too Many Requests触发限流或配额耗尽查看账户配额和请求频率加退避重试降低并发流式输出中文乱码编码不一致检查produces和响应头使用TEXT_EVENT_STREAM_VALUE请求超时网络慢或模型响应慢看日志中耗时分布调大read-timeout加超时降级上下文超长报错历史消息过多统计消息 Token 数启用滑动窗口裁剪线程池耗尽同步方式写 SSE看线程 dump改用 WebClient 异步首字延迟高未启用流式确认stream: true前端改用 SSE 接收5.2 我踩过的三个真实坑第一个坑block()在响应式线程里调用导致死锁。我一开始在流式接口里混用了block()结果请求直接卡死。原因是 Reactor 的线程模型不允许在非阻塞线程里做阻塞操作。后来把所有阻塞调用都挪到同步接口流式接口全程用Flux操作符问题消失。第二个坑SSE 连接被网关提前关闭。部署到有反向代理的环境后流式输出经常中途断掉。排查发现是代理的读超时设得太短默认 30 秒而模型生成长回答超过了这个时间。解决办法是在代理层调大读超时或者让服务端定期发送心跳注释行保持连接活跃。第三个坑历史消息里混入了空内容。前端传历史时某些助手回复因为网络问题存成了空字符串结果发给模型后报 400。后来在buildMessages里加了一层过滤跳过content为空的消息。5.3 成本控制的实操心得Token 就是钱这话一点不夸张。我做了三件事控制成本。一是限制max_tokens给输出设上限防止模型长篇大论。二是精简系统提示词系统提示词每轮都会发送写得太长等于每轮都在烧钱。三是缓存高频问答对于重复率高的固定问题直接返回缓存结果不走模型。这三招下来我的月度成本降了大概四成。注意max_tokens设得太小会导致回答被截断用户体验很差。我的经验是设 1024 到 2048 之间既能容纳大部分回答又不会失控。5.4 并发场景下的稳定性建议如果你的服务要面对较高并发有几个点必须注意。连接池要配够WebClient底层默认的连接池对高并发不够用需要显式配置ConnectionProvider的最大连接数和等待队列。限流要做用信号量或 Resilience4j 限制同时进行的模型请求数避免把配额打爆。监控要跟上记录每次请求的耗时、Token 消耗、成功率这些指标是发现问题的眼睛。我在压测时发现单实例在 100 并发下如果连接池只配了默认的 16 个连接请求会大量排队。把最大连接数调到 200 后吞吐量明显提升。但也不能无限调大因为模型服务端本身有限流调太大只会让请求在服务端排队反而增加超时概率。6. 从能跑到好用还差哪些工程化细节代码能跑通只是起点。真正上线前我补了几个工程化细节这里一并分享。日志脱敏。所有涉及请求体和响应体的日志都要过滤掉密钥和用户隐私内容。我写了一个LogSanitizer在打印前把敏感字段替换成***。这个习惯救过我一次——有次排查问题差点把带密钥的完整请求打到日志里。健康检查。加一个/health接口定期探测模型服务是否可达。这样负载均衡能及时摘除不健康的实例避免用户请求打到已经连不上模型的节点上。配置热更新。模型名称、超时时间这些参数最好支持不重启就生效。我用 Spring Cloud Config 或简单的配置中心实现了这一点调整参数不用重新发版运维效率高很多。接口版本管理。对话接口的请求体结构未来可能变我在 URL 里加了版本号比如/v1/chat这样老客户端不受影响新功能可以平滑上线。单元测试与集成测试。模型调用没法在单测里真发请求我用 MockWebServer 模拟响应覆盖正常返回、超时、错误码等各种分支。集成测试则用真实密钥跑少量用例确保端到端链路通畅。我个人在实际操作中的体会是这套东西的技术难度不在“调通接口”而在“稳定运行”。把超时、重试、降级、限流、监控这些看似琐碎的细节做扎实才是它能不能扛住真实流量的分水岭。最后再分享一个小技巧把每次对话的请求和响应脱敏后存一份到数据库出问题时可以完整回放排查效率比看日志高得多。这个内容后续还可以这样扩展——接入向量数据库做知识库检索增强让助手能回答你私有文档里的问题那就是另一个值得单独聊的话题了。
Spring Boot 集成 OpenAI API 实战：流式输出与上下文管理
1. 为什么要在 Spring Boot 里自己接一套 AI 对话服务先把结论摆在前面Spring Boot 集成 OpenAI API 这件事本质上不是“调个接口”那么简单而是要在 Java 生态里补齐一整套对话上下文管理、流式输出、异常兜底、密钥安全、成本控制的能力。我见过太多团队一开始觉得“不就是发个 HTTP 请求吗”结果上线两周就被超时、上下文丢失、Token 爆表和密钥泄露轮番教育。这套东西适合谁如果你是有 Spring Boot 基础、想给自己的管理系统、客服系统、内部工具加一个 AI 对话入口的 Java 开发者那这篇就是写给你的。如果你只是想快速验证一个想法那用现成的 SDK 或平台也行但只要你想把 AI 对话能力真正嵌进业务系统自己掌控请求链路、上下文策略和降级逻辑那自己搭一层服务几乎是必经之路。我这次做的场景很典型一个内部知识助手前端一个对话框后端 Spring Boot 提供/chat和/chat/stream两个接口底层对接 OpenAI 的对话模型。整个链路我踩过的坑包括同步阻塞导致 Tomcat 线程被占满、SSE 流式输出中文乱码、多轮对话把历史全塞进去导致 Token 爆炸、以及 API Key 被硬编码进配置文件后差点提交到仓库。下面我把整套设计思路、核心实现和排查经验完整拆开讲你可以直接照着复现。需要先说明一点OpenAI API 的 Key 获取、模型名称、计费规则这些会随时间变化我下面提到的具体模型名和参数是基于我实操时的常见实践你落地时以官方控制台当前说明为准。另外任何密钥都不要写进代码或提交到版本库这是底线。2. 整体架构设计与技术选型思路2.1 为什么不用现成 SDK 而选择自己封装 HTTP 层Java 生态里对接 OpenAI 有几条路官方或社区的 Java SDK、Spring AI 这类框架、以及自己用RestTemplate/WebClient封装。我最后选了自己封装 HTTP 层原因有三个。第一可控性。SDK 版本迭代快接口签名经常变一旦底层行为不符合预期比如超时策略、重试逻辑你很难插手。自己封装的话超时、重试、日志、熔断全在自己手里。第二依赖轻。引入一个 SDK 往往带进来一堆传递依赖跟项目里已有的 Jackson、OkHttp 版本打架是常事。第三学习成本反而更低——你只需要理解 OpenAI 的 REST 接口契约不用去啃某个框架的抽象层。那 Spring AI 呢它确实是个不错的选择尤其是你想快速接入多家模型、用统一的ChatClient抽象时。但在我这个场景里需求很聚焦就是对接一家、做多轮对话和流式输出自己封装反而更透明。如果你团队后续要接多家模型做对比那 Spring AI 的抽象价值就体现出来了这个取舍看你自己的规划。2.2 同步接口与流式接口为什么要分开设计对话服务我设计了两个入口/chat走同步返回/chat/stream走 SSE 流式返回。很多人会问既然有流式了还要同步干嘛同步接口的价值在于简单场景和内部调用。比如后台任务、定时脚本、或者某些不需要实时展示的批处理直接拿完整结果最省事。而流式接口的价值在于用户体验——大模型生成一段几百字的回答可能要好几秒如果等全部生成完再返回用户盯着转圈会以为卡死了。SSE 让首字延迟从几秒降到几百毫秒体感完全不同。这里有个关键决策流式接口必须用异步非阻塞的方式实现。如果你在 Spring MVC 里用同步方式写 SSE每个连接都会占住一个 Tomcat 线程并发一上来线程池直接耗尽。我一开始就踩了这个坑压测到 50 并发时接口开始大面积超时。后来改用WebClientFlux返回text/event-stream线程占用问题才解决。2.3 上下文管理的核心策略多轮对话的本质是把历史消息按顺序拼成一个数组发给模型。但历史不能无限增长否则 Token 消耗会指数级上升而且超出模型上下文窗口后请求直接报错。我的策略是滑动窗口 系统提示词固定。系统提示词system message永远放在最前面不参与裁剪用户和助手的对话历史保留最近 N 轮N 根据模型上下文窗口和单轮平均长度动态估算。具体来说我按“总 Token 预算的 70% 留给历史30% 留给本次输入和输出”来分配然后用一个粗略的字符数估算中文约 1 字符 ≈ 1 Token英文约 4 字符 ≈ 1 Token做裁剪判断。这个估算不精确但足够实用真要精确可以用分词库但会引入额外依赖和性能开销。提示上下文裁剪一定要保留完整的“用户-助手”配对不能只删用户消息或只删助手消息否则模型会收到语义不完整的对话回答质量明显下降。3. 核心实现细节与关键参数解析3.1 项目依赖与基础配置先看依赖。核心就三个spring-boot-starter-web提供 Web 能力、spring-boot-starter-webflux提供 WebClient 和响应式流、spring-boot-starter-validation参数校验。注意 web 和 webflux 同时引入时Spring Boot 默认还是以 MVC 为主WebClient 可以正常使用这个组合是安全的。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-validation/artifactId /dependency配置文件里密钥绝对不能硬编码。我用环境变量注入openai: api-key: ${OPENAI_API_KEY} base-url: https://api.openai.com/v1 model: gpt-4o-mini connect-timeout: 5000 read-timeout: 60000 max-history-rounds: 10这里几个参数值得说清楚。connect-timeout设 5 秒因为建连本身很快超过说明网络有问题没必要等。read-timeout设 60 秒因为流式生成长回答可能持续几十秒设太短会中途断开。max-history-rounds设 10是我实测下来在成本和体验之间的平衡点——大部分对话 10 轮内能解决问题再长的话用户自己也该开新会话了。3.2 请求体的构造与消息角色OpenAI 对话接口的请求体结构是固定的model、messages、temperature、stream等字段。messages是一个数组每个元素有role和content。role有三种system设定助手行为、user用户输入、assistant模型回复。我封装了一个ChatMessage记录类用 Java 的 record 特性简洁且不可变public record ChatMessage(String role, String content) { public static ChatMessage system(String content) { return new ChatMessage(system, content); } public static ChatMessage user(String content) { return new ChatMessage(user, content); } public static ChatMessage assistant(String content) { return new ChatMessage(assistant, content); } }temperature这个参数控制输出的随机性范围 0 到 2。做知识问答、客服这类需要稳定准确的场景我设 0.2 到 0.5做创意写作、头脑风暴可以设 0.8 以上。我默认用 0.3因为内部助手更看重准确性。3.3 流式响应的解析难点流式接口返回的是 SSE 格式每一行以data:开头内容是一个 JSON 片段最后以data: [DONE]结束。解析时有两个坑。第一个坑是数据可能跨行或粘包。网络传输不保证一次onNext就给你一个完整的data:行可能半行就来了。所以不能简单按行切分要维护一个缓冲区遇到换行符才处理完整行。第二个坑是空行和心跳。SSE 规范里空行是消息分隔符有些实现还会发注释行以:开头做心跳这些都要跳过。我用 WebClient 的bodyToFlux(String.class)拿到的是已经按 SSE 事件切分好的字符串省去了手动处理粘包的麻烦但每个字符串里可能包含多个data:行还是要逐行解析。解析逻辑是去掉data:前缀如果是[DONE]就结束否则反序列化成对象取出choices[0].delta.content这个字段在流式响应里是增量内容可能为空比如第一个 chunk 只有 role 信息。3.4 密钥安全与请求头设置API Key 通过请求头Authorization: Bearer key传递。这里的安全要点密钥只从环境变量或配置中心读取日志里绝对不能打印完整密钥我一般只打印前 4 位和后 4 位用于排查异常信息里也要过滤掉请求头。private String maskKey(String key) { if (key null || key.length() 8) return ****; return key.substring(0, 4) **** key.substring(key.length() - 4); }另外base-url也做成可配置的方便你在测试环境和生产环境之间切换或者对接兼容 OpenAI 协议的其他服务端点。这个设计让整套代码的复用性大大提升。4. 完整实操流程与核心代码实现4.1 服务层同步对话的完整实现先看同步对话。核心是用WebClient发 POST 请求拿到完整响应后解析出choices[0].message.content。Service public class ChatService { private final WebClient webClient; private final OpenAiProperties props; private final ObjectMapper objectMapper; public ChatService(WebClient.Builder builder, OpenAiProperties props, ObjectMapper objectMapper) { this.props props; this.objectMapper objectMapper; this.webClient builder .baseUrl(props.getBaseUrl()) .defaultHeader(HttpHeaders.AUTHORIZATION, Bearer props.getApiKey()) .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE) .build(); } public String chat(ListChatMessage messages) { MapString, Object body Map.of( model, props.getModel(), messages, messages, temperature, 0.3 ); String response webClient.post() .uri(/chat/completions) .bodyValue(body) .retrieve() .bodyToMono(String.class) .block(Duration.ofSeconds(60)); return extractContent(response); } }extractContent用 Jackson 解析 JSON取choices数组第一个元素的message.content。这里要处理choices为空的情况虽然正常不会发生但防御性编程能避免线上 NPE。4.2 服务层流式对话的实现流式对话返回FluxString每个元素是一段增量文本。Controller 层把它包装成 SSE。public FluxString chatStream(ListChatMessage messages) { MapString, Object body Map.of( model, props.getModel(), messages, messages, temperature, 0.3, stream, true ); return webClient.post() .uri(/chat/completions) .bodyValue(body) .retrieve() .bodyToFlux(String.class) .flatMap(this::parseSseLine) .filter(s - !s.isEmpty()); } private FluxString parseSseLine(String raw) { return Flux.fromArray(raw.split(\n)) .filter(line - line.startsWith(data: )) .map(line - line.substring(6).trim()) .filter(data - !data.equals([DONE])) .map(this::extractDelta) .filter(s - s ! null !s.isEmpty()); }extractDelta解析 JSON 取choices[0].delta.content这个字段可能不存在比如首个 chunk所以要判空。4.3 Controller 层SSE 接口的正确写法Controller 返回FluxServerSentEventString或直接FluxString配合produces MediaType.TEXT_EVENT_STREAM_VALUE。PostMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString chatStream(RequestBody Valid ChatRequest request) { ListChatMessage messages buildMessages(request); return chatService.chatStream(messages); }这里有个细节SSE 默认的字符编码要确认是 UTF-8否则中文会乱码。Spring 的TEXT_EVENT_STREAM_VALUE默认就是 UTF-8但如果你手动设置了produces为其他编码就会出问题。我实测下来只要用这个常量中文没问题。4.4 上下文构建与裁剪的落地代码buildMessages负责把系统提示词、历史消息、本次用户输入拼起来并做裁剪。private ListChatMessage buildMessages(ChatRequest request) { ListChatMessage result new ArrayList(); result.add(ChatMessage.system(props.getSystemPrompt())); ListChatMessage history request.getHistory(); int maxRounds props.getMaxHistoryRounds(); if (history ! null history.size() maxRounds * 2) { history history.subList(history.size() - maxRounds * 2, history.size()); } if (history ! null) { result.addAll(history); } result.add(ChatMessage.user(request.getMessage())); return result; }注意maxRounds * 2是因为一轮对话包含一条用户消息和一条助手消息。裁剪时从尾部取保证最近的对话优先保留。4.5 超时、重试与降级处理网络请求必须配超时否则线程会被无限期挂住。WebClient的超时通过HttpClient配置HttpClient httpClient HttpClient.create() .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, props.getConnectTimeout()) .responseTimeout(Duration.ofMillis(props.getReadTimeout())); this.webClient builder .baseUrl(props.getBaseUrl()) .clientConnector(new ReactorClientHttpConnector(httpClient)) .defaultHeader(HttpHeaders.AUTHORIZATION, Bearer props.getApiKey()) .build();重试要谨慎。对话接口不是幂等的吗其实对于同样的输入模型输出可能不同但重试在“请求失败”场景下是安全的——失败意味着没拿到结果重试不会产生副作用。我用retryWhen对 5xx 和超时做最多 2 次重试间隔 1 秒。但 4xx比如 401 密钥错误、429 限流不重试因为重试也没用反而浪费配额。降级方面如果模型服务不可用我返回一个友好的提示而不是把原始异常抛给前端。同时记录错误日志方便排查。5. 常见问题与排查技巧实录5.1 高频问题速查表问题现象可能原因排查方向解决方法401 Unauthorized密钥错误或未生效检查环境变量是否注入、密钥是否过期重新生成密钥确认maskKey日志429 Too Many Requests触发限流或配额耗尽查看账户配额和请求频率加退避重试降低并发流式输出中文乱码编码不一致检查produces和响应头使用TEXT_EVENT_STREAM_VALUE请求超时网络慢或模型响应慢看日志中耗时分布调大read-timeout加超时降级上下文超长报错历史消息过多统计消息 Token 数启用滑动窗口裁剪线程池耗尽同步方式写 SSE看线程 dump改用 WebClient 异步首字延迟高未启用流式确认stream: true前端改用 SSE 接收5.2 我踩过的三个真实坑第一个坑block()在响应式线程里调用导致死锁。我一开始在流式接口里混用了block()结果请求直接卡死。原因是 Reactor 的线程模型不允许在非阻塞线程里做阻塞操作。后来把所有阻塞调用都挪到同步接口流式接口全程用Flux操作符问题消失。第二个坑SSE 连接被网关提前关闭。部署到有反向代理的环境后流式输出经常中途断掉。排查发现是代理的读超时设得太短默认 30 秒而模型生成长回答超过了这个时间。解决办法是在代理层调大读超时或者让服务端定期发送心跳注释行保持连接活跃。第三个坑历史消息里混入了空内容。前端传历史时某些助手回复因为网络问题存成了空字符串结果发给模型后报 400。后来在buildMessages里加了一层过滤跳过content为空的消息。5.3 成本控制的实操心得Token 就是钱这话一点不夸张。我做了三件事控制成本。一是限制max_tokens给输出设上限防止模型长篇大论。二是精简系统提示词系统提示词每轮都会发送写得太长等于每轮都在烧钱。三是缓存高频问答对于重复率高的固定问题直接返回缓存结果不走模型。这三招下来我的月度成本降了大概四成。注意max_tokens设得太小会导致回答被截断用户体验很差。我的经验是设 1024 到 2048 之间既能容纳大部分回答又不会失控。5.4 并发场景下的稳定性建议如果你的服务要面对较高并发有几个点必须注意。连接池要配够WebClient底层默认的连接池对高并发不够用需要显式配置ConnectionProvider的最大连接数和等待队列。限流要做用信号量或 Resilience4j 限制同时进行的模型请求数避免把配额打爆。监控要跟上记录每次请求的耗时、Token 消耗、成功率这些指标是发现问题的眼睛。我在压测时发现单实例在 100 并发下如果连接池只配了默认的 16 个连接请求会大量排队。把最大连接数调到 200 后吞吐量明显提升。但也不能无限调大因为模型服务端本身有限流调太大只会让请求在服务端排队反而增加超时概率。6. 从能跑到好用还差哪些工程化细节代码能跑通只是起点。真正上线前我补了几个工程化细节这里一并分享。日志脱敏。所有涉及请求体和响应体的日志都要过滤掉密钥和用户隐私内容。我写了一个LogSanitizer在打印前把敏感字段替换成***。这个习惯救过我一次——有次排查问题差点把带密钥的完整请求打到日志里。健康检查。加一个/health接口定期探测模型服务是否可达。这样负载均衡能及时摘除不健康的实例避免用户请求打到已经连不上模型的节点上。配置热更新。模型名称、超时时间这些参数最好支持不重启就生效。我用 Spring Cloud Config 或简单的配置中心实现了这一点调整参数不用重新发版运维效率高很多。接口版本管理。对话接口的请求体结构未来可能变我在 URL 里加了版本号比如/v1/chat这样老客户端不受影响新功能可以平滑上线。单元测试与集成测试。模型调用没法在单测里真发请求我用 MockWebServer 模拟响应覆盖正常返回、超时、错误码等各种分支。集成测试则用真实密钥跑少量用例确保端到端链路通畅。我个人在实际操作中的体会是这套东西的技术难度不在“调通接口”而在“稳定运行”。把超时、重试、降级、限流、监控这些看似琐碎的细节做扎实才是它能不能扛住真实流量的分水岭。最后再分享一个小技巧把每次对话的请求和响应脱敏后存一份到数据库出问题时可以完整回放排查效率比看日志高得多。这个内容后续还可以这样扩展——接入向量数据库做知识库检索增强让助手能回答你私有文档里的问题那就是另一个值得单独聊的话题了。
