简介面向具备 Java 与 Spring 基础的开发者这份工程以 Spring Boot 结合微信开放平台演示 Web 端扫码登录的完整实现可用于解决第三方站点接入微信授权时流程不清、回调与令牌处理易出错的问题。代码围绕 OAuth 2.0 展开涵盖二维码获取、回调接收授权 code、换取 access_token 与 openid、拉取用户信息并与本地账号绑定等环节并涉及回调 URL 配置、state 状态码校验、Spring Security 认证衔接与 JWT 无状态令牌方案可作为课程设计或业务系统登录模块的参考。压缩包共 121 个文件、约 172KB以 java 源码与 class 字节码为主辅以 xml、properties 配置和 sample 示例另含 Maven 构建脚本与 Git 版本信息导入 IDE 即可运行调试。目前已有 11405 人学习下载读者可从中获得可跑通的扫码登录链路、接口参数与错误处理写法以及登录态与安全设计的落地思路。1. 后台管理系统接入微信扫码登录的真实起点运营同学嫌后台每次输账号密码麻烦提了个需求能不能像登录第三方网站那样拿手机扫一下就进去。这就是 springboot 实现 web 端微信扫码登录要解决的事——对接微信开放平台的「网站应用」走标准 OAuth2 授权码模式和公众号网页授权、小程序登录是三套完全不同的东西混着查文档会直接卡在第一步。这份项目适合两类人手里有后台系统、想让用户少记一个密码的开发者以及想拿它当 OAuth2 落地范本照着改成企业微信、钉钉、GitHub 登录的人。整条链路其实不长坑集中在回调域、code 一次性、身份合并这三处下面挨个拆开。2. 技术选型与工程结构一个扫码登录最少需要几个模块先把边界划清楚。微信扫码登录在服务端只干三件事拼一个带state的授权链接、拿回调回来的code去换微信侧身份、把微信身份和本地账号对上线并签发自己的会话。它不负责渲染二维码那是前端 JS 的事也不负责密码校验那是本地账号体系的事。想明白这层技术选型就不会跑偏不需要引入 Spring Security OAuth2 Client 那一整套那套的 provider 是给标准 OAuth2 服务端用的微信的snsapi_login在细节上跟标准有出入硬套要写一堆自定义OAuth2AccessTokenResponseClient反而比手写 HTTP 调用更绕。老实点用RestTemplate直接打两个接口代码量不到 80 行出问题还能一眼看到原始报文。2.1 依赖清单与三件套配置依赖控制在五个以内多一个都是负担!-- pom.xml 关键依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId !-- 存 state 和一次性票据 -- /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-validation/artifactId !-- 绑定接口参数校验 -- /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId !-- 账号表读写 -- /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId version0.11.5/version /dependency配置只认三件套app-id、app-secret、redirect-uri。这三个值来自开放平台后台创建「网站应用」后拿到的凭证缺一个都跑不通。wechat: open: app-id: wx0000000000000000 # 开放平台网站应用的 AppID app-secret: 00000000000000000000000000000000 redirect-uri: https://demo.example.com/callback/wechat # 必须与「授权回调域」同域 scope: snsapi_login # 网站应用固定这个不是 snsapi_userinfo connect-timeout: 3000 read-timeout: 5000scope这里踩过一次写成snsapi_userinfo页面直接白屏报错因为那是公众号网页授权用的值网站应用扫码只认snsapi_login。参数说明上redirect-uri在开放平台后台配置的是域名不带协议、不带路径、不带端口而代码里传的是完整 URL两者必须同域否则微信会返回「redirect_uri 参数错误」。对应绑定类ConfigurationProperties(prefix wechat.open) Data public class WxOpenProperties { private String appId; private String appSecret; private String redirectUri; private String scope snsapi_login; private int connectTimeout 3000; private int readTimeout 5000; }超时别用默认值。微信侧接口偶发慢响应RestTemplate不设超时会把 Tomcat 线程池拖住回调接口堵住之后用户看到的就是「扫码后一直转圈」。Bean public RestTemplate wxRestTemplate(WxOpenProperties props) { SimpleClientHttpRequestFactory f new SimpleClientHttpRequestFactory(); f.setConnectTimeout(props.getConnectTimeout()); f.setReadTimeout(props.getReadTimeout()); return new RestTemplate(f); }2.2 目录分层与各层职责工程按「HTTP 调用 / 业务编排 / 票据存储」三段切不要混src/main/java/com/example/wxlogin ├── WxLoginApplication.java ├── config │ ├── WxOpenProperties.java # 三件套配置绑定 │ ├── RestTemplateConfig.java # 带超时的 RestTemplate │ └── WebMvcConfig.java # 回调路径放行、CORS ├── controller │ ├── WxAuthController.java # /qrcode /callback /poll /bind /token │ └── UserController.java # /me ├── client │ └── WxOpenApiClient.java # 只做微信接口 HTTP 调用不含业务判断 ├── service │ ├── WxLoginService.java # 编排换身份 - 查绑定 - 发票据 │ ├── TicketService.java # Redis 票据的生成 / 消费 / 过期 │ └── WxAccountService.java # 绑定关系落库含并发兜底 ├── mapper │ └── WxAccountMapper.java ├── entity │ ├── WxAccount.java │ └── WxUserInfo.java # 微信侧身份openid/unionid/昵称/头像 └── common ├── R.java # 统一响应包装 ├── BizException.java └── JwtUtil.java分层的关键在于WxOpenApiClient只干一件事发请求、解析 JSON、把errcode翻译成异常。它不判断「这个用户有没有绑定过本地账号」那是WxLoginService的活。这么切的好处是后面要加企业微信或钉钉登录只换client层service编排逻辑基本不动。TicketService单独抽出来是因为整个流程里有三种生命周期不同的临时凭证state、绑定票据、登录票据散落在各个 service 里迟早会乱。统一交给一个类管过期时间、消费方式、key 命名都在一处排查时keys wx:login:*一眼就能看全。3. 核心链路拆解从二维码生成到本地会话落地的四段代码整条链路四个节点后端发授权链接 → 前端渲染二维码 → 用户扫码后微信回调 → 后端换身份并签发本地会话。每一段都有对应的代码块照抄改配置即可。3.1 生成授权链接与内嵌二维码二维码本身不用后端生成。微信提供两种方式整页跳转到open.weixin.qq.com/connect/qrconnect或者引入官方 JS 把二维码嵌到自己页面里。后者体验好用户不离开站点但要 HTTPS 页面且要传state。GetMapping(/api/auth/wechat/qrcode) public RQrCodeVO qrcode(RequestParam(defaultValue /dashboard) String redirect) { // state 一次性、5 分钟有效同时把扫码成功后要跳回的前端路径存进去 String state ticketService.newState(redirect); String url https://open.weixin.qq.com/connect/qrconnect ?appid props.getAppId() redirect_uri URLEncoder.encode(props.getRedirectUri(), StandardCharsets.UTF_8) response_typecode scope props.getScope() state state #wechat_redirect; // 锚点不能省否则部分浏览器样式和跳转会异常 return R.ok(new QrCodeVO(state, url, 300)); }QrCodeVO里带state是给前端轮询用的带url是给「整页跳转」方案兜底的。参数说明response_type固定codescope固定snsapi_loginredirect_uri必须URLEncoder编码一次否则带 query 的回调地址会被截断。前端内嵌渲染// 页面加载后拉一次后端接口拿到 state 和 url const { data } await axios.get(/api/auth/wechat/qrcode?redirect/dashboard); new WxLogin({ self_redirect: true, // true 表示在 iframe 内部跳转不整页刷新 id: wx-qrcode, // 容器 div 的 id appid: wx0000000000000000, // 与后端配置保持一致 scope: snsapi_login, redirect_uri: encodeURIComponent(https://demo.example.com/callback/wechat), state: data.state, style: black, href: // 自定义样式表地址留空用默认 });self_redirect设成true之后用户扫码确认时只有那个 iframe 跳去回调地址主页面不动接着靠轮询取结果——这就是后面 3.4 节要写的那段。3.2 回调入口code 换 openid 与 unionid微信回调会带两个参数code和state。code只能用一次、5 分钟过期拿到就立刻换别存着。GetMapping(/callback/wechat) public void callback(RequestParam(code) String code, RequestParam(state) String state, HttpServletResponse response) throws IOException { String target; try { // 1. state 必须存在且未被消费顺带取出扫码前想跳转的前端路径 ticketService.consumeState(state); // 2. code - openid/unionid WxUserInfo wx wxOpenApiClient.getUserByCode(code); // 3. 已绑定直接发登录票据未绑定发绑定票据 String ticket wxLoginService.loginOrBind(wx); target /login-bridge?ticket ticket; } catch (BizException e) { target /login-error?code e.getCode(); } // 重定向到不带 code 的地址避免用户按 F5 重放 response.sendRedirect(target); }这段里最关键的一行是最后的sendRedirect。如果回调页直接把结果渲染出来用户手一抖按了刷新浏览器会带着同一个code再请求一次微信侧返回40163 code been used前端就卡在错误页。重定向到不带code的地址刷新只是重新走前端页面不会重放。WxOpenApiClient里两个接口连着打public WxUserInfo getUserByCode(String code) { // 第一跳code 换 access_token openid String tokenUrl UriComponentsBuilder .fromHttpUrl(https://api.weixin.qq.com/sns/oauth2/access_token) .queryParam(appid, props.getAppId()) .queryParam(secret, props.getAppSecret()) .queryParam(code, code) .queryParam(grant_type, authorization_code) .toUriString(); JSONObject token checkError(get(tokenUrl)); String accessToken token.getString(access_token); String openid token.getString(openid); String unionid token.getString(unionid); // 应用绑到开放平台账号后才有 // 第二跳拉用户资料。注意 2021 年后昵称头像可能已匿名化 String infoUrl UriComponentsBuilder .fromHttpUrl(https://api.weixin.qq.com/sns/userinfo) .queryParam(access_token, accessToken) .queryParam(openid, openid) .queryParam(lang, zh_CN) .toUriString(); JSONObject info checkError(get(infoUrl)); WxUserInfo user new WxUserInfo(); user.setOpenid(openid); user.setUnionid(StringUtils.hasText(unionid) ? unionid : info.getString(unionid)); user.setNickname(info.getString(nickname)); user.setAvatar(info.getString(headimgurl)); return user; } private JSONObject checkError(JSONObject json) { Integer errcode json.getInteger(errcode); if (errcode ! null errcode ! 0) { // 40029 code 无效 / 40163 code 已被使用 / 40013 appid 不合法 throw new BizException(WX_ errcode, json.getString(errmsg)); } return json; }checkError这个薄封装很有必要。微信的接口 HTTP 状态码永远返回 200错误信息全塞在 body 的errcode里不主动判断就会把{errcode:40029}当成正常用户信息解析后面 NPE 报在任何地方都找不到根因。3.3 账号绑定新用户与老用户的分叉微信身份拿到之后要判断这个 openid/unionid 在本地库里有对应账号吗有就直接登录没有就走绑定流程。Transactional public String loginOrBind(WxUserInfo wx) { // 优先用 unionid 做身份主键它跨应用唯一没有才退回 openid String identity StringUtils.hasText(wx.getUnionid()) ? wx.getUnionid() : wx.getOpenid(); WxAccount account wxAccountMapper.selectByIdentity(identity); if (account ! null account.getUserId() ! null) { return ticketService.issueLoginTicket(account.getUserId()); // 老用户直接发登录票据 } return ticketService.issueBindTicket(wx); // 新用户发绑定票据 }绑定接口接住这张票据PostMapping(/api/auth/wechat/bind) public RLoginVO bind(RequestBody Valid BindDTO dto) { // 绑定票据一次性消费防止同一个扫码结果被拿来反复绑定 WxUserInfo wx ticketService.consumeBindTicket(dto.getBindTicket()); // 走本地账号体系校验账号密码 / 手机验证码这里以账号密码为例 User user userService.loginByPassword(dto.getUsername(), dto.getPassword()); wxAccountService.bind(user.getId(), wx); return R.ok(userService.issueToken(user)); }参数上bindTicket有效期我一般设 10 分钟——用户扫码后可能要找账号密码给太短会频繁过期给太长又放大重放风险。绑定成功后WxAccount表的user_id落库下次同一个微信扫码直接命中 3.3 的第一个分支。3.4 轮询换令牌把开放平台身份变成本地会话内嵌二维码模式下主页面不知道 iframe 里发生了什么靠轮询问后端GetMapping(/api/auth/wechat/poll) public RPollVO poll(RequestParam String state) { Ticket t ticketService.getTicket(state); if (t null) return R.ok(PollVO.expired()); if (t.isWaiting()) return R.ok(PollVO.waiting()); if (t.isNeedBind()) return R.ok(PollVO.needBind(t.getBindTicket())); return R.ok(PollVO.success(t.getLoginTicket())); }前端拿到success后再拿loginTicket换真正的 JWTPostMapping(/api/auth/wechat/token) public RLoginVO exchange(RequestParam String ticket) { // 一次性消费消费后立刻删 Redis同一个 ticket 换不出第二个 JWT Long userId ticketService.consumeLoginTicket(ticket); User user userService.getById(userId); return R.ok(userService.issueToken(user)); }这里的票据分两层loginTicket只是「证明你刚扫过码」的一次性凭证60 秒内有效真正给前端持久化的是 JWT。这么拆的原因是浏览器地址栏和前端日志都可能泄漏 ticket而 JWT 有签名、有exp还能配合 Redis 白名单做主动踢人。4. 状态机与安全细节state、Redis 票据与并发绑定扫码登录最容易出事的地方不是接口调不通而是「看起来通了但能被重放」。这一章讲三个防线。4.1 state 不是摆设防重放与防 CSRF很多人把state写成固定字符串甚至省略功能测试全过上线后被构造回调地址刷绑定。正确做法是32 位随机串、一次一用、和扫码会话绑定。private static final String STATE_KEY wx:login:state:; public String newState(String redirect) { String state RandomUtil.randomString(32); redis.opsForValue().set(STATE_KEY state, WAIT| redirect, Duration.ofMinutes(5)); return state; } // 读 删必须原子否则并发下同一个 state 会被消费两次 private static final RedisScriptLong DEL_IF_EQUALS new DefaultRedisScript( if redis.call(get, KEYS[1]) ARGV[1] then return redis.call(del, KEYS[1]) else return 0 end, Long.class); public String consumeState(String state) { String key STATE_KEY state; String val redis.opsForValue().get(key); if (val null) throw new BizException(STATE_EXPIRED, 二维码已过期); Long deleted redis.execute(DEL_IF_EQUALS, Collections.singletonList(key), val); if (deleted null || deleted 0) throw new BizException(STATE_REUSED, 请求已失效); return val.split(\\|, 2)[1]; // 取出扫码前想跳转的前端路径 }Lua 脚本那段是为了原子性。get完再del中间有窗口期攻击者并发打同一个state两个请求都能读到值都能往下走。用DEL_IF_EQUALS把「比对 删除」压成一个原子操作只有一个请求能拿到 1。4.2 Redis 票据的生命周期设计三张票据三套 TTL这张表建议直接抄进项目文档票据Redis Key写入时机TTL消费方消费方式statewx:login:state:{state}生成二维码5 分钟回调接口Lua 原子删除绑定票据wx:login:bind:{ticket}首次扫码未绑定10 分钟/api/auth/wechat/bindgetAndDelete登录票据wx:login:token:{ticket}已绑定或绑定成功60 秒/api/auth/wechat/tokengetAndDelete绑票据里存的是整个WxUserInfo的 JSON序列化用GenericJackson2JsonRedisSerializer别用 JDK 序列化——后者在容器里换个 JDK 小版本就可能读不出来排查起来纯纯玄学。登录票据只存userId越轻越好。需要注意state在回调消费掉之后轮询那边的 key 就查不到了。所以回调里消费state的同时要用同一个state再写一个轮询结果 key两个 key 前缀不同、生命周期独立别图省事混用一个。4.3 并发绑定与唯一索引兜底用户在两个浏览器同时扫同一个二维码或者网络抖动导致绑定接口重试都会往wx_account插重复记录。代码层的「先查再插」拦不住必须在库上加约束。CREATE TABLE wx_account ( id BIGINT NOT NULL AUTO_INCREMENT, user_id BIGINT DEFAULT NULL COMMENT 绑定的本地账号NULL 表示仅扫描未绑定, openid VARCHAR(64) NOT NULL, unionid VARCHAR(64) DEFAULT NULL, nickname VARCHAR(64) DEFAULT NULL, avatar VARCHAR(512) DEFAULT NULL, app_type VARCHAR(16) NOT NULL DEFAULT OPEN_WEB, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uk_openid_app (openid, app_type), UNIQUE KEY uk_unionid (unionid), KEY idx_user (user_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;unionid允许为 NULLMySQL 的唯一索引对多个 NULL 不做限制正好符合「没绑开放平台账号就没有 unionid」的情况。app_type加进联合唯一索引是为了同一个 openid 在不同应用网站应用、APP、公众号下能共存——它们本来就是不同维度的身份。代码侧接住这个约束public void bind(Long userId, WxUserInfo wx) { try { wxAccountMapper.insert(WxAccount.of(userId, wx)); } catch (DuplicateKeyException e) { // 并发下已经有记录了退化成更新保证幂等 wxAccountMapper.updateUserIdByIdentity(identityOf(wx), userId); } }5. 避坑与排查扫码登录最常见的 5 个翻车点这一章全是血泪经验每条按「现象 → 原因 → 解决」写遇到对得上的直接抄。5.1 页面提示「redirect_uri 参数错误」二维码都出不来现象点登录按钮微信页面白屏或者弹一行红字浏览器地址栏里redirect_uri看着是对的。原因开放平台后台的「授权回调域」填的不是一个纯域名。那个输入框只接受域名形如demo.example.com带上https://、带路径、带端口都会被判为不合法同时代码里传的redirect_uri必须与它同域路径可以有但域名部分必须完全一致。另一个高频原因是本地开发直接用localhost:8080当回调微信侧不接受这种地址。解决回调域只填域名本地调试把回调指到一个已经配置好的测试域名上通过反向代理转发到本机端口。还有一点网站应用需要企业资质审核个人主体申请不下来动手之前先确认手里有没有可用的 AppID不然代码写完也联调不了。5.2 扫码成功但立刻报 40163 code been used现象用户扫码确认回调接口报40163日志里同一个code出现了两次。原因code是一次性的5 分钟过期。常见的重复来源有三个——回调页直接渲染结果用户按了 F5浏览器预取或者某些安全插件提前请求了回调 URL前端在self_redirect模式下没关掉重试逻辑iframe 加载失败自动重试了一次。解决回调接口处理完立刻 302 到不带code的地址见 3.2 节最后一行。同时在回调入口加一层短 TTL 的code去重缓存同一个code第二次进来直接返回「请重新扫码」别再去打微信接口省得白白消耗配额。5.3 昵称全是「微信用户」头像是一张灰色默认图现象绑定时拿到的nickname是「微信用户」headimgurl是默认头像地址换几个号都一样。原因这不是代码问题。开放平台的用户信息接口在 2021 年底之后调整过策略不再返回真实的昵称和头像/sns/userinfo里那两个字段已经不可信。解决把昵称头像当成「可选信息」设计。首次绑定时让用户自己填昵称头像给几个预设或者上传如果业务强依赖头像走小程序或公众号侧的「头像昵称填写能力」让用户主动授权。别在登录链路上依赖这两个字段做任何判断比如「昵称为空就拒绝登录」这种逻辑上线就是全量拦截。5.4 同一个用户网站端和公众号端对不上号现象用户先关注了公众号在公众号里登录过后来在网站上扫码系统当成新用户又让他绑一次账号。原因openid是「应用维度」的标识。网站应用和公众号是两个不同的应用同一个用户在这两个应用下的 openid 完全不同拿 openid 做主键必然对不上。解决把两个应用都绑到同一个开放平台账号下用户信息里会多返回一个unionid它是「账号维度」的、跨应用唯一。工程上统一用unionid做身份主键openid只作为辅助字段存着用于后续调该应用自己的接口。代码里就是 3.3 节那句三元表达式有unionid用unionid没有才退回openid。5.5 扫码成功了前端一直转圈轮询永远返回 waiting现象手机端显示「已确认登录」PC 端页面还在转圈Network 面板里/poll每隔 2 秒返回一次waiting直到 5 分钟后变expired。原因回调里consumeState把wx:login:state:{state}删掉了而轮询接口查的是同一个 key自然永远查不到。这是流程设计上把「校验用的 state」和「承载结果的状态机」混成一个 key 导致的。也可能是前端轮询传的state是本地生成的 UUID跟后端返回的那个不是同一个。解决拆成两个 key。state只管防重放回调进来就消费掉另外用一个独立前缀比如wx:login:result:{state}写轮询结果值在WAIT/BIND:ticket/OK:ticket之间流转TTL 设 5 分钟。前端那边state一律以/qrcode接口返回的为准别自己造。6. 二次开发把扫码登录抽成可插拔的开放平台接入层这套代码跑通之后最自然的下一步是「再接一个平台」。如果按原始写法直接复制一份WxOpenApiClient改成企业微信版两周后就是四份几乎一样的回调代码改一个安全策略要改四处。我的做法是先抽接口再往里填实现。public interface OAuthClient { String platform(); // WX_OPEN / WX_WORK / OTHER String authorizeUrl(String state); // 拼授权链接 OAuthUser exchange(String code); // code 换身份 }WxOpenApiClient改成实现这个接口WxLoginService.loginOrBind的入参从WxUserInfo换成OAuthUser。回调路径带上平台标识/callback/{platform}由一个MapString, OAuthClient做分发——Spring 会自动把所有实现类注进这个 Mapkey 就是platform()的返回值加新平台只需要新增一个Component不改任何现有代码。票据层也要跟着泛化。TicketService里的三个方法目前入参都是WxUserInfo改成OAuthUser就行Redis key 前缀里带上平台标识避免不同平台的状态互相覆盖。改造完怎么验证我是用三个断言串起来的第一把redirect_uri故意改错一位确认回调能在 3 秒内返回明确的错误页而不是超时第二用同一个code连打两次回调接口确认第二次稳定返回业务异常且日志里有平台标识第三清空 Redis 后走完整流程确认三张票据的 TTL 与那张表对得上。这三步走完基本可以上线了。有个习惯我一直保留每次新增平台接入先在TicketService里把该平台的 key 前缀写进枚举再加 client 实现。顺序反了的话key 拼错是那种「功能正常但偶发不生效」的问题查起来最磨人。希望帮到你。本文还有配套的精品资源点击获取
简介面向具备 Java 与 Spring 基础的开发者这份工程以 Spring Boot 结合微信开放平台演示 Web 端扫码登录的完整实现可用于解决第三方站点接入微信授权时流程不清、回调与令牌处理易出错的问题。代码围绕 OAuth 2.0 展开涵盖二维码获取、回调接收授权 code、换取 access_token 与 openid、拉取用户信息并与本地账号绑定等环节并涉及回调 URL 配置、state 状态码校验、Spring Security 认证衔接与 JWT 无状态令牌方案可作为课程设计或业务系统登录模块的参考。压缩包共 121 个文件、约 172KB以 java 源码与 class 字节码为主辅以 xml、properties 配置和 sample 示例另含 Maven 构建脚本与 Git 版本信息导入 IDE 即可运行调试。目前已有 11405 人学习下载读者可从中获得可跑通的扫码登录链路、接口参数与错误处理写法以及登录态与安全设计的落地思路。1. 后台管理系统接入微信扫码登录的真实起点运营同学嫌后台每次输账号密码麻烦提了个需求能不能像登录第三方网站那样拿手机扫一下就进去。这就是 springboot 实现 web 端微信扫码登录要解决的事——对接微信开放平台的「网站应用」走标准 OAuth2 授权码模式和公众号网页授权、小程序登录是三套完全不同的东西混着查文档会直接卡在第一步。这份项目适合两类人手里有后台系统、想让用户少记一个密码的开发者以及想拿它当 OAuth2 落地范本照着改成企业微信、钉钉、GitHub 登录的人。整条链路其实不长坑集中在回调域、code 一次性、身份合并这三处下面挨个拆开。2. 技术选型与工程结构一个扫码登录最少需要几个模块先把边界划清楚。微信扫码登录在服务端只干三件事拼一个带state的授权链接、拿回调回来的code去换微信侧身份、把微信身份和本地账号对上线并签发自己的会话。它不负责渲染二维码那是前端 JS 的事也不负责密码校验那是本地账号体系的事。想明白这层技术选型就不会跑偏不需要引入 Spring Security OAuth2 Client 那一整套那套的 provider 是给标准 OAuth2 服务端用的微信的snsapi_login在细节上跟标准有出入硬套要写一堆自定义OAuth2AccessTokenResponseClient反而比手写 HTTP 调用更绕。老实点用RestTemplate直接打两个接口代码量不到 80 行出问题还能一眼看到原始报文。2.1 依赖清单与三件套配置依赖控制在五个以内多一个都是负担!-- pom.xml 关键依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId !-- 存 state 和一次性票据 -- /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-validation/artifactId !-- 绑定接口参数校验 -- /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId !-- 账号表读写 -- /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId version0.11.5/version /dependency配置只认三件套app-id、app-secret、redirect-uri。这三个值来自开放平台后台创建「网站应用」后拿到的凭证缺一个都跑不通。wechat: open: app-id: wx0000000000000000 # 开放平台网站应用的 AppID app-secret: 00000000000000000000000000000000 redirect-uri: https://demo.example.com/callback/wechat # 必须与「授权回调域」同域 scope: snsapi_login # 网站应用固定这个不是 snsapi_userinfo connect-timeout: 3000 read-timeout: 5000scope这里踩过一次写成snsapi_userinfo页面直接白屏报错因为那是公众号网页授权用的值网站应用扫码只认snsapi_login。参数说明上redirect-uri在开放平台后台配置的是域名不带协议、不带路径、不带端口而代码里传的是完整 URL两者必须同域否则微信会返回「redirect_uri 参数错误」。对应绑定类ConfigurationProperties(prefix wechat.open) Data public class WxOpenProperties { private String appId; private String appSecret; private String redirectUri; private String scope snsapi_login; private int connectTimeout 3000; private int readTimeout 5000; }超时别用默认值。微信侧接口偶发慢响应RestTemplate不设超时会把 Tomcat 线程池拖住回调接口堵住之后用户看到的就是「扫码后一直转圈」。Bean public RestTemplate wxRestTemplate(WxOpenProperties props) { SimpleClientHttpRequestFactory f new SimpleClientHttpRequestFactory(); f.setConnectTimeout(props.getConnectTimeout()); f.setReadTimeout(props.getReadTimeout()); return new RestTemplate(f); }2.2 目录分层与各层职责工程按「HTTP 调用 / 业务编排 / 票据存储」三段切不要混src/main/java/com/example/wxlogin ├── WxLoginApplication.java ├── config │ ├── WxOpenProperties.java # 三件套配置绑定 │ ├── RestTemplateConfig.java # 带超时的 RestTemplate │ └── WebMvcConfig.java # 回调路径放行、CORS ├── controller │ ├── WxAuthController.java # /qrcode /callback /poll /bind /token │ └── UserController.java # /me ├── client │ └── WxOpenApiClient.java # 只做微信接口 HTTP 调用不含业务判断 ├── service │ ├── WxLoginService.java # 编排换身份 - 查绑定 - 发票据 │ ├── TicketService.java # Redis 票据的生成 / 消费 / 过期 │ └── WxAccountService.java # 绑定关系落库含并发兜底 ├── mapper │ └── WxAccountMapper.java ├── entity │ ├── WxAccount.java │ └── WxUserInfo.java # 微信侧身份openid/unionid/昵称/头像 └── common ├── R.java # 统一响应包装 ├── BizException.java └── JwtUtil.java分层的关键在于WxOpenApiClient只干一件事发请求、解析 JSON、把errcode翻译成异常。它不判断「这个用户有没有绑定过本地账号」那是WxLoginService的活。这么切的好处是后面要加企业微信或钉钉登录只换client层service编排逻辑基本不动。TicketService单独抽出来是因为整个流程里有三种生命周期不同的临时凭证state、绑定票据、登录票据散落在各个 service 里迟早会乱。统一交给一个类管过期时间、消费方式、key 命名都在一处排查时keys wx:login:*一眼就能看全。3. 核心链路拆解从二维码生成到本地会话落地的四段代码整条链路四个节点后端发授权链接 → 前端渲染二维码 → 用户扫码后微信回调 → 后端换身份并签发本地会话。每一段都有对应的代码块照抄改配置即可。3.1 生成授权链接与内嵌二维码二维码本身不用后端生成。微信提供两种方式整页跳转到open.weixin.qq.com/connect/qrconnect或者引入官方 JS 把二维码嵌到自己页面里。后者体验好用户不离开站点但要 HTTPS 页面且要传state。GetMapping(/api/auth/wechat/qrcode) public RQrCodeVO qrcode(RequestParam(defaultValue /dashboard) String redirect) { // state 一次性、5 分钟有效同时把扫码成功后要跳回的前端路径存进去 String state ticketService.newState(redirect); String url https://open.weixin.qq.com/connect/qrconnect ?appid props.getAppId() redirect_uri URLEncoder.encode(props.getRedirectUri(), StandardCharsets.UTF_8) response_typecode scope props.getScope() state state #wechat_redirect; // 锚点不能省否则部分浏览器样式和跳转会异常 return R.ok(new QrCodeVO(state, url, 300)); }QrCodeVO里带state是给前端轮询用的带url是给「整页跳转」方案兜底的。参数说明response_type固定codescope固定snsapi_loginredirect_uri必须URLEncoder编码一次否则带 query 的回调地址会被截断。前端内嵌渲染// 页面加载后拉一次后端接口拿到 state 和 url const { data } await axios.get(/api/auth/wechat/qrcode?redirect/dashboard); new WxLogin({ self_redirect: true, // true 表示在 iframe 内部跳转不整页刷新 id: wx-qrcode, // 容器 div 的 id appid: wx0000000000000000, // 与后端配置保持一致 scope: snsapi_login, redirect_uri: encodeURIComponent(https://demo.example.com/callback/wechat), state: data.state, style: black, href: // 自定义样式表地址留空用默认 });self_redirect设成true之后用户扫码确认时只有那个 iframe 跳去回调地址主页面不动接着靠轮询取结果——这就是后面 3.4 节要写的那段。3.2 回调入口code 换 openid 与 unionid微信回调会带两个参数code和state。code只能用一次、5 分钟过期拿到就立刻换别存着。GetMapping(/callback/wechat) public void callback(RequestParam(code) String code, RequestParam(state) String state, HttpServletResponse response) throws IOException { String target; try { // 1. state 必须存在且未被消费顺带取出扫码前想跳转的前端路径 ticketService.consumeState(state); // 2. code - openid/unionid WxUserInfo wx wxOpenApiClient.getUserByCode(code); // 3. 已绑定直接发登录票据未绑定发绑定票据 String ticket wxLoginService.loginOrBind(wx); target /login-bridge?ticket ticket; } catch (BizException e) { target /login-error?code e.getCode(); } // 重定向到不带 code 的地址避免用户按 F5 重放 response.sendRedirect(target); }这段里最关键的一行是最后的sendRedirect。如果回调页直接把结果渲染出来用户手一抖按了刷新浏览器会带着同一个code再请求一次微信侧返回40163 code been used前端就卡在错误页。重定向到不带code的地址刷新只是重新走前端页面不会重放。WxOpenApiClient里两个接口连着打public WxUserInfo getUserByCode(String code) { // 第一跳code 换 access_token openid String tokenUrl UriComponentsBuilder .fromHttpUrl(https://api.weixin.qq.com/sns/oauth2/access_token) .queryParam(appid, props.getAppId()) .queryParam(secret, props.getAppSecret()) .queryParam(code, code) .queryParam(grant_type, authorization_code) .toUriString(); JSONObject token checkError(get(tokenUrl)); String accessToken token.getString(access_token); String openid token.getString(openid); String unionid token.getString(unionid); // 应用绑到开放平台账号后才有 // 第二跳拉用户资料。注意 2021 年后昵称头像可能已匿名化 String infoUrl UriComponentsBuilder .fromHttpUrl(https://api.weixin.qq.com/sns/userinfo) .queryParam(access_token, accessToken) .queryParam(openid, openid) .queryParam(lang, zh_CN) .toUriString(); JSONObject info checkError(get(infoUrl)); WxUserInfo user new WxUserInfo(); user.setOpenid(openid); user.setUnionid(StringUtils.hasText(unionid) ? unionid : info.getString(unionid)); user.setNickname(info.getString(nickname)); user.setAvatar(info.getString(headimgurl)); return user; } private JSONObject checkError(JSONObject json) { Integer errcode json.getInteger(errcode); if (errcode ! null errcode ! 0) { // 40029 code 无效 / 40163 code 已被使用 / 40013 appid 不合法 throw new BizException(WX_ errcode, json.getString(errmsg)); } return json; }checkError这个薄封装很有必要。微信的接口 HTTP 状态码永远返回 200错误信息全塞在 body 的errcode里不主动判断就会把{errcode:40029}当成正常用户信息解析后面 NPE 报在任何地方都找不到根因。3.3 账号绑定新用户与老用户的分叉微信身份拿到之后要判断这个 openid/unionid 在本地库里有对应账号吗有就直接登录没有就走绑定流程。Transactional public String loginOrBind(WxUserInfo wx) { // 优先用 unionid 做身份主键它跨应用唯一没有才退回 openid String identity StringUtils.hasText(wx.getUnionid()) ? wx.getUnionid() : wx.getOpenid(); WxAccount account wxAccountMapper.selectByIdentity(identity); if (account ! null account.getUserId() ! null) { return ticketService.issueLoginTicket(account.getUserId()); // 老用户直接发登录票据 } return ticketService.issueBindTicket(wx); // 新用户发绑定票据 }绑定接口接住这张票据PostMapping(/api/auth/wechat/bind) public RLoginVO bind(RequestBody Valid BindDTO dto) { // 绑定票据一次性消费防止同一个扫码结果被拿来反复绑定 WxUserInfo wx ticketService.consumeBindTicket(dto.getBindTicket()); // 走本地账号体系校验账号密码 / 手机验证码这里以账号密码为例 User user userService.loginByPassword(dto.getUsername(), dto.getPassword()); wxAccountService.bind(user.getId(), wx); return R.ok(userService.issueToken(user)); }参数上bindTicket有效期我一般设 10 分钟——用户扫码后可能要找账号密码给太短会频繁过期给太长又放大重放风险。绑定成功后WxAccount表的user_id落库下次同一个微信扫码直接命中 3.3 的第一个分支。3.4 轮询换令牌把开放平台身份变成本地会话内嵌二维码模式下主页面不知道 iframe 里发生了什么靠轮询问后端GetMapping(/api/auth/wechat/poll) public RPollVO poll(RequestParam String state) { Ticket t ticketService.getTicket(state); if (t null) return R.ok(PollVO.expired()); if (t.isWaiting()) return R.ok(PollVO.waiting()); if (t.isNeedBind()) return R.ok(PollVO.needBind(t.getBindTicket())); return R.ok(PollVO.success(t.getLoginTicket())); }前端拿到success后再拿loginTicket换真正的 JWTPostMapping(/api/auth/wechat/token) public RLoginVO exchange(RequestParam String ticket) { // 一次性消费消费后立刻删 Redis同一个 ticket 换不出第二个 JWT Long userId ticketService.consumeLoginTicket(ticket); User user userService.getById(userId); return R.ok(userService.issueToken(user)); }这里的票据分两层loginTicket只是「证明你刚扫过码」的一次性凭证60 秒内有效真正给前端持久化的是 JWT。这么拆的原因是浏览器地址栏和前端日志都可能泄漏 ticket而 JWT 有签名、有exp还能配合 Redis 白名单做主动踢人。4. 状态机与安全细节state、Redis 票据与并发绑定扫码登录最容易出事的地方不是接口调不通而是「看起来通了但能被重放」。这一章讲三个防线。4.1 state 不是摆设防重放与防 CSRF很多人把state写成固定字符串甚至省略功能测试全过上线后被构造回调地址刷绑定。正确做法是32 位随机串、一次一用、和扫码会话绑定。private static final String STATE_KEY wx:login:state:; public String newState(String redirect) { String state RandomUtil.randomString(32); redis.opsForValue().set(STATE_KEY state, WAIT| redirect, Duration.ofMinutes(5)); return state; } // 读 删必须原子否则并发下同一个 state 会被消费两次 private static final RedisScriptLong DEL_IF_EQUALS new DefaultRedisScript( if redis.call(get, KEYS[1]) ARGV[1] then return redis.call(del, KEYS[1]) else return 0 end, Long.class); public String consumeState(String state) { String key STATE_KEY state; String val redis.opsForValue().get(key); if (val null) throw new BizException(STATE_EXPIRED, 二维码已过期); Long deleted redis.execute(DEL_IF_EQUALS, Collections.singletonList(key), val); if (deleted null || deleted 0) throw new BizException(STATE_REUSED, 请求已失效); return val.split(\\|, 2)[1]; // 取出扫码前想跳转的前端路径 }Lua 脚本那段是为了原子性。get完再del中间有窗口期攻击者并发打同一个state两个请求都能读到值都能往下走。用DEL_IF_EQUALS把「比对 删除」压成一个原子操作只有一个请求能拿到 1。4.2 Redis 票据的生命周期设计三张票据三套 TTL这张表建议直接抄进项目文档票据Redis Key写入时机TTL消费方消费方式statewx:login:state:{state}生成二维码5 分钟回调接口Lua 原子删除绑定票据wx:login:bind:{ticket}首次扫码未绑定10 分钟/api/auth/wechat/bindgetAndDelete登录票据wx:login:token:{ticket}已绑定或绑定成功60 秒/api/auth/wechat/tokengetAndDelete绑票据里存的是整个WxUserInfo的 JSON序列化用GenericJackson2JsonRedisSerializer别用 JDK 序列化——后者在容器里换个 JDK 小版本就可能读不出来排查起来纯纯玄学。登录票据只存userId越轻越好。需要注意state在回调消费掉之后轮询那边的 key 就查不到了。所以回调里消费state的同时要用同一个state再写一个轮询结果 key两个 key 前缀不同、生命周期独立别图省事混用一个。4.3 并发绑定与唯一索引兜底用户在两个浏览器同时扫同一个二维码或者网络抖动导致绑定接口重试都会往wx_account插重复记录。代码层的「先查再插」拦不住必须在库上加约束。CREATE TABLE wx_account ( id BIGINT NOT NULL AUTO_INCREMENT, user_id BIGINT DEFAULT NULL COMMENT 绑定的本地账号NULL 表示仅扫描未绑定, openid VARCHAR(64) NOT NULL, unionid VARCHAR(64) DEFAULT NULL, nickname VARCHAR(64) DEFAULT NULL, avatar VARCHAR(512) DEFAULT NULL, app_type VARCHAR(16) NOT NULL DEFAULT OPEN_WEB, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uk_openid_app (openid, app_type), UNIQUE KEY uk_unionid (unionid), KEY idx_user (user_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;unionid允许为 NULLMySQL 的唯一索引对多个 NULL 不做限制正好符合「没绑开放平台账号就没有 unionid」的情况。app_type加进联合唯一索引是为了同一个 openid 在不同应用网站应用、APP、公众号下能共存——它们本来就是不同维度的身份。代码侧接住这个约束public void bind(Long userId, WxUserInfo wx) { try { wxAccountMapper.insert(WxAccount.of(userId, wx)); } catch (DuplicateKeyException e) { // 并发下已经有记录了退化成更新保证幂等 wxAccountMapper.updateUserIdByIdentity(identityOf(wx), userId); } }5. 避坑与排查扫码登录最常见的 5 个翻车点这一章全是血泪经验每条按「现象 → 原因 → 解决」写遇到对得上的直接抄。5.1 页面提示「redirect_uri 参数错误」二维码都出不来现象点登录按钮微信页面白屏或者弹一行红字浏览器地址栏里redirect_uri看着是对的。原因开放平台后台的「授权回调域」填的不是一个纯域名。那个输入框只接受域名形如demo.example.com带上https://、带路径、带端口都会被判为不合法同时代码里传的redirect_uri必须与它同域路径可以有但域名部分必须完全一致。另一个高频原因是本地开发直接用localhost:8080当回调微信侧不接受这种地址。解决回调域只填域名本地调试把回调指到一个已经配置好的测试域名上通过反向代理转发到本机端口。还有一点网站应用需要企业资质审核个人主体申请不下来动手之前先确认手里有没有可用的 AppID不然代码写完也联调不了。5.2 扫码成功但立刻报 40163 code been used现象用户扫码确认回调接口报40163日志里同一个code出现了两次。原因code是一次性的5 分钟过期。常见的重复来源有三个——回调页直接渲染结果用户按了 F5浏览器预取或者某些安全插件提前请求了回调 URL前端在self_redirect模式下没关掉重试逻辑iframe 加载失败自动重试了一次。解决回调接口处理完立刻 302 到不带code的地址见 3.2 节最后一行。同时在回调入口加一层短 TTL 的code去重缓存同一个code第二次进来直接返回「请重新扫码」别再去打微信接口省得白白消耗配额。5.3 昵称全是「微信用户」头像是一张灰色默认图现象绑定时拿到的nickname是「微信用户」headimgurl是默认头像地址换几个号都一样。原因这不是代码问题。开放平台的用户信息接口在 2021 年底之后调整过策略不再返回真实的昵称和头像/sns/userinfo里那两个字段已经不可信。解决把昵称头像当成「可选信息」设计。首次绑定时让用户自己填昵称头像给几个预设或者上传如果业务强依赖头像走小程序或公众号侧的「头像昵称填写能力」让用户主动授权。别在登录链路上依赖这两个字段做任何判断比如「昵称为空就拒绝登录」这种逻辑上线就是全量拦截。5.4 同一个用户网站端和公众号端对不上号现象用户先关注了公众号在公众号里登录过后来在网站上扫码系统当成新用户又让他绑一次账号。原因openid是「应用维度」的标识。网站应用和公众号是两个不同的应用同一个用户在这两个应用下的 openid 完全不同拿 openid 做主键必然对不上。解决把两个应用都绑到同一个开放平台账号下用户信息里会多返回一个unionid它是「账号维度」的、跨应用唯一。工程上统一用unionid做身份主键openid只作为辅助字段存着用于后续调该应用自己的接口。代码里就是 3.3 节那句三元表达式有unionid用unionid没有才退回openid。5.5 扫码成功了前端一直转圈轮询永远返回 waiting现象手机端显示「已确认登录」PC 端页面还在转圈Network 面板里/poll每隔 2 秒返回一次waiting直到 5 分钟后变expired。原因回调里consumeState把wx:login:state:{state}删掉了而轮询接口查的是同一个 key自然永远查不到。这是流程设计上把「校验用的 state」和「承载结果的状态机」混成一个 key 导致的。也可能是前端轮询传的state是本地生成的 UUID跟后端返回的那个不是同一个。解决拆成两个 key。state只管防重放回调进来就消费掉另外用一个独立前缀比如wx:login:result:{state}写轮询结果值在WAIT/BIND:ticket/OK:ticket之间流转TTL 设 5 分钟。前端那边state一律以/qrcode接口返回的为准别自己造。6. 二次开发把扫码登录抽成可插拔的开放平台接入层这套代码跑通之后最自然的下一步是「再接一个平台」。如果按原始写法直接复制一份WxOpenApiClient改成企业微信版两周后就是四份几乎一样的回调代码改一个安全策略要改四处。我的做法是先抽接口再往里填实现。public interface OAuthClient { String platform(); // WX_OPEN / WX_WORK / OTHER String authorizeUrl(String state); // 拼授权链接 OAuthUser exchange(String code); // code 换身份 }WxOpenApiClient改成实现这个接口WxLoginService.loginOrBind的入参从WxUserInfo换成OAuthUser。回调路径带上平台标识/callback/{platform}由一个MapString, OAuthClient做分发——Spring 会自动把所有实现类注进这个 Mapkey 就是platform()的返回值加新平台只需要新增一个Component不改任何现有代码。票据层也要跟着泛化。TicketService里的三个方法目前入参都是WxUserInfo改成OAuthUser就行Redis key 前缀里带上平台标识避免不同平台的状态互相覆盖。改造完怎么验证我是用三个断言串起来的第一把redirect_uri故意改错一位确认回调能在 3 秒内返回明确的错误页而不是超时第二用同一个code连打两次回调接口确认第二次稳定返回业务异常且日志里有平台标识第三清空 Redis 后走完整流程确认三张票据的 TTL 与那张表对得上。这三步走完基本可以上线了。有个习惯我一直保留每次新增平台接入先在TicketService里把该平台的 key 前缀写进枚举再加 client 实现。顺序反了的话key 拼错是那种「功能正常但偶发不生效」的问题查起来最磨人。希望帮到你。本文还有配套的精品资源点击获取
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
