簡(jiǎn)介面向Java后端開發(fā)者的小程序二維碼生成示例工程基于微信官方服務(wù)端能力實(shí)現(xiàn)覆蓋裂變分享、渠道推廣等常見營(yíng)銷場(chǎng)景。針對(duì)每個(gè)賬號(hào)生成專屬邀請(qǐng)二維碼的訴求系統(tǒng)梳理了5種實(shí)現(xiàn)方式并設(shè)計(jì)前端-后端API-微信API的安全調(diào)用鏈路規(guī)避secret與token泄露風(fēng)險(xiǎn)核心使用永久有效、無(wú)數(shù)量限制的getUnlimitedQRCode接口。資源包共69個(gè)文件壓縮后約53KB按Maven標(biāo)準(zhǔn)拆分主代碼、測(cè)試與資源配置包括java源碼、xml配置、properties參數(shù)文件及少量jar依賴可直接導(dǎo)入IDE運(yùn)行驗(yàn)證。已有2647人學(xué)習(xí)下載整體目錄結(jié)構(gòu)清晰便于對(duì)照不同實(shí)現(xiàn)方式在參數(shù)構(gòu)造、異常處理、返回碼校驗(yàn)上的差異理解各方案的適用邊界源碼中保留了完整應(yīng)用配置與接口調(diào)用骨架替換appid等參數(shù)即可快速集成到實(shí)際裂變活動(dòng)中對(duì)中小團(tuán)隊(duì)及個(gè)人開發(fā)者均很友好能有效降低二次開發(fā)與聯(lián)調(diào)成本。1. 生成微信小程序二維碼本質(zhì)上是一次帶 access_token 的 HTTP 請(qǐng)求做 Java 后端久了你會(huì)發(fā)現(xiàn)“生成微信小程序二維碼”這件事說(shuō)穿了就是一次帶 access_token 的 HTTP 請(qǐng)求。運(yùn)營(yíng)要的是每個(gè)用戶一張專屬碼微信官方不會(huì)提供可視化按鈕能靠的只有那幾個(gè)接口和一把 HTTP 客戶端。很多人第一反應(yīng)是找封裝好的 SDK但 SDK 封裝一多token 過(guò)期、接口報(bào)錯(cuò)反而更難排查。這篇筆記不綁定具體業(yè)務(wù)框架從 JDK 原生 HttpURLConnection 到常見的 HttpClient、OkHttp、RestTemplate、Hutool整理 5 種可落地的實(shí)現(xiàn)方式把接口選型、參數(shù)設(shè)置和踩過(guò)的坑一起說(shuō)清楚。后面涉及的代碼都保持同一個(gè)方法簽名方便你直接抄進(jìn)自己的 Service 里。2. 微信小程序二維碼接口與 AccessToken先選對(duì)接口再動(dòng)手2.1 三個(gè)官方接口的差異getwxacodeunlimit 才是主力微信官方一共給了三個(gè)生成二維碼/小程序碼的接口名字接近但限制天差地別。我見過(guò)不少新人把三個(gè)接口混著用照著 createwxaqrcode 寫了一版上線第一天就撞數(shù)量限制。所以動(dòng)手寫代碼前務(wù)必先確認(rèn)你用的是哪個(gè)接口。第一個(gè)是 getwxacodeunlimit全稱“獲取不限制數(shù)量的小程序碼”。它支持通過(guò) scene 傳入自定義參數(shù)生成數(shù)量不限制是做帶參數(shù)推廣的首選。page 參數(shù)可以指向已發(fā)布的小程序頁(yè)面也能配合 env_version 參數(shù)在開發(fā)版、體驗(yàn)版里調(diào)試。缺點(diǎn)是 scene 有長(zhǎng)度和字符限制最長(zhǎng) 32 個(gè)可見字符只支持?jǐn)?shù)字、大小寫英文和!#$()*,/:;?-._~這些特殊字符中文、空格、換行都不行。這個(gè)限制會(huì)在后面避坑部分重點(diǎn)展開。第二個(gè)是 getwxacode獲取小程序碼但不支持 scene 參數(shù)直接用 page 作為路徑。它生成的也是方形帶 logo 的小程序碼數(shù)量有限制適合某些固定頁(yè)面的低頻場(chǎng)景。第三個(gè)是 createwxaqrcode獲取小程序二維碼返回的是傳統(tǒng)二維碼樣式掃碼后跳轉(zhuǎn)指定頁(yè)面同樣有限制。這里還有一個(gè)小誤區(qū)用戶嘴上說(shuō)“要二維碼”實(shí)際要的往往是掃完能直接打開小程序的碼。getwxacodeunlimit 返回的是小程序碼為了讓用戶識(shí)別建議在需求階段就確認(rèn)清楚。選型上我的習(xí)慣是只要業(yè)務(wù)里需要按用戶或按活動(dòng)生成不同參數(shù)就統(tǒng)一用 getwxacodeunlimit。它雖然沒(méi)有傳統(tǒng)二維碼樣式但把參數(shù)放 scene后端拿到場(chǎng)景值自己解析是擴(kuò)展性和穩(wěn)定性最好的組合。下面是三接口對(duì)比建議直接收藏接口是否支持 scene數(shù)量限制返回樣式推薦場(chǎng)景getwxacodeunlimit支持不限小程序碼帶參推廣、按用戶生成getwxacode不支持有限小程序碼固定頁(yè)面、低頻createwxaqrcode不支持有限傳統(tǒng)二維碼需要舊版樣式接口調(diào)用頻率也得留意。getwxacode 和 createwxaqrcode 有累計(jì)數(shù)量限制而 getwxacodeunlimit 雖然不限總量但接口本身的 QPS 仍受官方限制不建議在循環(huán)里批量生成幾百?gòu)?。如果業(yè)務(wù)要預(yù)生成大量碼需要分批執(zhí)行控制每秒最多幾次請(qǐng)求。2.2 先用 curl 走通鏈路再寫 Java 封裝在寫 Java 代碼之前強(qiáng)烈建議先用 curl 把鏈路跑通。這樣能排掉大部分網(wǎng)絡(luò)和參數(shù)問(wèn)題也能對(duì)返回結(jié)果有一個(gè)直觀認(rèn)識(shí)。第一步是獲取 access_token微信接口文檔要求使用你的小程序 appid 和 secretGET 請(qǐng)求就行curl -s https://api.weixin.qq.com/cgi-bin/token?grant_typeclient_credentialappidAPPIDsecretAPPSECRET返回 JSON 包含 access_token 與 expires_inexpires_in 固定 7200 秒。這里有個(gè)容易忽略的點(diǎn)access_token 是 appid 維度的全局唯一值頻繁獲取會(huì)互相擠掉而且舊 token 失效前新 token 并不會(huì)立刻生效所以生產(chǎn)環(huán)境必須做緩存。后面第 5 章會(huì)專門講。拿到 access_token 后再調(diào)生成接口這一步就是 POST JSONscene、page、width 是必填參數(shù)curl -s https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_tokenTOKEN \ -H Content-Type: application/json; charsetutf-8 \ -d {scene:uid_1001,page:pages/index/index,width:430} \ -o wxacode.png如果生成的 wxacode.png 能正常打開說(shuō)明參數(shù)鏈路沒(méi)問(wèn)題接下來(lái)?yè)Q成 Java 只是換了 HTTP 客戶端。這里要強(qiáng)調(diào)微信接口雖然文檔里叫 HTTP 請(qǐng)求實(shí)際全部走 HTTPSJava 的 HTTP 請(qǐng)求庫(kù)會(huì)幫我們處理 SSL 握手不需要自己寫證書邏輯。curl 跑通之后建議再用file wxacode.png看一眼文件類型確認(rèn)是 PNG 圖片。如果返回的是 JSON大概率是參數(shù)錯(cuò)誤或者 token 失效。常見錯(cuò)誤碼可以先記住40001 表示 access_token 無(wú)效41030 表示 page 路徑無(wú)效41031 表示 scene 無(wú)效。這些錯(cuò)誤碼在 Java 里要按照 errcode 落到日志而不是只打印 HTTP 狀態(tài)碼。第 3 章的代碼都假設(shè)你已經(jīng)有有效 access_token并把生成方法統(tǒng)一為byte[] createWxACode(String accessToken, String scene, String page, int width)這樣每種客戶端只需要關(guān)注請(qǐng)求體、響應(yīng)體和異常處理。3. 5 種 Java HTTP 調(diào)用方式從原生到第三方工具庫(kù)下面的代碼示例都聚焦在“生成微信小程序碼”這一步方法簽名統(tǒng)一為byte[] createWxACode(String accessToken, String scene, String page, int width)。入?yún)⒁呀?jīng)拿到了 access_token所以代碼塊里不會(huì)再出現(xiàn)獲取 token 的邏輯。每種方式的依賴、超時(shí)配置、異常處理各不一樣我會(huì)在每個(gè)小節(jié)后面說(shuō)明。3.1 方式一JDK 原生 HttpURLConnection這是零依賴的實(shí)現(xiàn)適合不引入第三方庫(kù)的項(xiàng)目。JDK 8 的用戶需要把readAllBytes()換成手動(dòng)讀取流下面代碼以 JDK 9 為例邏輯大家都能看明白。public byte[] createWxACode(String accessToken, String scene, String page, int width) throws IOException { // 把 access_token 拼在 query 參數(shù)里這是微信接口的要求 URL url new URL(https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token accessToken); HttpURLConnection conn (HttpURLConnection) url.openConnection(); conn.setRequestMethod(POST); conn.setDoOutput(true); conn.setConnectTimeout(3000); // 連接超時(shí)單位毫秒 conn.setReadTimeout(5000); // 讀超時(shí)圖片生成一般很快5000 足夠 conn.setRequestProperty(Content-Type, application/json; charsetutf-8); // 拼 JSON 請(qǐng)求體這里沒(méi)有做 JSON 轉(zhuǎn)義實(shí)際生產(chǎn)建議用 JSON 庫(kù) String body String.format({\scene\:\%s\,\page\:\%s\,\width\:%d}, scene, page, width); try (OutputStream os conn.getOutputStream()) { os.write(body.getBytes(StandardCharsets.UTF_8)); } int responseCode conn.getResponseCode(); if (responseCode 200) { // 微信返回的是圖片二進(jìn)制流不是 JSON try (InputStream is conn.getInputStream()) { return is.readAllBytes(); } } // 非 200 時(shí)錯(cuò)誤流里一般是 JSON 錯(cuò)誤碼讀出來(lái)方便排查 try (InputStream es conn.getErrorStream()) { String errorBody new String(es.readAllBytes(), StandardCharsets.UTF_8); throw new IOException(微信接口返回失敗HTTP responseCode , body errorBody); } }邏輯說(shuō)明HttpURLConnection 打開連接后通過(guò)setDoOutput(true)聲明要寫請(qǐng)求體然后用getOutputStream()寫入 JSON 字符串。微信接口成功時(shí)返回圖片二進(jìn)制失敗時(shí)返回 JSON 錯(cuò)誤信息需要分別處理。參數(shù)說(shuō)明connectTimeout控制 TCP 連接建立時(shí)間readTimeout控制等待響應(yīng)的最長(zhǎng)時(shí)間如果你用的網(wǎng)絡(luò)環(huán)境較差可以把 5000 調(diào)到 8000但沒(méi)必要更長(zhǎng)接口通常會(huì)秒回。3.2 方式二Apache HttpClient 5Apache HttpClient 是老牌 HTTP 客戶端適合項(xiàng)目里已經(jīng)用了 httpclient 依賴的團(tuán)隊(duì)。HttpClient 5 的 API 比 4.x 更清晰連接池管理也更成熟。public byte[] createWxACode(String accessToken, String scene, String page, int width) throws Exception { // 默認(rèn)會(huì)使用連接池每次調(diào)用結(jié)束后要 close否則連接無(wú)法釋放 try (CloseableHttpClient client HttpClients.createDefault()) { HttpPost post new HttpPost(https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token accessToken); post.setHeader(Content-Type, application/json; charsetutf-8); String json String.format({\scene\:\%s\,\page\:\%s\,\width\:%d}, scene, page, width); post.setEntity(new StringEntity(json, ContentType.APPLICATION_JSON)); try (CloseableHttpResponse resp client.execute(post)) { byte[] bytes EntityUtils.toByteArray(resp.getEntity()); int status resp.getStatusLine().getStatusCode(); if (status 200) { return bytes; } throw new IOException(微信接口返回失敗HTTP status , body new String(bytes, StandardCharsets.UTF_8)); } } }這里用try-with-resources確保 HttpClient 和響應(yīng)都關(guān)閉。EntityUtils.toByteArray會(huì)把整個(gè)響應(yīng)讀進(jìn)內(nèi)存微信返回的圖片一般在幾十到幾百 KB不會(huì)有內(nèi)存壓力。如果想要更穩(wěn)健可以通過(guò)RequestConfig設(shè)置連接超時(shí)和讀取超時(shí)但示例從簡(jiǎn)生產(chǎn)環(huán)境要補(bǔ)上。對(duì)于并發(fā)較高的服務(wù)用同一個(gè) HttpClient 實(shí)例比每次 new 一個(gè)更好連接池復(fù)用是 Apache HttpClient 的核心優(yōu)勢(shì)。3.3 方式三OkHttp 4OkHttp 是 Android 和 Java 后端都很常用的 HTTP 客戶端API 簡(jiǎn)潔內(nèi)部對(duì)連接復(fù)用和超時(shí)處理做了大量?jī)?yōu)化。項(xiàng)目里如果用 OkHttp推薦優(yōu)先用它的 Builder 配置。public byte[] createWxACode(String accessToken, String scene, String page, int width) throws IOException { OkHttpClient client new OkHttpClient.Builder() .connectTimeout(3, TimeUnit.SECONDS) .readTimeout(5, TimeUnit.SECONDS) .build(); String url https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token accessToken; String json String.format({\scene\:\%s\,\page\:\%s\,\width\:%d}, scene, page, width); Request request new Request.Builder() .url(url) .post(RequestBody.create(json, MediaType.parse(application/json; charsetutf-8))) .build(); try (Response response client.newCall(request).execute()) { if (!response.isSuccessful()) { // body() 只能調(diào)用一次先取字符串再拋異常 throw new IOException(微信接口返回失敗: response.body().string()); } return response.body().bytes(); // bytes() 會(huì)把響應(yīng)體全部讀入內(nèi)存 } }OkHttp 的線程模型是異步可中斷的但這里用的是同步execute()返回后就是最終結(jié)果。注意response.body()只能調(diào)用一次所以先判斷成功再取 bytes。超時(shí)配置在 Builder 里完成connectTimeout和readTimeout與方式一的含義一致。如果你擔(dān)心 OkHttpClient 被反復(fù)創(chuàng)建可以在類里聲明為static final因?yàn)?OkHttpClient 本身就是線程安全的。3.4 方式四Spring RestTemplate如果項(xiàng)目已經(jīng)是 Spring BootRestTemplate 是很多人最早接觸的客戶端。它最大的坑是默認(rèn)消息轉(zhuǎn)換器可能把圖片二進(jìn)制當(dāng)字符串處理所以接收類型必須聲明為byte[]。public byte[] createWxACode(String accessToken, String scene, String page, int width) { // 生產(chǎn)環(huán)境建議把 RestTemplate 聲明為單例避免每次 new 浪費(fèi)性能 RestTemplate restTemplate new RestTemplate(); // 添加 ByteArrayHttpMessageConverter并放到第一位優(yōu)先處理二進(jìn)制響應(yīng) restTemplate.getMessageConverters().add(0, new ByteArrayHttpMessageConverter()); String url https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token accessToken; String json String.format({\scene\:\%s\,\page\:\%s\,\width\:%d}, scene, page, width); HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); HttpEntityString entity new HttpEntity(json, headers); ResponseEntitybyte[] response restTemplate.exchange( url, HttpMethod.POST, entity, byte[].class); if (response.getStatusCode().is2xxSuccessful()) { return response.getBody(); } throw new RuntimeException(微信接口返回失敗: HTTP response.getStatusCode()); }這里最關(guān)鍵的是new ByteArrayHttpMessageConverter()否則 RestTemplate 會(huì)根據(jù)響應(yīng)頭中的Content-Type選擇轉(zhuǎn)換器圖片的響應(yīng)頭往往不是標(biāo)準(zhǔn)的 application/jsonSpring 可能用 StringHttpMessageConverter 把它轉(zhuǎn)成亂碼字符串。把ByteArrayHttpMessageConverter放到 List 第一位能保證它優(yōu)先處理。如果你在 Spring Boot 項(xiàng)目里使用 RestTemplate最好用Bean統(tǒng)一配置而不是在方法里 new這樣也能避免多個(gè)調(diào)用點(diǎn)重復(fù)設(shè)置轉(zhuǎn)換器。3.5 方式五Hutool HttpUtilHutool 是工具集合很多項(xiàng)目已經(jīng)有它的依賴。用 HttpUtil 發(fā)請(qǐng)求非常簡(jiǎn)潔特別適合在內(nèi)部工具、定時(shí)任務(wù)里快速實(shí)現(xiàn)。public byte[] createWxACode(String accessToken, String scene, String page, int width) { String url https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token accessToken; // 這里用 Hutool 的 JSONObject 拼參數(shù)避免手寫 String.format 的轉(zhuǎn)義問(wèn)題 JSONObject body new JSONObject() .set(scene, scene) .set(page, page) .set(width, width); HttpResponse response HttpRequest.post(url) .body(body.toString()) .timeout(5000) .execute(); if (response.isOk()) { // bodyBytes() 返回原始字節(jié)流不會(huì)做字符串解碼 return response.bodyBytes(); } throw new RuntimeException(微信接口返回失敗: response.body()); }Hutool 的HttpRequest.post支持鏈?zhǔn)秸{(diào)用.body()可以傳 JSON 字符串.timeout()統(tǒng)一設(shè)置連接和讀取超時(shí)。response.isOk()判斷 HTTP 狀態(tài)碼是否為 2xx。注意這里返回的是HttpResponse需要用bodyBytes()而不是body()因?yàn)閎ody()會(huì)默認(rèn)按文本解碼圖片會(huì)被弄亂。如果你已經(jīng)依賴 Hutool這種方式是最省事的。3.6 五種方式怎么選如果你已經(jīng)把上面的代碼都看懂了選型其實(shí)就看你項(xiàng)目里的依賴現(xiàn)狀。我給一個(gè)常見選擇參考方式依賴適用場(chǎng)景我的建議HttpURLConnection無(wú)零依賴、學(xué)習(xí)或簡(jiǎn)單工具小流量可用但連接管理要自己做Apache HttpClient需要引入已用 httpclient 的團(tuán)隊(duì)連接池成熟推薦長(zhǎng)期服務(wù)OkHttp需要引入已用 OkHttp 或追求 API 簡(jiǎn)潔綜合體驗(yàn)好推薦RestTemplateSpring 項(xiàng)目自帶已在 Spring 生態(tài)注意 ByteArray 轉(zhuǎn)換器Hutool HttpUtil需要引入工具腳本、定時(shí)任務(wù)上手最快但依賴會(huì)綁 Hutool我的做法是內(nèi)部定時(shí)任務(wù)用 Hutool業(yè)務(wù)接口用 OkHttp 或 RestTemplate少一個(gè)依賴就少一分排查成本。選哪一種不重要核心是把第 4 章的參數(shù)和第 5 章的坑處理好。4. 參數(shù)與返回圖片處理scene、page、width 以及二進(jìn)制流4.1 scene、page、width 的填寫規(guī)則和常見誤解先給參數(shù)一個(gè)明確的表然后逐個(gè)拆。這是我在生產(chǎn)環(huán)境執(zhí)行了無(wú)數(shù)次的參數(shù)組合下面是關(guān)鍵參數(shù)清單參數(shù)類型必填說(shuō)明sceneString是unlimit 接口最大 32 個(gè)可見字符只能數(shù)字字母和部分符號(hào)pageString否默認(rèn)首頁(yè)頁(yè)面路徑如 pages/index/index不帶 / 和后綴widthInteger否默認(rèn) 430圖片寬度單位 px范圍 280-1280auto_colorBoolean否自動(dòng)配色true 時(shí)忽略 line_colorline_colorObject否線條顏色默認(rèn) black如 {r:0,g:0,b:0}env_versionString否release、trial、develop默認(rèn) releasescene 最容易踩坑。很多運(yùn)營(yíng)把訂單號(hào)、渠道碼、用戶ID 全塞進(jìn)去比如order202401010001userabcchannelxxx一不小心就超過(guò) 32 字符而且中文直接報(bào)錯(cuò)。正確的做法是scene 里只放一個(gè)短的業(yè)務(wù)標(biāo)識(shí)比如數(shù)據(jù)庫(kù)自增 ID或者uid_12345由后端拿到 scene 后去查真正的業(yè)務(wù)數(shù)據(jù)。如果確實(shí)要組合多個(gè)維度可以用_或-分隔但要控制在字符集和長(zhǎng)度內(nèi)。page 參數(shù)必須是小程序里真實(shí)存在的路徑不能帶.html或前導(dǎo)/也不能帶?參數(shù)。如果你在開發(fā)階段調(diào)試需要配合env_version: develop并確保這個(gè)頁(yè)面在開發(fā)者工具里已經(jīng)配置為可訪問(wèn)。width 控制圖片寬高430 在小程序碼里視覺(jué)效果最好如果嵌入到海報(bào)或長(zhǎng)圖中需要大圖可以調(diào)到 500 以上但不要超過(guò) 1280否則微信也會(huì)拒絕。在線下聯(lián)調(diào)時(shí)如果小程序頁(yè)面還沒(méi)發(fā)布getwxacodeunlimit 默認(rèn)會(huì)校驗(yàn) page 是否屬于 release 版本此時(shí)生成失敗。你需要在請(qǐng)求體里加env_versiondevelop并且保證后端使用的 appid 和小程序開發(fā)工具登錄的是同一個(gè)賬號(hào)。trial 則對(duì)應(yīng)體驗(yàn)版release 對(duì)應(yīng)正式版。這個(gè)參數(shù)容易被忽略我第一次聯(lián)調(diào)時(shí)就是被這個(gè)參數(shù)卡了一天。還可以用 line_color 指定小程序碼的顏色例如生成紅色碼。這里給一個(gè)帶顏色參數(shù)的請(qǐng)求體示例后續(xù)接口邏輯不變只是 JSON 多兩個(gè)字段String json {\scene\:\uid_12345\,\page\:\pages/index/index\,\width\:430, \auto_color\:false,\line_color\:{\r\:255,\g\:0,\b\:0}};4.2 拿到 byte[] 之后保存文件、轉(zhuǎn) Base64、直接輸出圖片流微信接口正常返回時(shí)body 是一張 PNG 圖片的二進(jìn)制流完全不是 JSON。不同業(yè)務(wù)場(chǎng)景對(duì)這份二進(jìn)制的消費(fèi)方式不同我拆成常見的三種。第一種是保存到服務(wù)器磁盤適用于定時(shí)生成、預(yù)生成文件后上傳 CDN 或 OSS 的場(chǎng)景// 保存前確保目錄存在否則會(huì)拋 NoSuchFileException byte[] bytes createWxACode(token, uid_12345, pages/index/index, 430); Path file Paths.get(/data/qr/uid_12345.png); Files.write(file, bytes);第二種是返回 Base64 字符串給前端前端可以直接放進(jìn)img srcdata:image/png;base64,...。注意要拼接data:前綴否則瀏覽器不會(huì)識(shí)別byte[] bytes createWxACode(token, uid_12345, pages/index/index, 430); String base64 Base64.getEncoder().encodeToString(bytes); // 返回給前端的就是 data:image/png;base64,xxxxxx String dataUrl data:image/png;base64, base64;第三種是后端接口直接輸出圖片流前端用img src/qrcode?scenexxx來(lái)加載。這種方式適合低頻調(diào)用每次請(qǐng)求實(shí)時(shí)生成// 偽代碼Controller 層 GetMapping(/qrcode) public void qrcode(HttpServletResponse response, RequestParam String scene) throws IOException { byte[] bytes createWxACode(token, scene, pages/index/index, 430); response.setContentType(image/png); response.getOutputStream().write(bytes); }微信接口成功時(shí) Content-Type 通常是 image/png失敗時(shí)則是 application/json。在 Java 中不要只判斷 HTTP 狀態(tài)碼因?yàn)榻涌谑∫部赡芊祷?200 但 body 是 JSON微信接口在部分錯(cuò)誤場(chǎng)景下會(huì)用 HTTP 200 返回 errcode。所以更穩(wěn)妥的做法是先讀取 byte[]然后判斷圖片魔數(shù)。PNG 文件的前四字節(jié)固定是0x89 0x50 0x4E 0x47也就是\x89PNG可以用下面的方式判斷byte[] bytes createWxACode(token, scene, page, width); if (bytes.length 4 (bytes[0] 0xFF) 0x89 bytes[1] P bytes[2] N bytes[3] G) { // 正常圖片繼續(xù)處理 } else { // 錯(cuò)誤 JSON轉(zhuǎn)字符串查看 errcode String err new String(bytes, StandardCharsets.UTF_8); log.error(微信接口錯(cuò)誤: {}, err); }三種返回方式各有取舍保存文件適合預(yù)生成Base64 適合后端接口直接返回 JSON 給前端不需要額外請(qǐng)求直接輸出流最簡(jiǎn)單但每次都要調(diào)微信流量一大就會(huì)觸發(fā)頻率限制。我建議把 Base64 和直接輸出流都作為上層選擇底層統(tǒng)一暴露byte[]這樣切起來(lái)非?？?。5. 避坑指南微信二維碼接口最常見的 4 個(gè)坑以下都是真實(shí)場(chǎng)景里反復(fù)出現(xiàn)的問(wèn)題我按“現(xiàn)象 → 原因 → 解決”的順序?qū)懨織l都可以直接對(duì)照排查。5.1 坑一access_token 在服務(wù)里頻繁失效接口報(bào) 40001現(xiàn)象生成二維碼的接口偶爾報(bào)錯(cuò)日志里出現(xiàn)errcode:40001, errmsg: invalid access_token而且不是每次失敗是隔一段時(shí)間就集中報(bào)一批。原因access_token 有效期 7200 秒但你的服務(wù)可能部署了多個(gè)節(jié)點(diǎn)每個(gè)節(jié)點(diǎn)各獲取各的 token。后拿到的 token 會(huì)把先前的擠掉但微信對(duì) token 的生效有延遲多節(jié)點(diǎn)之間會(huì)出現(xiàn)短暫的空窗期。另一個(gè)常見原因是沒(méi)有做緩存每次生成二維碼都重新調(diào) token 接口也會(huì)引發(fā) token 被刷新。解決用一個(gè)全局緩存比如 Rediskey 按 appid 區(qū)分value 存 access_token過(guò)期時(shí)間設(shè)為 7000 秒比有效期提前 200 秒刷新。如果請(qǐng)求期間發(fā)現(xiàn) token 過(guò)期加鎖重新獲取避免多個(gè)線程同時(shí)刷 token。下面是一個(gè)典型的封裝示意public String getAccessToken() { // 第一步查緩存命中就直接返回 String token redis.opsForValue().get(WX_TOKEN_KEY appid); if (token ! null) { return token; } // 第二步加鎖防止并發(fā)重復(fù)刷新 synchronized (this) { token redis.opsForValue().get(WX_TOKEN_KEY appid); if (token ! null) { return token; } // 調(diào)用微信 token 接口刷新 token fetchTokenFromWeixin(appid, secret); redis.opsForValue().set(WX_TOKEN_KEY appid, token, 7000, TimeUnit.SECONDS); } return token; }如果項(xiàng)目沒(méi)用 Redis也可以用本地內(nèi)存緩存但要注意多實(shí)例部署時(shí)每個(gè)實(shí)例的 token 可能不一致最好還是引入一個(gè)共享存儲(chǔ)。如果已經(jīng)用了 Redis 還出現(xiàn) 40001檢查多個(gè)服務(wù)實(shí)例的時(shí)鐘是否一致以及 Redis 的 key 是否被手動(dòng)刪除。這個(gè)坑不解決第 3 章的 5 種實(shí)現(xiàn)方式誰(shuí)寫都會(huì)炸。5.2 坑二scene 內(nèi)容超長(zhǎng)或帶中文接口返回 41031現(xiàn)象curl 或 Java 調(diào)用返回errcode:41031, errmsg: invalid scene。有時(shí)甚至生成成功但掃碼后小程序拿不到預(yù)期的參數(shù)。原因scene 參數(shù)被拼接得又長(zhǎng)又復(fù)雜或者里面帶了中文、空格。微信對(duì) scene 有嚴(yán)格限制最多 32 個(gè)可見字符只允許數(shù)字、字母以及!#$()*,/:;?-._~這些特殊字符。很多后端會(huì)下意識(shí)把userId123activityId456channelabcd整個(gè)塞進(jìn)去長(zhǎng)度超限。解決scene 里只放一個(gè)短 ID比如用戶表主鍵。需要傳多維度信息時(shí)可以在服務(wù)端維護(hù)一個(gè)超短隨機(jī)碼例如s 9 位隨機(jī)字符串把它和真實(shí)業(yè)務(wù)參數(shù)存到 Redis并設(shè)置過(guò)期時(shí)間。這樣 scene 永遠(yuǎn)只有 10 個(gè)字符既滿足限制又能讓掃碼后的頁(yè)面一次性拿到完整參數(shù)。// 生成短標(biāo)識(shí)作為 scene避免直接拼業(yè)務(wù)參數(shù) String scene s RandomStringUtils.randomAlphanumeric(9); redis.set(scene: scene, userId123activityId456, 300, TimeUnit.SECONDS);如果只是中文可以嘗試用英文字母替代但不建議對(duì)中文做 URL 編碼因?yàn)?scene 的總長(zhǎng)度限制按字符數(shù)算編碼后的 % 會(huì)占多個(gè)字符更容易超限。另外注意和是允許的但傳參前要對(duì)拼接后的字符串做一次長(zhǎng)度校驗(yàn)超過(guò) 32 字符直接拒絕并告警別讓它走到微信接口才報(bào)錯(cuò)。5.3 坑三page 路徑寫錯(cuò)或帶了 .html生成失敗現(xiàn)象調(diào)用接口返回errcode:41030, errmsg: invalid page或者生成了一張碼但是掃碼后提示頁(yè)面不存在。原因page 參數(shù)必須是小程序內(nèi)已存在的頁(yè)面路徑而且不能帶前導(dǎo)/不能帶.html不能帶參數(shù)。常見錯(cuò)誤是把pages/index/index.html寫進(jìn)去或者寫成了/pages/index/index。還有一個(gè)小程序端大小寫敏感的問(wèn)題路徑大小寫不匹配也會(huì)報(bào) 41030。解決先在小程序開發(fā)工具的“頁(yè)面”列表里確認(rèn)路徑復(fù)制不帶后綴的路徑。如果接口已經(jīng)報(bào) 41030先檢查路徑是否匹配。開發(fā)階段記得給請(qǐng)求體加env_version:develop否則默認(rèn) release 模式會(huì)直接校驗(yàn)線上已發(fā)布頁(yè)面本地未發(fā)布的頁(yè)面會(huì)失敗。下面是一個(gè)修復(fù)后的請(qǐng)求體示例{ scene: uid_12345, page: pages/index/index, width: 430, env_version: develop }還有一個(gè)細(xì)節(jié)page 如果不傳默認(rèn)跳小程序首頁(yè)如果你的首頁(yè)路徑不是pages/index/index最好顯式傳遞。如果想把這個(gè)參數(shù)配置化放到application.yml里不同環(huán)境用不同 path可以避免聯(lián)調(diào)時(shí)反復(fù)改代碼。5.4 坑四用 String 接收?qǐng)D片響應(yīng)得到一堆亂碼現(xiàn)象代碼里用response.body().string()或ResponseEntityString接收微信返回結(jié)果打印出來(lái)是一串亂碼或者保存后的文件不是圖片打開報(bào)錯(cuò)。原因微信接口返回的是二進(jìn)制圖片流但你用了文本解析器。比如 Hutool 的body()會(huì)按默認(rèn)編碼解碼RestTemplate 的 String 轉(zhuǎn)換器也會(huì)把字節(jié)流轉(zhuǎn)成亂碼字符串。更隱蔽的是某些 HTTP 客戶端會(huì)自動(dòng)把響應(yīng)頭里的Content-Type當(dāng)作文本類型導(dǎo)致內(nèi)部轉(zhuǎn)碼。解決統(tǒng)一用byte[]或字節(jié)數(shù)組接收響應(yīng)不要用 String。上面第 3 章代碼里我們用的readAllBytes、EntityUtils.toByteArray、response.body().bytes()、response.bodyBytes()都是正確的。如果使用 RestTemplate必須保證消息轉(zhuǎn)換器列表里ByteArrayHttpMessageConverter在最前面否則 Spring 會(huì)選 String 轉(zhuǎn)換器。排查時(shí)可以先打印響應(yīng)頭看Content-Type是不是image/png如果變成了application/json說(shuō)明接口返回了錯(cuò)誤信息而不是圖片這時(shí)候再去解碼錯(cuò)誤 JSON。6. 進(jìn)階玩法把二維碼生成做成穩(wěn)定生產(chǎn)線6.1 用 Redis 做圖片緩存按場(chǎng)景分層第 5 章的 token 緩存只是保底真正的生產(chǎn)環(huán)境我會(huì)把“二維碼圖片本身”也緩存起來(lái)。比如同一個(gè)活動(dòng)碼如果 scene 是 activityId所有用戶共用一張碼緩存 7 天都沒(méi)問(wèn)題。按用戶維度生成的碼內(nèi)容不同不能復(fù)用但也可以把生成結(jié)果存下來(lái)用戶再次請(qǐng)求時(shí)直接返回圖片字節(jié)。我在 service 層一般做兩層查詢byte[] getQrCode(String scene) { // 第一層Redis 緩存圖片字節(jié)避免重復(fù)調(diào)微信 byte[] cached redis.get(qr: scene); if (cached ! null) { return cached; } // 第二層調(diào)微信實(shí)時(shí)生成然后寫回緩存 byte[] fresh createWxACode(token, scene, pages/index/index, 430); redis.set(qr: scene, fresh, 24, TimeUnit.HOURS); return fresh; }緩存時(shí)間不要太長(zhǎng)因?yàn)樾〕绦蝽?yè)面內(nèi)容迭代后舊碼掃碼可能進(jìn)到一個(gè)報(bào)錯(cuò)頁(yè)面。一般 24 小時(shí)或按活動(dòng)周期設(shè)置。高頻活動(dòng)碼建議異步預(yù)生成而不是用戶點(diǎn)要求時(shí)才去請(qǐng)求微信。常見做法是在活動(dòng)創(chuàng)建時(shí)把需要的 scene 列表丟進(jìn)消息隊(duì)列消費(fèi)者拉取后統(tǒng)一調(diào)用微信接口生成圖片上傳到 OSS 或 CDN再把 URL 寫入數(shù)據(jù)庫(kù)。前端拿到的是一張 CDN 圖片不直接依賴微信接口。6.2 重試、監(jiān)控和最后留個(gè)習(xí)慣異步預(yù)生成也別忘了重試和監(jiān)控。微信接口失敗后延遲 1 分鐘重試并記錄錯(cuò)誤碼如果連續(xù)失敗超過(guò) 3 次郵件告警。這樣把實(shí)時(shí)調(diào)用變成了異步任務(wù)微信接口頻率限制的影響就小很多。小程序二維碼接口本身不復(fù)雜真正復(fù)雜的是 token 有效期的網(wǎng)絡(luò)問(wèn)題、參數(shù)格式的嚴(yán)格限制以及圖片流的正確消費(fèi)方式。以前我在一個(gè)業(yè)務(wù)系統(tǒng)里圖省事直接每次實(shí)時(shí)生成結(jié)果活動(dòng)流量一大微信接口報(bào)了很多超時(shí)和限流又被運(yùn)營(yíng)追著問(wèn)為什么圖片加載不出來(lái)。后來(lái)改成“Redis 緩存 異步預(yù)生成 圖片上傳 OSS”這套組合接口基本沒(méi)有打滿過(guò)微信頻率限制。每當(dāng)你準(zhǔn)備在業(yè)務(wù)代碼里直接調(diào)微信接口時(shí)多想想能不能緩存、能不能提前生成這比選哪個(gè) HTTP 客戶端更關(guān)鍵。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取