1. 为什么要在 Spring Boot 里自己接 OpenAI而不是直接调现成 SDK很多 Java 后端同学第一次接触大模型集成第一反应是去找一个封装好的 starter加个依赖、配个 key 就完事。我一开始也这么干结果踩了两个坑一是某些封装库版本迭代太快Spring Boot 2.6.x 和 2.3.x 的自动装配行为不一致升级一次就报NoSuchMethodError二是业务方要求对请求做细粒度的超时控制、重试策略和 token 统计封装层把RestTemplate或WebClient藏得太深改起来反而更费劲。所以后来我倾向于一个更朴素的做法用 Spring Boot 原生的 HTTP 客户端能力直接对接 OpenAI 的 Chat Completions 接口。这样做的好处很实在——依赖少、可控性强、出问题能一眼定位到是哪一层。你不需要引入spring-ai那一整套抽象也不用担心它和你的 Spring Boot 版本打架。当然如果你的项目已经在用 Spring AI 或者 Spring AI Alibaba那另说本文的重点是从零搭建把底层链路讲透。这篇文章适合谁看如果你会写 Spring Boot 的 Controller 和 Service知道RestController和ConfigurationProperties怎么用但对怎么把大模型对话能力接进自己的 Java 服务还没头绪那这篇就是给你准备的。我会从依赖选型、配置管理、请求封装、流式响应、异常处理一路讲到上线前要注意的坑代码都能直接抄。先明确一个核心概念OpenAI 的对话接口本质就是一个HTTPS POST 请求请求体是 JSON响应体也是 JSON。所谓集成无非是把 HTTP 调用包装成一个 Spring 的 Service把 API Key 管好把异常兜住把并发和超时控制住。想通这一点后面所有事情都顺了。2. 环境准备与依赖选型别一上来就堆框架2.1 Spring Boot 版本与 JDK 的取舍我实测下来Spring Boot 2.7.x 配 JDK 17是目前最稳的组合。为什么不是 3.x因为 Spring Boot 3.x 强制要求 JDK 17 起步而且把javax.*换成了jakarta.*如果你项目里还有老版本的第三方库没适配迁移成本不小。而 2.7.x 是 2.x 的最后一个大版本社区支持成熟JDK 8 到 17 都能跑。如果你是新项目、没有历史包袱直接上 Spring Boot 3.2.x JDK 21 也没问题本文的代码在两者上都能跑唯一要注意的是WebClient的依赖坐标在 3.x 里没变但spring-boot-starter-webflux的版本要跟着父 POM 走。至于热词里提到的spring boot 2.3.x 2.6.x我的建议是2.3.x 太老了WebClient的很多便利方法还没有2.6.x 可以用但要注意spring.mvc.pathmatch.matching-strategy默认值变了如果你同时用了 Swagger可能会遇到路径匹配报错加一行配置改成ant_path_matcher就行。2.2 用 RestTemplate 还是 WebClient这是第一个要做的技术决策我列个表对比一下维度RestTemplateWebClient编程模型同步阻塞同步/异步/流式流式响应支持不支持原生支持依赖spring-boot-starter-webspring-boot-starter-webflux学习成本低中等适用场景简单问答、后台任务打字机效果、高并发结论很明确只要你的对话服务需要打字机式的流式输出就必须用 WebClient。因为 OpenAI 的流式接口返回的是text/event-streamRestTemplate 拿到的是完整响应做不了逐字推送。而 WebClient 的bodyToFlux(String.class)可以一行行消费。如果你只是做后台批处理、不需要实时推给前端那 RestTemplate 更简单。但考虑到AI 对话服务这个场景流式几乎是标配所以我下面以 WebClient 为主线RestTemplate 的写法在需要的地方会补充。依赖就两个dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId /dependency注意同时引入 web 和 webflux 时Spring Boot 默认还是以 Servlet 容器Tomcat启动WebClient 可以正常用不会冲突。这一点很多人担心实测没问题。2.3 API Key 的获取与配置管理API Key 的获取流程这里不展开简单说就是登录 OpenAI 平台在 API Keys 页面创建一个格式是sk-开头的一长串。创建后只显示一次务必立刻保存这是新手最容易犯的错。配置管理上绝对不要把 key 硬编码在代码里也不建议直接写在application.yml里提交到 Git。我的做法是分三层本地开发用环境变量OPENAI_API_KEY在 IDE 的运行配置里设置。测试/生产用配置中心或容器编排的 Secret 注入。代码里通过Value(${openai.api-key})或ConfigurationProperties读取。openai: api-key: ${OPENAI_API_KEY:} base-url: https://api.openai.com/v1 model: gpt-4o-mini connect-timeout: 5000 read-timeout: 60000这里base-url单独抽出来是有讲究的——方便你切换到兼容 OpenAI 协议的其他服务端点或者做本地 mock 测试。read-timeout给到 60 秒是因为大模型生成一段长回复确实可能超过 30 秒设太短会频繁超时。3. 请求封装把 Chat Completions 接口吃透3.1 请求体结构逐字段拆解OpenAI 的/v1/chat/completions接口请求体核心就几个字段我用一个 Java 的 recordJDK 17或普通类来映射public record ChatRequest( String model, ListMessage messages, Double temperature, Integer max_tokens, Boolean stream ) { public record Message(String role, String content) {} }逐个说清楚model模型名比如gpt-4o-mini、gpt-4o。选哪个我的经验是日常对话、成本敏感的场景用gpt-4o-mini足够它的响应速度和价格都很友好需要复杂推理、代码生成再上gpt-4o。messages消息数组每条有role和content。role有三个值system设定人设和规则、user用户输入、assistant模型的历史回复。多轮对话的关键就是把历史消息按顺序拼进去模型本身是无状态的它不记得上一句说了什么全靠你把上下文带过去。temperature0 到 2 之间控制随机性。写代码、做客服问答建议 0.2 到 0.5创意写作可以到 0.8 以上。默认 1.0 有时候会太放飞。max_tokens限制回复长度。注意这是输出的 token 上限不是输入。设太小会导致回复被截断设太大浪费额度。一般对话 1024 够用。stream是否流式返回布尔值。这里有个容易忽略的点messages 的总 token 数是有上限的不同模型上限不同。如果你做多轮对话历史消息越堆越长迟早会超。所以必须做上下文裁剪这个后面第 5 节细讲。3.2 用 WebClient 发起非流式请求先看最简单的非流式调用适合后台任务Service public class ChatService { private final WebClient webClient; private final OpenAiProperties props; public ChatService(WebClient.Builder builder, OpenAiProperties props) { this.props props; this.webClient builder .baseUrl(props.getBaseUrl()) .defaultHeader(HttpHeaders.AUTHORIZATION, Bearer props.getApiKey()) .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE) .build(); } public String chat(String userInput) { ChatRequest request new ChatRequest( props.getModel(), List.of(new ChatRequest.Message(user, userInput)), 0.7, 1024, false ); ChatResponse response webClient.post() .uri(/chat/completions) .bodyValue(request) .retrieve() .bodyToMono(ChatResponse.class) .block(Duration.ofSeconds(60)); return response.choices().get(0).message().content(); } }响应体的结构也要映射好核心是choices[0].message.content另外usage字段里有prompt_tokens、completion_tokens、total_tokens做成本统计时非常有用建议一并解析出来存日志。3.3 流式响应SSE 逐字推送的实现流式才是对话服务的灵魂。OpenAI 的流式返回是一行行data: {...}的 SSE 格式最后以data: [DONE]结束。WebClient 的处理方式public FluxString chatStream(String userInput) { ChatRequest request new ChatRequest( props.getModel(), List.of(new ChatRequest.Message(user, userInput)), 0.7, 1024, true ); return webClient.post() .uri(/chat/completions) .bodyValue(request) .retrieve() .bodyToFlux(String.class) .filter(line - line.startsWith(data: )) .map(line - line.substring(6)) .takeUntil([DONE]::equals) .filter(json - ![DONE].equals(json)) .map(this::extractContent) .filter(s - !s.isEmpty()); }extractContent就是把每个 chunk 的 JSON 解析出choices[0].delta.content。注意流式返回里字段叫delta而不是message这是新手最容易搞混的地方。然后在 Controller 里用text/event-stream推给前端GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString stream(RequestParam String q) { return chatService.chatStream(q); }前端用EventSource或fetch的流式读取就能实现打字机效果。这里有个坑如果你前面挂了 Nginx必须关闭该路径的缓冲加proxy_buffering off;否则前端会等所有内容生成完才一次性收到流式就白做了。4. 多轮对话与上下文管理模型没有记忆你得替它记4.1 会话状态存哪里模型是无状态的多轮对话的本质是每次请求都把历史消息带上。那历史消息存哪三种方案前端存每次请求把完整历史发给后端。优点是后端无状态、易扩展缺点是请求体越来越大且容易被篡改。后端内存存用ConcurrentHashMapString, ListMessage按 sessionId 存。简单但重启就丢多实例部署不共享。Redis 存生产环境推荐。按 sessionId 存一个 List设置过期时间比如 30 分钟天然支持多实例。我一般用 Rediskey 设计成chat:session:{sessionId}value 用 JSON 序列化的消息列表。每次请求先读历史追加用户消息调用模型再把模型回复追加进去写回。4.2 上下文裁剪的三种策略历史越堆越长token 迟早爆。裁剪策略我试过三种滑动窗口只保留最近 N 轮。简单粗暴但会丢失早期的重要设定。保留 system 最近 N 轮system 消息永远保留人设不能丢user/assistant 只留最近几轮。这是我最常用的。摘要压缩把早期对话让模型总结成一段话替换掉原始消息。效果好但多一次调用成本和延迟都上去了。实际项目里我通常用策略 2N 取 10 轮左右。同时用一个粗略的估算中文大约 1 个字 1 到 2 个 token英文大约 4 个字符 1 个 token据此判断是否要裁剪。精确计算可以用对应的 tokenizer但引入额外依赖粗略估算对大多数场景够用。4.3 system 提示词的设计心得system 消息决定了模型的人设写得好不好直接决定服务质量。我的经验是明确角色你是一个专业的电商客服助手比你是一个助手效果好得多。给出边界如果用户问的问题超出你的知识范围请如实说明并建议联系人工客服能有效减少胡编。规定格式如果需要结构化输出在 system 里写清楚请以 JSON 格式返回包含 field1 和 field2 两个字段。别写太长system 提示词也占 token而且过长的规则模型未必都记得住抓重点。一个实测有效的模板你是{产品名}的智能助手负责回答用户关于产品功能和使用方法的问题。 回答要求 1. 简洁准确单次回复不超过 200 字 2. 不确定的信息不要编造引导用户联系人工客服 3. 语气友好专业不使用夸张表达5. 异常处理与稳定性上线前必须堵住的窟窿5.1 OpenAI 常见错误码与应对调用外部接口异常处理是重头戏。我把常见的错误码和应对策略整理成表HTTP 状态码含义应对策略401API Key 无效检查配置不重试429请求频率超限指数退避重试500/502/503服务端错误有限次重试400请求体有问题检查参数不重试超时网络或生成过慢重试或降级关键原则4xx 类错误重试没意义5xx 和超时才值得重试。重试要用指数退避比如第一次等 1 秒第二次 2 秒第三次 4 秒避免雪崩。5.2 超时与重试的代码落地WebClient 的超时配置要分连接超时和读取超时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();重试可以用 Reactor 的retryWhen.retrieve() .bodyToMono(ChatResponse.class) .retryWhen(Retry.backoff(3, Duration.ofSeconds(1)) .filter(e - e instanceof WebClientResponseException.TooManyRequests || e instanceof WebClientResponseException.ServiceUnavailable))注意filter里只对 429 和 503 重试其他异常直接抛出。流式请求不要轻易重试因为已经推给前端的内容没法撤回重试会导致内容重复。5.3 降级方案模型挂了怎么办生产环境一定要有降级。我的做法是主模型调用失败超过阈值后切到备用模型比如从gpt-4o降到gpt-4o-mini再失败就返回一个预设的兜底话术比如当前服务繁忙请稍后再试。用 Resilience4j 的 CircuitBreaker 可以很优雅地实现但即使手写一个计数器也能应付。另外API Key 要支持热更新。如果 key 泄露需要紧急更换总不能重启服务。可以把 key 放在配置中心监听变更事件重建 WebClient。6. 实测中的性能与成本优化6.1 连接池与并发控制WebClient 底层用的是 Reactor Netty默认连接池大小是 CPU 核数乘以 2。如果你的服务并发量高这个值可能不够会出现请求排队。可以通过ConnectionProvider调整ConnectionProvider provider ConnectionProvider.builder(openai-pool) .maxConnections(200) .pendingAcquireTimeout(Duration.ofSeconds(10)) .build();但要注意连接数不是越大越好OpenAI 那边对你的账号有速率限制RPM 和 TPM连接开太多反而更容易触发 429。合理做法是配合本地限流用RateLimiter控制每秒请求数。6.2 token 成本的可观测性成本控制的前提是能看见。我建议在每次调用后记录一条日志包含sessionId、模型名、prompt_tokens、completion_tokens、耗时、是否成功。这些数据攒起来用 Grafana 或简单的报表就能看出哪个功能最烧钱。一个实测数据供参考gpt-4o-mini处理一次普通问答输入 200 token、输出 300 token成本在千分之几美分级别一天一万次调用也就几美元。但如果用gpt-4o成本会高一个数量级。所以能用小模型解决的场景坚决不用大模型。6.3 缓存能省下的钱有些问题是重复的比如你们的退货政策是什么。这类高频问题完全可以做缓存把用户问题做归一化去空格、转小写后作为 key模型回复作为 value存 Redis设置合理过期时间。命中缓存直接返回既省钱又快。但要注意多轮对话场景下缓存要谨慎因为同样的用户输入在不同上下文里答案可能不同。我的做法是只对单轮、无历史的请求启用缓存。7. 几个我踩过的坑和对应解法第一个坑流式响应中文乱码。原因是 WebClient 默认按字节流处理如果没指定字符集中文可能被拆成半个字符。解法是在bodyToFlux(String.class)之前确保响应头Content-Type带charsetutf-8或者手动用DataBufferUtils按行切分并指定 UTF-8 解码。第二个坑ConfigurationProperties不生效。检查两点类上有没有加Component或通过EnableConfigurationProperties注册setter 方法是否齐全用 record 的话要确认 Spring Boot 版本支持构造绑定。我遇到过因为字段名是apiKey而配置写的是api-keyrelaxed binding 本该处理但因为少了 setter 导致绑定失败。第三个坑Nginx 缓冲导致流式失效。前面提过再强调一次proxy_buffering off和proxy_cache off都要加X-Accel-Buffering: no响应头也建议带上。第四个坑多实例部署时内存存会话导致串话。用户第一次请求打到实例 A第二次打到实例 B历史就丢了。所以会话状态必须外置到 Redis这是多实例部署的硬性要求。第五个坑忘记处理[DONE]标记。流式返回的最后一行是data: [DONE]如果不过滤掉解析 JSON 时会抛异常。用takeUntil提前终止流是最干净的做法。8. 从能跑到好用还差哪些工程化细节把对话跑通只是第一步真正上线还要补几块接口鉴权你的对话接口不能裸奔必须校验用户身份否则会被刷。用 Spring Security 加个 JWT 过滤器是标配。输入长度限制用户可能粘贴一篇长文进来直接超 token 上限。在 Controller 层就要限制输入字符数超了直接返回友好提示。敏感内容过滤用户输入和模型输出都要过一遍敏感词过滤这是合规底线。可以用现成的词库也可以接内容审核接口。日志脱敏对话内容可能包含用户隐私日志里不要全量打印或者做脱敏处理。灰度与开关新模型上线先灰度一部分用户出问题能一键切回。用一个配置开关控制走哪个模型比改代码重新发布快得多。监控告警错误率、平均耗时、token 消耗量都要有监控超过阈值告警。特别是 429 错误率一旦飙升说明要么该扩容要么该限流。我个人在实际操作中的体会是集成大模型这件事技术难度不在调用本身而在工程细节的把控。接口就那一个参数就那几个但要把超时、重试、降级、缓存、限流、监控、安全这些周边都做扎实才敢说这是一个能上生产的服务。很多团队 demo 跑得飞快一上量就各种问题根子都在这些不起眼的地方。最后分享一个小技巧本地开发时如果不想每次都真实调用消耗额度可以写一个 mock 的ChatService实现用Profile(local)激活返回固定话术。这样调试前端和联调时既快又省钱等真正需要验证模型效果时再切回真实实现。这个模式在团队协作里特别有用前端同学不用等后端配好 key 就能开工。