Spring Boot 集成 DeepSeek：从基础调用到流式与上下文管理

最近好几个开发群都在问同一个问题：Spring Boot 项目里怎么把 DeepSeek 的 API 接进来。这个问题表面看很简单，DeepSeek 的接口走的又是 OpenAI 兼容格式，拿 HttpURLConnection 硬调也能通，但真正落到工程里，你会遇到模型怎么选、参数怎么配、流式怎么接、超长上下文怎么处理、接口超时与限流怎么兜底这一连串问题。这篇文章不是贴一段代码就完事，而是把从零搭一个可用调用工程的全过程、踩过的坑和最终沉淀下来的方案，完整拆给你看。适合准备把 DeepSeek 接入业务系统、想做 AI 功能集成，或者对 Spring Boot 调用第三方 API 感兴趣的同学，看完可以直接照搬，而且能明白每一步为什么要这么做。

1. 整条调用链路的设计：为什么用 Spring Boot 来封装 DeepSeek API

1.1 这组技术组合到底能解决什么问题

把 DeepSeek 的接口接到业务系统，需求往往不是什么“我要跑一个 AI 程序”，而是更务实的场景：内部工单系统要接入智能摘要，客服后台要做一个问答助手，运营平台要批量生成文案，或者是给现有的 Java 老系统加一个“AI 能力层”。这些场景下，你不可能让业务方自己去拼 HTTP 请求、管 API Key、处理重试和异常，必须有一个独立的服务模块把这些琐碎事情全部封装好，对外暴露一个清晰的 REST 接口，让上游系统像调用普通后端服务一样调用 AI 能力。

Spring Boot 在这里的位置就是“胶水层”。它的核心职责有三个：一是把 DeepSeek API 的调用细节全部收敛在内部，包括鉴权、超时、重试、日志；二是把请求和响应映射成 Java 对象，让业务代码不再跟 JSON 字符串打交道；三是把 AI 能力以 REST 接口、消息队列消费者或者定时任务的形式输出，方便其他系统集成。换句话说，DeepSeek 是大脑，Spring Boot 是连接大脑和业务系统的那套神经系统。

1.2 方案选型的几个关键取舍

先说为什么选 DeepSeek 而不是其他大模型。很多团队在做内部功能时根本不需要那么复杂的模型管理平台，DeepSeek 的 API 价格合理，兼容 OpenAI 协议，Java 社区里现成的 SDK 和资料又多，接入成本很低。更重要的是，它的上下文窗口做得比较大，对“把业务文档塞进提示词里让模型总结”这类常见需求非常友好，不用总是想着做复杂的外部知识库方案。

再说为什么用 Spring Boot 而不是直接用 Python 脚本。团队技术栈是 Java，服务要部署在现有的 Spring Cloud 体系里，要做鉴权、限流、监控，要跟公司内部的统一配置中心、日志平台打通，这种情况下 Python 脚本很难融入基础设施。Spring Boot 本身对 HTTP 调用、JSON 序列化、线程池、链路追踪的支持都很成熟，写出来的东西好维护，招人也容易。这个选择基本没什么可犹豫的。

还有一个细节取舍：调用 DeepSeek API 的 HTTP 客户端到底用 RestTemplate、RestClient 还是 WebClient。老项目里大量用的是 RestTemplate，但它已经进入维护模式，功能也偏老。Spring Boot 3.2 之后官方推荐的是 RestClient，API 设计简洁，同步调用时体验很好。WebClient 则适合流式输出和异步场景，底层基于 Reactor，可以优雅地消费 SSE 流。我的建议是同步调用主用 RestClient，需要接流式输出时切换到 WebClient，两者可以共存，不用非此即彼。

1.3 链路设计与目录规范

整条链路的调用顺序是这样的：外部请求进来，先经过 Controller 层做参数校验，然后交给 Service 层组装消息列表，Service 层调用封装好的 DeepSeek Client，DeepSeek Client 负责拼接请求、加鉴权头、发起 HTTP 调用、处理异常和重试、解析响应，最后把结果一层层返回。这个链路里最关键的是隔离：DeepSeek 相关的所有细节都收在 client 层和 config 层，业务 Service 只依赖一个简单的 ChatResponse 对象，这样以后如果换模型服务商，改动范围可以控制得很小。

