1. 臨時素材上傳到底難在哪企業(yè)微信的臨時素材上傳看起來只是調(diào)一個接口的事但真到業(yè)務(wù)里跑起來坑比想象中多。我前后在三個項目里踩過這個環(huán)節(jié)從最開始用最樸素的方式硬懟到后來逐步抽象出一套相對優(yōu)雅的方案中間交了不少學(xué)費。這篇文章就把這些經(jīng)驗完整拆開講一遍適合正在對接企業(yè)微信素材能力、或者已經(jīng)對接但被各種邊界情況折騰過的開發(fā)者參考。先把概念理清楚。企業(yè)微信的臨時素材指的是上傳后只在服務(wù)端保留三天的媒體文件包括圖片、語音、視頻和普通文件。它和永久素材最大的區(qū)別就是生命周期短但勝在上傳接口簡單、不需要額外的素材管理邏輯。典型使用場景是客服系統(tǒng)里發(fā)送一張工單截圖、審批流里附帶一個PDF附件、機(jī)器人推送一段語音通知。這些場景的共同特點是文件用完即棄不需要長期存儲臨時素材剛好匹配。那難點在哪我總結(jié)下來主要是四塊第一上傳接口用的是multipart/form-data和普通JSON請求的封裝方式完全不同很多HTTP工具類默認(rèn)不支持或者支持得別扭第二media_id這個返回值有有效期業(yè)務(wù)側(cè)如果緩存了它過期后發(fā)送會直接失敗第三文件類型和大小有硬性限制圖片不能超過10MB、語音不能超過2MB且只支持AMR和MP3、視頻不能超過10MB超了接口直接報錯第四并發(fā)上傳時如果多個請求同時拿同一個文件流會出現(xiàn)流被消費完導(dǎo)致后續(xù)請求拿到空內(nèi)容的問題。這四點里前兩點是認(rèn)知問題后兩點是實打?qū)嵉募夹g(shù)坑。我見過不少項目在這塊的處理方式是寫一個工具方法每次要發(fā)文件就現(xiàn)讀現(xiàn)傳傳完拿到media_id立刻用掉。這種方式在低頻場景下沒問題但一旦量上來比如一天幾千次上傳就會暴露出重復(fù)上傳、流管理混亂、錯誤處理缺失等一系列問題。所以“優(yōu)雅”這個詞在這里不是錦上添花而是有明確的工程價值——它意味著可復(fù)用、可觀測、可容錯。下面我會從整體設(shè)計思路開始一步步拆到具體實現(xiàn)把每個決策背后的理由講清楚。你如果只是想快速抄個能跑的代碼可以直接跳到第三節(jié)但如果你想搞清楚為什么這么設(shè)計建議從頭看。2. 整體方案設(shè)計與選型考量2.1 為什么不用現(xiàn)成的SDK企業(yè)微信官方提供了多語言SDKJava、Python、PHP都有。我最初也想過直接用SDK省事但實際用下來發(fā)現(xiàn)兩個問題。一是SDK往往把access_token的管理和素材上傳耦合在一起而access_token本身需要全局緩存和刷新如果每個上傳請求都去觸發(fā)一次token獲取在高并發(fā)下會頻繁打企業(yè)微信的接口觸發(fā)頻率限制。二是SDK的封裝層次比較深出問題的時候排查鏈路長比如上傳失敗你很難快速判斷是token問題、網(wǎng)絡(luò)問題還是文件本身的問題。所以我的選擇是access_token自己管上傳邏輯自己寫只依賴一個通用的HTTP客戶端。這樣每一層都是透明的出問題能快速定位。當(dāng)然這不是說SDK不好如果你的項目規(guī)模小、上傳頻率低用SDK完全沒問題。但如果你追求可控性和可觀測性自己封裝是更穩(wěn)的路。2.2 核心設(shè)計原則整個方案我定了三條原則。第一條是流的一次性消費文件流從磁盤或網(wǎng)絡(luò)讀進(jìn)來之后只允許被消費一次避免重復(fù)讀取導(dǎo)致的性能損耗和狀態(tài)混亂。第二條是media_id不跨請求緩存每次上傳拿到media_id后立即返回給調(diào)用方由調(diào)用方在本次業(yè)務(wù)邏輯內(nèi)用完即棄不做全局緩存。第三條是錯誤分層把網(wǎng)絡(luò)錯誤、接口錯誤、文件校驗錯誤分開處理每類錯誤有不同的重試策略和日志級別。這三條原則看起來簡單但落地的時候需要一些設(shè)計上的取舍。比如第一條如果調(diào)用方傳進(jìn)來的是一個InputStream那上傳完之后這個流就關(guān)了調(diào)用方不能再讀。所以我在接口設(shè)計上要求調(diào)用方傳文件路徑或者字節(jié)數(shù)組而不是流。字節(jié)數(shù)組適合小文件文件路徑適合大文件這樣內(nèi)部可以自己控制流的生命周期。2.3 模塊劃分整個上傳能力我拆成了四個模塊。TokenManager負(fù)責(zé)access_token的獲取、緩存和刷新用雙檢鎖加過期時間控制保證多線程下只有一個線程去刷新。MediaValidator負(fù)責(zé)文件校驗包括類型、大小、擴(kuò)展名校驗不通過直接拋業(yè)務(wù)異常不走網(wǎng)絡(luò)請求。MediaUploader是核心上傳邏輯負(fù)責(zé)組裝multipart請求、發(fā)送、解析響應(yīng)。UploadResult是統(tǒng)一的返回結(jié)構(gòu)包含media_id、類型、創(chuàng)建時間以及一個isSuccess的標(biāo)志。這四個模塊之間是單向依賴Uploader依賴Validator和TokenManagerValidator和TokenManager互不依賴。這樣的好處是每個模塊可以單獨測試比如Validator的測試不需要mock網(wǎng)絡(luò)TokenManager的測試不需要真實文件。2.4 關(guān)于multipart的選型multipart/form-data的組裝我試過三種方式。第一種是手寫boundary拼接字節(jié)流靈活但容易出錯尤其是boundary和內(nèi)容里出現(xiàn)沖突的時候。第二種是用Apache HttpClient的MultipartEntityBuilder封裝好、穩(wěn)定但引入了一個比較重的依賴。第三種是用OkHttp的MultipartBody輕量、API清晰我最終選了這個。選OkHttp的理由是它的MultipartBody.Builder用起來很直觀addFormDataPart可以同時指定name、filename和RequestBody而且RequestBody可以基于文件或字節(jié)數(shù)組創(chuàng)建天然支持流式上傳。另外OkHttp的連接池和超時控制也比較成熟不需要自己再造輪子。如果你用的是Java生態(tài)里的其他HTTP客戶端思路是一樣的關(guān)鍵是找到支持流式multipart的API。3. 核心細(xì)節(jié)與實操要點拆解3.1 access_token的管理策略access_token是企業(yè)微信所有接口的通行證有效期7200秒也就是兩小時。它的獲取接口有頻率限制而且新獲取的token會讓舊的失效。這意味著你不能每個請求都去獲取也不能緩存太久導(dǎo)致過期。我的做法是用一個帶過期時間的緩存key是應(yīng)用的corpId和secret的組合value是token和過期時間戳。獲取token的時候先查緩存如果存在且距離過期還有300秒以上直接用否則加鎖去刷新。加鎖用雙檢鎖避免多個線程同時刷新。刷新成功后更新緩存失敗則拋異常讓上層決定是否重試。這里有個細(xì)節(jié)過期時間不要設(shè)成7200秒整要留出網(wǎng)絡(luò)延遲和時鐘偏差的余量。我一般設(shè)成6900秒也就是提前300秒過期。另外如果企業(yè)微信返回的token過期時間字段和預(yù)期不一致以返回的為準(zhǔn)不要硬編碼。注意access_token的緩存不要用本地Map簡單存多實例部署的時候每個實例都會各自刷新導(dǎo)致token頻繁失效。生產(chǎn)環(huán)境建議用Redis之類的集中式緩存或者至少保證同一時間只有一個實例在刷新。3.2 文件校驗的邊界條件文件校驗看起來簡單但邊界條件不少。企業(yè)微信對臨時素材的限制是這樣的圖片支持JPG、PNG、GIF、BMP、JPEG大小不超過10MB語音支持AMR、MP3大小不超過2MB播放長度不超過60秒視頻支持MP4大小不超過10MB普通文件大小不超過20MB。校驗的時候要注意幾點。第一擴(kuò)展名和實際內(nèi)容可能不一致比如一個exe文件改名為jpg光看擴(kuò)展名是攔不住的。如果業(yè)務(wù)安全要求高需要讀文件頭做魔數(shù)校驗。第二大小校驗要在讀取文件之前做用File.length()獲取避免把大文件讀進(jìn)內(nèi)存才發(fā)現(xiàn)超限。第三語音的時長校驗比較麻煩需要解析音頻文件頭如果業(yè)務(wù)不強制可以只校驗大小和格式時長交給企業(yè)微信接口去判斷。我一般把校驗規(guī)則做成配置用枚舉定義每種類型的允許擴(kuò)展名和大小上限這樣新增類型的時候只改配置不改代碼。校驗失敗的時候拋出帶明確錯誤碼的異常比如FILE_TOO_LARGE、UNSUPPORTED_TYPE方便上層做不同的提示。3.3 multipart請求的組裝細(xì)節(jié)組裝multipart請求的時候有幾個細(xì)節(jié)容易忽略。第一boundary的生成要用隨機(jī)字符串不要用固定值避免和文件內(nèi)容沖突。OkHttp會自動生成不用自己管。第二Content-Type要設(shè)成multipart/form-data并且?guī)蟗oundary參數(shù)這個OkHttp的MultipartBody會自動處理。第三每個part的name要和接口文檔一致企業(yè)微信上傳接口的字段名是media類型是filefilename要帶上原始文件名和擴(kuò)展名。代碼大概長這樣RequestBody fileBody RequestBody.create(file, MediaType.parse(application/octet-stream)); MultipartBody body new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart(media, file.getName(), fileBody) .build(); Request request new Request.Builder() .url(uploadUrl ?access_token token type type) .post(body) .build();這里type參數(shù)是素材類型取值是image、voice、video、file。注意type要放在URL的query參數(shù)里不是放在body里這是企業(yè)微信接口的設(shè)計。3.4 響應(yīng)解析與錯誤處理企業(yè)微信上傳接口的響應(yīng)是JSON成功的時候返回media_id、type、created_at。失敗的時候返回errcode和errmsg。解析的時候要先判斷HTTP狀態(tài)碼再判斷errcode。有些錯誤是HTTP 200但errcode非0比如40001表示token無效40004表示媒體文件類型不合法40005表示文件大小超限。我的處理方式是HTTP非200直接拋網(wǎng)絡(luò)異常HTTP 200但errcode非0則根據(jù)errcode映射成業(yè)務(wù)異常。40001這種token失效的錯誤觸發(fā)一次token刷新后重試一次其他錯誤直接拋給上層不重試。重試只做一次避免無限循環(huán)。提示errcode的映射表建議做成常量類不要散落在代碼里。企業(yè)微信的錯誤碼有幾百個常用的就那幾十個維護(hù)一份自己的映射表比每次查文檔快得多。3.5 并發(fā)場景下的流管理并發(fā)上傳同一個文件的時候如果多個線程共享一個InputStream會出現(xiàn)流被消費完的問題。我的做法是接口只接受File或byte[]不接受InputStream。如果是File每個線程自己打開一個新的FileInputStream如果是byte[]每個線程自己創(chuàng)建一個新的ByteArrayInputStream。這樣每個上傳請求都有獨立的流互不干擾。如果是大文件用File的方式更省內(nèi)存因為OkHttp會流式讀取文件不會一次性加載到內(nèi)存。如果是小文件用byte[]更方便因為可以復(fù)用不需要反復(fù)讀磁盤。我一般設(shè)一個閾值比如1MB以下的用byte[]以上的用File。4. 完整實操流程與關(guān)鍵環(huán)節(jié)4.1 環(huán)境準(zhǔn)備與依賴引入先說一下環(huán)境。我用的是Java 8加OkHttp 4.x構(gòu)建工具是Maven。依賴只需要兩個OkHttp和Jackson前者做HTTP請求后者解析JSON。如果你用的是Gradle換成對應(yīng)的坐標(biāo)就行。dependency groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId version4.9.3/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.13.0/version /dependencyOkHttp 4.x需要Kotlin標(biāo)準(zhǔn)庫Maven會自動帶上不用手動加。如果你用的是Java 11以上也可以考慮用Java自帶的HttpClient但multipart的支持不如OkHttp方便需要自己拼boundary。4.2 TokenManager的實現(xiàn)TokenManager的核心是一個帶過期時間的緩存和一個刷新鎖。我用ConcurrentHashMap存tokenkey是corpId加secretvalue是一個包含token和過期時間的對象。獲取token的方法先查緩存判斷是否過期過期則加鎖刷新。public String getToken(String corpId, String secret) { String key corpId : secret; TokenCache cache tokenMap.get(key); if (cache ! null !cache.isExpired()) { return cache.getToken(); } synchronized (this) { cache tokenMap.get(key); if (cache ! null !cache.isExpired()) { return cache.getToken(); } String token fetchTokenFromApi(corpId, secret); tokenMap.put(key, new TokenCache(token, System.currentTimeMillis() 6900 * 1000)); return token; } }fetchTokenFromApi就是調(diào)企業(yè)微信的gettoken接口解析返回的access_token和expires_in。注意expires_in是秒要轉(zhuǎn)成毫秒。如果接口返回errcode非0拋異常。注意synchronized鎖的是this如果TokenManager是單例沒問題如果是多例鎖不住。生產(chǎn)環(huán)境建議用分布式鎖或者保證TokenManager是單例。4.3 MediaValidator的實現(xiàn)Validator的職責(zé)是校驗文件是否符合企業(yè)微信的要求。我用一個枚舉定義每種類型的規(guī)則public enum MediaType { IMAGE(image, Arrays.asList(jpg, jpeg, png, gif, bmp), 10 * 1024 * 1024), VOICE(voice, Arrays.asList(amr, mp3), 2 * 1024 * 1024), VIDEO(video, Arrays.asList(mp4), 10 * 1024 * 1024), FILE(file, Collections.emptyList(), 20 * 1024 * 1024); private final String type; private final ListString allowedExtensions; private final long maxSize; // 構(gòu)造方法和getter省略 }校驗方法接收File和MediaType先判斷文件是否存在再判斷大小再判斷擴(kuò)展名。FILE類型不限制擴(kuò)展名只限制大小。校驗不通過拋MediaValidationException帶上錯誤碼。4.4 MediaUploader的核心邏輯Uploader是核心流程是校驗文件、獲取token、組裝multipart、發(fā)送請求、解析響應(yīng)、返回結(jié)果。我把它寫成一個方法接收File、MediaType、corpId、secret返回UploadResult。public UploadResult upload(File file, MediaType type, String corpId, String secret) { validator.validate(file, type); String token tokenManager.getToken(corpId, secret); String url UPLOAD_URL ?access_token token type type.getType(); RequestBody fileBody RequestBody.create(file, MediaType.parse(application/octet-stream)); MultipartBody body new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart(media, file.getName(), fileBody) .build(); Request request new Request.Builder().url(url).post(body).build(); try (Response response client.newCall(request).execute()) { String responseBody response.body().string(); return parseResponse(responseBody, type); } catch (IOException e) { throw new MediaUploadException(NETWORK_ERROR, e); } }parseResponse解析JSON如果errcode是0返回成功的UploadResult如果是40001刷新token后重試一次其他錯誤拋異常。4.5 重試機(jī)制的實現(xiàn)重試只針對token失效和網(wǎng)絡(luò)超時兩種情況。token失效的重試邏輯是捕獲到40001錯誤后強制刷新token重新組裝請求再發(fā)一次。網(wǎng)絡(luò)超時的重試是捕獲IOException后判斷是否是超時是則重試一次不是則直接拋。重試次數(shù)我設(shè)成1次也就是最多發(fā)兩次請求。為什么不設(shè)更多因為企業(yè)微信的接口本身有頻率限制重試太多會觸發(fā)限流反而更慢。而且如果是文件本身的問題重試多少次都沒用。private UploadResult uploadWithRetry(File file, MediaType type, String corpId, String secret, int retryCount) { try { return doUpload(file, type, corpId, secret); } catch (TokenExpiredException e) { if (retryCount 0) { tokenManager.refresh(corpId, secret); return uploadWithRetry(file, type, corpId, secret, retryCount - 1); } throw e; } catch (IOException e) { if (retryCount 0 isTimeout(e)) { return uploadWithRetry(file, type, corpId, secret, retryCount - 1); } throw new MediaUploadException(NETWORK_ERROR, e); } }4.6 調(diào)用示例與結(jié)果處理調(diào)用的時候業(yè)務(wù)代碼只需要三行MediaUploader uploader new MediaUploader(); UploadResult result uploader.upload(new File(/path/to/image.jpg), MediaType.IMAGE, corpId, secret); String mediaId result.getMediaId();拿到mediaId后立即在本次業(yè)務(wù)邏輯里用掉比如調(diào)發(fā)送消息接口。不要存到數(shù)據(jù)庫或者緩存里因為三天后就失效了。如果業(yè)務(wù)需要長期保存應(yīng)該把文件存到自己的對象存儲需要發(fā)送的時候再上傳一次。提示media_id的有效期是三天但實際使用中建議按兩天半來規(guī)劃留出余量。如果業(yè)務(wù)邏輯比較復(fù)雜從上傳到發(fā)送之間可能間隔很久那就要考慮重新上傳。5. 常見問題與排查技巧實錄5.1 上傳失敗排查速查表錯誤現(xiàn)象可能原因排查方法解決方案返回40001token無效或過期檢查token緩存是否過期是否被其他實例刷新覆蓋刷新token后重試檢查緩存策略返回40004文件類型不合法檢查擴(kuò)展名和實際類型是否匹配修正文件類型或做魔數(shù)校驗返回40005文件大小超限檢查文件實際大小壓縮文件或分片上傳返回41001缺少access_token參數(shù)檢查URL拼接確認(rèn)token不為空連接超時網(wǎng)絡(luò)問題或企業(yè)微信側(cè)限流檢查網(wǎng)絡(luò)連通性查看是否觸發(fā)頻率限制增加超時時間降低并發(fā)流被關(guān)閉多線程共享InputStream檢查是否傳入了共享流改用File或byte[]中文文件名亂碼編碼問題檢查filename的編碼用URLEncoder編碼文件名5.2 我踩過的三個坑第一個坑是token緩存用了本地Map結(jié)果多實例部署的時候A實例刷新了tokenB實例還在用舊的導(dǎo)致間歇性40001。后來改成Redis集中緩存問題解決。這個坑的教訓(xùn)是任何有狀態(tài)的東西在多實例環(huán)境下都要考慮一致性問題。第二個坑是文件校驗只看了擴(kuò)展名結(jié)果有個用戶上傳了一個改名為jpg的文本文件企業(yè)微信返回40004。后來加了魔數(shù)校驗讀文件前幾個字節(jié)判斷真實類型。魔數(shù)校驗的規(guī)則是JPG開頭是FFD8PNG開頭是89504E47GIF開頭是47494638。讀前8個字節(jié)就夠了。第三個坑是并發(fā)上傳同一個文件時多個線程共享了一個FileInputStream導(dǎo)致部分請求拿到空內(nèi)容。后來改成每個請求自己打開流問題解決。這個坑的教訓(xùn)是流是有狀態(tài)的不能跨線程共享。5.3 性能優(yōu)化的幾個點如果上傳頻率很高有幾個優(yōu)化點可以考慮。第一用連接池OkHttp默認(rèn)有連接池復(fù)用TCP連接減少握手開銷。第二大文件用流式上傳不要讀進(jìn)內(nèi)存OkHttp的RequestBody.create(File)就是流式的。第三token緩存用集中式緩存避免每個實例都去刷新。第四批量上傳的時候用異步OkHttp的enqueue方法可以并發(fā)發(fā)送但要注意控制并發(fā)數(shù)避免觸發(fā)限流。我實測下來單實例每秒上傳10個1MB的文件CPU和內(nèi)存都很平穩(wěn)。如果超過這個量建議做隊列削峰把上傳請求放到隊列里慢慢消費。5.4 日志與監(jiān)控上傳這種外部依賴的操作日志一定要打全。我一般記錄這幾個字段請求ID、文件大小、文件類型、耗時、結(jié)果碼。請求ID用于串聯(lián)上下游日志文件大小和類型用于分析失敗分布耗時用于發(fā)現(xiàn)性能問題結(jié)果碼用于統(tǒng)計成功率。監(jiān)控方面我會統(tǒng)計上傳成功率、平均耗時、失敗原因分布。成功率低于99%就告警平均耗時超過2秒也告警。失敗原因分布能幫你快速定位是token問題還是文件問題。注意日志里不要打media_id的完整值打前幾位就行避免泄露。也不要打access_token這個是敏感信息。5.5 關(guān)于素材類型的幾個疑問有人問過圖片能不能當(dāng)文件上傳可以type傳file就行但這樣企業(yè)微信不會做圖片處理發(fā)送的時候也是當(dāng)文件發(fā)。反過來文件能不能當(dāng)圖片上傳不行企業(yè)微信會校驗實際類型不匹配會返回40004。還有人問視頻的封面怎么處理企業(yè)微信上傳視頻接口支持傳封面但臨時素材接口不支持只有永久素材接口才支持。如果業(yè)務(wù)需要封面要么用永久素材要么自己在發(fā)送的時候處理。語音的時長限制是60秒這個是在上傳的時候校驗的超過會返回錯誤。如果你不確定音頻時長可以用FFmpeg之類的工具先探測一下或者干脆只校驗大小讓企業(yè)微信去判斷。6. 一些個人體會這套方案我在兩個項目里用過整體穩(wěn)定性不錯。最大的感受是對接外部接口優(yōu)雅的關(guān)鍵不在于代碼寫得多漂亮而在于對邊界情況的覆蓋。token過期、文件超限、網(wǎng)絡(luò)抖動、并發(fā)沖突這些才是真正消耗精力的地方。把這些問題處理好了代碼自然就優(yōu)雅了。另外一點是不要過度設(shè)計。我見過有的項目為了上傳一個文件搞了一套復(fù)雜的責(zé)任鏈加策略模式結(jié)果維護(hù)成本比收益還高。我的建議是先跑通再抽象。等你在三個地方寫了重復(fù)的上傳邏輯再考慮抽成公共模塊。過早抽象比不抽象更可怕。最后分享一個小技巧如果你不確定企業(yè)微信的接口行為可以用curl先手動調(diào)一次把請求和響應(yīng)都打出來看。比在代碼里調(diào)試快得多。比如上傳接口你可以這樣調(diào)curl -X POST https://qyapi.weixin.qq.com/cgi-bin/media/upload?access_tokenYOUR_TOKENtypeimage \ -F media/path/to/image.jpg把YOUR_TOKEN換成真實的token就能看到完整的響應(yīng)。這個方式在排查40004、40005這類錯誤的時候特別有用因為你能直接看到企業(yè)微信返回的errmsg比看代碼猜快多了。