简介：针对Java开发者实现钉钉微应用免登进入H5系统首页的完整技术方案文档，面向企业内部应用开发人员，解决用户通过钉钉打开微应用后免登录直登H5首页的授权与身份校验问题。压缩包内为1个PDF文件，整包大小仅129KB，内容精炼便于快速查阅。目前已有2113人学习下载。文档完整梳理了从钉钉开放平台创建微应用、配置白名单与接口权限，到ddNoLogin.html前端页面获取免登授权码、后端通过access_token换取用户信息的全流程，并附有Java定时刷新token的实现代码。读者可参照其中前后端协作思路，结合钉钉API快速落地免登功能，同时借鉴消息通知与权限判断等扩展设计，提升应用安全性与用户体验。
1. 钉钉微应用免登：为什么你的 H5 系统还在让用户重复输密码
很多公司把内部的 OA、报表、工单系统做成 H5 挂到钉钉工作台，用户每天第一件事就是在手机浏览器里再输一遍账号密码。钉钉微应用免登的意义就在于：用户在钉钉里点开微应用，钉钉客户端已经替他完成了身份认证，H5 通过一次授权码交换就能拿到钉钉用户身份，Java 服务端据此签发自己的登录态，用户直接落到 H5 系统首页，全程看不到登录页。这篇文章面向正在做企业自建应用接入、被登录态打通卡住的后端和前端同学，把免登链路、Java 实现、前端配合和常见坑一次讲透。适合谁：有 Java 后端基础，H5 是普通 SPA 或服务端渲染，想把钉钉身份和自有账号体系接起来的人。
2. 免登背后的认证链路：一次 code 交换一次钉钉身份
2.1 免登时序：钉钉客户端、H5 页面、Java 服务端三方怎么配合
钉钉微应用免登不是“钉钉直接把用户名密码发给你的系统”，它是一条三方配合的授权链。整个链路拆成五步：用户在钉钉工作台点开微应用，钉钉客户端注入 JSAPI 环境；H5 页面调用钉钉 JSAPI 获取免登授权码 authCode；H5 把 authCode 通过后端接口传给 Java 服务端；Java 服务端拿 authCode 加上自己的 appKey/appSecret，向钉钉开放平台换取用户身份 userid；最后服务端用 userid 查到或创建自有系统用户，签发 JWT 或会话，把登录态返回 H5，H5 带上登录态跳首页。
这里面最关键的设计是：H5 永远拿不到 appSecret，也拿不到钉钉用户的通讯录敏感资料，它只传递一次性 code。这样即使 H5 前端被攻击，泄露的也只是几分钟就失效的授权码，而不是整个企业通讯录权限。很多第一次接免登的同学会困惑“为什么前端还要传一个 code 给后端，不能直接告诉后端我是谁”，原因就在这：钉钉只认后端用 appSecret 签发的请求，前端说的话它一句都不信。
时序上还有一个容易忽略的点：authCode 发到 H5 之后，如果前端没有立刻传给后端，而是等用户填了个表单再提交，code 很可能已经过期了。所以免登动作要在页面加载后第一时间触发，拿到 code 马上走后端接口，不要把它暂存到某个全局变量里等业务操作完成再提交。这个顺序错一步，线上就会有 1% 到 2% 的免登失败率，表现为用户偶尔要重新登录。
和传统账号密码登录对比，免登省掉的不是安全校验，而是输入动作。系统该做的身份校验、权限校验一步都不能少，只是把“用户名+密码”换成了“钉钉说这个人是张三”，后端再根据张三去匹配系统角色。这也是为什么面试八股里常把单点登录和免登混在一起问，实际两者解决的不是同一个问题：单点登录解决多个系统共享登录态，免登解决移动端工作台到 H5 的身份传递。
2.2 免登必需的参数：appKey、appSecret、agentId 从哪来、怎么配
要跑通免登，你得先在钉钉开放平台创建一个“企业内部应用”。创建完成后，应用后台的基本信息里能看到三个关键参数：
| 参数 | 说明 | 获取位置 |
|---|---|---|
| appKey | 应用标识，客户端公开但不敏感 | 开发者后台 → 应用详情 → 凭证与基础信息 |
| appSecret | 应用密钥，等价于密码，只能后端持有 | 同上，建议放配置中心或环境变量 |
| agentId | 微应用 ID，部分接口和鉴权场景需要 | 应用详情 → 基本信息 |
除了这三个，还有两个容易漏的配置。一是“开发管理 → 服务器域名”，要把 H5 系统实际部署的域名加进白名单，否则免登接口会被钉钉拦截，本地 localhost 联调时还要把测试域名临时配上去；二是“版本管理与发布”，企业内部应用要发布一个版本后，工作台里才能被员工看到，调试时自己能看到不代表全员可见，很多团队开发完点开应用发现界面没更新，就是版本没发布。
注意：这里说的是企业自建应用。如果你做的是第三方应用（ISV），凭证名称会变成 suiteKey/suiteSecret，调用链路和自建应用完全不同，别拿第三方应用的配置套自建应用的代码，反过来也一样。自己没建过应用、直接抄别人代码最容易在这个地方翻车，跑起来后 gettoken 一直报错，排查半天发现是凭证类型不对。
2.3 访问令牌 access_token：免登的“门票”与两点核心约束
Java 服务端拿 authCode 换 userid 之前，得先向钉钉开放平台获取 access_token。这个 token 通过 gettoken 接口用 appKey 加 appSecret 换取，有效时长 7200 秒，是整个企业应用共享的通行证，调用通讯录、审批等接口都需要它。
第一个约束是必须缓存。如果每个免登请求都去调一次 gettoken，钉钉会按照应用维度限流，高并发下直接报“触发访问限制”。常见做法是把 access_token 放进程内缓存或 Redis，设置过期时间略短于 7200 秒，比如 6900 秒，留出刷新余量。放内存要考虑多实例问题，放 Redis 要考虑所有实例统一读一个 key，这两种做法各有取舍，后面代码里先给进程内缓存实现。
第二个约束是安全问题。access_token 能换取整个企业应用的数据权限，所以 appSecret 绝对不能出现在前端代码、静态资源包或 GitHub 仓库里。有些团队为图方便把 appSecret 写死在 H5 的 config.js 里，一旦源码泄露，攻击者直接调 gettoken 接口拿到企业通讯录全量数据，这种事故比免登失败严重得多。正确做法是 appSecret 只存在于 Java 服务端的配置中心，通过环境变量注入，代码仓库里只留占位符。
提示：access_token 过期后必须用 appSecret 重新换取，没有刷新 token 这个说法。所以服务端要做的是提前刷新，而不是等请求报错后再补一次获取，后者会造成偶发的免登失败。
3. Java 服务端实现免登接口：从 code 到登录态的完整代码
3.1 免登接口设计：请求参数、响应体与会话策略
先定接口契约，我一般这么设计：
- URL：POST /api/auth/dingtalk
- 请求体：{ "authCode": "一次性免登授权码" }
- 成功响应：{ "token": "JWT字符串", "userName": "张三", "expireAt": 1720000000000 }
- 失败响应：{ "code": 40001, "message": "免登失败：authCode 已失效" }
会话策略推荐用 JWT 而不是传统 HttpSession。原因是微应用 H5 经常会被嵌入到别的页面，或者从钉钉工作台跳到第三方浏览器内核，跨域场景下 Cookie 传递很麻烦，JWT 放在 Authorization 头里最省事。JWT 要设合理过期时间，比如 2 小时，同时服务端配合 Redis 做黑名单实现登出。
另一个设计点是：免登成功后要不要自动创建用户？我建议首次免登查到 userid 后，先到自有用户表按 dingUserId 查，查不到就自动建档，初始角色给“未激活”或“普通员工”，等管理员分配权限。这样员工第一次点开微应用就能直接进首页，不用等管理员手工建号。如果你们系统对权限敏感，可以把初始状态设计为“只能看首页，不能操作任何菜单”，既保体验又控风险。
3.2 调用钉钉免登 API：用 Java 的 HttpClient 实现 code 换 userid
这里不依赖钉钉官方 SDK，用 Java 11 自带的 java.net.http.HttpClient 就能跑通，省掉一堆历史版本冲突。只要 java 环境变量配好，JDK 11 以上直接能编译执行，不需要额外引包。先写一个 DingTalkClient 组件，负责两件事：获取并缓存 access_token、用 authCode 换 userid。
package com.example.dingtalk; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.time.Duration; @Component public class DingTalkClient { private static final String GET_TOKEN_URL = "https://oapi.dingtalk.com/gettoken"; private static final String GET_USER_INFO_URL = "https://oapi.dingtalk.com/topapi/v2/user/getuserinfo"; private final HttpClient httpClient = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(5)) .build(); private final ObjectMapper objectMapper = new ObjectMapper(); @Value("${dingtalk.app-key}") private String appKey; @Value("${dingtalk.app-secret}") private String appSecret; // access_token 本地缓存：volatile 保证多线程可见 private volatile String accessToken; private volatile long expireAt; /** * 获取 access_token，带进程内缓存 */ public String getAccessToken() { if (accessToken != null && System.currentTimeMillis() < expireAt) { return accessToken; } String url = GET_TOKEN_URL + "?appkey=" + appKey + "&appsecret=" + appSecret; String body = get(url); try { JsonNode node = objectMapper.readTree(body); if (node.get("errcode").asInt() != 0) { throw new RuntimeException("获取钉钉access_token失败: " + node.get("errmsg").asText()); } accessToken = node.get("access_token").asText(); int expiresIn = node.get("expires_in").asInt(); // 提前300秒过期，给刷新留余量 expireAt = System.currentTimeMillis() + (expiresIn - 300) * 1000L; return accessToken; } catch (Exception e) { throw new RuntimeException("解析钉钉access_token响应异常", e); } } /** * 免登 code 换取钉钉用户信息 */ public DingTalkUser getUserByAuthCode(String authCode) { String token = getAccessToken(); String url = GET_USER_INFO_URL + "?access_token=" + token; String requestBody = "{\"code\":\"" + authCode + "\"}"; String body = post(url, requestBody); try { JsonNode node = objectMapper.readTree(body); if (node.get("errcode").asInt() != 0) { throw new RuntimeException("钉钉免登失败: " + node.get("errmsg").asText()); } JsonNode result = node.get("result"); DingTalkUser user = new DingTalkUser(); user.setUserId(result.get("userid").asText()); return user; } catch (Exception e) { throw new RuntimeException("解析钉钉免登响应异常", e); } } private String get(String url) { try { HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .GET() .timeout(Duration.ofSeconds(5)) .build(); return httpClient.send(request, HttpResponse.BodyHandlers.ofString()).body(); } catch (Exception e) { throw new RuntimeException("GET请求钉钉接口异常", e); } } private String post(String url, String jsonBody) { try { HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(jsonBody)) .timeout(Duration.ofSeconds(5)) .build(); return httpClient.send(request, HttpResponse.BodyHandlers.ofString()).body(); } catch (Exception e) { throw new RuntimeException("POST请求钉钉接口异常", e); } } }这段代码里几个参数说明：GET_TOKEN_URL使用 oapi.dingtalk.com 域名下的 gettoken 接口，appKey 和 appSecret 直接跟在 query 上，服务端保存的 appSecret 永远不会暴露给 H5。getAccessToken()加了进程内缓存，提前 300 秒过期避免临界点失效，并发环境下用 volatile 保证拿到的是最新 token，但要注意多实例部署时每个进程各缓存一份，生产环境建议换成 Redis。
超时设 5 秒是实际联调攒出来的经验。钉钉开放平台接口在高峰期偶发慢响应，超时太长会拖垮业务线程池，太短又容易误判失败。5 秒是大多数团队权衡后的常用值，你可以根据线上接口 P99 再微调。getUserByAuthCode()调的 topapi/v2/user/getuserinfo 是当前免登推荐接口，access_token 在 URL query 上，authCode 在 JSON body 里，返回的 result 中 userid 是必取字段。
3.3 打通自有用户体系：userid 映射、JWT 签发与登录接口
拿到钉钉 userid 只是第一步，下一步是把钉钉身份映射到自有系统用户表，并签发自己的登录态。下面是 Controller 和 Service 的完整实现：
package com.example.dingtalk; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/api/auth") public class AuthController { private final DingTalkClient dingTalkClient; private final SysUserService userService; private final JwtTokenService tokenService; public AuthController(DingTalkClient dingTalkClient, SysUserService userService, JwtTokenService tokenService) { this.dingTalkClient = dingTalkClient; this.userService = userService; this.tokenService = tokenService; } @PostMapping("/dingtalk") public Result<LoginVo> loginByDingTalk(@RequestBody DingTalkLoginRequest request) { if (request.getAuthCode() == null || request.getAuthCode().isBlank()) { return Result.fail("缺少authCode"); } // 第一步：免登 code 换钉钉用户身份 DingTalkUser dingUser = dingTalkClient.getUserByAuthCode(request.getAuthCode()); // 第二步：按 userid 映射自有用户，不存在则自动建档 SysUser sysUser = userService.findOrCreateByDingUserId(dingUser.getUserId()); // 第三步：签发 JWT 登录态 String jwt = tokenService.createToken(sysUser.getId()); LoginVo vo = new LoginVo(jwt, sysUser.getNickname(), tokenService.getExpireAt()); return Result.ok(vo); } }Controller 里的三步顺序不能乱：先做认证，再做用户映射，最后发登录态。不要把“查到钉钉用户”当成“登录成功”，钉钉通讯录里的人和业务系统用户表不是一一对应的，它只是一条映射关系，有没有权限要落到自有用户表上判断。如果用户被管理员停用，即使钉钉身份有效，系统也应该拒绝签发 token，这一步要在findOrCreateByDingUserId里检查状态。
@Service public class SysUserService { private final SysUserMapper sysUserMapper; private final DingTalkContactClient contactClient; public SysUserService(SysUserMapper sysUserMapper, DingTalkContactClient contactClient) { this.sysUserMapper = sysUserMapper; this.contactClient = contactClient; } public SysUser findOrCreateByDingUserId(String dingUserId) { SysUser user = sysUserMapper.selectByDingUserId(dingUserId); if (user != null) { return user; } // 自动建档：同步钉钉昵称，初始状态设为未激活 SysUser newUser = new SysUser(); newUser.setDingUserId(dingUserId); newUser.setNickname(contactClient.getNickname(dingUserId)); newUser.setStatus("INACTIVE"); sysUserMapper.insert(newUser); return newUser; } }user 表的ding_user_id字段要建唯一索引，否则自动建档并发时会插入两条重复用户。JWT 的密钥从环境变量读取，别写死在 yml 配置里。token 里只放 userId 和一个会话随机数，不放钉钉 userid，避免之后钉钉人员调整时 JWT 里残留旧身份信息，这也是安全审计时容易被问到的一个点。
4. H5 前端接免登：从钉钉 JSAPI 拿 code 到跳回首页
4.1 引入 dingtalk-jsapi 与环境判断：钉钉里和浏览器里两条路
H5 页面要拿到免登 code，需要引入钉钉官方 JSAPI 库，npm 包名是 dingtalk-jsapi，安装后在入口文件里引入并配置：
import * as dd from 'dingtalk-jsapi';const DING_CONFIG = { corpId: 'dingxxxxxxxxxxxxxxxx', agentId: 123456789 }; // 判断是否在钉钉客户端内 const isInDingTalk = typeof window !== 'undefined' && window.DingTalkJSBridge;代码里corpId是企业的唯一标识，agentId是微应用 ID，两者在钉钉开发者后台都能看到，注意 agentId 是数字，corpId 是 ding 开头的字符串，写反了调用 JSAPI 会直接报错。isInDingTalk判断依赖钉钉客户端注入的 JSBridge 对象，这个对象只在钉钉内置浏览器里有，普通浏览器或微信里打开 H5 时不存在。
这个降级判断必须有。很多用户会把微应用链接收藏到浏览器里每天直接打开，如果一进去就调 requestAuthCode，只会得到一个失败回调，页面卡在空白。正确做法是：检测到不在钉钉环境，直接跳转到自有系统的账号密码登录页，登录成功后进同一个首页。这样钉钉内打开走免登，浏览器打开走账密，两条路都通。
4.2 获取免登 code 并交给 Java 服务端：完整前端登录流程
有了环境判断，接着写完整的免登登录方法：
import axios from 'axios'; function getDingTalkAuthCode() { return new Promise((resolve, reject) => { dd.ready(function () { dd.runtime.permission.requestAuthCode({ corpId: DING_CONFIG.corpId, onSuccess: function (info) { resolve(info.code); }, onFail: function (err) { reject(new Error('获取免登code失败: ' + JSON.stringify(err))); } }); }); }); } async function loginByDingTalk() { if (!window.DingTalkJSBridge) { // 非钉钉环境，跳转账号密码登录页兜底 window.location.href = '/login'; return; } try { const authCode = await getDingTalkAuthCode(); const { data } = await axios.post('/api/auth/dingtalk', { authCode }); if (data.code === 0) { localStorage.setItem('token', data.data.jwt); axios.defaults.headers.common['Authorization'] = 'Bearer ' + data.data.jwt; window.location.href = '/home'; // 进入H5系统首页 } } catch (e) { // 失败时跳登录页，避免卡死 window.location.href = '/login?error=dingtalk_auth_failed'; } }dd.runtime.permission.requestAuthCode是钉钉 JSAPI 里最常用的免登授权方法，onSuccess 的info.code就是一次性授权码，有效时间大约 5 分钟，只能用一次。拿到后立刻传给后端，不要在中间穿插其他业务逻辑。axios 拦截器里统一设置 Authorization 头，后续请求就都带上 JWT，不再重复走免登。
token 放 localStorage 是最简单做法，但要注意 XSS 风险：如果 H5 系统存在富文本渲染漏洞，攻击者能直接偷走 token。更稳的做法是放内存变量，刷新时重新请求一个短期 token，或者放 HttpOnly Cookie 并配好 SameSite 策略。取舍取决于你们前端架构，没有标准答案。
4.3 微应用首页 URL 配置与登录态续期：两个容易翻车的小细节
钉钉后台配置微应用首页 URL 时，可以直接填 H5 系统地址，也可以带固定参数，比如https://your-domain.com?from=dingtalk。但有一个容易被忽略的约束：如果配置 URL 时已经带了 query 参数，钉钉跳转时可能还会在后面追加自己的参数，前端解析时一旦用了错误的分隔方式，authCode 就是坏的。
我见过一个真实例子：首页 URL 配成https://a.com/index?channel=ding，跳转过后的链接变成https://a.com/index?channel=ding&authCode=xxx，前端直接把 authCode 值取出来传给后端，忘记做 URL decode，后端拿到的 code 带转义字符，去换 userid 必然失败。建议统一用 JSAPI 方式拿 code，不要在 URL 上解析参数，省得踩编码的坑。
另一个细节是登录态续期。JWT 2 小时过期，员工可能上午打开微应用挂到下午，再点某个按钮时 token 已失效。常见做法是前端在 axios 响应拦截器里判断 401，弹一个“登录已过期”的提示，然后跳回免登流程重新拿 code 换新 token。用户体验上，重新免登比重新输密码好得多，钉钉环境里登录过期对员工来说几乎是无感的。
5. 免登接入避坑指南：5 个真实踩坑记录
5.1 同样的 code 调两次接口，第二次报“无效的 code”
现象：用户反馈偶尔登录失败，后端日志里同一个 authCode 第一次请求成功，第二次报“无效的 code”。原因：钉钉免登 code 是一次性的，用了就作废。前端在弱网环境里请求超时后自动重试了一次，同一个 code 被消费两遍。
解决：前端做防重复提交，点击登录后按钮置灰加 loading 状态；后端再做一层幂等，把消费过的 code 指纹存 Redis，key 设为ding:code:{authCode}，过期时间 10 分钟，用 SETNX 判断是否已消费。这里要说明：code 有效期 5 分钟，Redis key 过期时间比它长一倍是为了覆盖重复请求窗口。
5.2 本地联调全通，部署到测试服务器就免登失败，报“域名不合法”
现象：本地跑得好好的，代码发到测试环境，一进微应用就报错，钉钉返回“域名不在白名单”。原因：钉钉开放平台对微应用服务器域名做白名单校验，本地 localhost 配过，测试域名没配。
解决：登录钉钉开发者后台，进入应用详情 → 开发管理 → 服务器域名，把 H5 系统实际使用的域名加进去。dev、test、prod 三套环境的域名要分别配，换域名后同步更新后台，否则下个环境上线就是一次线上事故。这里特别提醒：域名校验是精确匹配的，不要尝试配泛域名通配符，钉钉不支持，配了第二天接口就报错。
5.3 gettoken 接口报“appKey 无效”，明明从后台复制出来的没错
现象：代码里 appKey/appSecret 看着没问题，gettoken 一直返回“appKey 无效”。原因：多半是把第三方应用的 suiteKey/suiteSecret 当成自建应用的 appKey/appSecret 用了，或者用的是旧版应用遗留的凭证，新建应用后参数没同步。
解决：回到应用详情页重新复制“凭证与基础信息”里的 appKey/appSecret，只复制当前自建应用的。同时检查代码里有没有把 appSecret 硬编码在公共常量类，如果有，改到配置中心和环境变量。排查时可以用钉钉开放平台的在线调试工具先验证凭证本身是否有效，再回头查代码，少走半小时弯路。
5.4 免登成功，后端拿到 userid，但自有系统里查不到用户，页面空转
现象：员工第一次点微应用，后端免登接口正常返回，但页面一直停在加载中。原因：自有用户表和钉钉通讯录没建立映射，免登只认证身份，不创建业务账号，后端查不到用户直接抛异常。
解决：按 3.3 的 findOrCreateByDingUserId 自动建档，或者上线前跑一次全量同步任务，调用钉钉通讯录接口把所有有效员工的 userid、手机号、姓名同步进来。注意同步要考虑离职员工，要包含停用逻辑，避免人走了系统还在自动建档。自动建档还有个好处：员工首次进入就是可用的，不用管理员逐个手工建号。
5.5 微应用能打开，但 requestAuthCode 一直 onFail，提示 permission denied
现象：H5 页面正常渲染，一调 requestAuthCode 就走 onFail，错误是 permission denied。原因：钉钉 JSAPI 授权不仅看应用域名白名单，还看应用是否发布、当前用户是否在应用可见范围内。很多团队开发完没点“版本发布”，员工侧访问的还是旧版本，JSAPI 权限不完整。
解决：确认应用已在开发者后台完成版本发布，工作台可见范围包含测试账号。调试时用钉钉扫码登录管理后台，把测试账号加入可见范围。另外注意：如果 H5 是 SPA 动态切换路由，每次进入需要重新触发 dd.ready 的页面，都要保证初始化逻辑执行了，不要在某个子路由里直接调 requestAuthCode 绕过初始化。
6. 免登做得再稳一点：凭证缓存、幂等校验与安全留痕
免登链路跑通只是起点，线上稳定才是目标。我建议在三件事上继续投入。
第一，access_token 缓存从进程内存迁到 Redis，并加定时刷新任务。多实例部署时，如果每个实例各自缓存一份 token，钉钉按应用维度限流，高并发下部分实例会报“触发调用限制”。用 Redis 存 token，key 带 appKey 后缀，定时任务每 30 分钟检查一次，剩余有效时间小于 30 分钟就主动刷新，所有实例共享一份 token，回源频率降下来。
第二，免登 code 消费做成幂等。生产环境里前端重试、用户连点、网关重放都会让同一个 code 被提交多次，用 Redis 的 SETNX 做指纹去重，过期时间 10 分钟，正好覆盖 code 的 5 分钟有效期。顺手把这个去重结果写进日志，方便事后回溯是哪一次请求真正完成了登录。
第三，安全留痕要记录四样东西：钉钉 userid、本系统 userId、来源 IP、UA。日志格式统一成dingLogin|userId=1001|dingId=xxx|ip=1.2.3.4|ua=xxx，后面排查异常登录全靠它。这是血泪经验，早期免登不打日志，出问题时钉钉侧说有调用记录，我们这边却对不上人，两边黑匣子一样无从查起。
再加一条习惯：每周抽一次线上日志，关注免登成功率和失败率。正常情况员工在钉钉里点开微应用，免登成功率应该接近 100%，如果某天失败率涨到 5% 以上，优先看 access_token 是否过期、域名有没有变更。把失败率做成监控指标后，免登问题基本都能在员工感知之前被发现。
如果你后面要接飞书嵌入 H5 免登录，流程逻辑几乎一样，差别在 token 换取接口、code 命名和 corpId 的传法。把钉钉相关代码收敛到独立的 dingtalk 包下，适配层和业务层分开写，以后换平台只改适配层，业务登录逻辑一行都不用动。这是我对所有接入免登型项目的最后一条建议：别让钉钉代码散落在 Controller 和 Service 各处，维护起来会轻松很多。希望帮到你。
本文还有配套的精品资源，点击获取