目录结构我一般推荐这种分层方式：

com.example.deepseekdemo ├── config # 配置类：WebClient、RestClient、属性绑定 ├── controller # 对外 REST 接口 ├── service # 业务逻辑：组装消息、调用、后处理 ├── client # DeepSeek API 封装：请求、响应模型、错误处理 ├── dto # 请求/响应 DTO ├── common # 常量、异常、工具类 └── properties # 配置属性绑定类

很多应届生或者刚转 Java 的同学喜欢把所有类都堆在几个包里，这在小 demo 里问题不大，但项目一旦开始迭代，包结构混乱会让“找类”变成一件很痛苦的事。上面这套结构不是银弹，但按“配置、接口、业务、客户端、模型”分层以后，哪怕是后来接手的人，也能一眼看出某个功能应该改哪个位置。

2. 动手前的准备：API Key、模型选型与参数细节

2.1 API Key 的正确获取和安全存放方式

调用 DeepSeek API 第一步是去开放平台创建 API Key。这一步本身没什么难度，但 Key 的保管方式却是很多项目翻车的重灾区。我见过有人把 API Key 直接写在 application.yml 里提交到 Git 仓库，结果在内网代码扫描时被安全团队点名；也见过 Key 写在前端代码里，等于把账号免费开放给全网。

正确的做法是把 Key 放到环境变量或者配置中心里，代码仓库里只保留占位符。比如在 application.yml 中这样写：

deepseek: api-key: ${DEEPSEEK_API_KEY}

然后在本机启动服务时通过环境变量注入，在服务器上通过公司的配置中心或密钥管理系统注入。Spring Boot 对这类占位符解析是原生支持的，不需要额外写代码。另外，如果公司有多个环境，建议每个环境用独立的 Key，这样即便测试环境的 Key 泄露了，生产环境也不受影响。

还有一个容易忽略的点：DeepSeek 的请求头认证方式是Authorization: Bearer <你的Key>，注意 Bearer 后面有个空格，拼错了会一直报 401。很多人排查半天发现是字符串拼接少了空格，这类低级错误最好在封装 client 的时候就固化成代码逻辑，避免每次调用都手拼。

2.2 模型选型：chat 模型、reasoner 模型与 v4 系列

DeepSeek 开放平台目前可选的模型按用途分大致有两类。一类是通用对话模型，日常问答、文本生成、内容总结都走它，响应速度快，价格便宜；另一类是推理增强模型，适合数学推导、逻辑分析、复杂代码生成这类需要深度思考的任务，它会在回答前先内部生成一段推理过程，所以响应时间更长，对参数调整也更敏感。

最近官方开放的 v4 系列模型把上下文窗口拉到了百万级 token，像deepseek-v4-pro、deepseek-v4-flash这类模型名，分别对应更强的推理能力和更快的响应速度。实际选型的时候不要无脑上最大的模型，而是先想清楚场景：如果是高并发的文本分类、信息抽取，选响应快的模型就够了；如果是要做论文阅读、复杂业务规则推断，再上推理型模型。模型名配置在deepseek.model里，切换成本很低，建议放到配置项里而不是写死在代码中。

关于 deepseek-reasoner 这类推理模型，有一个经验要提醒：temperature 参数建议固定在一个合理的值附近，不要随便调高。因为推理模型本身已经在内部做了大量探索，你再把随机性拉满，反而容易得到不稳定的答案。通用对话模型则可以按场景调整 temperature，创意写作调高一点，数据抽取调低一点。

2.3 必须搞清楚的请求参数（附参数速查表）

请求体里的参数看起来不多，但每个都影响最终效果。messages 是消息列表，每一条消息有 role 和 content 两个字段，role 可以是 system、user、assistant。system 消息用来设定模型的角色和行为边界，比如“你是一个严谨的客服助手”，user 是用户输入，assistant 是历史回复。很多人在多轮对话里忘了把历史 assistant 消息传回去，导致模型每次都是“失忆”状态，体验很差。

