简介这是一份围绕微信小程序专属邀请二维码生成系统梳理多种服务端编码思路的Java后端资源合集适合需要在小程序裂变、渠道推广或奖励场景中落地二维码能力的开发者。资源基于微信官方getUnlimitedQRCode接口采用前端—后端API—微信API的调用链路专门解决长期有效、数量不限的小程序码生成问题并一次性提供5种不同实现方式。压缩包共含69个文件以Java源码、XML配置与class编译文件为主另有properties配置与依赖jar包可导入IDE直接阅读或运行整体体积仅53KB结构精简便于快速对照不同方案的差异。已有2647人学习/下载适合具备基础Spring/HTTP知识、希望减少接口对接试错成本的中级Java开发者。通过该资源可掌握5种编码思路、接口参数封装及后端分层设计并拿到开箱即用的全套工程模板。1. 生成微信小程序二维码先绕过“找SDK”这个弯我见过不少后端同学接到这个需求后的第一反应打开搜索引擎找“微信小程序二维码生成JDK”然后花半天调依赖、排版本冲突。其实这件事的正式做法非常轻——通过Java发起HTTP请求调用微信官方接口拿回图片字节流落盘或者转Base64交给前端。标题里的“5种实现方式”本质上是三个官方接口getUnlimited、getwxacode、createwxaqrcode和两种落地形态文件落地、Base64直出的组合选错接口会踩数量上限的坑选错落地形态会被access_token和缓存折腾到怀疑人生。这篇文章我按真实落地顺序跑一遍把参数差异和踩坑点写透适合正在做分销海报、活动码、分享裂变场景的后端同学。2. 5种实现方式都绕不开的三个官方接口先分清再动手在小程序码这个领域微信官方一共开放了三个生成接口后续所有方案都是围着它们转。很多人翻车的起点就是没搞清楚这三个接口的差异凭直觉挑了一个结果要么总数被限制要么动态参数传不进去。所以这一章先把接口选型讲明白再谈代码。2.1 getUnlimited / getwxacode / createwxaqrcode用一张表看懂差异这三个接口分别对应“小程序码(无限量)”“小程序码(固定路径)”“普通二维码(固定路径)”。别看都是生成一张图业务上的差别非常大。接口生成类型参数特点总量限制典型场景getUnlimitedgetwxacodeunlimit圆角小程序码scene传动态参数最多32位page传固定页面路径无总量限制用户ID、订单号、渠道标识等动态码getwxacode圆角小程序码path传固定页面路径不支持scene动态拼接总限额10万个固定页面入口码、线下物料长期码createwxaqrcode普通二维码path传固定页面路径不支持scene总限额10万个扫码进小程序的普通二维码、印刷物料我在模拟项目X里第一次做分销海报时选了getwxacode产品反馈“同一个码扫出来都一样”因为分销海报每个用户都要带不同参数这种场景只能上getUnlimited。反过来如果你只需要一个固定的“小程序首页入口码”用getUnlimited反而没必要——getwxacode够用且语义更清晰。还有一个容易忽略的点createwxaqrcode生成的是普通二维码不是圆角小程序码微信识别没问题但视觉上和品牌规范往往对不上。如果产品对码样式有要求圆角、透明底、自定义颜色优先考虑getwxacode和getUnlimited。另外getUnlimited支持auto_color和line_color自定义码眼颜色做活动视觉时比另外两个接口灵活很多。2.2 access_token是第一个黑匣子缓存与刷新策略所有生成接口都要在URL上带access_token而access_token是全局唯一的、有效期7200秒的凭证。它最大的坑在于不能每个请求都去获取也不能快过期了才刷新更不能多个实例各刷各的。我见过一个团队在并发下把token刷崩了二维码接口间歇性报41030。我一般用一个私有静态类统一管理token核心逻辑是“全局单例 过期前提前刷新”public class WxTokenHolder { private static volatile String token; private static volatile long expireAt; public static synchronized String get() { // token还在有效期内直接返回 if (token ! null System.currentTimeMillis() expireAt) { return token; } // 过期或即将过期重新请求微信接口 // 请求 https://api.weixin.qq.com/cgi-bin/token?grant_typeclient_credentialappid你的appidsecret你的secret // 响应体里解析 access_token 和 expires_in单位秒 String accessToken doRefresh(); // 伪代码实际写HTTP请求 int expiresIn 7200; // 从接口响应里取这里只做示例 token accessToken; expireAt System.currentTimeMillis() (expiresIn - 300) * 1000; // 提前5分钟刷新 return token; } }逻辑说明这里用volatile synchronized保证多线程下token只刷新一次提前300秒失效是为了避免边界情况——token刚好在请求发出后过期导致接口调用失败。实际项目中如果服务是多节点部署建议把token放到Redis里用SETNX加锁防止多个节点同时刷新。参数上唯一需要关注的只有expires_in微信返回的是秒记得做单位换算。2.3 按团队情况选实现方式前面说了5种实现方式本质上不是5个接口而是“接口 × HTTP客户端 × 落地形态”的组合。怎么选主要看你的项目里已经有什么依赖。项目是轻量Java工程、不想引额外依赖用原生HttpURLConnection代码少但连接不复用。老项目里已经用了Apache HttpClient直接复用连接池管理成熟适合服务间调用多的场景。新项目、对并发有要求用OkHttp连接池和超时控制做得比较顺手。Spring Boot项目用RestTemplate或WebClient和现有代码风格统一。全栈小团队、前端急着要图用Hutool的HttpUtil一行代码发出请求返回Base64给前端直接渲染。这五个方向就是下一章的5种实现方式。我不打算重复贴五遍一模一样的token逻辑下面的代码都默认WxTokenHolder已经就绪重点突出每种方式自己的差异。3. 用Java HTTP调微信接口5种实现方式与完整代码进入正题。先说统一的前提所有请求都是POSTContent-Type为application/json请求体是JSON字符串成功时返回图片字节流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(); // 动态小程序码接口scene传业务参数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); // 构造请求体注意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(); } // 微信接口即使业务失败HTTP状态码也可能返回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是动态参数的唯一入口业务侧最常用的是用户ID、订单号这类短标识page固定到小程序页面路径。readAllBytes()在Java 9可用如果你还在Java 8自己循环读流即可。几个参数说明width控制码的边长范围280到1280不是越大越清晰一般用430或默认值check_path在本地开发环境必须传false否则接口会因为页面未发布而报错env_version有三个取值release、trial、develop开发环境想测线上逻辑时用trial。接口响应是PNG字节流不用做任何解码直接落盘或转Base64都行。3.2 方式二Apache HttpClient getwxacode适合已有HttpClient的项目老项目里如果已经用了HttpClient没必要再引一套新依赖。getwxacode的特点是参数里直接传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); // 本地联调必须置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最大的区别是——getwxacode不带scene参数path就是整个码的内容。这意味着同一个页面同一个path生成的码永远一样想区分用户?做不到它天生就不是干这个的。参数上getwxacode还支持auto_color和line_color用于定制码的颜色。auto_color传true时line_color失效系统自动取页面主色想完全自定义就传auto_colorfalse以及RGB的line_color。实际做品牌物料时这个参数比标准黑码好看不少。另一个提醒getwxacode有总数10万个的限制长期项目建议做个计数器提前评估消耗速度别等码用完了才发现。3.3 方式三OkHttp createwxaqrcode连接池复用适合高并发如果你的服务并发量不低OkHttp是比HttpURLConnection更稳的选择。连接池复用、超时更精细、响应流处理也更安全。这里生成的是普通二维码场景是线下扫码引流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生成的环节。这里有一个容易忽略的点OkHttp的response.body().bytes()只能调用一次调用后流就关闭了。别先转成字符串再转byte[]那样会把二进制图片弄坏。我见过同事在这里翻车——用response.body().string()去拿图片结果全是乱码。正确做法是直接取bytes后续要Base64再编码。3.4 方式四RestTemplate getUnlimited 文件落盘Spring项目顺手做法Spring项目里最常见的做法是直接用RestTemplate把小程序码存到服务器本地或对象存储返回一个可访问的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); // 关键用byte[]接收响应强制把图片流当二进制处理 ResponseEntitybyte[] resp restTemplate.exchange( url, HttpMethod.POST, entity, byte[].class); if (resp.getStatusCode() ! HttpStatus.OK) { throw new IOException(HTTP状态码异常: 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[]类型作为响应泛型如果误用了String类型框架会按文本解码图片直接被转成乱码字符串。这也是为什么exchange比getForObject稳。落盘之后一般配合Nginx或对象存储把文件映射成URL。需要注意文件名的设计——如果用scene作为文件名的一部分要确保scene本身不含特殊字符否则URL解析会有问题。我习惯用“业务类型 日期 UUID片段”来命名避免文件名冲突也方便排查。3.5 方式五Hutool HttpUtil getUnlimited Base64输出小团队全栈最快路径当你不想写连接池、不想写资源关闭、就想快点把图给到前端时Hutool绝对是我现在最常用的选择。代码缩短到极致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); // 一行代码发起POST并拿回字节流 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客户端的使用但本质上它还是走HTTP POST响应处理逻辑和前面几种方式一致。bodyBytes()拿到的就是原始字节流不用关心连接池关闭。这种Base64直出方式很适合“前端弹窗实时展示分享海报”的场景——后端不落盘、不产生临时文件、不占用存储每次请求实时生成。要注意的是Base64字符串比原图大约增加33%的体积430px的小程序码转Base64通常也就几KB对接口响应影响不大。如果图片尺寸很大建议还是落盘走CDN别用Base64传输。方式五是我在模拟项目X里给前端做分享图功能时的最终方案联调效率比前几种高出一截。4. 生成小程序二维码避坑5个翻了车才记住的坑代码能跑通只是第一步真正折磨人的是各种隐蔽边界。下面这5个坑我都在不同项目里踩过每个都是真实线上的事故不是网上复制来的。4.1 path填成完整URL扫码出来一片空白现象码生成成功后用户扫出来页面打不开小程序直接报“页面不存在”或白屏。原因你以为path是“https://xxx.com/pages/index/index”就原样传给了微信接口。但小程序码里的path字段要求的是小程序内部页面路径必须从pages/开始完整的URL是非法值。解决把path规范成“pages/index/index”这种格式不要带域名、不要带http协议前缀。联调时打开微信开发者工具的Console看具体报错它会直接告诉你“page not found”。4.2 access_token被多实例刷崩接口间歇性报41030现象二维码服务运行一段时间后接口开始随机报41030(invalid access_token)重启后又恢复。原因多节点部署时每个节点各自持有token节点A刷新后节点B还在用旧token发起请求微信端旧token被新token顶掉B自然全部失效。解决token统一放到Redis里所有节点走同一个缓存刷新时用Redis的SETNX做锁抢到锁的节点才允许请求token接口。缓存过期时间不要设满7200秒留300秒余量避免边界过期。提示access_token本身的获取频率也有限制官方文档明确建议全局缓存。服务端每次生成码之前都先走WxTokenHolder或Redis不要重复获取。4.3 scene参数超长或带特殊字符接口直接报错现象scene参数拼接了“用户ID_时间戳_渠道标识”结果接口返回40097或参数不合法。原因scene最多32位且只支持数字、大小写英文、下划线等一部分字符。超长或被URL编码后改变语义都会校验失败。解决不要在scene里塞原始业务主键和长字符串。常见做法是生成一个短码存到Redis或数据库把映射关系存好scene只存短码用户扫码后通过短码反查真正的业务参数。这个设计还能附带一个好处——短码天然适合做冷热数据分析和埋点。4.4 check_pathtrue导致本地开发环境生成失败现象本地联调时调用getUnlimited接口一直报“path路径不合法”。原因check_pathtrue要求小程序页面必须先上传到微信后台本地开发环境下的页面路径根本不在微信的版本体系里自然校验失败。解决开发环境check_path传false发布到线上前再改成true。如果你用env_versiondevelop配合check_pathfalse可以在开发版小程序里正常打开页面进行调试。这个参数在测试环境最容易漏改建议做成配置项不同环境不同取值。4.5 HTTP状态码是200body却是一段JSON错误现象图片下载下来是0字节或者文件打不开但HTTP状态码明明是200。原因微信生成接口的特点是——业务失败时HTTP状态码依然返回200错误信息放在body的JSON里。代码里只要看到前面有if (code ! 200)就以为成功了然后把JSON错误文本当成图片写入文件。解决所有实现方式里都要加“body开头是否为{”的判断是则按错误处理。这个判断比HTTP状态码更可靠。我在上面五种方式的代码里都加了这段复制到生产环境时千万别删。5. 从“能出图”到“能上线”二维码生成的验证清单代码写完了接口也调通了最后一步是验证。很多项目死在“本地能生成一张码”和“线上稳定生成百万张码”之间的空档。我给自己定了一套验证清单每次新接生成码需求都按这个走。验证第一件事是文件头。PNG图片的前8个字节是固定标识0x89 0x50 0x4E 0x47。批量生成的二维码可以做一个自动化断言// 回归脚本片段验证接口返回的确实是PNG图片 byte[] bytes wxQrCodeService.createDynamicCode(u_10001, pages/index/index, 430); assertTrue(bytes.length 0); // PNG魔数检查能拦下把JSON错误当图片写入的翻车场景 assertTrue((bytes[0] 0xFF) 0x89); assertTrue((bytes[1] 0xFF) 0x50); assertTrue((bytes[2] 0xFF) 0x4E); assertTrue((bytes[3] 0xFF) 0x47);第二件事是参数边界回归批量化地去生成scene超长、scene特殊字符、path不存在、check_path开关切换、env_version三种取值、width极端值280和1280。不要只测正常链路这五个边界能覆盖我上面踩过的80%的坑。第三件事是真机扫码验证。后端生成了码不代表前端能正常跳转。找两台不同系统的手机一台扫码进正式版一台扫码进开发版确认真实业务参数传过去了。我遇到过一种情况码生成了页面也打开了但scene里的下划线在URL解析时被吃掉业务参数少了一位。这种问题只有真机扫码才能暴露。最后说个习惯我会在代码里给每个生成方法写一个简洁的日志包含接口名、scene、page、宽度、耗时、返回大小。上线后通过日志统计消耗速度——尤其是getwxacode和createwxaqrcode这类有10万总量限制的接口提前预估用量比到时候被限制再补救舒服得多。我第一次做这个功能的时候就是没做总量监控活动上线第三天码就用完了整个团队手忙脚乱。后来每次做二维码相关需求我第一件事就是确认用的哪个接口、有没有总量限制、日志有没有记录调用量。希望帮到你。本文还有配套的精品资源点击获取 Java后端生成微信小程序二维码的5种实现方式与避坑指南
简介这是一份围绕微信小程序专属邀请二维码生成系统梳理多种服务端编码思路的Java后端资源合集适合需要在小程序裂变、渠道推广或奖励场景中落地二维码能力的开发者。资源基于微信官方getUnlimitedQRCode接口采用前端—后端API—微信API的调用链路专门解决长期有效、数量不限的小程序码生成问题并一次性提供5种不同实现方式。压缩包共含69个文件以Java源码、XML配置与class编译文件为主另有properties配置与依赖jar包可导入IDE直接阅读或运行整体体积仅53KB结构精简便于快速对照不同方案的差异。已有2647人学习/下载适合具备基础Spring/HTTP知识、希望减少接口对接试错成本的中级Java开发者。通过该资源可掌握5种编码思路、接口参数封装及后端分层设计并拿到开箱即用的全套工程模板。1. 生成微信小程序二维码先绕过“找SDK”这个弯我见过不少后端同学接到这个需求后的第一反应打开搜索引擎找“微信小程序二维码生成JDK”然后花半天调依赖、排版本冲突。其实这件事的正式做法非常轻——通过Java发起HTTP请求调用微信官方接口拿回图片字节流落盘或者转Base64交给前端。标题里的“5种实现方式”本质上是三个官方接口getUnlimited、getwxacode、createwxaqrcode和两种落地形态文件落地、Base64直出的组合选错接口会踩数量上限的坑选错落地形态会被access_token和缓存折腾到怀疑人生。这篇文章我按真实落地顺序跑一遍把参数差异和踩坑点写透适合正在做分销海报、活动码、分享裂变场景的后端同学。2. 5种实现方式都绕不开的三个官方接口先分清再动手在小程序码这个领域微信官方一共开放了三个生成接口后续所有方案都是围着它们转。很多人翻车的起点就是没搞清楚这三个接口的差异凭直觉挑了一个结果要么总数被限制要么动态参数传不进去。所以这一章先把接口选型讲明白再谈代码。2.1 getUnlimited / getwxacode / createwxaqrcode用一张表看懂差异这三个接口分别对应“小程序码(无限量)”“小程序码(固定路径)”“普通二维码(固定路径)”。别看都是生成一张图业务上的差别非常大。接口生成类型参数特点总量限制典型场景getUnlimitedgetwxacodeunlimit圆角小程序码scene传动态参数最多32位page传固定页面路径无总量限制用户ID、订单号、渠道标识等动态码getwxacode圆角小程序码path传固定页面路径不支持scene动态拼接总限额10万个固定页面入口码、线下物料长期码createwxaqrcode普通二维码path传固定页面路径不支持scene总限额10万个扫码进小程序的普通二维码、印刷物料我在模拟项目X里第一次做分销海报时选了getwxacode产品反馈“同一个码扫出来都一样”因为分销海报每个用户都要带不同参数这种场景只能上getUnlimited。反过来如果你只需要一个固定的“小程序首页入口码”用getUnlimited反而没必要——getwxacode够用且语义更清晰。还有一个容易忽略的点createwxaqrcode生成的是普通二维码不是圆角小程序码微信识别没问题但视觉上和品牌规范往往对不上。如果产品对码样式有要求圆角、透明底、自定义颜色优先考虑getwxacode和getUnlimited。另外getUnlimited支持auto_color和line_color自定义码眼颜色做活动视觉时比另外两个接口灵活很多。2.2 access_token是第一个黑匣子缓存与刷新策略所有生成接口都要在URL上带access_token而access_token是全局唯一的、有效期7200秒的凭证。它最大的坑在于不能每个请求都去获取也不能快过期了才刷新更不能多个实例各刷各的。我见过一个团队在并发下把token刷崩了二维码接口间歇性报41030。我一般用一个私有静态类统一管理token核心逻辑是“全局单例 过期前提前刷新”public class WxTokenHolder { private static volatile String token; private static volatile long expireAt; public static synchronized String get() { // token还在有效期内直接返回 if (token ! null System.currentTimeMillis() expireAt) { return token; } // 过期或即将过期重新请求微信接口 // 请求 https://api.weixin.qq.com/cgi-bin/token?grant_typeclient_credentialappid你的appidsecret你的secret // 响应体里解析 access_token 和 expires_in单位秒 String accessToken doRefresh(); // 伪代码实际写HTTP请求 int expiresIn 7200; // 从接口响应里取这里只做示例 token accessToken; expireAt System.currentTimeMillis() (expiresIn - 300) * 1000; // 提前5分钟刷新 return token; } }逻辑说明这里用volatile synchronized保证多线程下token只刷新一次提前300秒失效是为了避免边界情况——token刚好在请求发出后过期导致接口调用失败。实际项目中如果服务是多节点部署建议把token放到Redis里用SETNX加锁防止多个节点同时刷新。参数上唯一需要关注的只有expires_in微信返回的是秒记得做单位换算。2.3 按团队情况选实现方式前面说了5种实现方式本质上不是5个接口而是“接口 × HTTP客户端 × 落地形态”的组合。怎么选主要看你的项目里已经有什么依赖。项目是轻量Java工程、不想引额外依赖用原生HttpURLConnection代码少但连接不复用。老项目里已经用了Apache HttpClient直接复用连接池管理成熟适合服务间调用多的场景。新项目、对并发有要求用OkHttp连接池和超时控制做得比较顺手。Spring Boot项目用RestTemplate或WebClient和现有代码风格统一。全栈小团队、前端急着要图用Hutool的HttpUtil一行代码发出请求返回Base64给前端直接渲染。这五个方向就是下一章的5种实现方式。我不打算重复贴五遍一模一样的token逻辑下面的代码都默认WxTokenHolder已经就绪重点突出每种方式自己的差异。3. 用Java HTTP调微信接口5种实现方式与完整代码进入正题。先说统一的前提所有请求都是POSTContent-Type为application/json请求体是JSON字符串成功时返回图片字节流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(); // 动态小程序码接口scene传业务参数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); // 构造请求体注意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(); } // 微信接口即使业务失败HTTP状态码也可能返回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是动态参数的唯一入口业务侧最常用的是用户ID、订单号这类短标识page固定到小程序页面路径。readAllBytes()在Java 9可用如果你还在Java 8自己循环读流即可。几个参数说明width控制码的边长范围280到1280不是越大越清晰一般用430或默认值check_path在本地开发环境必须传false否则接口会因为页面未发布而报错env_version有三个取值release、trial、develop开发环境想测线上逻辑时用trial。接口响应是PNG字节流不用做任何解码直接落盘或转Base64都行。3.2 方式二Apache HttpClient getwxacode适合已有HttpClient的项目老项目里如果已经用了HttpClient没必要再引一套新依赖。getwxacode的特点是参数里直接传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); // 本地联调必须置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最大的区别是——getwxacode不带scene参数path就是整个码的内容。这意味着同一个页面同一个path生成的码永远一样想区分用户?做不到它天生就不是干这个的。参数上getwxacode还支持auto_color和line_color用于定制码的颜色。auto_color传true时line_color失效系统自动取页面主色想完全自定义就传auto_colorfalse以及RGB的line_color。实际做品牌物料时这个参数比标准黑码好看不少。另一个提醒getwxacode有总数10万个的限制长期项目建议做个计数器提前评估消耗速度别等码用完了才发现。3.3 方式三OkHttp createwxaqrcode连接池复用适合高并发如果你的服务并发量不低OkHttp是比HttpURLConnection更稳的选择。连接池复用、超时更精细、响应流处理也更安全。这里生成的是普通二维码场景是线下扫码引流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生成的环节。这里有一个容易忽略的点OkHttp的response.body().bytes()只能调用一次调用后流就关闭了。别先转成字符串再转byte[]那样会把二进制图片弄坏。我见过同事在这里翻车——用response.body().string()去拿图片结果全是乱码。正确做法是直接取bytes后续要Base64再编码。3.4 方式四RestTemplate getUnlimited 文件落盘Spring项目顺手做法Spring项目里最常见的做法是直接用RestTemplate把小程序码存到服务器本地或对象存储返回一个可访问的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); // 关键用byte[]接收响应强制把图片流当二进制处理 ResponseEntitybyte[] resp restTemplate.exchange( url, HttpMethod.POST, entity, byte[].class); if (resp.getStatusCode() ! HttpStatus.OK) { throw new IOException(HTTP状态码异常: 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[]类型作为响应泛型如果误用了String类型框架会按文本解码图片直接被转成乱码字符串。这也是为什么exchange比getForObject稳。落盘之后一般配合Nginx或对象存储把文件映射成URL。需要注意文件名的设计——如果用scene作为文件名的一部分要确保scene本身不含特殊字符否则URL解析会有问题。我习惯用“业务类型 日期 UUID片段”来命名避免文件名冲突也方便排查。3.5 方式五Hutool HttpUtil getUnlimited Base64输出小团队全栈最快路径当你不想写连接池、不想写资源关闭、就想快点把图给到前端时Hutool绝对是我现在最常用的选择。代码缩短到极致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); // 一行代码发起POST并拿回字节流 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客户端的使用但本质上它还是走HTTP POST响应处理逻辑和前面几种方式一致。bodyBytes()拿到的就是原始字节流不用关心连接池关闭。这种Base64直出方式很适合“前端弹窗实时展示分享海报”的场景——后端不落盘、不产生临时文件、不占用存储每次请求实时生成。要注意的是Base64字符串比原图大约增加33%的体积430px的小程序码转Base64通常也就几KB对接口响应影响不大。如果图片尺寸很大建议还是落盘走CDN别用Base64传输。方式五是我在模拟项目X里给前端做分享图功能时的最终方案联调效率比前几种高出一截。4. 生成小程序二维码避坑5个翻了车才记住的坑代码能跑通只是第一步真正折磨人的是各种隐蔽边界。下面这5个坑我都在不同项目里踩过每个都是真实线上的事故不是网上复制来的。4.1 path填成完整URL扫码出来一片空白现象码生成成功后用户扫出来页面打不开小程序直接报“页面不存在”或白屏。原因你以为path是“https://xxx.com/pages/index/index”就原样传给了微信接口。但小程序码里的path字段要求的是小程序内部页面路径必须从pages/开始完整的URL是非法值。解决把path规范成“pages/index/index”这种格式不要带域名、不要带http协议前缀。联调时打开微信开发者工具的Console看具体报错它会直接告诉你“page not found”。4.2 access_token被多实例刷崩接口间歇性报41030现象二维码服务运行一段时间后接口开始随机报41030(invalid access_token)重启后又恢复。原因多节点部署时每个节点各自持有token节点A刷新后节点B还在用旧token发起请求微信端旧token被新token顶掉B自然全部失效。解决token统一放到Redis里所有节点走同一个缓存刷新时用Redis的SETNX做锁抢到锁的节点才允许请求token接口。缓存过期时间不要设满7200秒留300秒余量避免边界过期。提示access_token本身的获取频率也有限制官方文档明确建议全局缓存。服务端每次生成码之前都先走WxTokenHolder或Redis不要重复获取。4.3 scene参数超长或带特殊字符接口直接报错现象scene参数拼接了“用户ID_时间戳_渠道标识”结果接口返回40097或参数不合法。原因scene最多32位且只支持数字、大小写英文、下划线等一部分字符。超长或被URL编码后改变语义都会校验失败。解决不要在scene里塞原始业务主键和长字符串。常见做法是生成一个短码存到Redis或数据库把映射关系存好scene只存短码用户扫码后通过短码反查真正的业务参数。这个设计还能附带一个好处——短码天然适合做冷热数据分析和埋点。4.4 check_pathtrue导致本地开发环境生成失败现象本地联调时调用getUnlimited接口一直报“path路径不合法”。原因check_pathtrue要求小程序页面必须先上传到微信后台本地开发环境下的页面路径根本不在微信的版本体系里自然校验失败。解决开发环境check_path传false发布到线上前再改成true。如果你用env_versiondevelop配合check_pathfalse可以在开发版小程序里正常打开页面进行调试。这个参数在测试环境最容易漏改建议做成配置项不同环境不同取值。4.5 HTTP状态码是200body却是一段JSON错误现象图片下载下来是0字节或者文件打不开但HTTP状态码明明是200。原因微信生成接口的特点是——业务失败时HTTP状态码依然返回200错误信息放在body的JSON里。代码里只要看到前面有if (code ! 200)就以为成功了然后把JSON错误文本当成图片写入文件。解决所有实现方式里都要加“body开头是否为{”的判断是则按错误处理。这个判断比HTTP状态码更可靠。我在上面五种方式的代码里都加了这段复制到生产环境时千万别删。5. 从“能出图”到“能上线”二维码生成的验证清单代码写完了接口也调通了最后一步是验证。很多项目死在“本地能生成一张码”和“线上稳定生成百万张码”之间的空档。我给自己定了一套验证清单每次新接生成码需求都按这个走。验证第一件事是文件头。PNG图片的前8个字节是固定标识0x89 0x50 0x4E 0x47。批量生成的二维码可以做一个自动化断言// 回归脚本片段验证接口返回的确实是PNG图片 byte[] bytes wxQrCodeService.createDynamicCode(u_10001, pages/index/index, 430); assertTrue(bytes.length 0); // PNG魔数检查能拦下把JSON错误当图片写入的翻车场景 assertTrue((bytes[0] 0xFF) 0x89); assertTrue((bytes[1] 0xFF) 0x50); assertTrue((bytes[2] 0xFF) 0x4E); assertTrue((bytes[3] 0xFF) 0x47);第二件事是参数边界回归批量化地去生成scene超长、scene特殊字符、path不存在、check_path开关切换、env_version三种取值、width极端值280和1280。不要只测正常链路这五个边界能覆盖我上面踩过的80%的坑。第三件事是真机扫码验证。后端生成了码不代表前端能正常跳转。找两台不同系统的手机一台扫码进正式版一台扫码进开发版确认真实业务参数传过去了。我遇到过一种情况码生成了页面也打开了但scene里的下划线在URL解析时被吃掉业务参数少了一位。这种问题只有真机扫码才能暴露。最后说个习惯我会在代码里给每个生成方法写一个简洁的日志包含接口名、scene、page、宽度、耗时、返回大小。上线后通过日志统计消耗速度——尤其是getwxacode和createwxaqrcode这类有10万总量限制的接口提前预估用量比到时候被限制再补救舒服得多。我第一次做这个功能的时候就是没做总量监控活动上线第三天码就用完了整个团队手忙脚乱。后来每次做二维码相关需求我第一件事就是确认用的哪个接口、有没有总量限制、日志有没有记录调用量。希望帮到你。本文还有配套的精品资源点击获取