1. 为什么 AccessToken 是整个小程序服务端的地基做过微信小程序后端对接的人都有一个共识AccessToken 这东西看起来只是调一个接口拿一串字符串但它几乎是所有服务端能力的“总钥匙”。你后面要发订阅消息、要做内容安全检测、要生成小程序码、要拉用户手机号、要搞支付回调后的对账全都绕不开它。我在实际项目里踩过最惨的一次坑就是早期没把 AccessToken 的获取和刷新当回事结果线上跑了两天突然所有消息推送全部失败排查了半天才发现是多个业务模块各自去调微信接口刷新 token互相把对方的 token 顶掉了。所以这篇内容我想聊的不是“怎么调一个 HTTP 接口”这么浅的东西而是围绕SpringBoot 整合微信小程序获取 AccessToken这件事把背后的设计思路、缓存策略、并发问题、刷新机制、异常兜底、以及实际落地时那些文档里不会写的细节完整地拆一遍。适合正在做小程序后端、或者准备把小程序能力接入到现有 Java 服务体系里的开发者。不管你是刚接触微信生态的新手还是已经写过几版但总觉得不够稳的老手这里面的取舍逻辑应该都能给你一些参考。先明确一个基础认知微信小程序的 AccessToken 是应用级别的全局凭证不是用户级别的。也就是说你的整个小程序服务端在任意时刻理论上只应该维护一份有效的 token。它默认有效期是 7200 秒也就是两小时。微信官方对刷新次数也有限制频繁刷新会导致旧 token 失效甚至触发调用频率风控。这就决定了我们的核心目标不是“每次用的时候去拿”而是“拿一次缓存起来快过期了再换并且保证多线程、多实例环境下不会打架”。这个目标听起来简单但真正落地时会牵扯出一堆问题缓存放本地还是放 Redis多台服务器怎么保证只有一台去刷新刷新的时候正好有请求进来怎么办token 失效了怎么自动重试这些才是这篇博文真正要解决的东西。2. 整体方案设计与技术选型思路2.1 为什么不能“用一次拿一次”很多新手的第一版代码是这样的写一个工具方法每次业务需要 token 的时候就现场调一次微信的 token 接口。本地测试完全没问题因为就你一个人在点。但一上线就出事了。原因有三层。第一层是性能每次业务请求都多一次外部 HTTP 调用微信接口本身有网络延迟你的接口响应时间会被硬生生拉长几百毫秒。第二层是频率限制微信对 token 接口的调用是有频次约束的高频调用会被限制。第三层也是最致命的token 互踢微信在生成新 token 时会让上一个 token 失效。如果你有两个请求几乎同时去刷新A 拿到新 token 的同时 B 也拿到一个新 token那么 A 手里的那个瞬间就废了。业务上表现就是“时好时坏”这种 bug 最难查。所以正确的思路一定是集中获取、统一缓存、定时或惰性刷新、全局共享。2.2 缓存介质怎么选本地缓存 vs Redis这是方案设计里第一个要拍板的事。我的建议很明确单机部署可以用本地缓存但只要涉及多实例部署必须上 Redis。本地缓存比如用ConcurrentHashMap或者 Caffeine的优点是快、无外部依赖、实现简单。但它的致命问题是每台服务器都有一份自己的 token多台机器就会各自去刷新又回到了互踢的老问题。除非你做了单点刷新加广播同步否则多实例下本地缓存就是个坑。Redis 方案则是把 token 存成全局唯一的一份所有实例共享。配合分布式锁可以保证同一时刻只有一台机器去刷新。这是生产环境的标准做法。下面这张表可以帮你快速决策部署形态推荐缓存刷新协调方式风险点单机单实例本地缓存单机锁即可重启后需重新获取多实例无状态Redis分布式锁锁超时、网络抖动多实例高并发Redis本地二级缓存分布式锁本地兜底本地与 Redis 短暂不一致我个人的习惯是Redis 作为权威存储本地再放一个短时效的副本读取时优先读本地本地没有或快过期了再读 Redis。这样既减少了 Redis 的网络往返又保证了全局一致性。不过对于大多数中小项目直接用 Redis 就够了别过度设计。2.3 刷新策略定时刷新还是惰性刷新刷新策略有两种主流做法。定时刷新是起一个定时任务比如每 100 分钟刷一次保证 token 永远新鲜。惰性刷新是不主动刷等业务来取的时候判断是否快过期快过期了才去刷。定时刷新的问题是如果你的服务半夜没人用它照样在刷浪费调用次数而且如果定时任务所在的机器挂了刷新就断了。惰性刷新的问题是如果正好在过期临界点来了大量并发请求可能触发多次刷新。我的实战选择是两者结合以惰性刷新为主在获取 token 的方法里判断剩余有效期低于阈值比如还剩 5 分钟就触发刷新同时加一个兜底的定时任务比如每小时检查一次防止长期无请求导致 token 静默过期后第一次请求变慢。这个组合在我几个项目里跑下来都很稳。3. 核心细节解析与实操要点3.1 微信 token 接口的关键参数与返回结构先把接口本身说清楚。获取小程序 AccessToken 的接口是 GET 请求核心参数就三个grant_type固定为client_credentialappid是小程序的唯一标识secret是小程序密钥。返回是一个 JSON成功时包含access_token和expires_in失败时包含errcode和errmsg。这里有几个细节必须注意。第一appid和secret绝对不能硬编码在代码里更不能提交到代码仓库。我见过太多项目把 secret 直接写在application.yml里然后推到公开仓库这是重大安全隐患。正确做法是通过环境变量、配置中心或者加密配置注入。第二expires_in虽然官方说是 7200但千万不要直接用 7200 作为缓存时间一定要留出安全余量我一般用expires_in - 300也就是提前 5 分钟过期。第三返回的errcode为 0 或者不存在时才代表成功其他值都要当作异常处理尤其是 40001token 无效和 40164IP 白名单问题。public class AccessTokenResponse { private String access_token; private Integer expires_in; private Integer errcode; private String errmsg; // getter/setter 省略 }3.2 用 RestTemplate 还是 HttpClient 还是 OkHttpSpringBoot 项目里调外部 HTTP 接口常见选择有RestTemplate、WebClient、OkHttp、HttpClient。我的建议是如果项目已经是 SpringBoot 体系优先用 RestTemplate 或 WebClient减少额外依赖。RestTemplate 是同步阻塞的写法简单适合这种低频调用两小时才一次。WebClient 是响应式的适合高并发场景但引入 WebFlux 依赖对很多项目来说是杀鸡用牛刀。OkHttp 性能好、连接池管理优秀但需要额外引入依赖。考虑到 token 获取是低频操作性能根本不是瓶颈我倾向于用 RestTemplate配置好超时时间就行。超时设置很关键连接超时和读取超时都建议设成 3 到 5 秒避免微信接口抖动时把你的线程池拖垮。Bean public RestTemplate restTemplate() { SimpleClientHttpRequestFactory factory new SimpleClientHttpRequestFactory(); factory.setConnectTimeout(5000); factory.setReadTimeout(5000); return new RestTemplate(factory); }提示RestTemplate 默认没有超时不设置的话遇到网络问题会一直挂着这是生产事故的常见来源。3.3 分布式锁的粒度与超时设置多实例环境下刷新 token 必须加分布式锁。锁的 key 建议用lock:wx:access_token:{appid}粒度精确到具体的小程序这样如果你一个服务对接多个小程序也不会互相阻塞。锁的超时时间要仔细算。刷新 token 本身是一次 HTTP 调用正常几百毫秒极端情况几秒。锁超时设太短业务还没刷完锁就释放了别的线程又会进来重复刷设太长万一持锁线程崩了其他线程要等很久。我的经验值是10 秒足够覆盖一次正常的接口调用又不至于让故障恢复太慢。还有一个容易忽略的点获取锁失败后不要立即重试应该稍微 sleep 一下再去读缓存。因为持锁线程很可能已经刷好了 token你直接读缓存就能拿到没必要自己也去刷。String lockKey lock:wx:access_token: appid; Boolean locked redisTemplate.opsForValue() .setIfAbsent(lockKey, 1, 10, TimeUnit.SECONDS); if (Boolean.TRUE.equals(locked)) { try { // 双重检查防止重复刷新 String cached getFromCache(); if (cached ! null) return cached; return refreshToken(); } finally { redisTemplate.delete(lockKey); } } else { Thread.sleep(200); return getFromCache(); }3.4 双重检查为什么必不可少上面代码里的“双重检查”不是可有可无的装饰。设想这样一个场景线程 A 拿到锁开始刷新线程 B 没拿到锁sleep 200 毫秒后去读缓存。如果 A 刷得慢B 读的时候缓存还是空的B 就会返回 null业务就失败了。所以 B 在读不到缓存时应该再尝试获取一次锁或者再等一轮。更稳妥的做法是加一个自旋重试最多等个两三次每次间隔 200 毫秒。这样即使刷新稍慢业务请求也能等到结果而不是直接抛异常。这个细节在文档里基本不会提但线上高并发时非常关键。4. 完整实操流程与核心代码实现4.1 项目依赖与基础配置先看依赖。核心就是 SpringBoot 的 Web 模块、Redis 模块以及 JSON 处理。如果你用 JacksonSpringBoot 已经自带如果喜欢 Fastjson 或 Gson 也可以但要注意版本安全。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency配置方面appid 和 secret 我建议放在自定义配置项里通过环境变量覆盖wx: miniapp: appid: ${WX_APPID} secret: ${WX_SECRET} token-url: https://api.weixin.qq.com/cgi-bin/token这样本地开发可以用 IDE 的环境变量配置线上用容器编排的密钥管理secret 永远不进代码库。4.2 AccessToken 服务类的完整实现下面是我实际项目里用的服务类结构做了精简但保留了核心逻辑。它包含缓存读取、分布式锁刷新、异常兜底、以及强制刷新接口。Service public class WxAccessTokenService { private static final String CACHE_KEY wx:access_token:%s; private static final String LOCK_KEY lock:wx:access_token:%s; private static final long SAFE_SECONDS 300L; Resource private RestTemplate restTemplate; Resource private StringRedisTemplate redisTemplate; Value(${wx.miniapp.appid}) private String appid; Value(${wx.miniapp.secret}) private String secret; Value(${wx.miniapp.token-url}) private String tokenUrl; public String getAccessToken() { String cacheKey String.format(CACHE_KEY, appid); String token redisTemplate.opsForValue().get(cacheKey); if (token ! null) { return token; } return refreshWithLock(cacheKey); } private String refreshWithLock(String cacheKey) { String lockKey String.format(LOCK_KEY, appid); for (int i 0; i 3; i) { Boolean locked redisTemplate.opsForValue() .setIfAbsent(lockKey, 1, 10, TimeUnit.SECONDS); if (Boolean.TRUE.equals(locked)) { try { String again redisTemplate.opsForValue().get(cacheKey); if (again ! null) return again; return doRefresh(cacheKey); } finally { redisTemplate.delete(lockKey); } } try { Thread.sleep(200); } catch (InterruptedException e) { Thread.currentThread().interrupt(); } String cached redisTemplate.opsForValue().get(cacheKey); if (cached ! null) return cached; } throw new RuntimeException(获取微信 AccessToken 失败请稍后重试); } private String doRefresh(String cacheKey) { String url tokenUrl ?grant_typeclient_credential appid appid secret secret; AccessTokenResponse resp restTemplate.getForObject(url, AccessTokenResponse.class); if (resp null || resp.getAccess_token() null) { throw new RuntimeException(微信返回异常: resp); } if (resp.getErrcode() ! null resp.getErrcode() ! 0) { throw new RuntimeException(微信错误码: resp.getErrcode() , 信息: resp.getErrmsg()); } long ttl resp.getExpires_in() - SAFE_SECONDS; redisTemplate.opsForValue().set(cacheKey, resp.getAccess_token(), ttl, TimeUnit.SECONDS); return resp.getAccess_token(); } public void forceRefresh() { String cacheKey String.format(CACHE_KEY, appid); redisTemplate.delete(cacheKey); refreshWithLock(cacheKey); } }这段代码有几个设计点值得展开。自旋三次是为了应对刷新较慢的情况每次间隔 200 毫秒总共最多等 600 毫秒对业务来说基本无感。安全余量 300 秒保证 token 不会在业务使用过程中突然过期。forceRefresh方法用于特殊场景比如收到 40001 错误码时主动清缓存重刷。4.3 业务调用时的自动重试机制即使我们做了缓存和提前刷新仍然可能遇到 token 突然失效的情况比如微信侧主动失效、或者缓存被误删。这时候业务调用会返回 40001。一个健壮的系统应该能自动识别这个错误码并重试一次。我的做法是封装一个统一的微信接口调用模板捕获 40001 后调用forceRefresh然后重试一次。重试只做一次避免无限循环。public String callWxApi(String url, Object requestBody) { String token wxAccessTokenService.getAccessToken(); String fullUrl url ?access_token token; String result restTemplate.postForObject(fullUrl, requestBody, String.class); if (result ! null result.contains(\errcode\:40001)) { wxAccessTokenService.forceRefresh(); String newToken wxAccessTokenService.getAccessToken(); String retryUrl url ?access_token newToken; result restTemplate.postForObject(retryUrl, requestBody, String.class); } return result; }这个模板看起来简单但它把 token 管理的复杂度从每个业务方法里抽离出来了。业务代码只管调callWxApi不用关心 token 从哪来、什么时候过期、失效了怎么办。4.4 定时兜底任务的实现前面提到长期无请求时 token 会静默过期导致下一次请求变慢。加一个定时任务可以解决这个问题。用 Spring 的Scheduled就够了不需要引入 Quartz 这种重家伙。Component public class WxTokenRefreshTask { Resource private WxAccessTokenService wxAccessTokenService; Scheduled(fixedDelay 30 * 60 * 1000) public void refresh() { try { wxAccessTokenService.getAccessToken(); } catch (Exception e) { // 记录日志不抛出避免影响下次调度 log.error(定时刷新微信 token 失败, e); } } }注意这里用的是fixedDelay而不是fixedRate区别在于fixedDelay是上一次执行完后再等 30 分钟避免任务执行时间过长导致重叠。另外异常一定要吞掉并记日志否则一次失败会导致后续调度全部中断。5. 常见问题与排查技巧实录5.1 高频报错速查表下面这张表是我这几年遇到过的 token 相关问题汇总基本覆盖了 90% 的线上故障场景。错误码/现象根本原因排查方向解决方案40001token 无效或已被顶掉是否有其他地方也在刷新统一 token 管理入口40164调用方 IP 不在白名单服务器出口 IP 是否变更微信后台配置 IP 白名单45009接口调用频率超限是否高频刷新 token加缓存降低刷新频率40013appid 无效配置是否写错核对 appid40125secret 无效密钥是否重置过重新生成并更新配置token 时好时坏多实例互踢是否用了本地缓存改用 Redis 统一存储首次请求特别慢token 静默过期是否有定时兜底加定时刷新任务5.2 那些文档不会告诉你的坑第一个坑是IP 白名单。微信要求调用 token 接口的服务器 IP 必须在白名单里很多开发者本地测试用公司网络能通一部署到云服务器就报 40164。而且云服务器的公网 IP 有时候是 NAT 出口实际出口 IP 可能和你以为的不一样。排查方法是在服务器上执行curl ifconfig.me看真实出口 IP然后去微信后台配置。第二个坑是secret 泄露后的连锁反应。secret 一旦泄露别人可以用你的 appid 和 secret 去刷新 token把你的 token 顶掉导致你的服务全部失效。所以 secret 一定要严格管理一旦怀疑泄露立即在微信后台重置。重置后记得同步更新所有环境的配置。第三个坑是Redis 和本地缓存的不一致。如果你做了二级缓存本地缓存的过期时间一定要比 Redis 短否则 Redis 里的 token 已经刷新了本地还是旧的业务就会用到失效 token。我的做法是本地缓存 TTL 设为 Redis 的一半并且每次从 Redis 读到新 token 时同步更新本地。第四个坑是多小程序共用一套代码。如果你的服务对接了多个小程序缓存 key 和锁 key 一定要带上 appid 做区分否则 A 小程序的 token 会覆盖 B 小程序的业务直接错乱。这个错误在代码 review 时很容易被忽略因为单小程序测试时完全正常。5.3 监控与告警建议token 这种东西平时不出问题没人关注一出问题就是全站级别的。所以监控很有必要。我一般会埋三个点刷新成功率、刷新耗时、缓存命中率。刷新失败要立即告警因为这意味着两小时后所有微信能力都会失效。刷新耗时突然变长说明微信侧或网络有问题也要关注。缓存命中率如果异常低说明可能有地方在频繁清缓存或者缓存配置有问题。用 Micrometer 加 Prometheus 就能轻松实现这些指标成本很低但收益很大。别等到线上炸了才想起来加监控。6. 几个容易被忽视的进阶细节6.1 token 与 stable_token 的区别微信后来推出了stable_token接口和普通 token 的区别在于它不会因为频繁获取而互踢适合多实例场景。如果你的项目对稳定性要求极高可以考虑迁移到 stable_token。不过它的行为和普通 token 有差异迁移前一定要仔细读文档尤其是失效逻辑和返回结构。我目前的建议是新项目可以直接用 stable_token老项目如果普通 token 跑得稳不必急着换。6.2 优雅关闭时的缓存处理服务重启时如果 Redis 里的 token 还有效其实不需要重新获取。但有些同学在应用启动时会强制刷新一次 token这其实是浪费。正确做法是启动时先读缓存缓存有效就直接用无效才刷新。这样既减少了调用次数也避免了重启风暴时多个实例同时刷新的问题。6.3 配置热更新的处理如果 appid 或 secret 支持热更新比如通过配置中心那么更新后必须清掉旧缓存并重新获取。否则你会一直用旧 secret 对应的 token直到它自然过期。这个场景在密钥轮换时特别重要一定要在配置变更监听里加上清缓存的逻辑。我在实际项目里最大的体会是AccessToken 管理这件事代码量不大但设计密度很高。它考验的不是你会不会调接口而是你对缓存、并发、故障恢复的整体把控。把这套机制搭好之后后面接入任何微信能力都是水到渠成的事。最后再分享一个小技巧把 token 的获取和刷新全部收敛到一个服务类里业务代码永远不要直接碰 token 接口这样将来无论微信怎么改规则你只需要改一个地方。
1. 为什么 AccessToken 是整个小程序服务端的地基做过微信小程序后端对接的人都有一个共识AccessToken 这东西看起来只是调一个接口拿一串字符串但它几乎是所有服务端能力的“总钥匙”。你后面要发订阅消息、要做内容安全检测、要生成小程序码、要拉用户手机号、要搞支付回调后的对账全都绕不开它。我在实际项目里踩过最惨的一次坑就是早期没把 AccessToken 的获取和刷新当回事结果线上跑了两天突然所有消息推送全部失败排查了半天才发现是多个业务模块各自去调微信接口刷新 token互相把对方的 token 顶掉了。所以这篇内容我想聊的不是“怎么调一个 HTTP 接口”这么浅的东西而是围绕SpringBoot 整合微信小程序获取 AccessToken这件事把背后的设计思路、缓存策略、并发问题、刷新机制、异常兜底、以及实际落地时那些文档里不会写的细节完整地拆一遍。适合正在做小程序后端、或者准备把小程序能力接入到现有 Java 服务体系里的开发者。不管你是刚接触微信生态的新手还是已经写过几版但总觉得不够稳的老手这里面的取舍逻辑应该都能给你一些参考。先明确一个基础认知微信小程序的 AccessToken 是应用级别的全局凭证不是用户级别的。也就是说你的整个小程序服务端在任意时刻理论上只应该维护一份有效的 token。它默认有效期是 7200 秒也就是两小时。微信官方对刷新次数也有限制频繁刷新会导致旧 token 失效甚至触发调用频率风控。这就决定了我们的核心目标不是“每次用的时候去拿”而是“拿一次缓存起来快过期了再换并且保证多线程、多实例环境下不会打架”。这个目标听起来简单但真正落地时会牵扯出一堆问题缓存放本地还是放 Redis多台服务器怎么保证只有一台去刷新刷新的时候正好有请求进来怎么办token 失效了怎么自动重试这些才是这篇博文真正要解决的东西。2. 整体方案设计与技术选型思路2.1 为什么不能“用一次拿一次”很多新手的第一版代码是这样的写一个工具方法每次业务需要 token 的时候就现场调一次微信的 token 接口。本地测试完全没问题因为就你一个人在点。但一上线就出事了。原因有三层。第一层是性能每次业务请求都多一次外部 HTTP 调用微信接口本身有网络延迟你的接口响应时间会被硬生生拉长几百毫秒。第二层是频率限制微信对 token 接口的调用是有频次约束的高频调用会被限制。第三层也是最致命的token 互踢微信在生成新 token 时会让上一个 token 失效。如果你有两个请求几乎同时去刷新A 拿到新 token 的同时 B 也拿到一个新 token那么 A 手里的那个瞬间就废了。业务上表现就是“时好时坏”这种 bug 最难查。所以正确的思路一定是集中获取、统一缓存、定时或惰性刷新、全局共享。2.2 缓存介质怎么选本地缓存 vs Redis这是方案设计里第一个要拍板的事。我的建议很明确单机部署可以用本地缓存但只要涉及多实例部署必须上 Redis。本地缓存比如用ConcurrentHashMap或者 Caffeine的优点是快、无外部依赖、实现简单。但它的致命问题是每台服务器都有一份自己的 token多台机器就会各自去刷新又回到了互踢的老问题。除非你做了单点刷新加广播同步否则多实例下本地缓存就是个坑。Redis 方案则是把 token 存成全局唯一的一份所有实例共享。配合分布式锁可以保证同一时刻只有一台机器去刷新。这是生产环境的标准做法。下面这张表可以帮你快速决策部署形态推荐缓存刷新协调方式风险点单机单实例本地缓存单机锁即可重启后需重新获取多实例无状态Redis分布式锁锁超时、网络抖动多实例高并发Redis本地二级缓存分布式锁本地兜底本地与 Redis 短暂不一致我个人的习惯是Redis 作为权威存储本地再放一个短时效的副本读取时优先读本地本地没有或快过期了再读 Redis。这样既减少了 Redis 的网络往返又保证了全局一致性。不过对于大多数中小项目直接用 Redis 就够了别过度设计。2.3 刷新策略定时刷新还是惰性刷新刷新策略有两种主流做法。定时刷新是起一个定时任务比如每 100 分钟刷一次保证 token 永远新鲜。惰性刷新是不主动刷等业务来取的时候判断是否快过期快过期了才去刷。定时刷新的问题是如果你的服务半夜没人用它照样在刷浪费调用次数而且如果定时任务所在的机器挂了刷新就断了。惰性刷新的问题是如果正好在过期临界点来了大量并发请求可能触发多次刷新。我的实战选择是两者结合以惰性刷新为主在获取 token 的方法里判断剩余有效期低于阈值比如还剩 5 分钟就触发刷新同时加一个兜底的定时任务比如每小时检查一次防止长期无请求导致 token 静默过期后第一次请求变慢。这个组合在我几个项目里跑下来都很稳。3. 核心细节解析与实操要点3.1 微信 token 接口的关键参数与返回结构先把接口本身说清楚。获取小程序 AccessToken 的接口是 GET 请求核心参数就三个grant_type固定为client_credentialappid是小程序的唯一标识secret是小程序密钥。返回是一个 JSON成功时包含access_token和expires_in失败时包含errcode和errmsg。这里有几个细节必须注意。第一appid和secret绝对不能硬编码在代码里更不能提交到代码仓库。我见过太多项目把 secret 直接写在application.yml里然后推到公开仓库这是重大安全隐患。正确做法是通过环境变量、配置中心或者加密配置注入。第二expires_in虽然官方说是 7200但千万不要直接用 7200 作为缓存时间一定要留出安全余量我一般用expires_in - 300也就是提前 5 分钟过期。第三返回的errcode为 0 或者不存在时才代表成功其他值都要当作异常处理尤其是 40001token 无效和 40164IP 白名单问题。public class AccessTokenResponse { private String access_token; private Integer expires_in; private Integer errcode; private String errmsg; // getter/setter 省略 }3.2 用 RestTemplate 还是 HttpClient 还是 OkHttpSpringBoot 项目里调外部 HTTP 接口常见选择有RestTemplate、WebClient、OkHttp、HttpClient。我的建议是如果项目已经是 SpringBoot 体系优先用 RestTemplate 或 WebClient减少额外依赖。RestTemplate 是同步阻塞的写法简单适合这种低频调用两小时才一次。WebClient 是响应式的适合高并发场景但引入 WebFlux 依赖对很多项目来说是杀鸡用牛刀。OkHttp 性能好、连接池管理优秀但需要额外引入依赖。考虑到 token 获取是低频操作性能根本不是瓶颈我倾向于用 RestTemplate配置好超时时间就行。超时设置很关键连接超时和读取超时都建议设成 3 到 5 秒避免微信接口抖动时把你的线程池拖垮。Bean public RestTemplate restTemplate() { SimpleClientHttpRequestFactory factory new SimpleClientHttpRequestFactory(); factory.setConnectTimeout(5000); factory.setReadTimeout(5000); return new RestTemplate(factory); }提示RestTemplate 默认没有超时不设置的话遇到网络问题会一直挂着这是生产事故的常见来源。3.3 分布式锁的粒度与超时设置多实例环境下刷新 token 必须加分布式锁。锁的 key 建议用lock:wx:access_token:{appid}粒度精确到具体的小程序这样如果你一个服务对接多个小程序也不会互相阻塞。锁的超时时间要仔细算。刷新 token 本身是一次 HTTP 调用正常几百毫秒极端情况几秒。锁超时设太短业务还没刷完锁就释放了别的线程又会进来重复刷设太长万一持锁线程崩了其他线程要等很久。我的经验值是10 秒足够覆盖一次正常的接口调用又不至于让故障恢复太慢。还有一个容易忽略的点获取锁失败后不要立即重试应该稍微 sleep 一下再去读缓存。因为持锁线程很可能已经刷好了 token你直接读缓存就能拿到没必要自己也去刷。String lockKey lock:wx:access_token: appid; Boolean locked redisTemplate.opsForValue() .setIfAbsent(lockKey, 1, 10, TimeUnit.SECONDS); if (Boolean.TRUE.equals(locked)) { try { // 双重检查防止重复刷新 String cached getFromCache(); if (cached ! null) return cached; return refreshToken(); } finally { redisTemplate.delete(lockKey); } } else { Thread.sleep(200); return getFromCache(); }3.4 双重检查为什么必不可少上面代码里的“双重检查”不是可有可无的装饰。设想这样一个场景线程 A 拿到锁开始刷新线程 B 没拿到锁sleep 200 毫秒后去读缓存。如果 A 刷得慢B 读的时候缓存还是空的B 就会返回 null业务就失败了。所以 B 在读不到缓存时应该再尝试获取一次锁或者再等一轮。更稳妥的做法是加一个自旋重试最多等个两三次每次间隔 200 毫秒。这样即使刷新稍慢业务请求也能等到结果而不是直接抛异常。这个细节在文档里基本不会提但线上高并发时非常关键。4. 完整实操流程与核心代码实现4.1 项目依赖与基础配置先看依赖。核心就是 SpringBoot 的 Web 模块、Redis 模块以及 JSON 处理。如果你用 JacksonSpringBoot 已经自带如果喜欢 Fastjson 或 Gson 也可以但要注意版本安全。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency配置方面appid 和 secret 我建议放在自定义配置项里通过环境变量覆盖wx: miniapp: appid: ${WX_APPID} secret: ${WX_SECRET} token-url: https://api.weixin.qq.com/cgi-bin/token这样本地开发可以用 IDE 的环境变量配置线上用容器编排的密钥管理secret 永远不进代码库。4.2 AccessToken 服务类的完整实现下面是我实际项目里用的服务类结构做了精简但保留了核心逻辑。它包含缓存读取、分布式锁刷新、异常兜底、以及强制刷新接口。Service public class WxAccessTokenService { private static final String CACHE_KEY wx:access_token:%s; private static final String LOCK_KEY lock:wx:access_token:%s; private static final long SAFE_SECONDS 300L; Resource private RestTemplate restTemplate; Resource private StringRedisTemplate redisTemplate; Value(${wx.miniapp.appid}) private String appid; Value(${wx.miniapp.secret}) private String secret; Value(${wx.miniapp.token-url}) private String tokenUrl; public String getAccessToken() { String cacheKey String.format(CACHE_KEY, appid); String token redisTemplate.opsForValue().get(cacheKey); if (token ! null) { return token; } return refreshWithLock(cacheKey); } private String refreshWithLock(String cacheKey) { String lockKey String.format(LOCK_KEY, appid); for (int i 0; i 3; i) { Boolean locked redisTemplate.opsForValue() .setIfAbsent(lockKey, 1, 10, TimeUnit.SECONDS); if (Boolean.TRUE.equals(locked)) { try { String again redisTemplate.opsForValue().get(cacheKey); if (again ! null) return again; return doRefresh(cacheKey); } finally { redisTemplate.delete(lockKey); } } try { Thread.sleep(200); } catch (InterruptedException e) { Thread.currentThread().interrupt(); } String cached redisTemplate.opsForValue().get(cacheKey); if (cached ! null) return cached; } throw new RuntimeException(获取微信 AccessToken 失败请稍后重试); } private String doRefresh(String cacheKey) { String url tokenUrl ?grant_typeclient_credential appid appid secret secret; AccessTokenResponse resp restTemplate.getForObject(url, AccessTokenResponse.class); if (resp null || resp.getAccess_token() null) { throw new RuntimeException(微信返回异常: resp); } if (resp.getErrcode() ! null resp.getErrcode() ! 0) { throw new RuntimeException(微信错误码: resp.getErrcode() , 信息: resp.getErrmsg()); } long ttl resp.getExpires_in() - SAFE_SECONDS; redisTemplate.opsForValue().set(cacheKey, resp.getAccess_token(), ttl, TimeUnit.SECONDS); return resp.getAccess_token(); } public void forceRefresh() { String cacheKey String.format(CACHE_KEY, appid); redisTemplate.delete(cacheKey); refreshWithLock(cacheKey); } }这段代码有几个设计点值得展开。自旋三次是为了应对刷新较慢的情况每次间隔 200 毫秒总共最多等 600 毫秒对业务来说基本无感。安全余量 300 秒保证 token 不会在业务使用过程中突然过期。forceRefresh方法用于特殊场景比如收到 40001 错误码时主动清缓存重刷。4.3 业务调用时的自动重试机制即使我们做了缓存和提前刷新仍然可能遇到 token 突然失效的情况比如微信侧主动失效、或者缓存被误删。这时候业务调用会返回 40001。一个健壮的系统应该能自动识别这个错误码并重试一次。我的做法是封装一个统一的微信接口调用模板捕获 40001 后调用forceRefresh然后重试一次。重试只做一次避免无限循环。public String callWxApi(String url, Object requestBody) { String token wxAccessTokenService.getAccessToken(); String fullUrl url ?access_token token; String result restTemplate.postForObject(fullUrl, requestBody, String.class); if (result ! null result.contains(\errcode\:40001)) { wxAccessTokenService.forceRefresh(); String newToken wxAccessTokenService.getAccessToken(); String retryUrl url ?access_token newToken; result restTemplate.postForObject(retryUrl, requestBody, String.class); } return result; }这个模板看起来简单但它把 token 管理的复杂度从每个业务方法里抽离出来了。业务代码只管调callWxApi不用关心 token 从哪来、什么时候过期、失效了怎么办。4.4 定时兜底任务的实现前面提到长期无请求时 token 会静默过期导致下一次请求变慢。加一个定时任务可以解决这个问题。用 Spring 的Scheduled就够了不需要引入 Quartz 这种重家伙。Component public class WxTokenRefreshTask { Resource private WxAccessTokenService wxAccessTokenService; Scheduled(fixedDelay 30 * 60 * 1000) public void refresh() { try { wxAccessTokenService.getAccessToken(); } catch (Exception e) { // 记录日志不抛出避免影响下次调度 log.error(定时刷新微信 token 失败, e); } } }注意这里用的是fixedDelay而不是fixedRate区别在于fixedDelay是上一次执行完后再等 30 分钟避免任务执行时间过长导致重叠。另外异常一定要吞掉并记日志否则一次失败会导致后续调度全部中断。5. 常见问题与排查技巧实录5.1 高频报错速查表下面这张表是我这几年遇到过的 token 相关问题汇总基本覆盖了 90% 的线上故障场景。错误码/现象根本原因排查方向解决方案40001token 无效或已被顶掉是否有其他地方也在刷新统一 token 管理入口40164调用方 IP 不在白名单服务器出口 IP 是否变更微信后台配置 IP 白名单45009接口调用频率超限是否高频刷新 token加缓存降低刷新频率40013appid 无效配置是否写错核对 appid40125secret 无效密钥是否重置过重新生成并更新配置token 时好时坏多实例互踢是否用了本地缓存改用 Redis 统一存储首次请求特别慢token 静默过期是否有定时兜底加定时刷新任务5.2 那些文档不会告诉你的坑第一个坑是IP 白名单。微信要求调用 token 接口的服务器 IP 必须在白名单里很多开发者本地测试用公司网络能通一部署到云服务器就报 40164。而且云服务器的公网 IP 有时候是 NAT 出口实际出口 IP 可能和你以为的不一样。排查方法是在服务器上执行curl ifconfig.me看真实出口 IP然后去微信后台配置。第二个坑是secret 泄露后的连锁反应。secret 一旦泄露别人可以用你的 appid 和 secret 去刷新 token把你的 token 顶掉导致你的服务全部失效。所以 secret 一定要严格管理一旦怀疑泄露立即在微信后台重置。重置后记得同步更新所有环境的配置。第三个坑是Redis 和本地缓存的不一致。如果你做了二级缓存本地缓存的过期时间一定要比 Redis 短否则 Redis 里的 token 已经刷新了本地还是旧的业务就会用到失效 token。我的做法是本地缓存 TTL 设为 Redis 的一半并且每次从 Redis 读到新 token 时同步更新本地。第四个坑是多小程序共用一套代码。如果你的服务对接了多个小程序缓存 key 和锁 key 一定要带上 appid 做区分否则 A 小程序的 token 会覆盖 B 小程序的业务直接错乱。这个错误在代码 review 时很容易被忽略因为单小程序测试时完全正常。5.3 监控与告警建议token 这种东西平时不出问题没人关注一出问题就是全站级别的。所以监控很有必要。我一般会埋三个点刷新成功率、刷新耗时、缓存命中率。刷新失败要立即告警因为这意味着两小时后所有微信能力都会失效。刷新耗时突然变长说明微信侧或网络有问题也要关注。缓存命中率如果异常低说明可能有地方在频繁清缓存或者缓存配置有问题。用 Micrometer 加 Prometheus 就能轻松实现这些指标成本很低但收益很大。别等到线上炸了才想起来加监控。6. 几个容易被忽视的进阶细节6.1 token 与 stable_token 的区别微信后来推出了stable_token接口和普通 token 的区别在于它不会因为频繁获取而互踢适合多实例场景。如果你的项目对稳定性要求极高可以考虑迁移到 stable_token。不过它的行为和普通 token 有差异迁移前一定要仔细读文档尤其是失效逻辑和返回结构。我目前的建议是新项目可以直接用 stable_token老项目如果普通 token 跑得稳不必急着换。6.2 优雅关闭时的缓存处理服务重启时如果 Redis 里的 token 还有效其实不需要重新获取。但有些同学在应用启动时会强制刷新一次 token这其实是浪费。正确做法是启动时先读缓存缓存有效就直接用无效才刷新。这样既减少了调用次数也避免了重启风暴时多个实例同时刷新的问题。6.3 配置热更新的处理如果 appid 或 secret 支持热更新比如通过配置中心那么更新后必须清掉旧缓存并重新获取。否则你会一直用旧 secret 对应的 token直到它自然过期。这个场景在密钥轮换时特别重要一定要在配置变更监听里加上清缓存的逻辑。我在实际项目里最大的体会是AccessToken 管理这件事代码量不大但设计密度很高。它考验的不是你会不会调接口而是你对缓存、并发、故障恢复的整体把控。把这套机制搭好之后后面接入任何微信能力都是水到渠成的事。最后再分享一个小技巧把 token 的获取和刷新全部收敛到一个服务类里业务代码永远不要直接碰 token 接口这样将来无论微信怎么改规则你只需要改一个地方。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