max_tokens 控制的是单次回复最多生成的 token 数，不是上下文总长度，这两个概念特别容易混淆。比如上下文窗口是 1048576 tokens，但 max_tokens 设 100，模型就只能回复一个很短的答案。temperature 控制随机性，top_p 是核采样概率，两者效果有重叠，一般建议固定其中一个来调，不要同时大幅度调整。

下面是一份常用的参数速查表，方便对照配置：

这套参数如果只是自己调试，怎么配都行，但一旦做成产品功能，就必须把参数配置收口到配置文件里，由后端统一管控，不要让上游调用方随便传。原因很简单：不同业务对随机性、回复长度的要求不一样，如果每个调用方都能随意传参，最终模型输出质量会变得不可控，出了问题也很难排查是谁改的。

3. Spring Boot 实操：从 Maven 工程到一次完整调用

3.1 Maven 工程结构、依赖与构建配置

创建一个标准的 Spring Boot 工程，我习惯用 Maven 方式，因为公司内部的项目基本都以 Maven 为主，私服、插件、父子工程都方便。Java 版本建议 17 以上，Spring Boot 版本使用 3.2 或更新版本，因为 RestClient 和更完善的 WebClient 支持都需要较新的基线。先看 pom.xml 的核心依赖：

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.3.4</version> <relativePath/> </parent> <properties> <java.version>17</java.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> </dependencies>

很多新手会疑惑：web 和 webflux 两个 starter 都加，会不会冲突？实际上 Spring Boot 项目里如果同时引入两者，默认仍然是以 Spring MVC 作为 Web 层，webflux 的引入主要是为了使用 WebClient 这个响应式 HTTP 客户端。这是一套非常常见的组合，不会导致启动冲突，放心用。Lombok 可以省掉一堆 Getter/Setter，如果是团队规范禁止 Lombok，也可以手动生成，后面代码里涉及到的地方对应改一下就行。

3.2 配置文件、HTTP 客户端选择与底层差异

配置我建议拆成两部分：一部分是 Spring Boot 原生配置，比如服务端口、应用名；另一部分是自定义的 DeepSeek 配置，单独用@ConfigurationProperties绑定。自定义配置放在application.yml里是下面这个样子：

server: port: 8080 spring: application: name: deepseek-api-demo deepseek: base-url: https://api.deepseek.com api-key: ${DEEPSEEK_API_KEY} model: deepseek-chat temperature: 0.7 max-tokens: 2048 connect-timeout: 10s read-timeout: 60s

配置类可以这样写：

@Data @ConfigurationProperties(prefix = "deepseek") @Component public class DeepSeekProperties { private String baseUrl; private String apiKey; private String model; private Double temperature; private Integer maxTokens; private Duration connectTimeout; private Duration readTimeout; }

这里把超时时间单独拆出来，是因为大模型接口有一个特点：非流式调用时，如果模型在深度思考，响应可能要几十秒甚至更久，默认的 HTTP 超时经常不够用。connectTimeout 和 readTimeout 要区分对待，前者设置 10 秒足够了，后者建议至少 60 秒，如果是推理模型还要更长。超时配置如果不单独拿出来，直接写死在代码里，到时候线上调参数还得重新发版，太折腾。

HTTP 客户端的核心配置，我直接用 RestClient 处理同步调用。RestClient 的 API 风格和 WebClient 很像，但返回结果是同步的，对大多数业务系统来说心智负担更低：

@Configuration public class DeepSeekRestClientConfig { @Bean public RestClient deepSeekRestClient(DeepSeekProperties properties) { return RestClient.builder() .baseUrl(properties.getBaseUrl()) .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + properties.getApiKey()) .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE) .requestFactory(getRequestFactory(properties)) .build(); } private ClientHttpRequestFactory getRequestFactory(DeepSeekProperties properties) { SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory(); factory.setConnectTimeout(properties.getConnectTimeout()); factory.setReadTimeout(properties.getReadTimeout()); return factory; } }

