本文档是基本自己的项目基本实现逻辑一致基于 JustAuth 开源组件的三种微信登录形态集成说明微信开放平台、微信公众平台、小程序等目录一、前提准备应用注册二、整体架构概览三、技术栈与依赖四、JustAuth 框架封装说明五、全局配置六、方式一公众号扫码登录PC/普通浏览器七、方式二微信开放平台快捷登录H5/App 快捷登录八、方式三微信浏览器内静默授权无感知获取 openid九、注意事项与常见问题一、前提准备应用注册在对接任何一种微信登录之前必须先在微信官方平台申请相应应用并拿到以下关键凭证平台申请入口用途关键凭证微信公众平台https://mp.weixin.qq.com公众号扫码登录 微信内静默授权AppID、AppSecret微信开放平台https://open.weixin.qq.com快捷登录微信内 H5、App 拉起微信授权AppID、AppSecret微信开放平台 →网站应用开放平台内 → 创建应用 → 网站应用PC 网站扫码登录AppID、AppSecret注册后必须配置的白名单登录方式需配置的白名单位置公众号扫码登录网页授权域名不带协议、不带路径公众平台 → 开发 → 基本配置 → 公众号设置 → 功能设置开放平台快捷登录授权回调域开放平台 → 应用详情 → 网站信息 → 授权回调域微信内静默授权网页授权域名同公众号扫码同公众号扫码重要微信白名单不支持 localhost / 127.0.0.1本地调试需配 hosts 虚拟域名 Nginx 反代。二、整体架构概览三种方式的核心差异对比项方式一公众号扫码方式二开放平台快捷方式三静默授权适用终端PC、普通浏览器H5、App、PC仅微信内浏览器微信平台公众平台开放平台公众平台JustAuth 请求类AuthWeChatMpRequestAuthWeChatOpenRequestAuthWeChatMpRequest(仅换 openid)前端是否展示二维码✅ 是❌ 否前端调起授权❌ 否静默前端角色轮询等待扫码结果回调后直接拿 code仅触发跳转后端静默获取最终目的获取微信用户完整信息 → 登录获取微信用户完整信息 → 登录仅获取 openid→ 用于支付等场景三、技术栈与依赖技术说明JDK17框架Spring BootORMMyBatis-Plus三方登录核心JustAuthme.zhyd.oauth缓存Redis登录态管理Sa-Token工具HutoolBase64、JSON 等四、JustAuth 框架封装说明本项目通过SocialUtils对 JustAuth 进行了统一封装屏蔽了各平台的差异。4.1 核心类关系4.2 SocialUtils 支持的 source 值以下为与微信相关的三种 source完整支持列表见源码 switch-casesourceJustAuth 实现微信平台用途wechat_mpAuthWeChatMpRequest公众平台公众号扫码 静默授权wechat_openAuthWeChatOpenRequest开放平台快捷登录H5 / App / 网站五、全局配置5.1 application.yml 配置结构# JustAuth 三方登录配置 justauth: # 前端外网访问基址用于拼接 redirectUri address: https://your-domain.com ​ # 各平台独立配置 type: # --- 微信开放平台快捷登录 --- wechat_open: client-id: wx开放平台AppID client-secret: wx开放平台AppSecret # 后端回调接口本项目定义 redirect-uri: ${justauth.address}/auth/social/wechatOpen?sourcewechat_open ​ # --- 微信公众平台公众号扫码 静默授权 --- wechat_mp: client-id: wx公众号AppID client-secret: wx公众号AppSecret # 公众号扫码登录的回调方式一使用 redirect-uri: ${justauth.address}/auth/social/callback?sourcewechat_mp5.2 额外配置项# 静默授权成功后服务端重定向的首页地址 # 来源数据库 sys_dict_data 或 sys_config 表 # key wx.auth.redirect.url5.3 配置类绑定前缀justauth→SocialProperties带ConfigurationPropertiesjustauth.type.*→MapString, SocialLoginConfigProperties六、方式一公众号扫码登录PC/普通浏览器核心流程服务端拼接授权地址 → 前端生成二维码 → 用户扫码 → 微信回调后端 →前端轮询Redis 获取结果 → 调用统一登录接口6.1 时序图6.2 涉及接口清单#接口方法调用方说明1/auth/binding/wechat_mpGET前端生成微信 authorizeUrl uuid2/auth/social/callbackGET微信服务器扫码授权回调code 换 AuthUser写 Redis3/auth/scanCodeResGET前端轮询根据 uuid 读取 Redis 中的扫码结果4/auth/loginPOST前端拿结果后统一登录入口grantTypesocial6.3 关键接口详细说明① 生成扫码 URLGET /auth/binding/{source}?domain{domain} sourcewechat_mp请求参数参数类型必传说明sourceString是固定wechat_mpdomainString是前端当前域名用于后续前端回跳返回示例state里面是自定义参数。redirect_uri跳转地址服务端需要和配置的域名一致{ code: 200, msg: 操作成功, data: { uuid: e9cbbe619d7823493469ae83d477ee40, authorizeUrl: https://open.weixin.qq.com/connect/oauth2/authorize?appidwxd761ef931d1a57deredirect_urihttps%3A%2F%2Fecc.waper.com.cn%2Fwp3dmall%2Fauth%2Fsocial%2Fcallback%3Fsource%3Dwechat_mpresponse_typecodescopesnsapi_userinfostateeyJkb21haW4iNuIiwic3RhdGUiOiJlOWNiYmU2MTlkNzgyMzQ5MzQ2OWFlODNkNDc3ZWU0MCJ9#wechat_redirect, state: eyJkb21haW4iNuIiwic3RhdGUiOiJlOWNiYmU2MTlkNzgyMzQ5MzQ2OWFlODNkNDc3ZWU0MCJ9 }, isExpired: false }② 微信扫码回调GET /auth/social/callback?sourcewechat_mpcode{code}state{state}此接口由微信服务器主动回调前端不直接调用。后端处理Base64 解码state→ 拿到内部uuidSocialUtils.loginAuth(wechat_mp, code, state, properties)→ JustAuth 内部完成code → access_token → 刷新 access_token → 用户信息最终返回AuthUser含 uuid / nickname / avatar / openid 等RedisUtils.setCacheObject(SOCIAL_USER uuid, AuthUser, 10min)— 存完整用户信息RedisUtils.setCacheObject(SOCIAL_LOGIN uuid, SocialLoginBody, 10min)— 存登录参数返回成功 HTML 页面用户扫码后看到扫码成功请关闭此页面③ 前端轮询扫码结果GET /auth/scanCodeRes?uuid{uuid}返回未扫码 / 未授权R.ok(null, false)已授权R.ok(socialLoginBody)— data 为SocialLoginBody对象SocialLoginBody 字段字段类型说明sourceString固定wechat_mpsocialCodeString微信 codesocialStateString微信 stateBase64 编码phonenumberString绑定手机号时传bindUserboolean是否已绑定系统用户uuidString本次扫码唯一标识七、方式二微信开放平台快捷登录PC 网页快捷登录系统实现效果当无法识别微信是否登录时或浏览器不支持时会以二维码的形式进行授权登录核心流程前端拿到 code → 调后端换用户信息 → 后端写 Redis 并直接返回 → 前端走统一登录接口7.1 时序图7.2 涉及接口清单#接口方法调用方说明1/auth/binding/wechat_open可选GET前端生成 authorizeUrl也可前端直接调微信这里主要是2/auth/social/wechatOpenGET前端核心接口code 换 AuthUser 写 Redis 直接返回 SocialLoginBody3/auth/loginPOST前端统一登录入口7.3 wechatOpen 接口特点与方式一回调接口的关键差异对比项方式一 callback方式二 wechatOpen调用方微信服务器浏览器302跳转前端 JSXHR/fetch返回类型返回 HTML 页面返回 JSON 对象R.ok(socialLoginBody)前端体验需轮询 关闭浏览器同步等待即可拿到 SocialLoginBody 直接调 login适用PC 扫码场景H5/App 快捷授权场景八、方式三微信浏览器内静默授权无感知获取 openid适用场景用户在微信内浏览器打开系统链接需要无感知拿到 openid用于后续支付等场景不做登录。核心流程前端拿 authorizeUrl → 微信静默授权scopesnsapi_base→ 后端回调 code 换 openid → Redis 存 openid → 服务端重定向到系统首页8.1 时序图8.2 涉及接口清单#接口方法调用方说明1/auth/social/getCallbackUrlGET前端生成静默授权 authorizeUrl state2/auth/social/callback/getAuthGET微信服务器code 换 openid写 Redis重定向首页3/auth/social/getOpenIdGET前端登录后根据 state 从 Redis 取 openid8.3 getCallbackUrl 接口细节GET /auth/social/getCallbackUrl无请求参数内部固定使用wechat_mp配置 snsapi_base作用域。返回{ code: 0, msg: null, data: { authorizeUrl: https://open.weixin.qq.com/connect/oauth2/authorize?appid...redirect_uri...response_typecodescopesnsapi_basestate...#wechat_redirect, state: MWIyYzNkNGU1ZjY3ODkA, appId: 公众号 AppID } }8.4 与方式一/二的关键差异对比项方式三静默授权方式一/二扫码/快捷登录scopesnsapi_base仅 openidsnsapi_userinfo用户完整信息JustAuth 调用gerAccessToken()loginAuth()Redis KeySOCIAL_AUTH:{state}SOCIAL_USER:{uuid}SOCIAL_LOGIN:{uuid}最终目的拿 openid拿用户信息 → 登录系统前端后续动作首页加载后调getOpenId调/auth/login是否需要登录取 openid 时需要已登录登录前调用九、注意事项与常见问题9.1 redirect_uri 编码JustAuth 内部会处理 redirect_uri 的编码但微信官方要求回调地址必须与注册时的完全一致包括 query 参数。排错技巧回调失败先检查 redirect_uri 在微信后台注册的是否和配置文件justauth.type.*.redirect-uri完全一致。9.2 state 防 CSRFJustAuth 自带 state 校验机制AuthRedisStateCache生成 authorizeUrl 时写入 Redis回调时自动比对过期时间与授权时间保持一致9.3 三种方式的使用边界场景推荐方式原因PC 网页登录方式一公众号扫码PC 没有微信 App只能扫码H5 登录浏览器中方式二开放平台开放平台快捷授权体验更好App 拉起微信登录方式二开放平台开放平台支持 App 端拉起微信 SDK微信内浏览器无感知拿 openid方式三静默授权唯一能在微信内静默拿 openid 的方式微信内浏览器登录方式二开放平台 App 授权开放平台授权后直接回传用户信息9.4 本地调试方案微信白名单不支持 localhost推荐方案# hosts 127.0.0.1 your-test-domain.comNginx 反代 (HTTPS)server { listen 443 ssl; server_name your-test-domain.com; ssl_certificate ...;location / { proxy_pass http://127.0.0.1:8080; }}然后把justauth.address改为https://your-test-domain.com。9.5 JustAuth getAccessToken 与 loginAuth 对比方法微信接口返回内容适用getAccessToken()/sns/oauth2/access_tokenAuthTokenaccess_token、openid、refresh_token、expireIn只需要 openidlogin()/sns/oauth2/access_token /sns/userinfoAuthUseruuid、nickname、avatar、openid token需要完整用户信息做登录9.6 跨平台统一用户unionid当用户同时关注公众号、使用开放平台应用时微信通过unionid识别同一用户。JustAuth 返回的AuthUser.uuid优先取 unionid如果配置了unionId: true否则取 openid。建议在wechat_open和wechat_mp配置中都开启unionId: true以确保多端登录识别到同一用户。