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