这么封装之后，所有请求都会自动带上鉴权头和超时配置，Service 层不需要关心这些细节，只负责传消息进来。如果你希望同步调用和流式响应都使用同一套配置，可以再额外定义一个 WebClient Bean，道理是一样的，只是返回类型从业务对象变成 Flux。

3.3 请求体与响应体的 DTO 封装

请求和响应的 DTO 是整条调用链里最容易写错的部分。DeepSeek API 的字段是 snake_case 风格，比如max_tokens、finish_reason、prompt_tokens，而 Java 命名习惯是驼峰，如果直接拿 Map 接收再手动取值，代码会非常难维护。正确做法是定义清晰的 DTO，用 Jackson 的@JsonProperty做字段映射。

请求体 DTO：

@Data @Builder @NoArgsConstructor @AllArgsConstructor public class ChatMessage { private String role; private String content; }

@Data @Builder @NoArgsConstructor @AllArgsConstructor public class ChatRequest { private String model; private List<ChatMessage> messages; private Double temperature; @JsonProperty("max_tokens") private Integer maxTokens; @JsonProperty("stream") private Boolean stream; }

响应体 DTO 稍微复杂一点，主要包含 id、choices、usage 三块。choices 数组里是模型返回的内容，usage 里是 token 消耗统计：

@Data @Builder @NoArgsConstructor @AllArgsConstructor public class ChatResponse { private String id; private String object; private Long created; private String model; private List<Choice> choices; private Usage usage; @Data @Builder @NoArgsConstructor @AllArgsConstructor public static class Choice { private Integer index; private ChatMessage message; @JsonProperty("finish_reason") private String finishReason; } @Data @Builder @NoArgsConstructor @AllArgsConstructor public static class Usage { @JsonProperty("prompt_tokens") private Integer promptTokens; @JsonProperty("completion_tokens") private Integer completionTokens; @JsonProperty("total_tokens") private Integer totalTokens; } }

这里有个细节值得说：很多新人在做响应解析时直接把 choices 里第一个元素的 message.content 作为“答案”，忽略了 choices 其实是个数组。虽然大多数情况下数组里只有一个元素，但如果你搞传参、多候选之类的高级用法，数组里可能会多出几项。代码里统一取第一个元素的逻辑没问题，但最好加个空判断和日志，避免数组为空时抛空指针还一脸懵。

3.4 Service 层实现与 Controller 暴露 REST 接口

Service 层负责把业务输入转换成模型需要的消息列表。一个最简洁的调用示例如下：

@Service public class DeepSeekService { private final RestClient restClient; private final DeepSeekProperties properties; public DeepSeekService(RestClient deepSeekRestClient, DeepSeekProperties properties) { this.restClient = deepSeekRestClient; this.properties = properties; } public ChatResponse chat(List<ChatMessage> messages) { ChatRequest request = ChatRequest.builder() .model(properties.getModel()) .messages(messages) .temperature(properties.getTemperature()) .maxTokens(properties.getMaxTokens()) .stream(false) .build(); return restClient.post() .uri("/chat/completions") .body(request) .retrieve() .body(ChatResponse.class); } }

调用路径是/chat/completions，这也是兼容 OpenAI 协议的标准路径。如果 DeepSeek 平台同时支持带/v1前缀的地址，baseUrl 里配成不带 v1 的域名，路径里补全即可，原理一样。

Controller 层按照 RESTful 接口规范来设计，动词用 POST，路径体现资源语义，请求体用 DTO 接收。比如：

@RestController @RequestMapping("/api/v1/chat") public class ChatController { private final DeepSeekService deepSeekService; public ChatController(DeepSeekService deepSeekService) { this.deepSeekService = deepSeekService; } @PostMapping public ChatResponse chat(@RequestBody List<ChatMessage> messages) { return deepSeekService.chat(messages); } }

这样对外暴露的接口很简单，调用方只需要知道“往 /api/v1/chat 发一个消息列表，拿到回答”，完全不需要理解 DeepSeek 的 API 细节。实际项目里我还会在 Controller 层加一层参数校验，比如 messages 不能为空、content 长度不能超过限制，这些校验能有效避免把脏数据传给大模型，既省 token 又降低报错概率。

