簡(jiǎn)介本資源面向使用Java開(kāi)發(fā)釘釘企業(yè)內(nèi)部應(yīng)用的開(kāi)發(fā)者聚焦“釘釘微應(yīng)用免登進(jìn)入H5系統(tǒng)首頁(yè)”這一典型場(chǎng)景幫助讀者打通前端獲取免登授權(quán)碼與后端校驗(yàn)用戶(hù)身份的完整鏈路。資源包內(nèi)含1個(gè)PDF文檔壓縮包約129KB以圖文形式梳理了從釘釘開(kāi)放平臺(tái)創(chuàng)建H5微應(yīng)用、配置agentId、appKey、appSecret與corpId到前端ddNoLogin.html調(diào)用requestAuthCode獲取code、后端換取access_token并查詢(xún)用戶(hù)信息的實(shí)現(xiàn)思路同時(shí)涉及接口權(quán)限開(kāi)通、公網(wǎng)IP白名單、token定時(shí)刷新與緩存等關(guān)鍵細(xì)節(jié)。目前已有2113人學(xué)習(xí)下載適合需要快速落地釘釘免登功能、減少重復(fù)登錄步驟的Java后端與前端協(xié)作開(kāi)發(fā)者參考可據(jù)此理解授權(quán)流程、接口調(diào)用順序及異常處理要點(diǎn)。1. 釘釘微應(yīng)用免登進(jìn) H5為什么你的首頁(yè)總在登錄頁(yè)打轉(zhuǎn)做過(guò)釘釘微應(yīng)用的人都遇到過(guò)一個(gè)尷尬場(chǎng)景用戶(hù)在釘釘工作臺(tái)點(diǎn)開(kāi)應(yīng)用本該直接看到業(yè)務(wù)首頁(yè)結(jié)果頁(yè)面先跳出一個(gè)賬號(hào)密碼框或者干脆白屏卡在 loading。這不是前端路由寫(xiě)錯(cuò)了而是免登鏈路里某個(gè)環(huán)節(jié)斷了。釘釘微應(yīng)用免登進(jìn)入某 H5 系統(tǒng)首頁(yè)本質(zhì)是讓釘釘客戶(hù)端把當(dāng)前用戶(hù)的身份憑證傳給后端后端換取用戶(hù)信息并建立會(huì)話前端拿到會(huì)話后直接渲染首頁(yè)全程不需要用戶(hù)輸入任何賬號(hào)密碼。這套機(jī)制依賴(lài)三個(gè)東西釘釘?shù)拿獾鞘跈?quán)碼、企業(yè)內(nèi)部的 AppKey/AppSecret、以及后端對(duì)釘釘開(kāi)放接口的調(diào)用。適合誰(shuí)看正在用 Java 做企業(yè)內(nèi)嵌 H5 的開(kāi)發(fā)者尤其是被“微應(yīng)用免登”卡過(guò)一整天的人。下面按真實(shí)落地順序拆開(kāi)講從原理到代碼到踩坑能直接抄。2. 免登鏈路拆解從釘釘容器到 Java 后端的完整握手2.1 免登到底免了什么三個(gè)角色和兩次交換先把角色擺清楚。釘釘客戶(hù)端是容器H5 頁(yè)面跑在容器的 WebView 里Java 后端是業(yè)務(wù)服務(wù)器。免登不是“不驗(yàn)證”而是把驗(yàn)證動(dòng)作從用戶(hù)輸入密碼換成了釘釘內(nèi)部的身份傳遞。具體走兩步交換第一步H5 頁(yè)面通過(guò)釘釘提供的 JSAPI 拿到一個(gè)臨時(shí)授權(quán)碼這個(gè)碼叫 authCode有效期很短通常幾分鐘且一次只能用一次第二步Java 后端拿 authCode 加上自己的 AppKey 和 AppSecret去釘釘開(kāi)放平臺(tái)換用戶(hù) ID再用用戶(hù) ID 查自己數(shù)據(jù)庫(kù)里的賬號(hào)建立 session 或簽發(fā) token。整個(gè)過(guò)程用戶(hù)無(wú)感知所以叫免登。這里有個(gè)容易混淆的點(diǎn)authCode 不是 access_token。authCode 是用戶(hù)級(jí)別的臨時(shí)憑證access_token 是應(yīng)用級(jí)別的調(diào)用憑證。很多新手把兩者搞混拿 authCode 去調(diào)需要 access_token 的接口直接報(bào)錯(cuò)。正確順序是先用 AppKey AppSecret 換企業(yè)級(jí) access_token再用 access_token authCode 換用戶(hù)信息。這個(gè)順序不能反。2.2 前端拿 authCodedd.ready 里那行不能省的代碼H5 頁(yè)面要拿到 authCode必須引入釘釘?shù)?JSAPI并在 dd.ready 回調(diào)里調(diào)用 runtime.permission.requestAuthCode。注意這個(gè)調(diào)用必須在釘釘容器內(nèi)才有效用普通瀏覽器打開(kāi)會(huì)直接失敗。下面是最小可用的前端代碼。// 引入釘釘 JSAPI通常放在 head 里 // script srchttps://g.alicdn.com/dingding/dingtalk-jsapi/2.13.42/dingtalk.open.js/script dd.ready(function() { // 必須傳 corpId否則拿不到 authCode dd.runtime.permission.requestAuthCode({ corpId: 你的企業(yè)corpId, onSuccess: function(info) { // info.code 就是 authCode傳給后端 var authCode info.code; fetch(/api/dingtalk/login, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ authCode: authCode }) }) .then(res res.json()) .then(data { if (data.success) { // 后端返回 token存起來(lái)跳首頁(yè) localStorage.setItem(token, data.token); window.location.href /home; } else { console.error(免登失敗, data.msg); } }); }, onFail: function(err) { console.error(獲取authCode失敗, err); } }); });邏輯說(shuō)明dd.ready 保證 JSAPI 加載完成后再調(diào)用否則 dd 對(duì)象可能未定義。corpId 是企業(yè)標(biāo)識(shí)在釘釘開(kāi)放平臺(tái)后臺(tái)能查到填錯(cuò)會(huì)直接返回權(quán)限錯(cuò)誤。authCode 拿到后立刻發(fā)給后端不要在前端做任何解析或緩存因?yàn)樗且淮涡缘?。參?shù)上requestAuthCode 只接受 corpId 一個(gè)必填項(xiàng)其他可選參數(shù)一般不用動(dòng)。2.3 Java 后端換用戶(hù)信息兩步 HTTP 調(diào)用和參數(shù)表后端收到 authCode 后要做兩次 HTTP 請(qǐng)求。第一次用 AppKey 和 AppSecret 換 access_token第二次用 access_token 和 authCode 換用戶(hù) ID。下面用 Java 的 HttpClient 寫(xiě)一個(gè)完整示例不依賴(lài)第三方 SDK方便你直接放進(jìn)項(xiàng)目。import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; public class DingTalkLoginService { private static final String APP_KEY 你的AppKey; private static final String APP_SECRET 你的AppSecret; private static final String GET_TOKEN_URL https://oapi.dingtalk.com/gettoken; private static final String GET_USER_URL https://oapi.dingtalk.com/topapi/v2/user/getuserinfo; private final HttpClient httpClient HttpClient.newHttpClient(); private final ObjectMapper objectMapper new ObjectMapper(); // 第一步獲取 access_token public String getAccessToken() throws Exception { String url GET_TOKEN_URL ?appkey APP_KEY appsecret APP_SECRET; HttpRequest request HttpRequest.newBuilder() .uri(URI.create(url)) .GET() .build(); HttpResponseString response httpClient.send(request, HttpResponse.BodyHandlers.ofString()); JsonNode node objectMapper.readTree(response.body()); if (node.get(errcode).asInt() ! 0) { throw new RuntimeException(獲取token失敗: node.get(errmsg).asText()); } return node.get(access_token).asText(); } // 第二步用 authCode 換用戶(hù)ID public String getUserId(String authCode) throws Exception { String accessToken getAccessToken(); String url GET_USER_URL ?access_token accessToken code authCode; HttpRequest request HttpRequest.newBuilder() .uri(URI.create(url)) .GET() .build(); HttpResponseString response httpClient.send(request, HttpResponse.BodyHandlers.ofString()); JsonNode node objectMapper.readTree(response.body()); if (node.get(errcode).asInt() ! 0) { throw new RuntimeException(獲取用戶(hù)信息失敗: node.get(errmsg).asText()); } return node.get(result).get(userid).asText(); } }邏輯說(shuō)明getAccessToken 把 appkey 和 appsecret 拼在 URL 上釘釘返回 JSONerrcode 為 0 才算成功。access_token 默認(rèn)有效期 7200 秒不要每次請(qǐng)求都重新獲取建議緩存起來(lái)否則容易觸發(fā)頻率限制。getUserId 用 access_token 和 authCode 換 userid這個(gè) userid 是企業(yè)內(nèi)唯一標(biāo)識(shí)拿它去查你系統(tǒng)的用戶(hù)表。參數(shù)上APP_KEY 和 APP_SECRET 必須從釘釘開(kāi)放平臺(tái)后臺(tái)獲取不要硬編碼在代碼里放配置文件或環(huán)境變量。2.4 建立會(huì)話與首頁(yè)跳轉(zhuǎn)token 簽發(fā)和攔截器配置拿到 userid 后下一步是把它映射成你系統(tǒng)的用戶(hù)。常見(jiàn)做法是維護(hù)一張 dingtalk_user 表字段包括 userid、系統(tǒng)賬號(hào)、姓名等。如果 userid 已存在直接簽發(fā) token如果不存在可以自動(dòng)創(chuàng)建賬號(hào)或走綁定流程。token 建議用 JWT有效期設(shè) 2 小時(shí)左右刷新機(jī)制另做。前端拿到 token 后存 localStorage后續(xù)請(qǐng)求帶在 Header 里。后端配一個(gè)攔截器校驗(yàn) token 有效性無(wú)效則返回 401前端收到 401 再重新走免登。這樣首頁(yè)就能直接渲染不會(huì)跳登錄頁(yè)。3. 把免登接進(jìn)現(xiàn)有 Java 系統(tǒng)配置、緩存和異常兜底3.1 配置文件怎么寫(xiě)AppKey 和 corpId 的存放位置不要把 AppKey、AppSecret、corpId 寫(xiě)死在 Java 代碼里。推薦放在 application.yml 或 properties 里通過(guò) Value 或 ConfigurationProperties 注入。下面是一個(gè) Spring Boot 的配置示例。dingtalk: app-key: dingxxxxxxxxxxxx app-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx corp-id: dingxxxxxxxxxxxx token-cache-seconds: 7000邏輯說(shuō)明token-cache-seconds 設(shè) 7000 而不是 7200是留 200 秒余量避免邊界時(shí)間失效。corpId 前端也要用可以通過(guò)接口下發(fā)給前端不要在前端硬編碼。如果項(xiàng)目沒(méi)有用 Spring Boot用 Properties 類(lèi)加載也一樣核心是配置和代碼分離。3.2 access_token 緩存別每次請(qǐng)求都去換access_token 有調(diào)用頻率限制每次免登都重新獲取會(huì)很快觸發(fā)限流。常見(jiàn)做法是用本地緩存比如 Caffeine 或 Guava Cache設(shè)置過(guò)期時(shí)間略小于 7200 秒。下面是一個(gè)簡(jiǎn)單的緩存實(shí)現(xiàn)。import com.github.benmanes.caffeine.cache.Cache; import com.github.benmanes.caffeine.cache.Caffeine; import java.util.concurrent.TimeUnit; public class TokenCache { private static final CacheString, String CACHE Caffeine.newBuilder() .expireAfterWrite(7000, TimeUnit.SECONDS) .maximumSize(10) .build(); public static String getToken(DingTalkLoginService service) throws Exception { String token CACHE.getIfPresent(access_token); if (token null) { token service.getAccessToken(); CACHE.put(access_token, token); } return token; } }邏輯說(shuō)明expireAfterWrite 設(shè) 7000 秒寫(xiě)入后 7000 秒自動(dòng)過(guò)期。maximumSize 設(shè) 10 足夠因?yàn)橥ǔＶ挥幸粋€(gè)企業(yè)的 token。如果多企業(yè)場(chǎng)景key 換成 appKey。注意Caffeine 是本地緩存多實(shí)例部署時(shí)每個(gè)實(shí)例各自緩存token 可能不一致但釘釘允許同一應(yīng)用多個(gè)有效 token所以問(wèn)題不大。如果要求嚴(yán)格一致用 Redis 集中緩存。3.3 免登失敗時(shí)的降級(jí)什么時(shí)候該跳綁定頁(yè)免登不是 100% 成功。常見(jiàn)失敗原因有authCode 過(guò)期、userid 在系統(tǒng)里不存在、網(wǎng)絡(luò)超時(shí)。這時(shí)候不能直接白屏要有降級(jí)策略。如果 userid 不存在跳轉(zhuǎn)到賬號(hào)綁定頁(yè)讓用戶(hù)輸入一次系統(tǒng)賬號(hào)密碼綁定后下次就能免登。如果 authCode 過(guò)期前端重新調(diào) requestAuthCode 再試一次。如果網(wǎng)絡(luò)超時(shí)提示用戶(hù)重試。下面是一個(gè)后端返回結(jié)構(gòu)的建議。{ success: false, code: USER_NOT_BOUND, msg: 用戶(hù)未綁定請(qǐng)先綁定賬號(hào), bindUrl: /bind?dingUserIdxxx }邏輯說(shuō)明code 用枚舉值前端根據(jù) code 決定跳哪個(gè)頁(yè)面。bindUrl 帶上 dingUserId綁定頁(yè)提交時(shí)一起傳給后端。這樣用戶(hù)體驗(yàn)是連貫的不會(huì)卡在登錄頁(yè)。4. 免登踩坑實(shí)錄authCode 失效、corpId 錯(cuò)配和跨域4.1 authCode 只能用一次重復(fù)使用直接報(bào)錯(cuò)現(xiàn)象前端拿到 authCode 后因?yàn)榫W(wǎng)絡(luò)抖動(dòng)重試了一次請(qǐng)求后端第二次用同一個(gè) authCode 換用戶(hù)信息釘釘返回 invalid code。原因authCode 是一次性憑證用過(guò)即廢。解決前端在請(qǐng)求失敗時(shí)不要復(fù)用舊 authCode而是重新調(diào) requestAuthCode 獲取新的。后端也可以做冪等但 authCode 本身無(wú)法冪等只能前端重新獲取。4.2 corpId 填錯(cuò)dd.ready 里直接拿不到 code現(xiàn)象dd.ready 回調(diào)執(zhí)行了但 requestAuthCode 的 onFail 被觸發(fā)錯(cuò)誤信息是權(quán)限不足。原因corpId 和企業(yè)實(shí)際 ID 不匹配或者應(yīng)用沒(méi)有在該企業(yè)下開(kāi)通。解決去釘釘開(kāi)放平臺(tái)后臺(tái)確認(rèn) corpId確保應(yīng)用已發(fā)布且可見(jiàn)范圍包含當(dāng)前用戶(hù)。corpId 通常以 ding 開(kāi)頭不要和 AppKey 搞混。4.3 跨域問(wèn)題H5 域名沒(méi)加進(jìn)釘釘白名單現(xiàn)象前端 fetch 請(qǐng)求后端接口時(shí)被瀏覽器攔截報(bào) CORS 錯(cuò)誤。原因釘釘容器內(nèi) WebView 的域名安全策略或者后端沒(méi)配 CORS。解決在釘釘開(kāi)放平臺(tái)后臺(tái)把 H5 頁(yè)面域名加入“安全域名”列表同時(shí)后端配好 Access-Control-Allow-Origin。注意釘釘容器內(nèi)跨域和普通瀏覽器略有不同安全域名必須配否則 JSAPI 都可能調(diào)不了。4.4 access_token 緩存過(guò)期邊界導(dǎo)致偶發(fā)免登失敗現(xiàn)象大部分用戶(hù)免登正常少數(shù)用戶(hù)偶爾失敗錯(cuò)誤是 access_token 無(wú)效。原因緩存過(guò)期時(shí)間設(shè)得和釘釘實(shí)際有效期太接近邊界時(shí)刻拿到已失效的 token。解決緩存時(shí)間設(shè) 7000 秒留足余量。如果還出現(xiàn)檢查服務(wù)器時(shí)間是否同步時(shí)間偏差也會(huì)導(dǎo)致 token 校驗(yàn)失敗。4.5 用戶(hù) userid 對(duì)不上免登后查不到賬號(hào)現(xiàn)象免登流程走通了但后端用 userid 查用戶(hù)表返回空用戶(hù)看到“賬號(hào)不存在”。原因釘釘?shù)?userid 和企業(yè)內(nèi)部賬號(hào)的映射關(guān)系沒(méi)建立或者用戶(hù)換了部門(mén)導(dǎo)致 userid 變化。解決首次免登時(shí)如果 userid 不存在走綁定流程把 userid 和系統(tǒng)賬號(hào)關(guān)聯(lián)起來(lái)。后續(xù)如果 userid 變化需要同步更新映射表。建議在用戶(hù)表加一個(gè) ding_userid 字段并建索引。5. 免登之后用 JWT 續(xù)期和靜默刷新把首頁(yè)體驗(yàn)做順免登只是第一步用戶(hù)進(jìn)入首頁(yè)后token 會(huì)過(guò)期。如果每次過(guò)期都重新走免登體驗(yàn)會(huì)斷。更好的做法是 JWT 雙 token 機(jī)制access_token 短有效期refresh_token 長(zhǎng)有效期。access_token 過(guò)期時(shí)前端用 refresh_token 靜默刷新用戶(hù)無(wú)感知。下面是一個(gè)簡(jiǎn)單的刷新接口示例。// 刷新token接口 public String refreshToken(String refreshToken) { // 校驗(yàn)refreshToken有效性 if (!jwtUtil.validate(refreshToken)) { throw new RuntimeException(refreshToken無(wú)效); } String userId jwtUtil.getUserId(refreshToken); // 簽發(fā)新的accessToken return jwtUtil.sign(userId, 7200); // 2小時(shí) }邏輯說(shuō)明refreshToken 有效期可以設(shè) 7 天存在 localStorage。前端攔截 401 響應(yīng)自動(dòng)調(diào)刷新接口拿到新 token 后重試原請(qǐng)求。如果 refreshToken 也過(guò)期再走一次免登。這樣用戶(hù)只要在釘釘里就能一直保持登錄態(tài)。另一個(gè)技巧是首頁(yè)數(shù)據(jù)預(yù)加載。免登成功后后端在簽發(fā) token 的同時(shí)把首頁(yè)需要的用戶(hù)信息和配置一起返回前端拿到后直接渲染減少一次請(qǐng)求。這個(gè)看業(yè)務(wù)復(fù)雜度如果首頁(yè)數(shù)據(jù)多可以拆成異步加載但用戶(hù)信息建議同步返回。我自己的習(xí)慣是免登接口的日志一定要打全包括 authCode 的前幾位、userid、耗時(shí)、錯(cuò)誤碼。出問(wèn)題時(shí)這些日志能幫你快速定位是釘釘側(cè)還是自己側(cè)的問(wèn)題。還有測(cè)試環(huán)境不要用生產(chǎn)企業(yè)的 corpId申請(qǐng)一個(gè)測(cè)試企業(yè)避免污染真實(shí)數(shù)據(jù)。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取