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