说到接口规范，路径里的v1前缀是 API 版本管理的基本做法。业务系统一旦上线，很难保证接口不变化，有版本号以后，即便是破坏性升级，老调用方也能继续用旧版本，不用被迫跟着改。这个习惯建议从一开始就养成，后面省很多事。

4. 进阶：流式输出与超长上下文处理

4.1 流式输出（SSE）在交互场景里的价值

第一次做 AI 功能的人通常会忽略流式输出，等到产品经理说“回答太慢了，用户一直盯着转圈”的时候才意识到问题。深层原因是人的耐心阈值太低，超过两三秒没有反馈就会焦虑，而大模型非流式调用动辄十几秒，这个体验在面向用户的场景里完全不可接受。

流式输出的本质是让模型一边生成一边把内容推给客户端，典型实现是 SSE（Server-Sent Events）。它和 WebSocket 不同，SSE 是单向的，服务器主动往客户端推数据，恰好匹配大模型“生成一段推一段”的场景，而且基于普通 HTTP 协议，不需要额外维护连接状态，Spring Boot 对它有原生支持，实现成本很低。

流式响应还有一个隐藏的好处：用户可以更早地看到输出内容，哪怕结果还没完整生成，也能先判断方向对不对，如果不对可以提前终止，省的继续烧 token。这个体验价值和成本价值都值得你为它单独写一套接口。

4.2 Spring Boot 里接入 SSE 流式响应的两种写法

第一种写法是在 Service 层用 WebClient 消费 DeepSeek 的流式响应，把返回的每条数据直接透传给前端。核心是把请求里的stream字段设成 true，然后用bodyToFlux(String.class)接收 SSE 字节流：

public Flux<String> chatStream(List<ChatMessage> messages) { ChatRequest request = ChatRequest.builder() .model(properties.getModel()) .messages(messages) .temperature(properties.getTemperature()) .maxTokens(properties.getMaxTokens()) .stream(true) .build(); return webClient.post() .uri("/chat/completions") .bodyValue(request) .accept(MediaType.TEXT_EVENT_STREAM) .retrieve() .bodyToFlux(String.class) .map(this::parseContentFromSse); }

这里要注意，DeepSeek 返回的 SSE 数据并不是每一行都是干净的 JSON，中间有大量data: {...}这样的前缀，以及最后可能有一条data: [DONE]表示结束。所以parseContentFromSse里需要做两件事：过滤掉非 data 开头的行，把data:前缀去掉以后再解析 JSON 取choices[0].delta.content。流式响应的结构和非流式不一样，内容字段在 delta 里，不在 message 里，这个和很多人的第一直觉不同。

Controller 层的写法是设置produces = MediaType.TEXT_EVENT_STREAM_VALUE，让 Spring 以 SSE 的方式把 Flux 输出给前端：

@PostMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<String> chatStream(@RequestBody List<ChatMessage> messages) { return deepSeekService.chatStream(messages); }

第二种写法是使用 SseEmitter，适合在不引入 WebClient 和响应式编程的老项目里做流式输出。SseEmitter 的思路是：Controller 先返回一个 SseEmitter 对象给前端，此时 HTTP 连接保持打开，然后你在自己的业务线程里往 emitter 发送数据，最后调用 complete 结束。这种方式更贴近传统 Servlet 编程习惯，代码直观，但并发控制、线程管理都要自己留意，不如 WebClient 方案简洁。

前端如果用的是 fetch，可以直接解析text/event-stream的响应体；如果用的是 EventSource API，要注意 EventSource 只支持 GET 请求，而大模型对话一般需要传大量消息体，所以实践中更多还是用 fetch 加 POST 方式手动解析 SSE 流，这个细节在前后端联调时经常成为沟通成本点。

4.3 1048576 tokens 上下文限制与消息窗口管理

新手在调 DeepSeek API 时最常撞见的一个报错，大概长这样：

