Spring Boot接入DeepSeek这件事，我在项目里前前后后折腾了小两周，踩了不少文档里没写的坑。今天把我最终跑通的完整方案和排查思路整理出来，给同样在用Java做后端、想给系统接上大模型能力的同学一条可以直接走的路。这套东西不挑场景，无论是给内部系统做个AI助手，还是在毕业设计里加个智能对话模块，甚至是想把公司的老Spring Boot项目低成本地“AI化”，思路都是一样的。我会尽量讲清楚每个关键选择背后的原因，而不仅仅是贴代码。
1. 为什么是DeepSeek，为什么用Spring Boot来接
先说结论：DeepSeek是目前国内极少数API调用成本极低、效果又足够能打的大模型服务。它的接口采用OpenAI兼容格式，这意味着你过去积累的很多OpenAI调用经验、工具链，几乎可以无缝平移过来。更关键的是，DeepSeek的定价对个人开发者和中小企业非常友好，很多场景下可以放心地在生产环境里跑，而不只是“演示一下”。
那为什么强调用Spring Boot来接？我见过不少人图省事，直接在业务代码里用HttpClient拼URL、拼JSON，然后把API Key硬编码在类里面。这种写法在Demo阶段没什么问题，但一旦涉及多环境切换、并发控制、超时管理、日志审计，就会开始失控。Spring Boot的价值在这里就体现出来了：它天然提供了一套完整的依赖管理、配置中心、生命周期管理和监控体系，你可以把大模型接入当成一个普通的Spring Bean来管理，而不是一个孤立的第三方HTTP调用。
另外，从企业级应用的角度看，Java和Spring Boot的存量市场实在太大了。很多公司内部的CRM、ERP、工单系统都是Java技术栈，这些系统恰恰是最需要AI能力加持的——智能客服、知识库问答、数据报表解读。用Spring Boot接入DeepSeek，意味着可以直接在你现有的工程体系里长出一个AI能力模块，而不是另起炉灶搞一套Python服务再通过接口对接。
实际动手之前，我先说清楚架构上的选择。DeepSeek API本身是纯粹的HTTP REST接口，所以Spring Boot接入的核心就是两件事：构造请求、处理响应。这里Spring Boot的优势并不是它有什么魔法，而是它把HTTP客户端、JSON序列化、配置绑定、线程池管理这些东西都给你整理得明明白白。你可以聚焦在业务逻辑上，而不是纠结“该用哪种HTTP库”“JSON解析要不要多线程”。
2. 准备工作：API Key、工程骨架和合理的依赖结构
2.1 拿到API Key和模型名称
首先要去DeepSeek开放平台注册账号，创建API Key。这个Key要妥善保存，它相当于你调用模型的凭证。我建议把它配置在环境变量或者.yml配置文件里，不要硬编码在代码中，更不要提交到Git仓库。这一步很多人觉得“无所谓”，但我在实际项目中见过不止一次因为Key泄露导致账单异常的情况。
创建Key之后，需要确认你用的是哪个模型。DeepSeek的接口用model字段指定模型名，当前常用的对话模型是deepseek-chat。如果项目跑在下游应用上，还需要关注请求的base-url，默认是https://api.deepseek.com。这部分信息在平台文档里都有，但很多人会忽略一个问题：不同平台的API地址可能是不同的，如果你用的是第三方转发服务，base-url要记得改。
2.2 创建Spring Boot工程，别选太新的版本
创建工程我建议直接到Spring Initializr官网下载一个干净的骨架，或者用IDE内置的创建向导。这里有一个非常实际的建议：选Spring Boot版本时不要一味追新，选一个稳定版本就好。我见过有人用Spring Boot 3.5的测试版，结果和某个依赖不兼容，排查了很久。要是你不想在这上面花时间，用Spring Boot 2.7或者3.2这些已经发布很久、社区反馈充分的版本。JDK版本跟着Spring Boot的规范走就行。
工程创建时，依赖方面只要加一个Spring Web就够了。后面如果我们采用流式输出方案，还会用到WebFlux，但这可以后面按需添加，不必在一开始就加上。
2.3 HTTP客户端选型：我用的是RestTemplate，但需要注意的事情不少
Spring Boot里调用第三方HTTP接口，有RestTemplate、WebClient、OkHttp、HttpClient几种选择。如果你使用的是Spring Boot 2.x，RestTemplate是最顺手的选择；如果是Spring Boot 3.x，官方更推荐WebClient。我最终在项目里使用的是RestTemplate，原因有两个：一是API简单，同步调用思维很直白；二是搭配RestTemplate的拦截器机制，可以非常方便地统一注入API Key、打印日志，这些在接入DeepSeek时都是刚需。
不过RestTemplate有一个经典的问题：如果不显式设置底层连接工厂，它默认使用SimpleClientHttpRequestFactory，不支持连接池，也没有超时控制。这在高并发下会变成性能瓶颈。所以我在配置里明确设置了连接超时、读取超时，并且换成了HttpComponentsClientHttpRequestFactory，让底层走Apache HttpClient的连接池。这些细节在之后“踩坑”部分会展开讲，这里先记住结论。
2.4 配置文件设计：把变量抽到application.yml里
先看我的application.yml设计，这种写法能让你的接入代码保持干净，切换环境时只需要改配置文件：
deepseek: api-key: ${DEEPSEEK_API_KEY:sk-xxxx} base-url: https://api.deepseek.com model: deepseek-chat temperature: 0.7 max-tokens: 2048 timeout: connect: 5000 read: 60000把API相关的参数全部以deepseek.开头配置，用@ConfigurationProperties绑定到对应的配置类。这样后期不管是要切换模型、调整温度参数，还是重新设置超时，都不需要改动Java代码，运维同学也能轻松操作。
3. 核心请求链路：设计一个能扛住问题的服务类
3.1 理解DeepSeek的API调用格式
DeepSeek的/chat/completions接口，核心请求结构大致长这样：
{ "model": "deepseek-chat", "messages": [ {"role": "system", "content": "你是一个中文助手"}, {"role": "user", "content": "用一句话介绍你自己"} ], "temperature": 0.7, "max_tokens": 2048 }响应里最重要的字段是choices[0].message.content，这就是大模型生成的文本。messages是一个对话历史数组，system角色用来设定大模型的“人设”，user是用户输入。这个概念很像我们平时聊天时的对话语境：不只要把当前这句发给大模型，还需要把前面的对话关键内容都带上，模型才有上下文。
这里有个Java开发者最容易忽略的点：messages不是一次性发完就结束的。如果你要在项目里做多轮对话，每次请求都需要把之前的历史对话重新发一遍，因为API本身是无状态的。一个直观的方案是在内存里维护一个对话会话对象，保存该会话的message列表，每次调用时把整个列表传给服务端。
3.2 定义请求与响应的POJO
我不太喜欢在代码里拼JSON字符串，维护性太差。Java有强大的类型系统，正确的做法是定义请求和响应的POJO，用Jackson自动做序列化和反序列化。
对应的Java实体类大致长这样：
public class ChatRequest { private String model; private List<Message> messages = new ArrayList<>(); private Double temperature; private Integer maxTokens; private Boolean stream; // getter/setter 省略 } public class Message { private String role; private String content; // getter/setter 省略 } public class ChatResponse { private List<Choice> choices; private Usage usage; // 内部类略 }有一点需要说明：stream字段很重要，后面讲流式输出时要用到。如果stream设为true，响应就不是一个完整的JSON对象，而是连续的多行JSON数据，每行代表一个增量片段。
3.3 核心Service实现：一个支持普通模式和流式模式的Service
下面是一个典型的Service代码，注意异常的封装和参数的传递：
@Service public class DeepSeekService { private final RestTemplate restTemplate; private final DeepSeekProperties properties; public DeepSeekService(RestTemplate restTemplate, DeepSeekProperties properties) { this.restTemplate = restTemplate; this.properties = properties; } public String chat(String userMessage, String systemPrompt) { List<Message> messages = new ArrayList<>(); if (StringUtils.hasText(systemPrompt)) { messages.add(new Message("system", systemPrompt)); } messages.add(new Message("user", userMessage)); ChatRequest request = new ChatRequest(); request.setModel(properties.getModel()); request.setMessages(messages); request.setTemperature(properties.getTemperature()); request.setMaxTokens(properties.getMaxTokens()); request.setStream(false); String url = properties.getBaseUrl() + "/chat/completions"; ChatResponse response = restTemplate.postForObject(url, request, ChatResponse.class); if (response != null && response.getChoices() != null && !response.getChoices().isEmpty()) { return response.getChoices().get(0).getMessage().getContent(); } throw new RuntimeException("DeepSeek API返回结果为空"); } }注意这里我把API Key放在了RestTemplate的拦截器里，而不是在Service里手工添加Header。这是两者的混编方案里常见的工程化处理，后面统一说明。
3.4 RestTemplate注入API Key与统一日志
RestTemplate支持通过ClientHttpRequestInterceptor对所有请求进行统一拦截处理。我一个很自然的想法是在里面加Header：
public class DeepSeekAuthInterceptor implements ClientHttpRequestInterceptor { private final String apiKey; public DeepSeekAuthInterceptor(String apiKey) { this.apiKey = apiKey; } @Override public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException { request.getHeaders().setBearerAuth(apiKey); request.getHeaders().setContentType(MediaType.APPLICATION_JSON); return execution.execute(request, body); } }这样Service的代码就非常清爽，不用在每次请求的地方手动添加Header。同时你可以在拦截器里加请求耗时日志，方便监控线上调用情况。
4. 流式输出：把“打字机”效果原样搬到Spring Boot中
4.1 为什么必须支持流式输出
如果你只是做一个“问一句答一句”的后台接口，非流式就够了。但如果你要做聊天机器人、AI写作助手、报表解读这类需要“边生成边显示”的场景，流式输出是必须的。原因是DeepSeek生成内容需要时间，一个完整回答可能需要几十秒，如果用户要等所有内容生成完才能看到结果，体验会非常差。而流式输出能让用户在模型生成第一个字时就立刻看到内容，效果很像ChatGPT那种“打字机”效果。
4.2 写一个带自动累加的SSE读法
API的stream参数设为true之后，服务端不再返回完整JSON，而是返回一段段data:开头的事件流。逐行解析时，每一行都是一个独立的JSON片段，最终回答文本来自所有delta.content的拼合。
Spring Boot接收外部流式响应，最简单的做法是用一个ResponseExtractor去读取响应体流。这里我不直接推荐复杂的WebFlux，先给你看一个走RestTemplate就能实现流式输出的方法：
public void chatStream(String userMessage, String systemPrompt, Consumer<String> onDelta) { // 构造request时将stream置为true request.setStream(true); // 利用RestTemplate的execute方法与ResponseExtractor，逐行读取流 String url = properties.getBaseUrl() + "/chat/completions"; restTemplate.execute(url, HttpMethod.POST, requestEntity -> { // 可以在这里对requestEntity再补充header }, response -> { BufferedReader reader = new BufferedReader(new InputStreamReader(response.getBody(), StandardCharsets.UTF_8)); String line; while ((line = reader.readLine()) != null) { if (line.startsWith("data:")) { String data = line.substring(5).trim(); if ("[DONE]".equals(data)) { break; } // 解析data中的JSON片段，取出delta.content JsonNode node = objectMapper.readTree(data); String delta = node.path("choices").path(0).path("delta").path("content").asText(null); if (delta != null) { onDelta.accept(delta); } } } return null; }); }这里有几个实战要点需要特别注意：
- 必须显式设置二进制内容类型：由于这是一个流式响应，不能直接按对象反序列化，所以要用
ResponseExtractor来读。如果你在请求头里错误地设置了Accept不能接受text/event-stream，服务端可能拒绝返回。 - 字符集问题：
BufferedReader一定要指定UTF-8，否则中文会出现乱码。 - 超时时间：流式输出时读取超时不能设置得太短。我设置的是60秒。如果回答很长，适当调大这个值，或者改用无超时连接，但对生产环境来说，更推荐合理设置+心跳机制。
4.3 如果使用Spring WebFlux做接口转发
有一类需求是：你自己的Spring Boot项目作为中间层，前端调用你的接口，你再去调用DeepSeek。这种情况下，一个很好的方案是让你的接口也返回Flux<String>，通过WebFlux把流式响应直接“串”给前端。
使用WebFlux后，代码会变得更自然：
@PostMapping(value = "/chat-stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<String> chatStream(@RequestBody ChatStreamRequest chatStreamRequest) { return webClient.post() .uri("/chat/completions") .bodyValue(buildRequest(chatStreamRequest)) .retrieve() .bodyToFlux(String.class) .map(this::extractDeltaContent) .filter(Objects::nonNull); }但注意，引入WebFlux意味着Spring MVC和WebFlux不能共存于同一个应用里。如果你的项目里已经有很多基于Spring MVC的Controller，那要慎重使用WebFlux方案，否则会出现路由冲突。这一点是实际项目中最容易踩的坑。
4.4 前端如何配合
最省事的前端方案是使用fetch配合ReadableStream逐段读取响应，把收到的数据块实时插入DOM中，不需要引入额外的SDK。这里不展开前端代码，但需要提醒：如果你是在浏览器里直接调用你的Spring Boot接口，要处理好CORS跨域配置；如果你是在小程序或App里调用，则要确保网络层能正常接收流式数据。
5. 生产环境必须处理的五个高频问题
到了这个阶段，你已经能从Spring Boot里调通DeepSeek了。但真正在生产环境运行，下面这些坑几乎个个都会遇到，我先把我踩过的和排查过的分享出来。
5.1 超时设置：非流式和流式完全不一样
非流式请求的温度参数和生成长度会影响响应时间，一个较长回答可能超过30秒。如果你按默认的RestTemplate走，连接超时和读取超时都是几秒钟，肯定会“Read timed out”。我当时的做法是把连接超时设为5秒，读取超时设为60秒。流式请求则更灵活一些，因为是边读边显示，读取超时可以设置得更大，比如120秒。这里的关键是：不要把所有请求都用一个超时值，最好针对不同接口分别定义。
5.2 API错误处理：401、402、429分别怎么答
DeepSeek API会返回标准的HTTP状态码。401通常是API Key无效；402是余额不足；429是请求过于频繁，触发了限频。我在Service里统一捕获HttpClientErrorException，根据状态码转换为业务异常，并记录详细日志。
实际项目中，429是最需要关心的。如果你在业务里做了批量处理或用户并发较高，很容易触发限流。解决方案是加一个简单的重试机制：遇到429时等待一段时间再重试，或者引入一个简单的令牌桶限流器，把自己的请求频率控制在一个安全范围内。Spring Retry可以帮上忙，但需要你自行判断哪些异常值得重试。我实现的是一套带最大重试次数的指数退避策略，效果很稳。
5.3 上下文长度与费用控制
DeepSeek的max_tokens参数既控制了回答长度，也直接和费用挂钩。很多开发者想都不想就设置成4096或8192，这会带来两个问题：一是费用上升，二是超出模型最大上下文限制导致报错。
更经济的做法是维护一个消息队列，只发送最近的N条消息作为上下文。比如每次请求只保留最近的10条对话记录，超出部分丢弃。这不仅能控制支出，也能保证模型不会因为上下文过长而降低回复质量。还可以在请求前用tiktoken之类的工具预估token数量，超过阈值时自动裁剪。
5.4 并发控制：别让大模型接口打爆你的后端线程池
RestTemplate是同步阻塞模型，一次调用会占用一个Tomcat工作线程。如果用户在界面上频繁提问，每次都要等几十秒，线程池很快会被占满，最终导致整个应用的其它接口也响应缓慢。因此生产环境里，最好对DeepSeek的调用做并发隔离：独立配置一个专用的线程池，限制最大并发数。超出并发上限的请求进入队列排队，或者快速失败给用户一个“系统繁忙”的提示。
5.5 日志与审计：记录必要的信息，但别把敏感内容打进日志
接入大模型后，日志中会包含用户输入和模型输出。从合规角度讲，你需要记录调用行为、耗时、结果状态，但不要把含有个人隐私信息的内容原样打印出来。我采用的方案是：打印请求摘要，比如用户的会话ID、请求长度、token用量，不打印完整的正文内容。审计日志单独存储，需要排查问题时再通过会话ID反查。
6. 模块化与再封装：从“能用”到“好用”
到这里，你已经有了一个能稳定运行的DeepSeek接入服务。但如果只是把代码堆在Controller里，后续维护会非常痛苦。我最后再做了一次重构，把大模型能力封装成一个可复用的模块，这里分享几个我觉得最有价值的改进方向。
6.1 把Service拆成“会话管理”和“模型调用”两层
模型调用层只负责和DeepSeek API交互，接受标准化的请求参数，返回结果。会话管理层则负责维护每个用户的对话历史、清理过期会话。拆成两层的好处是：如果你以后想换别的模型，只需替换模型调用层，而不会影响会话层。
6.2 接入Spring Cache做缓存
DeepSeek的API是按token计费的，重复请求相同的问答是一种浪费。我遇到一个场景：很多用户会问类似的问题，比如“怎么重置密码”“怎么导出报表”。对于这类高频问题和固定回答，可以在Service前面加一层缓存，用用户问题的哈希作为Key。详细信息可以通过Redis实现分布式缓存。这样既能节省费用，又能降低响应时间。
6.3 设计一个可插拔的Provider接口
如果你有“国产模型替换”“多模型融合”的需求，建议定义一个ChatProvider接口，对外暴露统一的chat和chatStream方法。DeepSeek、通义千问、文心一言各自实现这个接口，通过Spring的@ConditionalOnProperty注解，在配置文件中切换模型供应商，代码完全不用改动。这种设计的价值不仅在当前的DeepSeek接入，更在于你能在未来的AI模型迭代中随时切换或增加供应商，而不需要推倒重来。
7. 一些更接地气的建议
最后再补充几条我在这个项目里沉淀下来的经验，不一定写进文档，但对实际项目很有用。
环境变量管理API Key这件事，建议不仅在本地开发时用.env文件配合IDEA读取，在服务器上也要通过K8s Secret或配置中心统一托管，不要在启动命令里明文传参。
压测时别只看“能不能通”，要看“并发到多少开始超时”和“线程池占满后整个应用的反应”。我用JMeter跑过一轮，发现随着并发请求数上升，首字符返回时间会明显变长。这个指标对聊天类应用非常重要，因为流式输出的核心体验就是“尽快看到第一个字”。
如果你是在给老项目接DeepSeek，不要一上来就改大结构，可以先在工程里独立建一个ai包，把DeepSeek相关代码全部放进去，通过接口对外暴露能力。这样即使出了问题，可以直接关掉开关，不影响原有业务。
有一点要特别提醒：不要下流传入各种“绕过限制”的所谓提示词模板。正常的业务场景里，合规使用模型的能力已经足够解决绝大多数问题，越是追求“破解”越容易给自己找麻烦，而且可能让你的API Key被风控限制，得不偿失。
接入DeepSeek只是第一步，真正有价值的是你如何设计Prompt、如何管理对话状态、如何评估回答质量。这些工程化的工作，远比单纯把接口调通更影响最终效果。希望这篇内容能帮你把路铺平，省下我当初踩坑的时间。
