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