400 Bad Request this model's maximum context length is 1048576 tokens. However, your messages resulted in 1048600 tokens. Please reduce the length of the messages.

第一次看到这个报错的人通常会以为是模型出了问题，其实不是。这个错误的意思是：你把太多历史消息一股脑塞进了请求里，导致整个上下文超出了模型窗口。只要上下文窗口是 1048576 tokens，换算成中文大概是几十万字到一百多万字，普通对话根本碰不到上限，会触发这个错误，多半是你在循环里不断拼接历史消息，或者把整本业务文档直接丢进了提示词。

要解决这个问题，核心思路是“消息窗口管理”，也就是在调用 API 之前，对 messages 列表做裁剪，保留 system 指令和最近几轮对话，丢掉中间的冗长内容。我总是用一句话给团队讲这个逻辑：和 AI 聊天和和人聊天是一样的，你不能把十年前的对话全背一遍再问今天的问题，得做取舍。

实现上，可以先做一个简单的 token 估算工具。中文字符一个大约占 1 到 2 个 token，英文字符大约 4 个字符占 1 个 token，工程上可以用字符数除以 2作为估算值，虽然不精准，但够用来做提前拦截：

public static int estimateTokens(String text) { if (text == null || text.isEmpty()) { return 0; } return (int) Math.ceil(text.length() / 2.0); }

然后写一个裁剪方法，从消息列表末尾往前叠，保留最近的对话直到接近阈值。为什么要从后往前？因为离当前问题越近的内容对回答影响越大，system 指令则单独保留并放在最前面：

public List<ChatMessage> trimMessages(List<ChatMessage> messages, int maxContextTokens) { List<ChatMessage> result = new ArrayList<>(); int totalTokens = 0; for (int i = messages.size() - 1; i >= 0; i--) { ChatMessage msg = messages.get(i); int tokens = estimateTokens(msg.getContent()); if (totalTokens + tokens > maxContextTokens) { break; } result.add(msg); totalTokens += tokens; } Collections.reverse(result); return result; }

调用前先执行一次裁剪，如果消息总 token 数超过了阈值，就把超出的部分截掉，宁可丢上下文也不要让请求直接 400。这里有一个取舍：直接截断可能让模型丢失关键信息，所以生产环境里更推荐的做法是配合向量检索来压缩上下文，只把和当前问题最相关的片段传给模型。但对于大多数中小业务，先做好滑动窗口已经能解决 90% 的问题。

另外，如果业务确实需要超长文本处理，还可以考虑分段总结再拼接摘要的方式：先在前面加一轮“请总结上一段内容”，拿到摘要后取代原文，再喂给最终对话。这个思路实现起来不难，但效果比单纯截断好得多。

5. 高频错误排查与工程化避坑

5.1 认证与令牌类错误

调用 DeepSeek API 最常见的认证报错是 401 Unauthorized，返回信息一般写着 invalid api key。看到这个别急着怀疑平台，先按顺序排查：检查环境变量是否真的注入了，检查 Key 有没有复制完整（尾部很容易多一个空格或换行），检查请求头 Authorization 是不是标准的Bearer xxx格式。我遇到过好几次，Docker 部署时环境变量没传进去，代码里读到的 Key 是 null，拼出来的 header 就成了Bearer null，平台自然直接拒绝。

另一种认证类错误是 403 Forbidden，这种通常不是 Key 本身的问题，而是账号权限、套餐额度或者 IP 白名单限制。如果你是在公司网络环境下调用，先确认平台是否需要配置出口 IP；如果是在多个环境共用同一个 Key，先确认这个 Key 有没有被平台的风控策略锁掉。这类错误在本地调得好好的、一上测试环境就挂，多半就是网络或白名单问题。

5.2 参数与上下文超限错误

400 错误里除了前面说的上下文超限，还有一类是参数校验不通过，比如 model 名字写错、messages 里缺少 content、temperature 传了超出范围的值。DeepSeek 支持的模型名是固定的，像 deepseek-chat、deepseek-reasoner 以及 v4 系列，写成deepseek-V4或者多打一个空格都会直接报错。这种问题排查最快的办法是把发给平台的完整请求体打印出来，和官方文档对照一眼就能看出来。

