Skip to content

Docs for DingTalk 2.x

Jump to bottom
Jaemon edited this page Dec 19, 2020 · 6 revisions

DingTalk 2.x 使用文档

针对项目中的消息体进行统一管理，发布dingtalk 2.x 版本。支持xml和注解两种方式定义消息体内容。

 

开发环境说明

  • JDK1.8
  • springboot版本： 2.0.3.RELEASE

 

相关注解说明

注解 功能描述 适用说明
@DingerScan 标识Dinger层扫描路径 SpringBoot启动类Application.java中定义使用
@Dinger 用于指定 @DingerScan 指定扫描路径之外的 XXXDinger.java 文件 XXXDinger.java接口层(接口类或接口方法上均可)
@DingerConfiguration 用于 XXXDinger.java 层(注解和XML)级别机器人信息配置 XXXDinger.java接口类上
@AsyncExecute 用于 XXXDinger.java 层(注解和XML)级别异步发送 XXXDinger.java接口类上
@DingerClose 用于关闭 XXXDinger.java 或者指定其中的一个至多个方法 XXXDinger.java接口层(接口类或接口方法上均可)
- 作用于Dinger类上，关闭Dinger类中所有方法通知；
- 作用于方法上， 关闭当前方法通知；
@Parameter 如果消息体中使用的参数变量和方法定义的参数名称不一致，可使用该注解进行个性化设置参数变量名称 XXXDinger.java接口层接口方法参数上
@Keyword 标识关键词，用于根据关键词信息快速定位请求日志(主要用于发送钉钉消息异常时的日志定位) XXXDinger.java接口层接口方法参数上
@DingerText 注解方式定义Text消息体 XXXDinger.java接口层接口方法上
@DingerMarkdown 注解方式定义Markdown消息体 XXXDinger.java接口层接口方法上

 

消息体定义说明： 对于同一个接口， 钉钉发送消息体内容只能被定义一次， 要么使用注解方式定义消息体， 要么使用xml方式定义消息体，两者定义方式只能选择一种

  • 注解方式： @DingerText 或 @DingerMarkdown
  • xml方式： XXXDinger.xml， 需要配置spring.dingtalk.dinger-locations属性信息

 

钉钉机器人配置信息优先级： 动态配置(2.0.5及以上) > 多机器人配置(3.x及以上) > @DingerText | @DingerMarkdown | XML > @DingerConfiguration > ***.yml | ***.properties

  • 异步配置如果没有显示指定，则使用上一级配置，以此类推。

 

jar包依赖

    <dependency>
        <groupId>com.github.answerail</groupId>
        <artifactId>dingtalk-spring-boot-starter</artifactId>
        <version>3.0.0-RELEASE</version>
    </dependency>

 

配置文件

