現(xiàn)方式與避坑指南)
簡(jiǎn)介這是一份圍繞微信小程序?qū)傺?qǐng)二維碼生成系統(tǒng)梳理多種服務(wù)端編碼思路的Java后端資源合集適合需要在小程序裂變、渠道推廣或獎(jiǎng)勵(lì)場(chǎng)景中落地二維碼能力的開(kāi)發(fā)者。資源基于微信官方getUnlimitedQRCode接口采用前端—后端API—微信API的調(diào)用鏈路專門(mén)解決長(zhǎng)期有效、數(shù)量不限的小程序碼生成問(wèn)題并一次性提供5種不同實(shí)現(xiàn)方式。壓縮包共含69個(gè)文件以Java源碼、XML配置與class編譯文件為主另有properties配置與依賴jar包可導(dǎo)入IDE直接閱讀或運(yùn)行整體體積僅53KB結(jié)構(gòu)精簡(jiǎn)便于快速對(duì)照不同方案的差異。已有2647人學(xué)習(xí)/下載適合具備基礎(chǔ)Spring/HTTP知識(shí)、希望減少接口對(duì)接試錯(cuò)成本的中級(jí)Java開(kāi)發(fā)者。通過(guò)該資源可掌握5種編碼思路、接口參數(shù)封裝及后端分層設(shè)計(jì)并拿到開(kāi)箱即用的全套工程模板。1. 生成微信小程序二維碼先繞過(guò)“找SDK”這個(gè)彎我見(jiàn)過(guò)不少后端同學(xué)接到這個(gè)需求后的第一反應(yīng)打開(kāi)搜索引擎找“微信小程序二維碼生成JDK”然后花半天調(diào)依賴、排版本沖突。其實(shí)這件事的正式做法非常輕——通過(guò)Java發(fā)起HTTP請(qǐng)求調(diào)用微信官方接口拿回圖片字節(jié)流落盤(pán)或者轉(zhuǎn)Base64交給前端。標(biāo)題里的“5種實(shí)現(xiàn)方式”本質(zhì)上是三個(gè)官方接口getUnlimited、getwxacode、createwxaqrcode和兩種落地形態(tài)文件落地、Base64直出的組合選錯(cuò)接口會(huì)踩數(shù)量上限的坑選錯(cuò)落地形態(tài)會(huì)被access_token和緩存折騰到懷疑人生。這篇文章我按真實(shí)落地順序跑一遍把參數(shù)差異和踩坑點(diǎn)寫(xiě)透適合正在做分銷(xiāo)海報(bào)、活動(dòng)碼、分享裂變場(chǎng)景的后端同學(xué)。2. 5種實(shí)現(xiàn)方式都繞不開(kāi)的三個(gè)官方接口先分清再動(dòng)手在小程序碼這個(gè)領(lǐng)域微信官方一共開(kāi)放了三個(gè)生成接口后續(xù)所有方案都是圍著它們轉(zhuǎn)。很多人翻車(chē)的起點(diǎn)就是沒(méi)搞清楚這三個(gè)接口的差異憑直覺(jué)挑了一個(gè)結(jié)果要么總數(shù)被限制要么動(dòng)態(tài)參數(shù)傳不進(jìn)去。所以這一章先把接口選型講明白再談代碼。2.1 getUnlimited / getwxacode / createwxaqrcode用一張表看懂差異這三個(gè)接口分別對(duì)應(yīng)“小程序碼(無(wú)限量)”“小程序碼(固定路徑)”“普通二維碼(固定路徑)”。別看都是生成一張圖業(yè)務(wù)上的差別非常大。接口生成類(lèi)型參數(shù)特點(diǎn)總量限制典型場(chǎng)景getUnlimitedgetwxacodeunlimit圓角小程序碼scene傳動(dòng)態(tài)參數(shù)最多32位page傳固定頁(yè)面路徑無(wú)總量限制用戶ID、訂單號(hào)、渠道標(biāo)識(shí)等動(dòng)態(tài)碼getwxacode圓角小程序碼path傳固定頁(yè)面路徑不支持scene動(dòng)態(tài)拼接總限額10萬(wàn)個(gè)固定頁(yè)面入口碼、線下物料長(zhǎng)期碼createwxaqrcode普通二維碼path傳固定頁(yè)面路徑不支持scene總限額10萬(wàn)個(gè)掃碼進(jìn)小程序的普通二維碼、印刷物料我在模擬項(xiàng)目X里第一次做分銷(xiāo)海報(bào)時(shí)選了getwxacode產(chǎn)品反饋“同一個(gè)碼掃出來(lái)都一樣”因?yàn)榉咒N(xiāo)海報(bào)每個(gè)用戶都要帶不同參數(shù)這種場(chǎng)景只能上getUnlimited。反過(guò)來(lái)如果你只需要一個(gè)固定的“小程序首頁(yè)入口碼”用getUnlimited反而沒(méi)必要——getwxacode夠用且語(yǔ)義更清晰。還有一個(gè)容易忽略的點(diǎn)createwxaqrcode生成的是普通二維碼不是圓角小程序碼微信識(shí)別沒(méi)問(wèn)題但視覺(jué)上和品牌規(guī)范往往對(duì)不上。如果產(chǎn)品對(duì)碼樣式有要求圓角、透明底、自定義顏色優(yōu)先考慮getwxacode和getUnlimited。另外getUnlimited支持auto_color和line_color自定義碼眼顏色做活動(dòng)視覺(jué)時(shí)比另外兩個(gè)接口靈活很多。2.2 access_token是第一個(gè)黑匣子緩存與刷新策略所有生成接口都要在URL上帶access_token而access_token是全局唯一的、有效期7200秒的憑證。它最大的坑在于不能每個(gè)請(qǐng)求都去獲取也不能快過(guò)期了才刷新更不能多個(gè)實(shí)例各刷各的。我見(jiàn)過(guò)一個(gè)團(tuán)隊(duì)在并發(fā)下把token刷崩了二維碼接口間歇性報(bào)41030。我一般用一個(gè)私有靜態(tài)類(lèi)統(tǒng)一管理token核心邏輯是“全局單例 過(guò)期前提前刷新”public class WxTokenHolder { private static volatile String token; private static volatile long expireAt; public static synchronized String get() { // token還在有效期內(nèi)直接返回 if (token ! null System.currentTimeMillis() expireAt) { return token; } // 過(guò)期或即將過(guò)期重新請(qǐng)求微信接口 // 請(qǐng)求 https://api.weixin.qq.com/cgi-bin/token?grant_typeclient_credentialappid你的appidsecret你的secret // 響應(yīng)體里解析 access_token 和 expires_in單位秒 String accessToken doRefresh(); // 偽代碼實(shí)際寫(xiě)HTTP請(qǐng)求 int expiresIn 7200; // 從接口響應(yīng)里取這里只做示例 token accessToken; expireAt System.currentTimeMillis() (expiresIn - 300) * 1000; // 提前5分鐘刷新 return token; } }邏輯說(shuō)明這里用volatile synchronized保證多線程下token只刷新一次提前300秒失效是為了避免邊界情況——token剛好在請(qǐng)求發(fā)出后過(guò)期導(dǎo)致接口調(diào)用失敗。實(shí)際項(xiàng)目中如果服務(wù)是多節(jié)點(diǎn)部署建議把token放到Redis里用SETNX加鎖防止多個(gè)節(jié)點(diǎn)同時(shí)刷新。參數(shù)上唯一需要關(guān)注的只有expires_in微信返回的是秒記得做單位換算。2.3 按團(tuán)隊(duì)情況選實(shí)現(xiàn)方式前面說(shuō)了5種實(shí)現(xiàn)方式本質(zhì)上不是5個(gè)接口而是“接口 × HTTP客戶端 × 落地形態(tài)”的組合。怎么選主要看你的項(xiàng)目里已經(jīng)有什么依賴。項(xiàng)目是輕量Java工程、不想引額外依賴用原生HttpURLConnection代碼少但連接不復(fù)用。老項(xiàng)目里已經(jīng)用了Apache HttpClient直接復(fù)用連接池管理成熟適合服務(wù)間調(diào)用多的場(chǎng)景。新項(xiàng)目、對(duì)并發(fā)有要求用OkHttp連接池和超時(shí)控制做得比較順手。Spring Boot項(xiàng)目用RestTemplate或WebClient和現(xiàn)有代碼風(fēng)格統(tǒng)一。全棧小團(tuán)隊(duì)、前端急著要圖用Hutool的HttpUtil一行代碼發(fā)出請(qǐng)求返回Base64給前端直接渲染。這五個(gè)方向就是下一章的5種實(shí)現(xiàn)方式。我不打算重復(fù)貼五遍一模一樣的token邏輯下面的代碼都默認(rèn)WxTokenHolder已經(jīng)就緒重點(diǎn)突出每種方式自己的差異。3. 用Java HTTP調(diào)微信接口5種實(shí)現(xiàn)方式與完整代碼進(jìn)入正題。先說(shuō)統(tǒng)一的前提所有請(qǐng)求都是POSTContent-Type為application/json請(qǐng)求體是JSON字符串成功時(shí)返回圖片字節(jié)流PNG失敗時(shí)返回JSON錯(cuò)誤體通常errcodeerrmsg。3.1 方式一原生HttpURLConnection getUnlimited零依賴也能跑通最適合臨時(shí)腳本、工具類(lèi)或不想引入任何依賴的后端模塊。直接看代碼public class WxQrCodeService { public byte[] createDynamicCode(String scene, String page, int width) throws IOException { String token WxTokenHolder.get(); // 動(dòng)態(tài)小程序碼接口scene傳業(yè)務(wù)參數(shù)page傳固定頁(yè)面路徑 String url https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token token; URL httpUrl new URL(url); HttpURLConnection conn (HttpURLConnection) httpUrl.openConnection(); conn.setRequestMethod(POST); conn.setDoOutput(true); conn.setConnectTimeout(5000); conn.setReadTimeout(5000); conn.setRequestProperty(Content-Type, application/json; charsetutf-8); // 構(gòu)造請(qǐng)求體注意scene最多32位page必須從pages/開(kāi)頭 JSONObject param new JSONObject(); param.put(scene, scene); param.put(page, page); param.put(width, width); param.put(check_path, false); param.put(env_version, release); try (OutputStream os conn.getOutputStream()) { os.write(param.toJSONString().getBytes(StandardCharsets.UTF_8)); os.flush(); } // 微信接口即使業(yè)務(wù)失敗HTTP狀態(tài)碼也可能返回200所以必須讀body判斷 byte[] body; try (InputStream in conn.getInputStream()) { body in.readAllBytes(); } // 返回體以{開(kāi)頭說(shuō)明是錯(cuò)誤JSON不能當(dāng)圖片使用 if (body.length 0 body[0] {) { throw new RuntimeException(微信接口報(bào)錯(cuò): new String(body, StandardCharsets.UTF_8)); } return body; } }邏輯說(shuō)明getUnlimited的scene是動(dòng)態(tài)參數(shù)的唯一入口業(yè)務(wù)側(cè)最常用的是用戶ID、訂單號(hào)這類(lèi)短標(biāo)識(shí)page固定到小程序頁(yè)面路徑。readAllBytes()在Java 9可用如果你還在Java 8自己循環(huán)讀流即可。幾個(gè)參數(shù)說(shuō)明width控制碼的邊長(zhǎng)范圍280到1280不是越大越清晰一般用430或默認(rèn)值check_path在本地開(kāi)發(fā)環(huán)境必須傳false否則接口會(huì)因?yàn)轫?yè)面未發(fā)布而報(bào)錯(cuò)env_version有三個(gè)取值release、trial、develop開(kāi)發(fā)環(huán)境想測(cè)線上邏輯時(shí)用trial。接口響應(yīng)是PNG字節(jié)流不用做任何解碼直接落盤(pán)或轉(zhuǎn)Base64都行。3.2 方式二Apache HttpClient getwxacode適合已有HttpClient的項(xiàng)目老項(xiàng)目里如果已經(jīng)用了HttpClient沒(méi)必要再引一套新依賴。getwxacode的特點(diǎn)是參數(shù)里直接傳path適合固定頁(yè)面入口碼public byte[] createFixedCode(String path, int width) throws Exception { String token WxTokenHolder.get(); CloseableHttpClient client HttpClients.createDefault(); HttpPost httpPost new HttpPost( https://api.weixin.qq.com/wxa/getwxacode?access_token token); httpPost.setHeader(Content-Type, application/json;charsetUTF-8); JSONObject param new JSONObject(); param.put(path, path); // 固定頁(yè)面路徑如 pages/index/index param.put(width, width); // 碼寬度 param.put(check_path, false); // 本地聯(lián)調(diào)必須置false httpPost.setEntity(new StringEntity(param.toJSONString(), UTF-8)); try (CloseableHttpResponse response client.execute(httpPost)) { byte[] body EntityUtils.toByteArray(response.getEntity()); // 同樣要先判斷是不是錯(cuò)誤JSON if (body.length 0 body[0] {) { throw new RuntimeException(微信接口報(bào)錯(cuò): new String(body, StandardCharsets.UTF_8)); } return body; } }邏輯說(shuō)明getwxacode和getUnlimited最大的區(qū)別是——getwxacode不帶scene參數(shù)path就是整個(gè)碼的內(nèi)容。這意味著同一個(gè)頁(yè)面同一個(gè)path生成的碼永遠(yuǎn)一樣想?yún)^(qū)分用戶?做不到它天生就不是干這個(gè)的。參數(shù)上getwxacode還支持auto_color和line_color用于定制碼的顏色。auto_color傳true時(shí)line_color失效系統(tǒng)自動(dòng)取頁(yè)面主色想完全自定義就傳auto_colorfalse以及RGB的line_color。實(shí)際做品牌物料時(shí)這個(gè)參數(shù)比標(biāo)準(zhǔn)黑碼好看不少。另一個(gè)提醒getwxacode有總數(shù)10萬(wàn)個(gè)的限制長(zhǎng)期項(xiàng)目建議做個(gè)計(jì)數(shù)器提前評(píng)估消耗速度別等碼用完了才發(fā)現(xiàn)。3.3 方式三OkHttp createwxaqrcode連接池復(fù)用適合高并發(fā)如果你的服務(wù)并發(fā)量不低OkHttp是比HttpURLConnection更穩(wěn)的選擇。連接池復(fù)用、超時(shí)更精細(xì)、響應(yīng)流處理也更安全。這里生成的是普通二維碼場(chǎng)景是線下掃碼引流public String createQrBase64(String path, int width) throws IOException { String token WxTokenHolder.get(); OkHttpClient client new OkHttpClient.Builder() .connectTimeout(5, TimeUnit.SECONDS) .readTimeout(5, TimeUnit.SECONDS) .build(); JSONObject param new JSONObject(); param.put(path, path); param.put(width, width); RequestBody requestBody RequestBody.create( MediaType.parse(application/json; charsetutf-8), param.toJSONString()); Request request new Request.Builder() .url(https://api.weixin.qq.com/cgi-bin/wxaapp/createwxaqrcode?access_token token) .post(requestBody) .build(); try (Response response client.newCall(request).execute()) { byte[] bytes response.body().bytes(); if (bytes.length 0 bytes[0] {) { throw new RuntimeException(微信接口報(bào)錯(cuò): new String(bytes, StandardCharsets.UTF_8)); } return Base64.getEncoder().encodeToString(bytes); } }邏輯說(shuō)明createwxaqrcode生成的是普通二維碼形狀不是圓角小程序碼。如果你的頁(yè)面里需要展示二維碼圖片Base64字符串可以直接放到img標(biāo)簽的src里省掉文件上傳和URL生成的環(huán)節(jié)。這里有一個(gè)容易忽略的點(diǎn)OkHttp的response.body().bytes()只能調(diào)用一次調(diào)用后流就關(guān)閉了。別先轉(zhuǎn)成字符串再轉(zhuǎn)byte[]那樣會(huì)把二進(jìn)制圖片弄壞。我見(jiàn)過(guò)同事在這里翻車(chē)——用response.body().string()去拿圖片結(jié)果全是亂碼。正確做法是直接取bytes后續(xù)要Base64再編碼。3.4 方式四RestTemplate getUnlimited 文件落盤(pán)Spring項(xiàng)目順手做法Spring項(xiàng)目里最常見(jiàn)的做法是直接用RestTemplate把小程序碼存到服務(wù)器本地或?qū)ο蟠鎯?chǔ)返回一個(gè)可訪問(wèn)的URL給前端。下面這段是生成后落盤(pán)的完整邏輯public String saveQrToFile(String scene, String page, String fileName) throws IOException { String token WxTokenHolder.get(); String url https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token token; HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); JSONObject param new JSONObject(); param.put(scene, scene); param.put(page, page); param.put(width, 430); param.put(check_path, false); HttpEntityString entity new HttpEntity(param.toJSONString(), headers); // 關(guān)鍵用byte[]接收響應(yīng)強(qiáng)制把圖片流當(dāng)二進(jìn)制處理 ResponseEntitybyte[] resp restTemplate.exchange( url, HttpMethod.POST, entity, byte[].class); if (resp.getStatusCode() ! HttpStatus.OK) { throw new IOException(HTTP狀態(tài)碼異常: resp.getStatusCode()); } byte[] body resp.getBody(); if (body null || body.length 0) { throw new IOException(二維碼圖片為空); } Files.write(Paths.get(fileName), body); return fileName; }邏輯說(shuō)明RestTemplate接收?qǐng)D片流時(shí)必須用byte[]類(lèi)型作為響應(yīng)泛型如果誤用了String類(lèi)型框架會(huì)按文本解碼圖片直接被轉(zhuǎn)成亂碼字符串。這也是為什么exchange比getForObject穩(wěn)。落盤(pán)之后一般配合Nginx或?qū)ο蟠鎯?chǔ)把文件映射成URL。需要注意文件名的設(shè)計(jì)——如果用scene作為文件名的一部分要確保scene本身不含特殊字符否則URL解析會(huì)有問(wèn)題。我習(xí)慣用“業(yè)務(wù)類(lèi)型 日期 UUID片段”來(lái)命名避免文件名沖突也方便排查。3.5 方式五Hutool HttpUtil getUnlimited Base64輸出小團(tuán)隊(duì)全棧最快路徑當(dāng)你不想寫(xiě)連接池、不想寫(xiě)資源關(guān)閉、就想快點(diǎn)把圖給到前端時(shí)Hutool絕對(duì)是我現(xiàn)在最常用的選擇。代碼縮短到極致public String createWxCodeBase64(String scene, String page) { String token WxTokenHolder.get(); String url https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token token; JSONObject param new JSONObject(); param.put(scene, scene); param.put(page, page); param.put(width, 430); param.put(check_path, false); param.put(env_version, release); // 一行代碼發(fā)起POST并拿回字節(jié)流 byte[] body HttpUtil.createPost(url) .body(param.toJSONString()) .execute() .bodyBytes(); if (body.length 0 body[0] {) { throw new RuntimeException(微信接口報(bào)錯(cuò): new String(body, StandardCharsets.UTF_8)); } // data:image/png;base64 是前端img可以直接渲染的格式 return data:image/png;base64, Base64.getEncoder().encodeToString(body); }邏輯說(shuō)明Hutool的HttpUtil簡(jiǎn)化了HTTP客戶端的使用但本質(zhì)上它還是走HTTP POST響應(yīng)處理邏輯和前面幾種方式一致。bodyBytes()拿到的就是原始字節(jié)流不用關(guān)心連接池關(guān)閉。這種Base64直出方式很適合“前端彈窗實(shí)時(shí)展示分享海報(bào)”的場(chǎng)景——后端不落盤(pán)、不產(chǎn)生臨時(shí)文件、不占用存儲(chǔ)每次請(qǐng)求實(shí)時(shí)生成。要注意的是Base64字符串比原圖大約增加33%的體積430px的小程序碼轉(zhuǎn)Base64通常也就幾KB對(duì)接口響應(yīng)影響不大。如果圖片尺寸很大建議還是落盤(pán)走CDN別用Base64傳輸。方式五是我在模擬項(xiàng)目X里給前端做分享圖功能時(shí)的最終方案聯(lián)調(diào)效率比前幾種高出一截。4. 生成小程序二維碼避坑5個(gè)翻了車(chē)才記住的坑代碼能跑通只是第一步真正折磨人的是各種隱蔽邊界。下面這5個(gè)坑我都在不同項(xiàng)目里踩過(guò)每個(gè)都是真實(shí)線上的事故不是網(wǎng)上復(fù)制來(lái)的。4.1 path填成完整URL掃碼出來(lái)一片空白現(xiàn)象碼生成成功后用戶掃出來(lái)頁(yè)面打不開(kāi)小程序直接報(bào)“頁(yè)面不存在”或白屏。原因你以為path是“https://xxx.com/pages/index/index”就原樣傳給了微信接口。但小程序碼里的path字段要求的是小程序內(nèi)部頁(yè)面路徑必須從pages/開(kāi)始完整的URL是非法值。解決把path規(guī)范成“pages/index/index”這種格式不要帶域名、不要帶http協(xié)議前綴。聯(lián)調(diào)時(shí)打開(kāi)微信開(kāi)發(fā)者工具的Console看具體報(bào)錯(cuò)它會(huì)直接告訴你“page not found”。4.2 access_token被多實(shí)例刷崩接口間歇性報(bào)41030現(xiàn)象二維碼服務(wù)運(yùn)行一段時(shí)間后接口開(kāi)始隨機(jī)報(bào)41030(invalid access_token)重啟后又恢復(fù)。原因多節(jié)點(diǎn)部署時(shí)每個(gè)節(jié)點(diǎn)各自持有token節(jié)點(diǎn)A刷新后節(jié)點(diǎn)B還在用舊token發(fā)起請(qǐng)求微信端舊token被新token頂?shù)鬊自然全部失效。解決token統(tǒng)一放到Redis里所有節(jié)點(diǎn)走同一個(gè)緩存刷新時(shí)用Redis的SETNX做鎖搶到鎖的節(jié)點(diǎn)才允許請(qǐng)求token接口。緩存過(guò)期時(shí)間不要設(shè)滿7200秒留300秒余量避免邊界過(guò)期。提示access_token本身的獲取頻率也有限制官方文檔明確建議全局緩存。服務(wù)端每次生成碼之前都先走WxTokenHolder或Redis不要重復(fù)獲取。4.3 scene參數(shù)超長(zhǎng)或帶特殊字符接口直接報(bào)錯(cuò)現(xiàn)象scene參數(shù)拼接了“用戶ID_時(shí)間戳_渠道標(biāo)識(shí)”結(jié)果接口返回40097或參數(shù)不合法。原因scene最多32位且只支持?jǐn)?shù)字、大小寫(xiě)英文、下劃線等一部分字符。超長(zhǎng)或被URL編碼后改變語(yǔ)義都會(huì)校驗(yàn)失敗。解決不要在scene里塞原始業(yè)務(wù)主鍵和長(zhǎng)字符串。常見(jiàn)做法是生成一個(gè)短碼存到Redis或數(shù)據(jù)庫(kù)把映射關(guān)系存好scene只存短碼用戶掃碼后通過(guò)短碼反查真正的業(yè)務(wù)參數(shù)。這個(gè)設(shè)計(jì)還能附帶一個(gè)好處——短碼天然適合做冷熱數(shù)據(jù)分析和埋點(diǎn)。4.4 check_pathtrue導(dǎo)致本地開(kāi)發(fā)環(huán)境生成失敗現(xiàn)象本地聯(lián)調(diào)時(shí)調(diào)用getUnlimited接口一直報(bào)“path路徑不合法”。原因check_pathtrue要求小程序頁(yè)面必須先上傳到微信后臺(tái)本地開(kāi)發(fā)環(huán)境下的頁(yè)面路徑根本不在微信的版本體系里自然校驗(yàn)失敗。解決開(kāi)發(fā)環(huán)境check_path傳false發(fā)布到線上前再改成true。如果你用env_versiondevelop配合check_pathfalse可以在開(kāi)發(fā)版小程序里正常打開(kāi)頁(yè)面進(jìn)行調(diào)試。這個(gè)參數(shù)在測(cè)試環(huán)境最容易漏改建議做成配置項(xiàng)不同環(huán)境不同取值。4.5 HTTP狀態(tài)碼是200body卻是一段JSON錯(cuò)誤現(xiàn)象圖片下載下來(lái)是0字節(jié)或者文件打不開(kāi)但HTTP狀態(tài)碼明明是200。原因微信生成接口的特點(diǎn)是——業(yè)務(wù)失敗時(shí)HTTP狀態(tài)碼依然返回200錯(cuò)誤信息放在body的JSON里。代碼里只要看到前面有if (code ! 200)就以為成功了然后把JSON錯(cuò)誤文本當(dāng)成圖片寫(xiě)入文件。解決所有實(shí)現(xiàn)方式里都要加“body開(kāi)頭是否為{”的判斷是則按錯(cuò)誤處理。這個(gè)判斷比HTTP狀態(tài)碼更可靠。我在上面五種方式的代碼里都加了這段復(fù)制到生產(chǎn)環(huán)境時(shí)千萬(wàn)別刪。5. 從“能出圖”到“能上線”二維碼生成的驗(yàn)證清單代碼寫(xiě)完了接口也調(diào)通了最后一步是驗(yàn)證。很多項(xiàng)目死在“本地能生成一張碼”和“線上穩(wěn)定生成百萬(wàn)張碼”之間的空檔。我給自己定了一套驗(yàn)證清單每次新接生成碼需求都按這個(gè)走。驗(yàn)證第一件事是文件頭。PNG圖片的前8個(gè)字節(jié)是固定標(biāo)識(shí)0x89 0x50 0x4E 0x47。批量生成的二維碼可以做一個(gè)自動(dòng)化斷言// 回歸腳本片段驗(yàn)證接口返回的確實(shí)是PNG圖片 byte[] bytes wxQrCodeService.createDynamicCode(u_10001, pages/index/index, 430); assertTrue(bytes.length 0); // PNG魔數(shù)檢查能攔下把JSON錯(cuò)誤當(dāng)圖片寫(xiě)入的翻車(chē)場(chǎng)景 assertTrue((bytes[0] 0xFF) 0x89); assertTrue((bytes[1] 0xFF) 0x50); assertTrue((bytes[2] 0xFF) 0x4E); assertTrue((bytes[3] 0xFF) 0x47);第二件事是參數(shù)邊界回歸批量化地去生成scene超長(zhǎng)、scene特殊字符、path不存在、check_path開(kāi)關(guān)切換、env_version三種取值、width極端值280和1280。不要只測(cè)正常鏈路這五個(gè)邊界能覆蓋我上面踩過(guò)的80%的坑。第三件事是真機(jī)掃碼驗(yàn)證。后端生成了碼不代表前端能正常跳轉(zhuǎn)。找兩臺(tái)不同系統(tǒng)的手機(jī)一臺(tái)掃碼進(jìn)正式版一臺(tái)掃碼進(jìn)開(kāi)發(fā)版確認(rèn)真實(shí)業(yè)務(wù)參數(shù)傳過(guò)去了。我遇到過(guò)一種情況碼生成了頁(yè)面也打開(kāi)了但scene里的下劃線在URL解析時(shí)被吃掉業(yè)務(wù)參數(shù)少了一位。這種問(wèn)題只有真機(jī)掃碼才能暴露。最后說(shuō)個(gè)習(xí)慣我會(huì)在代碼里給每個(gè)生成方法寫(xiě)一個(gè)簡(jiǎn)潔的日志包含接口名、scene、page、寬度、耗時(shí)、返回大小。上線后通過(guò)日志統(tǒng)計(jì)消耗速度——尤其是getwxacode和createwxaqrcode這類(lèi)有10萬(wàn)總量限制的接口提前預(yù)估用量比到時(shí)候被限制再補(bǔ)救舒服得多。我第一次做這個(gè)功能的時(shí)候就是沒(méi)做總量監(jiān)控活動(dòng)上線第三天碼就用完了整個(gè)團(tuán)隊(duì)手忙腳亂。后來(lái)每次做二維碼相關(guān)需求我第一件事就是確認(rèn)用的哪個(gè)接口、有沒(méi)有總量限制、日志有沒(méi)有記錄調(diào)用量。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取 Java后端生成微信小程序二維碼的5種實(shí)現(xiàn)方式與避坑指南
簡(jiǎn)介這是一份圍繞微信小程序?qū)傺?qǐng)二維碼生成系統(tǒng)梳理多種服務(wù)端編碼思路的Java后端資源合集適合需要在小程序裂變、渠道推廣或獎(jiǎng)勵(lì)場(chǎng)景中落地二維碼能力的開(kāi)發(fā)者。資源基于微信官方getUnlimitedQRCode接口采用前端—后端API—微信API的調(diào)用鏈路專門(mén)解決長(zhǎng)期有效、數(shù)量不限的小程序碼生成問(wèn)題并一次性提供5種不同實(shí)現(xiàn)方式。壓縮包共含69個(gè)文件以Java源碼、XML配置與class編譯文件為主另有properties配置與依賴jar包可導(dǎo)入IDE直接閱讀或運(yùn)行整體體積僅53KB結(jié)構(gòu)精簡(jiǎn)便于快速對(duì)照不同方案的差異。已有2647人學(xué)習(xí)/下載適合具備基礎(chǔ)Spring/HTTP知識(shí)、希望減少接口對(duì)接試錯(cuò)成本的中級(jí)Java開(kāi)發(fā)者。通過(guò)該資源可掌握5種編碼思路、接口參數(shù)封裝及后端分層設(shè)計(jì)并拿到開(kāi)箱即用的全套工程模板。1. 生成微信小程序二維碼先繞過(guò)“找SDK”這個(gè)彎我見(jiàn)過(guò)不少后端同學(xué)接到這個(gè)需求后的第一反應(yīng)打開(kāi)搜索引擎找“微信小程序二維碼生成JDK”然后花半天調(diào)依賴、排版本沖突。其實(shí)這件事的正式做法非常輕——通過(guò)Java發(fā)起HTTP請(qǐng)求調(diào)用微信官方接口拿回圖片字節(jié)流落盤(pán)或者轉(zhuǎn)Base64交給前端。標(biāo)題里的“5種實(shí)現(xiàn)方式”本質(zhì)上是三個(gè)官方接口getUnlimited、getwxacode、createwxaqrcode和兩種落地形態(tài)文件落地、Base64直出的組合選錯(cuò)接口會(huì)踩數(shù)量上限的坑選錯(cuò)落地形態(tài)會(huì)被access_token和緩存折騰到懷疑人生。這篇文章我按真實(shí)落地順序跑一遍把參數(shù)差異和踩坑點(diǎn)寫(xiě)透適合正在做分銷(xiāo)海報(bào)、活動(dòng)碼、分享裂變場(chǎng)景的后端同學(xué)。2. 5種實(shí)現(xiàn)方式都繞不開(kāi)的三個(gè)官方接口先分清再動(dòng)手在小程序碼這個(gè)領(lǐng)域微信官方一共開(kāi)放了三個(gè)生成接口后續(xù)所有方案都是圍著它們轉(zhuǎn)。很多人翻車(chē)的起點(diǎn)就是沒(méi)搞清楚這三個(gè)接口的差異憑直覺(jué)挑了一個(gè)結(jié)果要么總數(shù)被限制要么動(dòng)態(tài)參數(shù)傳不進(jìn)去。所以這一章先把接口選型講明白再談代碼。2.1 getUnlimited / getwxacode / createwxaqrcode用一張表看懂差異這三個(gè)接口分別對(duì)應(yīng)“小程序碼(無(wú)限量)”“小程序碼(固定路徑)”“普通二維碼(固定路徑)”。別看都是生成一張圖業(yè)務(wù)上的差別非常大。接口生成類(lèi)型參數(shù)特點(diǎn)總量限制典型場(chǎng)景getUnlimitedgetwxacodeunlimit圓角小程序碼scene傳動(dòng)態(tài)參數(shù)最多32位page傳固定頁(yè)面路徑無(wú)總量限制用戶ID、訂單號(hào)、渠道標(biāo)識(shí)等動(dòng)態(tài)碼getwxacode圓角小程序碼path傳固定頁(yè)面路徑不支持scene動(dòng)態(tài)拼接總限額10萬(wàn)個(gè)固定頁(yè)面入口碼、線下物料長(zhǎng)期碼createwxaqrcode普通二維碼path傳固定頁(yè)面路徑不支持scene總限額10萬(wàn)個(gè)掃碼進(jìn)小程序的普通二維碼、印刷物料我在模擬項(xiàng)目X里第一次做分銷(xiāo)海報(bào)時(shí)選了getwxacode產(chǎn)品反饋“同一個(gè)碼掃出來(lái)都一樣”因?yàn)榉咒N(xiāo)海報(bào)每個(gè)用戶都要帶不同參數(shù)這種場(chǎng)景只能上getUnlimited。反過(guò)來(lái)如果你只需要一個(gè)固定的“小程序首頁(yè)入口碼”用getUnlimited反而沒(méi)必要——getwxacode夠用且語(yǔ)義更清晰。還有一個(gè)容易忽略的點(diǎn)createwxaqrcode生成的是普通二維碼不是圓角小程序碼微信識(shí)別沒(méi)問(wèn)題但視覺(jué)上和品牌規(guī)范往往對(duì)不上。如果產(chǎn)品對(duì)碼樣式有要求圓角、透明底、自定義顏色優(yōu)先考慮getwxacode和getUnlimited。另外getUnlimited支持auto_color和line_color自定義碼眼顏色做活動(dòng)視覺(jué)時(shí)比另外兩個(gè)接口靈活很多。2.2 access_token是第一個(gè)黑匣子緩存與刷新策略所有生成接口都要在URL上帶access_token而access_token是全局唯一的、有效期7200秒的憑證。它最大的坑在于不能每個(gè)請(qǐng)求都去獲取也不能快過(guò)期了才刷新更不能多個(gè)實(shí)例各刷各的。我見(jiàn)過(guò)一個(gè)團(tuán)隊(duì)在并發(fā)下把token刷崩了二維碼接口間歇性報(bào)41030。我一般用一個(gè)私有靜態(tài)類(lèi)統(tǒng)一管理token核心邏輯是“全局單例 過(guò)期前提前刷新”public class WxTokenHolder { private static volatile String token; private static volatile long expireAt; public static synchronized String get() { // token還在有效期內(nèi)直接返回 if (token ! null System.currentTimeMillis() expireAt) { return token; } // 過(guò)期或即將過(guò)期重新請(qǐng)求微信接口 // 請(qǐng)求 https://api.weixin.qq.com/cgi-bin/token?grant_typeclient_credentialappid你的appidsecret你的secret // 響應(yīng)體里解析 access_token 和 expires_in單位秒 String accessToken doRefresh(); // 偽代碼實(shí)際寫(xiě)HTTP請(qǐng)求 int expiresIn 7200; // 從接口響應(yīng)里取這里只做示例 token accessToken; expireAt System.currentTimeMillis() (expiresIn - 300) * 1000; // 提前5分鐘刷新 return token; } }邏輯說(shuō)明這里用volatile synchronized保證多線程下token只刷新一次提前300秒失效是為了避免邊界情況——token剛好在請(qǐng)求發(fā)出后過(guò)期導(dǎo)致接口調(diào)用失敗。實(shí)際項(xiàng)目中如果服務(wù)是多節(jié)點(diǎn)部署建議把token放到Redis里用SETNX加鎖防止多個(gè)節(jié)點(diǎn)同時(shí)刷新。參數(shù)上唯一需要關(guān)注的只有expires_in微信返回的是秒記得做單位換算。2.3 按團(tuán)隊(duì)情況選實(shí)現(xiàn)方式前面說(shuō)了5種實(shí)現(xiàn)方式本質(zhì)上不是5個(gè)接口而是“接口 × HTTP客戶端 × 落地形態(tài)”的組合。怎么選主要看你的項(xiàng)目里已經(jīng)有什么依賴。項(xiàng)目是輕量Java工程、不想引額外依賴用原生HttpURLConnection代碼少但連接不復(fù)用。老項(xiàng)目里已經(jīng)用了Apache HttpClient直接復(fù)用連接池管理成熟適合服務(wù)間調(diào)用多的場(chǎng)景。新項(xiàng)目、對(duì)并發(fā)有要求用OkHttp連接池和超時(shí)控制做得比較順手。Spring Boot項(xiàng)目用RestTemplate或WebClient和現(xiàn)有代碼風(fēng)格統(tǒng)一。全棧小團(tuán)隊(duì)、前端急著要圖用Hutool的HttpUtil一行代碼發(fā)出請(qǐng)求返回Base64給前端直接渲染。這五個(gè)方向就是下一章的5種實(shí)現(xiàn)方式。我不打算重復(fù)貼五遍一模一樣的token邏輯下面的代碼都默認(rèn)WxTokenHolder已經(jīng)就緒重點(diǎn)突出每種方式自己的差異。3. 用Java HTTP調(diào)微信接口5種實(shí)現(xiàn)方式與完整代碼進(jìn)入正題。先說(shuō)統(tǒng)一的前提所有請(qǐng)求都是POSTContent-Type為application/json請(qǐng)求體是JSON字符串成功時(shí)返回圖片字節(jié)流PNG失敗時(shí)返回JSON錯(cuò)誤體通常errcodeerrmsg。3.1 方式一原生HttpURLConnection getUnlimited零依賴也能跑通最適合臨時(shí)腳本、工具類(lèi)或不想引入任何依賴的后端模塊。直接看代碼public class WxQrCodeService { public byte[] createDynamicCode(String scene, String page, int width) throws IOException { String token WxTokenHolder.get(); // 動(dòng)態(tài)小程序碼接口scene傳業(yè)務(wù)參數(shù)page傳固定頁(yè)面路徑 String url https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token token; URL httpUrl new URL(url); HttpURLConnection conn (HttpURLConnection) httpUrl.openConnection(); conn.setRequestMethod(POST); conn.setDoOutput(true); conn.setConnectTimeout(5000); conn.setReadTimeout(5000); conn.setRequestProperty(Content-Type, application/json; charsetutf-8); // 構(gòu)造請(qǐng)求體注意scene最多32位page必須從pages/開(kāi)頭 JSONObject param new JSONObject(); param.put(scene, scene); param.put(page, page); param.put(width, width); param.put(check_path, false); param.put(env_version, release); try (OutputStream os conn.getOutputStream()) { os.write(param.toJSONString().getBytes(StandardCharsets.UTF_8)); os.flush(); } // 微信接口即使業(yè)務(wù)失敗HTTP狀態(tài)碼也可能返回200所以必須讀body判斷 byte[] body; try (InputStream in conn.getInputStream()) { body in.readAllBytes(); } // 返回體以{開(kāi)頭說(shuō)明是錯(cuò)誤JSON不能當(dāng)圖片使用 if (body.length 0 body[0] {) { throw new RuntimeException(微信接口報(bào)錯(cuò): new String(body, StandardCharsets.UTF_8)); } return body; } }邏輯說(shuō)明getUnlimited的scene是動(dòng)態(tài)參數(shù)的唯一入口業(yè)務(wù)側(cè)最常用的是用戶ID、訂單號(hào)這類(lèi)短標(biāo)識(shí)page固定到小程序頁(yè)面路徑。readAllBytes()在Java 9可用如果你還在Java 8自己循環(huán)讀流即可。幾個(gè)參數(shù)說(shuō)明width控制碼的邊長(zhǎng)范圍280到1280不是越大越清晰一般用430或默認(rèn)值check_path在本地開(kāi)發(fā)環(huán)境必須傳false否則接口會(huì)因?yàn)轫?yè)面未發(fā)布而報(bào)錯(cuò)env_version有三個(gè)取值release、trial、develop開(kāi)發(fā)環(huán)境想測(cè)線上邏輯時(shí)用trial。接口響應(yīng)是PNG字節(jié)流不用做任何解碼直接落盤(pán)或轉(zhuǎn)Base64都行。3.2 方式二Apache HttpClient getwxacode適合已有HttpClient的項(xiàng)目老項(xiàng)目里如果已經(jīng)用了HttpClient沒(méi)必要再引一套新依賴。getwxacode的特點(diǎn)是參數(shù)里直接傳path適合固定頁(yè)面入口碼public byte[] createFixedCode(String path, int width) throws Exception { String token WxTokenHolder.get(); CloseableHttpClient client HttpClients.createDefault(); HttpPost httpPost new HttpPost( https://api.weixin.qq.com/wxa/getwxacode?access_token token); httpPost.setHeader(Content-Type, application/json;charsetUTF-8); JSONObject param new JSONObject(); param.put(path, path); // 固定頁(yè)面路徑如 pages/index/index param.put(width, width); // 碼寬度 param.put(check_path, false); // 本地聯(lián)調(diào)必須置false httpPost.setEntity(new StringEntity(param.toJSONString(), UTF-8)); try (CloseableHttpResponse response client.execute(httpPost)) { byte[] body EntityUtils.toByteArray(response.getEntity()); // 同樣要先判斷是不是錯(cuò)誤JSON if (body.length 0 body[0] {) { throw new RuntimeException(微信接口報(bào)錯(cuò): new String(body, StandardCharsets.UTF_8)); } return body; } }邏輯說(shuō)明getwxacode和getUnlimited最大的區(qū)別是——getwxacode不帶scene參數(shù)path就是整個(gè)碼的內(nèi)容。這意味著同一個(gè)頁(yè)面同一個(gè)path生成的碼永遠(yuǎn)一樣想?yún)^(qū)分用戶?做不到它天生就不是干這個(gè)的。參數(shù)上getwxacode還支持auto_color和line_color用于定制碼的顏色。auto_color傳true時(shí)line_color失效系統(tǒng)自動(dòng)取頁(yè)面主色想完全自定義就傳auto_colorfalse以及RGB的line_color。實(shí)際做品牌物料時(shí)這個(gè)參數(shù)比標(biāo)準(zhǔn)黑碼好看不少。另一個(gè)提醒getwxacode有總數(shù)10萬(wàn)個(gè)的限制長(zhǎng)期項(xiàng)目建議做個(gè)計(jì)數(shù)器提前評(píng)估消耗速度別等碼用完了才發(fā)現(xiàn)。3.3 方式三OkHttp createwxaqrcode連接池復(fù)用適合高并發(fā)如果你的服務(wù)并發(fā)量不低OkHttp是比HttpURLConnection更穩(wěn)的選擇。連接池復(fù)用、超時(shí)更精細(xì)、響應(yīng)流處理也更安全。這里生成的是普通二維碼場(chǎng)景是線下掃碼引流public String createQrBase64(String path, int width) throws IOException { String token WxTokenHolder.get(); OkHttpClient client new OkHttpClient.Builder() .connectTimeout(5, TimeUnit.SECONDS) .readTimeout(5, TimeUnit.SECONDS) .build(); JSONObject param new JSONObject(); param.put(path, path); param.put(width, width); RequestBody requestBody RequestBody.create( MediaType.parse(application/json; charsetutf-8), param.toJSONString()); Request request new Request.Builder() .url(https://api.weixin.qq.com/cgi-bin/wxaapp/createwxaqrcode?access_token token) .post(requestBody) .build(); try (Response response client.newCall(request).execute()) { byte[] bytes response.body().bytes(); if (bytes.length 0 bytes[0] {) { throw new RuntimeException(微信接口報(bào)錯(cuò): new String(bytes, StandardCharsets.UTF_8)); } return Base64.getEncoder().encodeToString(bytes); } }邏輯說(shuō)明createwxaqrcode生成的是普通二維碼形狀不是圓角小程序碼。如果你的頁(yè)面里需要展示二維碼圖片Base64字符串可以直接放到img標(biāo)簽的src里省掉文件上傳和URL生成的環(huán)節(jié)。這里有一個(gè)容易忽略的點(diǎn)OkHttp的response.body().bytes()只能調(diào)用一次調(diào)用后流就關(guān)閉了。別先轉(zhuǎn)成字符串再轉(zhuǎn)byte[]那樣會(huì)把二進(jìn)制圖片弄壞。我見(jiàn)過(guò)同事在這里翻車(chē)——用response.body().string()去拿圖片結(jié)果全是亂碼。正確做法是直接取bytes后續(xù)要Base64再編碼。3.4 方式四RestTemplate getUnlimited 文件落盤(pán)Spring項(xiàng)目順手做法Spring項(xiàng)目里最常見(jiàn)的做法是直接用RestTemplate把小程序碼存到服務(wù)器本地或?qū)ο蟠鎯?chǔ)返回一個(gè)可訪問(wèn)的URL給前端。下面這段是生成后落盤(pán)的完整邏輯public String saveQrToFile(String scene, String page, String fileName) throws IOException { String token WxTokenHolder.get(); String url https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token token; HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); JSONObject param new JSONObject(); param.put(scene, scene); param.put(page, page); param.put(width, 430); param.put(check_path, false); HttpEntityString entity new HttpEntity(param.toJSONString(), headers); // 關(guān)鍵用byte[]接收響應(yīng)強(qiáng)制把圖片流當(dāng)二進(jìn)制處理 ResponseEntitybyte[] resp restTemplate.exchange( url, HttpMethod.POST, entity, byte[].class); if (resp.getStatusCode() ! HttpStatus.OK) { throw new IOException(HTTP狀態(tài)碼異常: resp.getStatusCode()); } byte[] body resp.getBody(); if (body null || body.length 0) { throw new IOException(二維碼圖片為空); } Files.write(Paths.get(fileName), body); return fileName; }邏輯說(shuō)明RestTemplate接收?qǐng)D片流時(shí)必須用byte[]類(lèi)型作為響應(yīng)泛型如果誤用了String類(lèi)型框架會(huì)按文本解碼圖片直接被轉(zhuǎn)成亂碼字符串。這也是為什么exchange比getForObject穩(wěn)。落盤(pán)之后一般配合Nginx或?qū)ο蟠鎯?chǔ)把文件映射成URL。需要注意文件名的設(shè)計(jì)——如果用scene作為文件名的一部分要確保scene本身不含特殊字符否則URL解析會(huì)有問(wèn)題。我習(xí)慣用“業(yè)務(wù)類(lèi)型 日期 UUID片段”來(lái)命名避免文件名沖突也方便排查。3.5 方式五Hutool HttpUtil getUnlimited Base64輸出小團(tuán)隊(duì)全棧最快路徑當(dāng)你不想寫(xiě)連接池、不想寫(xiě)資源關(guān)閉、就想快點(diǎn)把圖給到前端時(shí)Hutool絕對(duì)是我現(xiàn)在最常用的選擇。代碼縮短到極致public String createWxCodeBase64(String scene, String page) { String token WxTokenHolder.get(); String url https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token token; JSONObject param new JSONObject(); param.put(scene, scene); param.put(page, page); param.put(width, 430); param.put(check_path, false); param.put(env_version, release); // 一行代碼發(fā)起POST并拿回字節(jié)流 byte[] body HttpUtil.createPost(url) .body(param.toJSONString()) .execute() .bodyBytes(); if (body.length 0 body[0] {) { throw new RuntimeException(微信接口報(bào)錯(cuò): new String(body, StandardCharsets.UTF_8)); } // data:image/png;base64 是前端img可以直接渲染的格式 return data:image/png;base64, Base64.getEncoder().encodeToString(body); }邏輯說(shuō)明Hutool的HttpUtil簡(jiǎn)化了HTTP客戶端的使用但本質(zhì)上它還是走HTTP POST響應(yīng)處理邏輯和前面幾種方式一致。bodyBytes()拿到的就是原始字節(jié)流不用關(guān)心連接池關(guān)閉。這種Base64直出方式很適合“前端彈窗實(shí)時(shí)展示分享海報(bào)”的場(chǎng)景——后端不落盤(pán)、不產(chǎn)生臨時(shí)文件、不占用存儲(chǔ)每次請(qǐng)求實(shí)時(shí)生成。要注意的是Base64字符串比原圖大約增加33%的體積430px的小程序碼轉(zhuǎn)Base64通常也就幾KB對(duì)接口響應(yīng)影響不大。如果圖片尺寸很大建議還是落盤(pán)走CDN別用Base64傳輸。方式五是我在模擬項(xiàng)目X里給前端做分享圖功能時(shí)的最終方案聯(lián)調(diào)效率比前幾種高出一截。4. 生成小程序二維碼避坑5個(gè)翻了車(chē)才記住的坑代碼能跑通只是第一步真正折磨人的是各種隱蔽邊界。下面這5個(gè)坑我都在不同項(xiàng)目里踩過(guò)每個(gè)都是真實(shí)線上的事故不是網(wǎng)上復(fù)制來(lái)的。4.1 path填成完整URL掃碼出來(lái)一片空白現(xiàn)象碼生成成功后用戶掃出來(lái)頁(yè)面打不開(kāi)小程序直接報(bào)“頁(yè)面不存在”或白屏。原因你以為path是“https://xxx.com/pages/index/index”就原樣傳給了微信接口。但小程序碼里的path字段要求的是小程序內(nèi)部頁(yè)面路徑必須從pages/開(kāi)始完整的URL是非法值。解決把path規(guī)范成“pages/index/index”這種格式不要帶域名、不要帶http協(xié)議前綴。聯(lián)調(diào)時(shí)打開(kāi)微信開(kāi)發(fā)者工具的Console看具體報(bào)錯(cuò)它會(huì)直接告訴你“page not found”。4.2 access_token被多實(shí)例刷崩接口間歇性報(bào)41030現(xiàn)象二維碼服務(wù)運(yùn)行一段時(shí)間后接口開(kāi)始隨機(jī)報(bào)41030(invalid access_token)重啟后又恢復(fù)。原因多節(jié)點(diǎn)部署時(shí)每個(gè)節(jié)點(diǎn)各自持有token節(jié)點(diǎn)A刷新后節(jié)點(diǎn)B還在用舊token發(fā)起請(qǐng)求微信端舊token被新token頂?shù)鬊自然全部失效。解決token統(tǒng)一放到Redis里所有節(jié)點(diǎn)走同一個(gè)緩存刷新時(shí)用Redis的SETNX做鎖搶到鎖的節(jié)點(diǎn)才允許請(qǐng)求token接口。緩存過(guò)期時(shí)間不要設(shè)滿7200秒留300秒余量避免邊界過(guò)期。提示access_token本身的獲取頻率也有限制官方文檔明確建議全局緩存。服務(wù)端每次生成碼之前都先走WxTokenHolder或Redis不要重復(fù)獲取。4.3 scene參數(shù)超長(zhǎng)或帶特殊字符接口直接報(bào)錯(cuò)現(xiàn)象scene參數(shù)拼接了“用戶ID_時(shí)間戳_渠道標(biāo)識(shí)”結(jié)果接口返回40097或參數(shù)不合法。原因scene最多32位且只支持?jǐn)?shù)字、大小寫(xiě)英文、下劃線等一部分字符。超長(zhǎng)或被URL編碼后改變語(yǔ)義都會(huì)校驗(yàn)失敗。解決不要在scene里塞原始業(yè)務(wù)主鍵和長(zhǎng)字符串。常見(jiàn)做法是生成一個(gè)短碼存到Redis或數(shù)據(jù)庫(kù)把映射關(guān)系存好scene只存短碼用戶掃碼后通過(guò)短碼反查真正的業(yè)務(wù)參數(shù)。這個(gè)設(shè)計(jì)還能附帶一個(gè)好處——短碼天然適合做冷熱數(shù)據(jù)分析和埋點(diǎn)。4.4 check_pathtrue導(dǎo)致本地開(kāi)發(fā)環(huán)境生成失敗現(xiàn)象本地聯(lián)調(diào)時(shí)調(diào)用getUnlimited接口一直報(bào)“path路徑不合法”。原因check_pathtrue要求小程序頁(yè)面必須先上傳到微信后臺(tái)本地開(kāi)發(fā)環(huán)境下的頁(yè)面路徑根本不在微信的版本體系里自然校驗(yàn)失敗。解決開(kāi)發(fā)環(huán)境check_path傳false發(fā)布到線上前再改成true。如果你用env_versiondevelop配合check_pathfalse可以在開(kāi)發(fā)版小程序里正常打開(kāi)頁(yè)面進(jìn)行調(diào)試。這個(gè)參數(shù)在測(cè)試環(huán)境最容易漏改建議做成配置項(xiàng)不同環(huán)境不同取值。4.5 HTTP狀態(tài)碼是200body卻是一段JSON錯(cuò)誤現(xiàn)象圖片下載下來(lái)是0字節(jié)或者文件打不開(kāi)但HTTP狀態(tài)碼明明是200。原因微信生成接口的特點(diǎn)是——業(yè)務(wù)失敗時(shí)HTTP狀態(tài)碼依然返回200錯(cuò)誤信息放在body的JSON里。代碼里只要看到前面有if (code ! 200)就以為成功了然后把JSON錯(cuò)誤文本當(dāng)成圖片寫(xiě)入文件。解決所有實(shí)現(xiàn)方式里都要加“body開(kāi)頭是否為{”的判斷是則按錯(cuò)誤處理。這個(gè)判斷比HTTP狀態(tài)碼更可靠。我在上面五種方式的代碼里都加了這段復(fù)制到生產(chǎn)環(huán)境時(shí)千萬(wàn)別刪。5. 從“能出圖”到“能上線”二維碼生成的驗(yàn)證清單代碼寫(xiě)完了接口也調(diào)通了最后一步是驗(yàn)證。很多項(xiàng)目死在“本地能生成一張碼”和“線上穩(wěn)定生成百萬(wàn)張碼”之間的空檔。我給自己定了一套驗(yàn)證清單每次新接生成碼需求都按這個(gè)走。驗(yàn)證第一件事是文件頭。PNG圖片的前8個(gè)字節(jié)是固定標(biāo)識(shí)0x89 0x50 0x4E 0x47。批量生成的二維碼可以做一個(gè)自動(dòng)化斷言// 回歸腳本片段驗(yàn)證接口返回的確實(shí)是PNG圖片 byte[] bytes wxQrCodeService.createDynamicCode(u_10001, pages/index/index, 430); assertTrue(bytes.length 0); // PNG魔數(shù)檢查能攔下把JSON錯(cuò)誤當(dāng)圖片寫(xiě)入的翻車(chē)場(chǎng)景 assertTrue((bytes[0] 0xFF) 0x89); assertTrue((bytes[1] 0xFF) 0x50); assertTrue((bytes[2] 0xFF) 0x4E); assertTrue((bytes[3] 0xFF) 0x47);第二件事是參數(shù)邊界回歸批量化地去生成scene超長(zhǎng)、scene特殊字符、path不存在、check_path開(kāi)關(guān)切換、env_version三種取值、width極端值280和1280。不要只測(cè)正常鏈路這五個(gè)邊界能覆蓋我上面踩過(guò)的80%的坑。第三件事是真機(jī)掃碼驗(yàn)證。后端生成了碼不代表前端能正常跳轉(zhuǎn)。找兩臺(tái)不同系統(tǒng)的手機(jī)一臺(tái)掃碼進(jìn)正式版一臺(tái)掃碼進(jìn)開(kāi)發(fā)版確認(rèn)真實(shí)業(yè)務(wù)參數(shù)傳過(guò)去了。我遇到過(guò)一種情況碼生成了頁(yè)面也打開(kāi)了但scene里的下劃線在URL解析時(shí)被吃掉業(yè)務(wù)參數(shù)少了一位。這種問(wèn)題只有真機(jī)掃碼才能暴露。最后說(shuō)個(gè)習(xí)慣我會(huì)在代碼里給每個(gè)生成方法寫(xiě)一個(gè)簡(jiǎn)潔的日志包含接口名、scene、page、寬度、耗時(shí)、返回大小。上線后通過(guò)日志統(tǒng)計(jì)消耗速度——尤其是getwxacode和createwxaqrcode這類(lèi)有10萬(wàn)總量限制的接口提前預(yù)估用量比到時(shí)候被限制再補(bǔ)救舒服得多。我第一次做這個(gè)功能的時(shí)候就是沒(méi)做總量監(jiān)控活動(dòng)上線第三天碼就用完了整個(gè)團(tuán)隊(duì)手忙腳亂。后來(lái)每次做二維碼相關(guān)需求我第一件事就是確認(rèn)用的哪個(gè)接口、有沒(méi)有總量限制、日志有沒(méi)有記錄調(diào)用量。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取