上下文超限的 400 错误处理方案在前面已经说了，核心是消息窗口管理。这里再补充一个实操技巧：把每次请求的usage.total_tokens记录下来，按用户维度做统计。这样你能知道每个用户平均消耗多少 token，如果某个用户频繁触达窗口上限，说明你的裁剪策略阈值没设对，或者对话轮数太深，需要提示用户开新会话。

5.3 网络超时、限流与重试策略

调用第三方 API 永远要把对方当成“随时可能出故障”的系统来设计。DeepSeek 服务稳定归稳定，但高并发时段也可能出现 429（请求过多）或者 502/503（网关异常）。这类错误不是你的代码 bug，但如果你不做任何处理，故障就会直接暴露给业务方。

推荐的兜底策略是重试加指数退避：第一次失败后等 500 毫秒再试，第二次等 1 秒，第三次等 2 秒，同时加一个最大重试次数，超过就放弃并返回友好错误。Spring Retry 可以很优雅地实现这个逻辑：

@Service public class DeepSeekService { @Retryable( retryFor = {WebClientResponseException.class}, noRetryFor = {IllegalArgumentException.class}, backoff = @Backoff(delay = 500, multiplier = 2.0, maxDelay = 10000), maxAttempts = 3 ) public ChatResponse chat(List<ChatMessage> messages) { // 调用逻辑 } }

注意不是所有异常都值得重试。400 这种参数错误，重试一万次还是 400，还浪费 token；429 和 5xx 才值得重试。所以在设计重试规则时，要把“确定性的参数错误”排除在重试范围之外，这个noRetryFor配置就是干这个的。另外，重试时要防止同一个请求被同时执行多次，可以加一层简单的分布式锁或者让调用方传入请求幂等号，不过大多数内部系统没这个必要，知道有这层考虑就行。

5.4 附带提醒：Actuator 端点的暴露要收敛

很多 Spring Boot 项目都会引入 Actuator 做健康检查和监控，但默认配置会把所有端点暴露出来，包括/actuator/env、/actuator/heapdump这样的敏感端点。如果你把服务直接暴露到内网或公网，又没有做认证，别人可以通过这些端点看到环境变量、配置信息，甚至导出堆内存进行分析，这比 API Key 硬编码进代码还要危险。

生产环境里至少要做到两点：一是只暴露必要的端点，比如 health、info、metrics、prometheus；二是给 Actuator 端点加认证或者放到独立的管理端口。配置文件里可以这样收敛：

management: endpoints: web: exposure: include: health,info,metrics,prometheus endpoint: health: show-details: never

如果接了 Prometheus 监控，再用 Micrometer 统计大模型调用的延迟、错误率、token 消耗量，就能在监控面板上直观看到服务状况。这个组合在热词里经常出现，实际用起来也确实香：把 DeepSeek 调用延迟和成功率做成指标，一旦接口变慢或者被限流，告警能第一时间触发，不用等用户来反馈。

5.5 错误速查表

把开发调试过程中高频遇到的情况整理成一个表，遇到报错直接对号入座：

这个表是我在实际调试里总结出来的，覆盖面不一定全，但把常见的坑都列进来了。建议你接手一个 Spring Boot 调 DeepSeek 的项目时，先把这个表贴到团队文档里，能省掉很多重复排查的沟通成本。

我自己在实际项目里把 DeepSeek 接入 Spring Boot 以后，最大的感受是：真正的复杂度根本不在“调一次 API”本身，而在于工程化细节。API Key 的安全存放、超时时长的设置、流式响应的对接、上下文窗口的管理、重试降级的策略，每一个环节都值得单独打磨。最后再分享一个小技巧：开发阶段可以在配置里加一个开关，让 DeepSeek 请求和响应的完整日志打到日志文件里，定位问题的时候非常管用；但上线前务必把日志级别调回来，否则你的日志系统会被 token 内容撑爆，还会有敏感信息泄露风险。调试日志是一把双刃剑，用好了事半功倍，用不好就是把隐私往外送。