spring:
  dingtalk:
    token-id: c60d4824e0ba4a30544e81212256789331d68b0085ed1a5b2279715741355fbc
    project-id: ${spring.application.name}
    title: 预警通知
    secret: APC3eb471b2761851d6ddd1abcndf2d97be21447d8818f1231c5ed61234as52d1w0
    # 定义 XXXDinger.xml 文件存放路径
    dinger-locations: classpath*:dinger/*.xml

 

启动类设置

@SpringBootApplication
@MapperScan(basePackages = "com.jaemon.dt.mapper")
// 标识Dinger层扫描路径
@DingerScan(basePackages = "com.jaemon.dt.dinger")	
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class,args);

    }
}

DingerScan的basePackages属性值注意更改为自己项目定义的dinger接口层包路径

 

Dinger层

说明： `注解方式` 和 `xml配置方式` 两者选其一即可

注解方式

package com.jaemon.dt.dinger;

public interface OrderDinger {

    @DingerText(value = "订单号${orderNum}下单成功啦, 下单金额${amt}", phones = {"13520200906"})
    DingTalkResult orderSuccess(
        @Parameter("orderNum") String orderNo, 
        @Parameter("amt") BigDecimal amt
    );

    @DingerMarkdown(
            value = "#### 下单失败啦 @13520200906\n - 订单号： ${orderNo}\n - 标识： ${flag}\n - 数量： ${num}",
            title = "下单结果反馈",
            phones = {"13520200906"},
            tokenId = @DingerTokenId(
                    value = "c60d4824e0ba4a30544e81212256789331d68b0085ed1a5b2279715741355fbc",
                    secret = "APC3eb471b2761851d6ddd1abcndf2d97be21447d8818f1231c5ed61234as52d1w0")
    )
    DingTalkResult orderFailed(String orderNo, int num, boolean flag);
}

 

xml方式

配置文件新增dinger-locations路径配置

spring:
  dingtalk:
    dinger-locations: classpath*:dinger/*.xml

以上配置dinger配置文件对应的路径: resources/dinger/OrderDinger.xml

OrderDinger.java接口层

package com.jaemon.dt.dinger;

public interface OrderDinger {
    DingTalkResult orderSuccess(
        @Parameter("orderNum") String orderNo, 
        @Parameter("amt") BigDecimal amt
    );

    DingTalkResult orderFailed(String orderNo, int num, boolean flag);
}

OrderDinger.xml配置

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE dinger SYSTEM "dingtalk-dinger.dtd">
<!DOCTYPE dinger PUBLIC "-//AnswerAIL//DTD Dinger 2.0//EN" "dingtalk-dinger.dtd">

<dinger namespace="com.jaemon.dt.dinger.OrderDinger">

	<message id="orderSuccess" type="TEXT">
		<body>
            <!-- 2.0.2版本不推荐使用, 推荐使用message标签的type属性 -->
			<!--<type>text</type>-->
			<content>
				订单号${orderNum}下单成功啦, 下单金额${amt}
			</content>

			<phones atAll="true" />
		</body>

        <!-- 配置消息体使用的钉钉机器人信息 -->
		<configuration async="true">
			<token-id
		secret="APC3eb471b2761851d6ddd1abcndf2d97be21447d8818f1231c5ed61234as52d1w0"
		decrypt-key="MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCeSpqEVuq2NVNDu2lJb">						iH178Wn85rI+Mlguimxml79o5/w/CVGEjVWULfJog
			</token-id>
            <!-- 是否异步发送, 2.0.2版本不推荐使用, 推荐使用configuration标签的async属性 -->
			<!--<async-execute>true</async-execute>-->
		</configuration>
	</message>


	<message id="orderFailed" type="MARKDOWN">
		<body>
			<!--<type>markdown</type>-->
			<content title="下单结果反馈">
				#### 下单失败啦 @13520200906
				- 订单号： ${orderNo}
				- 标识： ${flag}
				- 数量： ${num}
			</content>

			<!-- markdown不支持@全部, 只支持@指定用户 -->
			<phones>
				<!-- 指定的phone的用户必须在tokenId群中 -->
				<phone value="13520200906" />
			</phones>
		</body>
	</message>
</dinger>

 

验证

@Slf4j
@RestController
public class TestController {
    @Autowired
    private OrderDinger orderDinger;

    @GetMapping("/notify")
    public void notify() {
        // 动态指定当前消息发送的群机器人信息(2.0.5支持)
//      DingerHelper.assignDinger("tokenId", "secret");
        DingTalkResult result = orderDinger.orderSuccess("20200906", BigDecimal.valueOf(10000));
        log.info(JSON.toJSONString(result));

        result = orderDinger.orderFailed("20200906", 10, false);
        log.info(JSON.toJSONString(result));
    }
}

 

收到消息格式

钉钉收到的orderSuccess通知消息

  • 订单号20200906下单成功啦, 下单金额1000@所有人

钉钉收到的orderFailed通知消息

下单失败啦 @XXX

  • 订单号： 20200906
  • 标识： false
  • 数量： 10

Dinger开发手册

Getting Started

Developer Guides

Information

Examples

 

DingTalk开发手册

Getting Started

Developer Guides

Information

Clone this wiki locally