简介面向Java开发者的钉钉集成完整方案覆盖开放平台接入、OAuth2.0授权、消息推送、企业通讯录管理、工作日志与审批流构建以及Android/iOS移动端对接等企业级协作场景适合有Java基础、正计划将业务系统与钉钉深度整合的开发人员。压缩包共174个文件类目涵盖Java源码、class编译文件、jar依赖库、HTML示例页面、JS脚本、XML配置等整体约8.17MB可按模块快速定位所需代码。已有3481人浏览学习内容包含从初始化配置、获取access_token到调用接口封装的完整Demo并针对鉴权、加密、异步事件回调等关键点整理出可直接复用的辅助类。资源还附带源码分析与测试调试思路有助于开发者理解钉钉API调用全流程规避常见权限与时效问题从而高效构建稳健的定制化集成应用。1. 阿里钉钉集成APIJava到底在解决什么问题从“应用孤岛”到“统一工作台”阿里钉钉集成APIJava听起来像“调用一个接口”真正做起来是把企业内部系统接到钉钉开放平台让员工在钉钉工作台里收到工作通知、点击链接进入内部业务页面或者把审批结果自动回传到公司台账。大多数团队做这件事不是为了聊天而是为了把“人、消息、流程”收拢到一个入口里减少来回切换系统的成本。适合谁维护Java后端、负责OA/HR/CRM对接的开发者以及准备在钉钉上做企业内部应用集成的技术负责人。这篇笔记会把落地路径拆开讲清楚先讲选型与权限再给获取token、发消息、拉通讯录和审批的Java代码最后列几条常见的线上排错结论。2. 集成前必须想清楚的五件事应用类型、权限点、域名与Java选型代码动手之前先确认四件事应用类型、权限点、回调域名和Java HTTP客户端。很多项目做到一半翻车不是接口不会调而是应用类型选错、权限没发布、IP白名单没配。我一般会先开一个文档把下面这几项逐条确认再写代码。2.1 先定应用类型企业内部应用能做什么、不能做什么钉钉开放平台上应用分为企业内部应用和第三方应用两大类。企业内部应用由企业自己创建只服务本组织的成员创建后直接拿到appKey和appSecret不需要审核也可以配置应用可见范围。第三方应用也叫“应用市场应用”需要开发者以服务商身份申请走应用发布和一整套授权流程一般是软件服务商给多个客户交付时使用。对大部分公司来讲把内部OA、HR、ERP接到钉钉选择“企业内部应用”就够了。这个决定会直接影响后续API的调用方式。企业内部应用的appSecret只有一份所有后端服务共享同一个token第三方应用的鉴权则涉及套件、授权企业的corpId复杂度高一个数量级。我见过一个项目开发时图省事在第三方应用上调试结果权限模型一直对不上最后推倒重来改成企业内部应用。如果你的目标只是“让公司员工在钉钉里打开我们的系统”不需要考虑多租户交付就选企业内部应用别犹豫。另外还要区分“H5微应用”和“扫码登录应用”前者挂在钉钉工作台里员工从工作台进入后者是让外部用户在网页上通过钉钉扫码登录。两者都能调用部分API但应用类型不同后台入口和权限列表也不同。如果既要工作台入口又要扫码登录通常需要创建两个应用分别管理不要指望一个应用同时具备所有能力。2.2 权限点申请与作用域权限不是勾选即生效钉钉的每个OpenAPI接口都对应一个权限点后台叫“权限管理”。你需要先在权限管理里搜索接口对应的权限集并申请然后在“版本管理与发布”里发布一个新版本权限才会对这个应用真正生效。这个流程我强调一下不是后台勾上权限就够了很多团队在测试环境申请了权限代码里还是报无权限排查半天发现是正式环境的应用没有重新发布。常见权限对照可以参考下面这张表业务场景权限集/权限点典型接口获取部门与员工信息通讯录个人信息读权限/v1.0/contact/subDepartments、/v1.0/contact/users发送工作通知工作通知消息发送权限/v1.0/robot/workNotice/send读取审批实例审批实例读权限/topapi/processinstance/get接收事件回调事件订阅回调权限回调URL上面表格里的权限集名称可能会随开放平台改版变化但思路一致接口名可以在权限点列表里搜索找到后确认它属于哪个权限集。还有一点容易被忽略权限范围。如果你的应用“可用范围”只选了技术部那么即使你有通讯录读取权限接口返回的数据大概率也被限定在技术部可见范围内不是全公司。需要拉全量数据时把应用范围加上对应部门并让管理员注意数据隐私。2.3 回调域名与服务器出口IP两个硬性配置事件订阅是钉钉集成里最常用的能力消息已读、审批结果、通讯录变更都可以通过回调推给你。配置回调时有两点必须注意。第一回调URL必须是钉钉服务器可以访问到的公网HTTPS地址不能是localhost也不能带query参数。第二URL要能响应钉钉的验证请求这个验证不是普通Rest接口的GET而是POST一段加密数据具体逻辑放到第4章讲。除了回调域名还有一个“服务器出口IP”配置。在应用后台的开发管理里钉钉允许你配置后端服务器的出口IP白名单。配置后所有来自该应用的API调用都必须来源于白名单IP否则会报IP受限。这个功能很安全但也是个坑如果你用了负载均衡或弹性伸缩服务器出口IP可能不固定导致线上调用偶尔失败。常见做法是先不配IP白名单把功能调通再核对服务器的真实出口IP并写入白名单。注意如果服务器有IPv6双栈出口IP可能不止一个需要全部加进去。2.4 Java侧选型Spring Boot RestTemplate Jackson技术选型上我通常用Spring Boot RestTemplate Jackson不额外引入官方SDK。原因有三个一是团队对Spring技术栈最熟RestTemplate足够覆盖钉钉API这种简单HTTP调用二是官方SDK的版本和钉钉OpenAPI演进速度不完全同步有些接口在SDK里找不到反而逼着你去翻原始文档三是裸接口调用出现的错误可以在日志里直接看到钉钉返回的JSON定位问题比翻SDK源码快得多。如果你对HTTP客户端有更高性能要求可以换成OkHttp或WebClient但要注意连接池配置。钉钉API的QPS限制通常不高RestTemplate默认使用的SimpleClientHttpRequestFactory在并发稍高时会创建大量连接我一般会替换成HttpClient的工厂设置最大连接数。Java工程里依赖长这样dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.apache.httpcomponents.client5/groupId artifactIdhttpclient5/artifactId /dependencypom不写版本号Spring Boot的依赖管理会自动带入。第一个依赖提供RestTemplate和Jackson第二个依赖提供连接池支持。使用时把RestTemplate注册成一个Bean并替换底层请求工厂Bean public RestTemplate dingTalkRestTemplate() { HttpClientBuilder builder HttpClients.custom() .setMaxConnTotal(200) .setMaxConnPerRoute(50); CloseableHttpClient httpClient builder.build(); HttpComponentsClientHttpRequestFactory factory new HttpComponentsClientHttpRequestFactory(httpClient); factory.setConnectTimeout(3000); factory.setReadTimeout(5000); return new RestTemplate(factory); }这段代码的关键是连接池和超时。钉钉API偶发慢请求3秒连接超时、5秒读超时是我习惯的起点如果机器到钉钉机房链路比较长可以放宽到6秒但不要超过10秒——回调处理如果太慢钉钉会判定超时重试。等代码量上来之后你会发现超时配置直接影响线上故障率尤其是月底审批高峰时慢请求会把线程池拖垮。3. 从零跑通钉钉APIJava获取accessToken与工作通知的最小代码在后台创建好企业内部应用拿到appKey和appSecret之后第一步就是获取accessToken。钉钉开放平台目前有新旧两套API我下面的代码以新版为主因为新应用默认使用新版接口token放在请求头里比拼在URL上更容易控制日志泄露风险。3.1 认清新旧两套API别用错域名旧版接口域名是oapi.dingtalk.com鉴权方式是把access_token作为URL参数例如gettoken接口返回的是access_token字段。新版接口域名是api.dingtalk.com接口路径以/v1.0开头统一的token获取接口是/v1.0/oauth2/accessToken返回字段是accessToken。很多教程混着写导致不少同学拿着新版的token去请求旧版接口或者反过来。我的建议是如果是新创建的应用全部使用新版接口只有碰到新版没有覆盖的接口比如部分审批详情才保留个别旧版调用并在代码里注明原因。3.2 获取accessToken的最小Java方法直接看代码public class DingTalkTokenClient { private static final String TOKEN_URL https://api.dingtalk.com/v1.0/oauth2/accessToken; private final RestTemplate restTemplate; public DingTalkTokenClient(RestTemplate restTemplate) { this.restTemplate restTemplate; } public String getAccessToken(String appKey, String appSecret) { // 新版token接口的请求体是appKey/appSecret小驼峰 MapString, String body new HashMap(); body.put(appKey, appKey); body.put(appSecret, appSecret); HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); HttpEntityMapString, String request new HttpEntity(body, headers); MapString, Object response restTemplate.postForObject( TOKEN_URL, request, Map.class); if (response null || !response.containsKey(accessToken)) { throw new IllegalStateException(钉钉token接口响应异常: response); } return (String) response.get(accessToken); } }这段代码做三件事拼请求体、设置Content-Type为application/json、发起POST。注意钉钉新版返回的是accessToken首字母小写t不是access_token。如果看到response里取不到accessToken优先检查是不是把请求体里的appKey写成了appkey。另外token返回时带一个expireIn字段单位是秒默认7200不要硬编码成永久。3.3 发送工作通知msgParam是个JSON字符串拿到token后最常用的一个能力是给员工发工作通知。新版接口路径是/v1.0/robot/workNotice/send鉴权通过请求头x-acs-dingtalk-access-token传入token。发送文本消息的最小代码public void sendWorkNotice(String accessToken, String userId, String content) throws JsonProcessingException { String url https://api.dingtalk.com/v1.0/robot/workNotice/send; HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); headers.set(x-acs-dingtalk-access-token, accessToken); // msgParam 需要是字符串这里先把文本参数序列化为JSON ObjectMapper mapper new ObjectMapper(); MapString, String textParam new HashMap(); textParam.put(content, content); String msgParam mapper.writeValueAsString(textParam); MapString, Object body new HashMap(); body.put(userId, userId); body.put(msgKey, sampleText); body.put(msgParam, msgParam); HttpEntityMapString, Object request new HttpEntity(body, headers); MapString, Object response restTemplate.postForObject( url, request, Map.class); if (response null || response.containsKey(code)) { throw new IllegalStateException(发送工作通知失败: response); } }这里最容易踩的坑是msgParam。钉钉定义的msgParam是一个字符串里面装的是JSON对象序列化后的文本。很多人直接把Map放进去接口返回参数错误。msgKey决定消息模板sampleText对应纯文本sampleMarkdown对应MarkdownsampleActionCard对应带按钮的卡片。如果只是做业务通知sampleMarkdown比纯文本效果好因为标题加粗、支持多行。还需要注意userId。新版工作通知的接收人字段是userId不是手机号也不是工号。你需要先通过通讯录接口根据手机号或工号拿到钉钉体系里的userId再调发送接口。一个userId一次只能发一个人要批量发送就循环调用并在循环里加一点间隔不要一次性把几百个请求打过去。3.4 accessToken全局刷新策略缓存、锁与提前过期token有效期只有7200秒必须管理生命周期。最简单的方案是单实例缓存加锁Component public class AccessTokenHolder { private final DingTalkTokenClient tokenClient; private final String appKey your-app-key; private final String appSecret your-app-secret; private volatile String token; private volatile long expireAt; public AccessTokenHolder(DingTalkTokenClient tokenClient) { this.tokenClient tokenClient; } public String get() { long now System.currentTimeMillis(); // 提前2秒过期避免网络延迟导致延续使用过期token if (now expireAt - 2000) { return token; } synchronized (this) { if (now expireAt - 2000) { return token; } token tokenClient.getAccessToken(appKey, appSecret); expireAt now 7200 * 1000; return token; } } }双重检查锁是为了防止并发请求同时去刷新token。如果你用Spring Cloud或Kubernetes部署了多个实例建议把token放到Redis里key设为dingtalk:accessTokenvalue为token过期时间设为7000秒并加一个分布式锁否则每个实例各持一个token一旦实例增多钉钉侧会看到大量token请求容易被限流。我经历过一次两个实例同时刷新明明接口配置没问题却每隔一小时出现几分钟鉴权失败最后才发现是token获取被限流了。4. 通讯录与审批四个高频场景的Java封装与参数陷阱token管理稳定之后就可以开始接业务接口了。我给你整理四个高频场景的调用思路和参数获取部门、获取用户、拉取审批、订阅事件回调。这四个场景基本覆盖了内部系统与钉钉对接的大多数诉求。4.1 获取部门列表树形结构处理与根部门ID钉钉的部门是树形结构根部门ID是1。新版获取子部门接口是public ListMapString, Object listSubDepartments( String accessToken, Long parentId) { String url https://api.dingtalk.com/v1.0/contact/subDepartments ?departmentId parentId; HttpHeaders headers new HttpHeaders(); headers.set(x-acs-dingtalk-access-token, accessToken); HttpEntityVoid request new HttpEntity(headers); ResponseEntityMap exchange restTemplate.exchange( url, HttpMethod.GET, request, Map.class); MapString, Object response exchange.getBody(); // 返回结构里result是部门数组 ListMapString, Object result (ListMapString, Object) response.get(result); return result null ? Collections.emptyList() : result; }返回值里的每个部门至少包含departmentId、name、parentId三个字段。递归拼装整棵树时建议按parentId分组再递归避免每层查询都调用一次接口。如果部门数量很大钉钉也会对单个接口加分页限制我在项目里是按层遍历每层一个请求控制QPS。还有一种更省事的方案只拉取当前业务需要的部门和子部门不追求全量组织架构。4.2 获取部门用户列表分页从0开始获取部门用户列表新版接口是public ListMapString, Object listUsers( String accessToken, Long departmentId, int pageNumber, int pageSize) { String url https://api.dingtalk.com/v1.0/contact/users?departmentId departmentId pageNumber pageNumber pageSize pageSize; HttpHeaders headers new HttpHeaders(); headers.set(x-acs-dingtalk-access-token, accessToken); HttpEntityVoid request new HttpEntity(headers); ResponseEntityMap exchange restTemplate.exchange( url, HttpMethod.GET, request, Map.class); MapString, Object response exchange.getBody(); MapString, Object result (MapString, Object) response.get(result); ListMapString, Object list (ListMapString, Object) result.get(list); return list null ? Collections.emptyList() : list; }这里的pageNumber从0开始不是从1开始pageSize最大100。如果按1开始第一页会跳过第一个用户批量拉取时会出现“少一个人”现象。返回的每个用户里有userId、name、title、mobile等字段mobile默认脱敏需要申请通讯录敏感信息权限。关联自建系统时优先使用userId因为它在企业内稳定如果同一个员工在多个组织里对应不同账号才需要unionId。4.3 拉取审批实例主动查询还是回调推送审批场景有两种接法轮询和回调。轮询多用于一次性补偿数据回调用于实时通知。审批详情接口我沿用旧版因为它在老版OpenAPI上最稳定public MapString, Object getProcessInstance( String accessToken, String processInstanceId) { String url https://oapi.dingtalk.com/topapi/processinstance/get?access_token accessToken; MapString, Object body new HashMap(); body.put(process_instance_id, processInstanceId); HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); HttpEntityMapString, Object request new HttpEntity(body, headers); MapString, Object response restTemplate.postForObject( url, request, Map.class); if (response null || !0.equals(String.valueOf(response.get(errcode)))) { throw new IllegalStateException(审批实例查询失败: response); } return (MapString, Object) response.get(result); }注意这里把access_token拼在URL上这是旧版接口的鉴权方式和前面新版接口的Header方式不同。返回的result里有审批状态、审批人、表单组件值form_component_values表单值需要遍历解析成你业务对象的字段。如果团队刚起步我建议先做回调在事件订阅里勾选“审批实例开始”和“审批实例结束”收到事件后拿processInstanceId去查详情比每分钟轮询高效得多也不容易触发限流。4.4 事件订阅回调验签、解密与返回success回调接口虽然不复杂但第一个坑就是验证流程。钉钉POST到你的回调URL时URL参数里带signature、timestamp、nonce消息体是一个JSON长这样{ encrypt: 加密后的消息体 }你首先要根据timestamp、nonce加上自己配置的token按钉钉的签名算法计算签名和signature比对然后用自己的EncodingAESKey解密encrypt得到业务事件JSON处理完业务后把字符串success加密后再作为响应体返回。下面是示意代码PostMapping(/dingtalk/callback) public MapString, String callback( RequestParam(signature) String signature, RequestParam(timestamp) String timestamp, RequestParam(nonce) String nonce, RequestBody CallbackBody requestBody) { String decrypt DingTalkCrypto.decrypt( requestBody.getEncrypt(), aesKey, appKey); // parse eventType / processInstanceId / userId... String responseEncrypt DingTalkCrypto.encrypt( success, aesKey, appKey); return Map.of(encrypt, responseEncrypt); }DingTalkCrypto是封装过的官方加解密工具。不要自己实现AES很容易在填充模式、key大小写上出错。DingTalkCrypto.decrypt返回的明文里包含eventType字段比如审批实例结束的eventType是bpms_instance_change你需要根据这个字段分发到不同业务处理器。回调处理必须是幂等的钉钉会重试未确认的事件哪怕你已经处理过也要先查本地状态再决定是否重复入库。4.5 按业务收敛封装Client不要全量造轮子最后聊聊封装边界。我不建议为钉钉的几十个接口写“完整SDK”而是按业务收敛成客户端。比如消息模块、通讯录模块、审批模块各自独立每个模块只暴露业务方法内部组合token获取、通用请求和错误码解析。这样做的优势是钉钉接口升级时你只需要改对应模块的URL和参数而不是在业务代码里到处改。也便于统一维护日志埋点和限流降级。5. 钉钉集成APIJava避坑指南鉴权、回调与数据同步的四个翻车现场代码写通了不代表能可靠运行。下面这四类问题我在不同项目里都见过每条都按“现象→原因→解决”整理排查的时候可以直接对照。5.1 应用配置正常却一直报“无权限”现象用测试应用调通讯录接口返回Forbidden.AccessDeniedappKey、appSecret都没问题token也能获取就是接口不可用。原因权限点没有真正发布到应用上。钉钉后台的权限变更需要经过“版本管理与发布”生成新版本而不是勾选后立刻生效另外服务器出口IP白名单如果开启但当前请求源IP不在白名单里也会返回类似无权限的错误。解决先关闭IP白名单做对比实验。如果关了就好是出口IP问题如果关了仍然报错去权限管理里搜索对应接口名确认权限已申请并已发布。线上应用尽量保留至少两个版本发布新版本后观察5分钟确认无误再停掉旧版本。5.2 回调地址验证一直失败浏览器访问却正常现象在后台配置事件订阅系统一直提示URL验证失败你在浏览器里打开那个URL发现服务是正常的返回了文本。原因钉钉的回调验证不是普通GET请求而是POST加密数据。它要求回调接口能完成验签、解密、处理、再次加密返回success。如果你只写了一个“/callback”返回“ok”的接口后台会认为验证失败。解决按照第4.4节的流程实现完整验证。特别注意解密后的明文里会带一个type字段验证请求的type是url_verify你需要原样返回解密出的参数而不是直接返回“success”。很多网上的示例统一返回“success”在老版本回调里能过新版本就不行。出现问题时先在后台看回调失败日志再对照官方加解密示例一行行核对。5.3 工作通知发送成功用户却收不到现象发送接口返回正常没有抛异常但指定用户没在钉钉里看到消息。原因最常见的是userId传错。新版工作通知接收人必须是钉钉通讯录里的userId不是手机号、工号也不是unionId。其次是应用可见范围没包含该用户——即使接口调用成功钉钉也会在投递环节拦截。解决先用通讯录的“根据手机号查userId”接口或用户分页接口确认目标userId再发送。检查应用的“可用范围”确保测试账号被完整包含。另外工作通知默认会收敛到钉钉的“工作通知”会话里用户容易忽略如果是测试可以换成sampleMarkdown类型并设置一个醒目标题避免以为没发出来。5.4 分页拉取通讯录数据总是漏人或重复现象写了个批处理按部门分页拉用户列表入库运行几次发现人数对不上有时多了有时少了。原因pageNumber从1开始而接口从0开始第一页跳人更隐蔽的是拉取期间有人调岗或离职部门用户列表发生了变更导致下一页偏移。通讯录本身是动态数据全量分页不适合做增量同步。解决先确认分页起始值。然后按钉钉的增量方案做订阅通讯录变更事件收到“部门删除/用户离职”等事件后主动拉取相关部门做增量更新而不是每天全量对比。如果只是定时补偿建议在凌晨低峰期全量重拉一次并且用“更新用户”的updateTime字段做增量判断。6. 让钉钉集成API上线后少出问题的三个习惯日志、监控与验证6.1 上线前跑一遍冒烟脚本我会在每次环境变更后跑一个main方法获取token、拉根部门、发一条只给自己userId的工作通知、查一条测试审批。这个脚本不需要复杂框架用JUnit或者一个独立的Java类都可以。脚本里不要写死token要真实走一遍token缓存逻辑这样才能暴露配置和环境问题。跑通了再切流量跑不通就在发布窗口内解决而不是等用户投诉。6.2 日志脱敏与请求追踪打印钉钉请求响应时永远不要把accessToken和appSecret打到日志里。我习惯只打印requestId、URL路径、错误码和耗时token放在内存里出了问题宁可重新获取一次。钉钉返回的requestId是排错的关键遇到疑难问题带着requestId去查比自己猜快得多。回调日志还要打印加解密状态这样可以区分“验签失败”和“业务处理失败”。6.3 给关键调用加监控给token获取次数、工作通知发送失败数、回调失败数加几个计数器。一旦token获取次数异常上涨大概率是token缓存失效或限流回调失败数上涨先看是不是自己服务重启导致回调积压。这些指标不需要复杂监控平台日志里每分钟统计一次就够了。上线之后每天扫一眼比事后看告警从容得多。最后一个教训我之前做一个内部消息推送图省事没有做token复用上线当晚被钉钉限流第二天凌晨被电话叫醒改成缓存加锁后一直安然无恙。自那以后任何钉钉集成上线前我都会先跑一遍冒烟脚本确认新环境配置没问题再切流量。希望帮到你。本文还有配套的精品资源点击获取
