把 DeepSeek API 接進 Spring Boot這事看起來無非就是“發(fā) HTTP 請求 解析 JSON”。但我實際上手做了幾個內(nèi)部項目之后發(fā)現(xiàn)真正決定項目成敗的往往是那些邊角料問題密鑰放哪兒、超時怎么配、流式返回怎么斷句、限流之后怎么退避。這篇文章把我會用到的完整做法拆開講適合正在做 AI 應(yīng)用集成的后端同學(xué)也適合想把項目從“能調(diào)通”升級到“能上線”的人。1. 動手之前技術(shù)選型和配置設(shè)計1.1 為什么是 Spring Boot而不是直接寫 HTTP 工具類如果你只是臨時跑一個腳本直接拿HttpClient寫幾十行代碼完全夠用。但放到 Spring Boot 項目里問題就不一樣了連接怎么復(fù)用、超時怎么統(tǒng)一管理、鑒權(quán)頭怎么注入、接口返回怎么反序列化、調(diào)用失敗后怎么重試這些如果全部靠手寫團隊里每個人都有自己的寫法最后代碼會變成一鍋粥。Spring Boot 一個比較舒服的地方是它把 HTTP 客戶端的生命周期交給了容器。你可以在配置類里聲明RestTemplate或WebClientBean統(tǒng)一設(shè)置超時、攔截器、連接池然后到處注入使用。調(diào)用方只關(guān)心業(yè)務(wù)方法不關(guān)心底層走了什么協(xié)議、連接怎么建立的。尤其是項目里要同時對接對話補全和流式對話兩種模式統(tǒng)一封裝的價值會更明顯。至于性能很多人擔心 Spring 封裝的客戶端不夠快。其實只要連接池配置合理異步場景用 WebClient同步場景用配置好連接池的 RestTemplate性能完全夠日常業(yè)務(wù)使用。真正的問題通常不在客戶端而是你在每次請求時 new 了一個 HttpClient導(dǎo)致連接頻繁建立和銷毀。所以先用 Spring 管理客戶端后續(xù)再根據(jù)壓測結(jié)果優(yōu)化路徑會順暢很多。1.2 API Key 的存放方式別寫死在配置文件里第一次對接時最容易踩的坑就是把 API Key 直接寫在application.yml里然后不小心提交到代碼倉庫。這個習(xí)慣一旦養(yǎng)成后面要么找人幫忙重置密鑰要么寫一堆腳本去清理倉庫歷史。我現(xiàn)在的做法是配置文件里只留占位符真實密鑰從環(huán)境變量或者部署平臺的密鑰管理服務(wù)里讀取。deepseek: api-key: ${DEEPSEEK_API_KEY} base-url: https://api.deepseek.com connect-timeout: 5s read-timeout: 60s這里用${DEEPSEEK_API_KEY}Spring 在啟動時會自動去環(huán)境變量里取值。本地開發(fā)可以在 IDE 的運行配置里設(shè)置環(huán)境變量 CI/CD 平臺一般也都有 Secrets 功能。這樣代碼倉庫和鏡像里都看不到明文密鑰出問題的時候只需要在部署平臺統(tǒng)一更新不需要重新提交代碼。另外一個細節(jié)是不要把Authorization頭打到業(yè)務(wù)日志里。很多公司會有全局的請求日志切面如果你在切面里打印了HttpHeaders密鑰就全出去了。我在項目里會給日志過濾器加一個脫敏邏輯只要 header 名是Authorization值統(tǒng)一顯示成***這個后面在排查實錄里再展開。1.3 版本組合Spring Boot 2.x 還是 3.x如果你是新項目我推薦直接上 Spring Boot 3.x JDK 17。原因很簡單Boot 3 的 WebClient 使用體驗更完整jakarta.*命名空間也解決了歷史包袱。如果你維護的是老項目Boot 2.7 也能做只是要注意javax.servlet變成jakarta.servlet那批依賴還有 Spring Security 版本關(guān)系。DeepSeek API 本身是 HTTPS 接口沒有 Java 版本相關(guān)的強綁定所以核心矛盾在 Spring 版本。我的建議是新服務(wù)Spring Boot 3.2JDK 17用 WebClient 處理流式用 RestTemplate 或者RestClient處理簡單同步請求。老服務(wù)Spring Boot 2.7JDK 8 也能跑但注意RestTemplate的線程安全性和超時配置。下面我會按要求同時給出同步和異步兩種實現(xiàn)你可以根據(jù)自己項目的基礎(chǔ)設(shè)施選擇。不管用哪個DTO 設(shè)計是完全一樣的。2. 請求與響應(yīng)模型設(shè)計2.1 Chat Completions 接口的協(xié)議要點DeepSeek 的對話補全接口本質(zhì)上是一個標準的 HTTP POST 接口。你需要請求一個固定的 URL把對話消息列表、模型名稱、生成參數(shù)放到 JSON 請求體里然后從響應(yīng)里拿生成結(jié)果。最核心的請求字段有這幾個model指定使用哪個模型比如deepseek-chat或deepseek-reasoner。messages對話消息列表每一條包含role和content。role通常是system、user、assistant。temperature采樣溫度值越高回答越隨機。max_tokens限制生成的最大 token 數(shù)。stream是否開啟流式返回。如果之前對接過類似的 Chat Completions 接口會發(fā)現(xiàn)這套字段非常眼熟。這個格式現(xiàn)在基本屬于行業(yè)通用習(xí)慣所以我建議不要自己發(fā)明字段直接沿用標準結(jié)構(gòu)可以降低以后接入其他模型的遷移成本。2.2 定義 Java DTO字段越少越不容易出錯在 Spring Boot 里我建議用 Java Record 來承載這類純數(shù)據(jù)對象。Record 自帶構(gòu)造器、equals、hashCode和toString寫起來干凈也不容易手抖加錯 setter。public record ChatMessage(String role, String content) {} public record ChatRequest( String model, ListChatMessage messages, Double temperature, Integer maxTokens, Boolean stream ) { // Jackson 默認使用參數(shù)名做 JSON 映射需要在編譯期開啟 -parameters // 或者通過 jackson-databind 的字段命名策略來兼容 snake_case。 }這里有個小坑DeepSeek API 的請求字段是max_tokens這種下劃線風(fēng)格而 Java 風(fēng)格是maxTokens。如果你不想在每個字段上寫JsonProperty可以在項目里配置 Jackson 的PropertyNamingStrategies.SNAKE_CASE讓全局字段命名自動轉(zhuǎn)換。Bean public Jackson2ObjectMapperBuilderCustomizer snakeCaseCustomizer() { return builder - builder.propertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE); }我個人的習(xí)慣是全局開啟 SNAKE_CASE 反而對大型項目不友好容易把別的接口也轉(zhuǎn)換了。更穩(wěn)妥的是只在 DTO 關(guān)鍵字段上顯式標注public record ChatRequest( String model, ListChatMessage messages, Double temperature, JsonProperty(max_tokens) Integer maxTokens, Boolean stream ) {}顯示標注帶來的好處是以后走查代碼時誰都能一眼看出這個字段對應(yīng) API 里的哪個名字不用依賴隱式配置去猜。2.3 響應(yīng)結(jié)構(gòu)解析到哪一層最合適響應(yīng)結(jié)構(gòu)比請求稍微復(fù)雜一點。外層有幾個固定字段真正有用的是choices數(shù)組里的第一項因為你請求一次對話通常只希望模型返回一條候選內(nèi)容。每一項里有message和finish_reason。message.content是最終文本finish_reason則告訴你生成是因為正常結(jié)束stop還是達到了 token 上限length。public record ChatResponse( String id, String model, ListChoice choices, Usage usage ) { public record Choice(Integer index, ChatMessage message, String finishReason) {} public record Usage(Integer promptTokens, Integer completionTokens, Integer totalTokens) {} }我見過很多新手把整個ChatResponse直接返回給前端讓前端自己從choices[0].message.content里取文本。短時間能用但只要 API 結(jié)構(gòu)稍微變化前端就要跟著改。比較好的做法是在 Service 層再包一層業(yè)務(wù)對象把需要的數(shù)據(jù)都組裝成ChatResultController 只面向業(yè)務(wù)對象。public record ChatResult(String content, String finishReason, Integer totalTokens) {}這樣做還有一個好處后續(xù)如果要記錄 token 消耗、做費用統(tǒng)計Usage信息已經(jīng)被 Service 層拿走了Controller 不會把敏感信息暴露出去。3. 兩步寫出可用的調(diào)用客戶端3.1 先用 RestTemplate 把同步流程跑通很多業(yè)務(wù)場景其實不需要流式返回比如后臺生成摘要、批量打標簽、離線分析。這時候用RestTemplate最直觀代碼也最好維護。先配置一個獨立的RestTemplateBean避免使用 Spring Boot 自動裝配的默認實例。Configuration public class DeepSeekClientConfig { Bean public RestTemplate deepSeekRestTemplate(DeepSeekProperties properties) { SimpleClientHttpRequestFactory factory new SimpleClientHttpRequestFactory(); factory.setConnectTimeout((int) properties.connectTimeout().toMillis()); factory.setReadTimeout((int) properties.readTimeout().toMillis()); return new RestTemplate(factory); } Bean public DeepSeekClient deepSeekClient( RestTemplate deepSeekRestTemplate, DeepSeekProperties properties) { return new DeepSeekClient(deepSeekRestTemplate, properties); } }注意這里設(shè)置了connectTimeout和readTimeout。大模型接口通常不是毫秒級返回如果readTimeout只給 5 秒長一點的文本生成一定會超時。我一般把連接超時控制在 5 秒內(nèi)讀取超時根據(jù)業(yè)務(wù)容錯能力放寬到 30 到 120 秒。然后寫一個客戶端調(diào)用方法Service public class DeepSeekClient { private final RestTemplate restTemplate; private final DeepSeekProperties properties; public ChatResult chat(String userMessage) { HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); headers.setBearerAuth(properties.apiKey()); ListChatMessage messages new ArrayList(); messages.add(new ChatMessage(system, 你是一個有用的中文助手)); messages.add(new ChatMessage(user, userMessage)); ChatRequest request new ChatRequest( properties.model(), messages, 0.7, 2000, false ); HttpEntityChatRequest entity new HttpEntity(request, headers); ResponseEntityChatResponse response restTemplate.exchange( properties.baseUrl() /chat/completions, HttpMethod.POST, entity, ChatResponse.class ); if (response.getStatusCode().is2xxSuccessful() response.getBody() ! null) { ChatResponse body response.getBody(); ChatResponse.Choice choice body.choices().get(0); return new ChatResult( choice.message().content(), choice.finishReason(), body.usage().totalTokens() ); } throw new DeepSeekException(調(diào)用失敗狀態(tài)碼 response.getStatusCode()); } }這段代碼里的重點是headers.setBearerAuth。它會自動生成Authorization: Bearer xxxx比手動拼接字符串更安全也避免出現(xiàn)多一個空格、少一個空格的問題。實際項目中system提示詞不建議寫死在客戶端里。更好的做法是讓調(diào)用方傳入或者放到配置中心這樣運營或者算法同事調(diào)整提示詞時不需要動代碼。3.2 用 WebClient 做流式返回如果要實現(xiàn)“打字機”效果就需要對接 SSE 流式返回。DeepSeek API 開啟stream: true后HTTP 響應(yīng)頭是Content-Type: text/event-stream每一行以data:開頭里面是一小段 JSON。Spring Boot 里的 WebClient 對 SSE 有比較好的支持。先聲明一個支持流式的 WebClient BeanBean public WebClient deepSeekWebClient(DeepSeekProperties properties) { return WebClient.builder() .baseUrl(properties.baseUrl()) .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE) .defaultHeader(HttpHeaders.AUTHORIZATION, Bearer properties.apiKey()) .build(); }注意這里通過baseUrl指定了根地址業(yè)務(wù)調(diào)用時只要寫相對路徑/chat/completions即可。后續(xù)如果要切換到別的 API 域名只需要改配置不用改代碼。流式方法可以這樣寫public FluxString streamChat(String userMessage) { ListChatMessage messages List.of( new ChatMessage(user, userMessage) ); ChatRequest request new ChatRequest( properties.model(), messages, 0.7, 2000, true ); return webClient.post() .uri(/chat/completions) .bodyValue(request) .retrieve() .bodyToFlux(new ParameterizedTypeReferenceServerSentEventString() {}) .filter(event - Objects.nonNull(event.data())) .map(event - parseContent(event.data())) .filter(Objects::nonNull); }ServerSentEventString會把 SSE 的data字段解析成String。因為data本身是一段 JSON所以還需要一個parseContent方法從 JSON 里把增量文本取出來private String parseContent(String json) { JsonNode node objectMapper.readTree(json); if (node.path(choices).isEmpty()) { return null; } JsonNode delta node.path(choices).get(0).path(delta).path(content); return delta.isMissingNode() ? null : delta.asText(); }流式返回里每一段只是增量文本不是完整回答。前端拿到后要做字符串拼接形成最終展示。這個邏輯放在前端做比較合適后端只負責把文本片段按順序推給前端。如果你的業(yè)務(wù)需要通過 HTTP 對外暴露常見做法是用 WebSocket 或者 SSE 把后端收到的內(nèi)容和前端對接不要讓業(yè)務(wù)服務(wù)直接依賴外部 API 的格式。3.3 超時、連接池和并發(fā)控制同步調(diào)用如果用默認的SimpleClientHttpRequestFactory它在高并發(fā)下連接復(fù)用能力比較弱。如果你的項目要長期承接較高的調(diào)用量我會建議換成基于 Apache HttpComponents 的客戶端。Bean public RestTemplate deepSeekRestTemplate(DeepSeekProperties properties) { PoolingHttpClientConnectionManager connectionManager new PoolingHttpClientConnectionManager(); connectionManager.setMaxTotal(200); connectionManager.setDefaultMaxPerRoute(50); CloseableHttpClient httpClient HttpClients.custom() .setConnectionManager(connectionManager) .setDefaultRequestConfig(RequestConfig.custom() .setConnectTimeout((int) properties.connectTimeout().toMillis()) .setSocketTimeout((int) properties.readTimeout().toMillis()) .build()) .build(); HttpComponentsClientHttpRequestFactory factory new HttpComponentsClientHttpRequestFactory(httpClient); return new RestTemplate(factory); }為什么要關(guān)注連接池因為大模型接口的平均響應(yīng)時間可能遠高于普通接口比如 10 秒甚至 20 秒。如果每個請求都占用一個連接高峰期連接池很容易被占滿。同一個線程如果還有第二個請求要發(fā)就只能排隊等空閑連接導(dǎo)致整體的吞吐量下降。所以給RestTemplate配連接池不是可有可無的優(yōu)化而是高并發(fā)下的必需品。對于 WebClient默認響應(yīng)時間是 30 秒我一般會在 WebClient 的 builder 里顯式設(shè)置responseTimeout。注意不要只在請求級設(shè)置最好在 Bean 初始化時就固定下來避免每一處調(diào)用都重復(fù)配置。4. 異常處理、重試與降級4.1 先把異常分門別類對接第三方 API 和對接本地數(shù)據(jù)庫不一樣網(wǎng)絡(luò)抖動、服務(wù)端限流、模型過載都非常常見。如果只是拋一個Exception出來Controller 層很難針對性地做處理。我通常先建一個異常分類表場景特征處理方式鑒權(quán)失敗HTTP 401不重試只告警提示檢查 Key限流HTTP 429讀取Retry-After指數(shù)退避后重試服務(wù)端錯誤HTTP 5xx重試 2-3 次仍失敗則降級連接超時SocketTimeoutException重試一次避免重復(fù)提交讀取超時ReadTimeoutException無法確認服務(wù)端是否已生成謹慎重試網(wǎng)絡(luò)中斷IOException指數(shù)退避后重試這個表的價值在于它決定了你寫catch邏輯時該往哪個方向處理。如果所有異常都用一個重試策略很可能出現(xiàn)“401 也重試三次”這種既浪費時間又浪費配額的情況。4.2 用 Spring Retry 實現(xiàn)指數(shù)退避Spring Retry 是現(xiàn)成的重試框架配合RetryTemplate可以控制重試次數(shù)和退避時間。調(diào)用外部大模型接口指數(shù)退避比固定間隔更有意義因為限流和服務(wù)端過載往往需要一定時間恢復(fù)。Configuration public class RetryConfig { Bean public RetryTemplate deepSeekRetryTemplate() { return RetryTemplate.builder() .maxAttempts(3) .exponentialBackoff(1000, 2, 10000) .retryOn(DeepSeekRetryableException.class) .build(); } }使用方式很簡單public ChatResult chatWithRetry(String userMessage) { return retryTemplate.execute(context - chat(userMessage)); }這里我會單獨定義一個DeepSeekRetryableException然后在 catch 里做翻譯catch (IllegalArgumentException e) { throw e; } catch (Exception e) { return new DeepSeekRetryableException(e); }為什么要做這層翻譯因為RetryTemplate默認會重試所有異常但認證錯誤、參數(shù)錯誤、業(yè)務(wù)校驗失敗這些情況是不應(yīng)該重試的。通過明確的異常類型你才能精確控制“什么該重試、什么不該重試”。4.3 降級策略寧可返回默認結(jié)果也不要讓依賴鏈崩掉如果調(diào)用方是一個對實時性要求不高的功能比如后臺離線聚合降級策略可以直接返回緩存結(jié)果或者兜底文案。如果調(diào)用方是實時對話界面降級會復(fù)雜一些但至少要有“模型暫不可用”的提示而不是讓請求直接 500。一個簡單的寫法public ChatResult chatSafely(String userMessage) { try { return retryTemplate.execute(ctx - chat(userMessage)); } catch (Exception e) { log.warn(DeepSeek 調(diào)用失敗返回兜底結(jié)果, e); return new ChatResult(抱歉我暫時無法回答這個問題請稍后再試。, fallback, 0); } }實際項目中兜底結(jié)果可以來自 Redis 緩存。舉個例子如果同一個 prompt 之前已經(jīng)調(diào)用成功過就直接把結(jié)果返回既省 token又避免頻繁觸發(fā)限流。我會把這種需求放到“成本控制”一節(jié)具體講。4.4 重試與冪等的平衡調(diào)用聊天補全接口時“重試”不像普通數(shù)據(jù)庫更新操作那么嚴格因為一次生成請求被重試可能造成多次計費也可能產(chǎn)生兩條不同回答。所以在重試之前要問自己這個業(yè)務(wù)能不能接受重復(fù)調(diào)用我的習(xí)慣是單輪問答可以重試。多輪對話重試可能改變上下文通常不自動重試。計費敏感場景重試次數(shù)控制在 2 次以內(nèi)。如果你用的是流式接口重試會更麻煩因為前端可能已經(jīng)接收到一部分內(nèi)容了。這時候我更推薦讓 WebSocket 或前端業(yè)務(wù)層來負責“斷線續(xù)傳”而不是后端默默重發(fā)整個請求。5. 常見問題排查實錄5.1 Connection timed out排查網(wǎng)絡(luò)邊界有一個很容易忽略的問題服務(wù)器在云端但云端主機默認只能訪問特定網(wǎng)段或者需要經(jīng)過額外的網(wǎng)絡(luò)出口才能訪問公網(wǎng)。我遇到過最典型的情況是代碼在本地開發(fā)環(huán)境能調(diào)通部署到測試環(huán)境后一直Connection timed out。排查步驟一般如下用命令行curl先測試 API URL 是否可達。檢查安全組或防火墻有沒有限制出方向訪問。檢查 DNS 解析是否正常。檢查應(yīng)用服務(wù)器上是否配置了全局代理。curl都通了再去看 Java 代碼里的客戶端超時配置。很多時候問題不是代碼邏輯而是環(huán)境策略。如果確認網(wǎng)絡(luò)沒問題再看是不是connectTimeout設(shè)置得太短。5.2 429 Too Many Requests限流了別硬頂429 出現(xiàn)時說明當前調(diào)用頻率超過了服務(wù)端限制。此時唯一正確的做法是退避重試或者降級。千萬不要寫一個while(true)循環(huán)不僅浪費 API 配額還可能讓限流時間更長。DeepSeek API 如果返回了Retry-After請求頭建議優(yōu)先讀取這個時間。沒有的話用指數(shù)退避第一次等 1 秒第二次等 2 秒第三次等 4 秒。我遇到比較極端的一次是調(diào)用方?jīng)]有做并發(fā)限制幾十個線程同時請求結(jié)果 429 持續(xù)了好幾分鐘。后來加了信號量限流才把問題解決。5.3 返回的 content 被截斷了先看 finish_reason如果你發(fā)現(xiàn)模型回答到一半就停了不要急著懷疑 API 出錯了先看choices[0].finish_reason。如果是stop說明模型認為回答已經(jīng)完整。如果是length說明max_tokens不夠回答被截斷了。如果是content_filter說明內(nèi)容被過濾這是一種正常保護策略?！盎卮鸬揭话搿弊畛Ｒ姷母词莔ax_tokens設(shè)置太小。尤其你用deepseek-reasoner這類推理模型時思考過程本身會占用很多 token最后留給正式回答的空間可能不夠。此時可以調(diào)大max_tokens或者在前端追加一次“請繼續(xù)”請求。5.4 密鑰泄露到日志Authorization 頭必須脫敏有一次我排查線上問題順手翻了應(yīng)用日志發(fā)現(xiàn)請求日志里把完整的Authorization: Bearer sk-xxxx打印出來了。當場冒了冷汗。密鑰一旦出現(xiàn)在中心化日志系統(tǒng)里所有能看日志的同事都能拿到權(quán)限控制再嚴格也經(jīng)不起這種暴露。我的解決方案是在 WebFilter 里統(tǒng)一脫敏。Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) { String auth request.getHeader(HttpHeaders.AUTHORIZATION); if (StringUtils.hasText(auth)) { String masked auth.substring(0, 15) ***; log.info(request uri: {}, authorization: {}, request.getRequestURI(), masked); } chain.doFilter(request, response); }注意這里只是順手舉例子真正生產(chǎn)環(huán)境我不建議你打印任何請求頭。即使要打也必須確保Authorization只保留前幾位。5.5 中文亂碼和 JSON 轉(zhuǎn)義對接時如果直接用String接收響應(yīng)可能會出現(xiàn)中文亂碼。最簡單的解決辦法是確保請求頭帶有Content-Type: application/json;charsetUTF-8同時 Jackson 默認就是 UTF-8 解碼一般不大會亂。比較討厭的是返回內(nèi)容里有換行、引號、反斜杠被 JSON 轉(zhuǎn)義后顯示成\n或\。前端拿到后要記得用 JSON 解析不要直接把 content 顯示出來。后端如果是傳給內(nèi)部系統(tǒng)可以在ChatResult里先做一次反轉(zhuǎn)義但更推薦保留原始 JSON 字段由前端統(tǒng)一處理。5.6 流式返回拼接出現(xiàn)重復(fù)或丟失流式返回的每一段data都是不同步到達的可能存在空delta也可能出現(xiàn)連續(xù)兩個事件內(nèi)容為同一個 token 的情況。我在處理時習(xí)慣的做法是過濾掉data為空的事件。只取delta.content有值的片段。前端按順序 append不在后端做聚合。如果你在后端強行聚合完整文本再一次性推給前端就失去流式意義了。只要保持事件順序正確拼接工作交給前端是最省心的。6. 再聊幾個工程化習(xí)慣6.1 用 MockRestServiceServer 寫單元測試對接真實 API 的測試不穩(wěn)定也燒錢。更好的方式是使用 Spring 提供的MockRestServiceServer預(yù)先定義好請求和響應(yīng)的 mock然后驗證客戶端邏輯。SpringBootTest class DeepSeekClientTest { Autowired DeepSeekClient deepSeekClient; Autowired RestTemplate restTemplate; Test void shouldParseChatResponse() { MockRestServiceServer server MockRestServiceServer.bindTo(restTemplate).build(); server.expect(once(), requestTo(https://api.deepseek.com/chat/completions)) .andExpect(method(HttpMethod.POST)) .andRespond(withSuccess( { id: test, model: deepseek-chat, choices: [ { index: 0, message: {role: assistant, content: 你好}, finish_reason: stop } ], usage: {prompt_tokens: 10, completion_tokens: 5, total_tokens: 15} } , MediaType.APPLICATION_JSON)); ChatResult result deepSeekClient.chat(早上好); Assertions.assertEquals(你好, result.content()); server.verify(); } }有了這種測試你可以放心調(diào)整 DTO 字段、異常邏輯和重試策略不用每次都跑到真實環(huán)境去驗證。我甚至?xí)跍y試里故意返回429確認重試模板是否按預(yù)期執(zhí)行。6.2 在 Controller 和底層客戶端之間加一層門面直接讓 Controller 調(diào)用 DeepSeek 的RestTemplate方法短期沒問題長期會越來越難維護。因為 Controller 面向的是“業(yè)務(wù)輸入輸出”不應(yīng)該知道消息列表怎么組裝、溫度怎么設(shè)置、重試策略是什么。我習(xí)慣先定義一個面向業(yè)務(wù)的接口public interface ChatClient { ChatResult chat(String userMessage); FluxString streamChat(String userMessage); }然后寫一個基于 DeepSeek 的實現(xiàn)Service public class DeepSeekChatClient implements ChatClient { // 內(nèi)部注入 DeepSeekClient }將來如果業(yè)務(wù)需要切換模型或者同時對接多個模型只需要新增一個實現(xiàn)然后通過配置切換具體實現(xiàn)類。調(diào)用方完全不感知測試也更好做。6.3 成本控制緩存相同請求結(jié)果大模型 API 是按 token 計費的。同一個問題如果被重復(fù)請求費用會不斷累積。我在內(nèi)部項目里常用兩種手段短時間窗口緩存把相同 prompt 的結(jié)果在 Redis 內(nèi)存 5 分鐘之后用ChatResult直接從緩存返回。并發(fā)限流用Semaphore限制同時發(fā)往 DeepSeek 的請求數(shù)量避免瞬時峰值觸發(fā) 429。限流代碼很簡單private final Semaphore semaphore new Semaphore(20); public ChatResult chatWithLimit(String message) { if (!semaphore.tryAcquire()) { return fallback(); } try { return chat(message); } finally { semaphore.release(); } }有人會覺得這種限流會犧牲響應(yīng)速度但對于大多數(shù)內(nèi)部系統(tǒng)來說寧可讓少部分請求降級也不能讓所有請求因為限流或超時全部失敗。緩存和限流結(jié)合起來既節(jié)省成本又讓系統(tǒng)的行為更可預(yù)期。6.4 最后一點心得實際做下來最耽誤進度的往往不是 API 本身而是沒有提前想清楚異常、日志和測試。先寫一個能跑通的最小按鈕再做超時和重試最后才鋪開業(yè)務(wù)功能是我現(xiàn)在比較推薦的方式。如果你剛接觸建議先復(fù)制一份同步調(diào)用代碼跑通一次再嘗試改成流式最后再往工程化方向打磨。這個順序走完以后再接別的模型 API基本一天之內(nèi)就能上線。