打通Gitlab与钉钉之间的通讯-CSDN博客

[TOC]

公司使用了Gitlab,Jira等工具来管理,沟通方面主要是钉钉,但郁闷的是各系统相互独立,而我已经习惯了前公司那种方式:
有bug的时候会自动发送消息到聊天框中,而不是目前这样,需要开发人员手动定时去刷新jira页面才能知道,效率低下;

gitlab也是一样,有merge请求的时候,我希望不需要别人提醒我去审核代码,而是gitlab直接发送merge消息到我钉钉即可;

可能其他同事习惯邮件通知吧,公司并无打通各系统与钉钉联系的计划,所以我只能自己撸一套了,我不是专职后端,轻喷,功能够我用就好;

Github项目地址

原理: 利用各系统自带的 Webhook 功能, 在触发指定操作时,发送一条 hook 信息到我们的服务器上, 服务器做出处理后转发消息到对应人员的钉钉上;

效果展示

步骤

在 gitlab 上启用 Webhooks 通知(可指定要 Webhooks 的操作,这里hook了 merge 操作);
注意:需要项目管理权限才能设定, jira 也是类似;
在server端,根据 post 请求的 head 信息来区分不同系统发来的 hook 消息:
- gitlab 的 merge 请求包含: X-Gitlab-Event:Merge Request Hook
- jira 的 hook 请求包含: user-agent:Atlassian HttpClient0.17.3 / JIRA-6.3.15 (6346) / Default
在 server 端获取钉钉的人员信息,并调用其企业会话消息接口发送指定消息;
由于该会话接口需要 员工id 和 企业应用id 以及 access_token ,而获取access_token 需要 CorpId 和 CorpSecret (二者是企业的唯一标识);

公司当然不可能对个人开放其 CorpId 等信息 ,因此还是自己注册一个企业,创建部门并添加你想通知的人员作为部门员工即可,这样也能获取员工的通讯录详情 , 得到其 userId ,从而发送消息到其钉钉上;
创建一个微应用,以该应用为会话发起人来发送消息;

建立钉钉微应用

在钉钉开放平台中搜索 微应用 就可以找到 Step 1 -- 注册钉钉企业 的链接;
根据上面的 step 引导操作注册企业并添加部门和员工,然后进入钉钉管理后台;
切换到 工作台 标签页(即上图中的 企业应用,现已改名,偷懒就不重新截图了╮(￣▽￣)╭) , 点击下方的自建应用 ,按需填写信息;
完成后点击新建的微应用图标,选择 设置 即可查看到微应用的 AgentID;

获取企业的 `CorpID` 和 `CorpSecret`

登录钉钉管理后台;
点击 工作台 - 应用开发 即可查看到企业的 CorpID 和 CorpSecret信息;

文档链接若有变化, 请自行到钉钉开放平台搜索 CorpSecret ;

通讯录规则

在通讯录root部门中添加所有人,以便发送消息到特定用户时可以从root部门中通过查询用户姓名得到用户id;
gitlab会特殊一点,有些操作需要通知项目所有成员,所以还需要根据项目来创建部门:

假设gitlab项目地址为: https://gitlab.lynxz.org/demo-android/detail-android ,则表示项目名称(name) 为: detail-android ,项目所在空间(namespace)为: demo-android
在钉钉后台通讯录中需要先创建部门: demo_android ,然后创建其子部门 detail_android;
注意:
- 由于钉钉部门名称不允许使用 -,因此创建时改为 _ 替代;
- 目前只支持两级部门结构,若有多个部门符合上述规则 gitlab merge 通过时会通知所有匹配的部门成员;

备注: 更新钉钉通讯录后,记得及时通知 server 刷新本地数据,本版支持通过url出发刷新命令,直接访问如下网址即可(其中 yourServerHost 是war包运行后的访问地址): {yourServerHost}/action/updateDepartmentInfo

钉钉发送消息流程

1. retrofit请求

// kotlin
interface ApiService {
    /**
     * [获取钉钉AccessToken](https://open-doc.dingtalk.com/docs/doc.htm?spm=a219a.7629140.0.0.dfrJ5p&treeId=172&articleId=104980&docType=1)
     * @param id        corpid 企业id
     * @param secret    corpsecret 企业应用的凭证密钥
     * */
    @GET("gettoken")
    fun getAccessToken(@Query("corpid") id: String, @Query("corpsecret") secret: String): Observable<AccessTokenBean>

    /**
     * [获取部门列表信息](https://open-doc.dingtalk.com/docs/doc.htm?spm=a219a.7629140.0.0.xIVqtB&treeId=172&articleId=104979&docType=1#s0)
     */
    @GET("department/list")
    fun getDepartmentList(): Observable<DepartmentListBean>

    /**
     * [获取指定部门的成员信息,默认获取全部成员](https://open-doc.dingtalk.com/docs/doc.htm?spm=a219a.7629140.0.0.xIVqtB&treeId=172&articleId=104979&docType=1#s12)
     * */
    @GET("user/simplelist")
    fun getDepartmentMemberList(@Query("department_id") id: Int = 1): Observable<DepartmentMemberListBean>

    /**
     * [向指定用户发送普通文本消息](https://open-doc.dingtalk.com/docs/doc.htm?spm=a219a.7629140.0.0.oavHEu&treeId=172&articleId=104973&docType=1#s2)
     */
    @POST("message/send")
    fun sendTextMessage(@Body bean: MessageTextBean): Observable<MessageResponseBean>
}
复制代码

2. 添加必要的request信息

// kotlin
// 给请求添加统一的query参数:access_token
// 这里的ConstantsPara.accessToken是全局变量,存储获取到的accessToken 
val queryInterceptor = Interceptor { chain ->
    val original = chain.request()
    val url = original.url().newBuilder()
            .addQueryParameter("access_token", ConstantsPara.accessToken)
            .build()

    val requestBuilder = original.newBuilder().url(url)
    chain.proceed(requestBuilder.build())
}

// 给请求添加统一的header参数:Content-Type
val headerInterceptor = Interceptor { chain ->
    val request = chain.request().newBuilder()
            .addHeader("Content-Type", "application/json")
            .build()
    chain.proceed(request)
}

val okHttpClient: OkHttpClient = OkHttpClient()
        .newBuilder()
        .addInterceptor(headerInterceptor)
        .addInterceptor(queryInterceptor)
        .build()

val ddRetrofit: Retrofit = Retrofit.Builder()
        .client(okHttpClient)
        .baseUrl("https://oapi.dingtalk.com/") // 钉钉后台服务地址
        .addConverterFactory(GsonConverterFactory.create())
        .addCallAdapterFactory(RxJava2CallAdapterFactory.create())
        .build()
    
val apiService: ApiService = ddRetrofit.create(ApiService::class.java)
复制代码

3. 刷新钉钉的AccessToken

// kotlin
apiService.getAccessToken(ConstantsPara.dd_corp_id, ConstantsPara.dd_corp_secret)
        .retry(1)
        .subscribe(object : Observer<AccessTokenBean> {
            override fun onError(e: Throwable) {
                e.printStackTrace()
            }

            override fun onSubscribe(d: Disposable) {
                addDisposable(d)
            }

            override fun onComplete() {
            }

            override fun onNext(t: AccessTokenBean) {
                println("refreshAccessToken $t")
                ConstantsPara.accessToken = t.access_token ?: ""
            }
        })
复制代码

4. 获取部门列表及各部门下的成员信息

部门信息存放在 ConstantsPara.departmentNameMap 中,是一个 HashMap ,记录部门id及名称;
部门成员通讯录存放在 ConstantsPara.departmentMemberMap中, 也是一个 HashMap, 记录部门id及部门中的所有成员信息;

备注:

部门名称需跟 gitlab 项目名称对应,需要群发时通过项目名称查找对应的部门id; (目的: 创建 gitlab 项目与钉钉部门之间的映射关系);
部门id用于唯一确定部门,用于查找指定部门成员信息;
其中部门id为 1 的是公司的根部门(root部门),要将所有人员都添加进去,以便在需要通知指定人员时,能从root部门成员中通过查找用户姓名获取其用户id,然后发出钉钉消息;

// kotlin
apiService.getDepartmentList()
        .flatMap { list ->
            ConstantsPara.departmentList = list
            list.department.forEach { ConstantsPara.departmentNameMap.put(it.id, it.name) }
            Observable.fromIterable(list.department)
        }
        .map { departmentBean -> departmentBean.id }
        .flatMap { departmentId ->
            Observable.zip(Observable.create({ it.onNext(departmentId) }),
                    apiService.getDepartmentMemberList(departmentId),
                    BiFunction<Int, DepartmentMemberListBean, DepartmentMemberListBean> { t1, t2 ->
                        t2.departmentId = t1
                        t2
                    })
        }
        .retry(1)
        .subscribe(object : Observer<DepartmentMemberListBean> {
            override fun onNext(t: DepartmentMemberListBean) {
                ConstantsPara.departmentMemberMap.put(t.departmentId, t.userlist)
            }

            override fun onSubscribe(d: Disposable) {
                addDisposable(d)
            }

            override fun onError(e: Throwable) {
                e.printStackTrace()
            }

            override fun onComplete() {
                println("getDepartmentInfo onComplete:\n${ConstantsPara.departmentMemberMap.keys.forEach { println("departId: $it") }}")
//                        sendTextMessage(ConstantsPara.defaultNoticeUserName, "test from server")
            }
        })
复制代码

5. 发送钉钉消息

/**
* kotlin
* 向指定用户[targetUserName]发送文本内容[message]
* 若目标用户名[targetUserName]为空,则发送给指定部门[departmentId]所有人,比如gitlab merge请求通过时,通知所有人
* */
fun sendTextMessage(targetUserName: String? = null, message: String = "", departmentId: Int = 1) {
    ConstantsPara.departmentMemberMap[departmentId]?.apply {
        stream().filter { targetUserName.isNullOrBlank() or it.name.equals(targetUserName, true) }
                .forEach {
                    val textBean = MessageTextBean().apply {
                        touser = it.userid
                        agentid = ConstantsPara.dd_agent_id
                        msgtype = MessageType.TEXT
                        text = MessageTextBean.TextBean().apply {
                            content = message
                        }
                    }
                    apiService.sendTextMessage(textBean)
                            .subscribeOn(Schedulers.io())
                            .subscribe(object : Observer<MessageResponseBean> {
                                override fun onComplete() {
                                }

                                override fun onSubscribe(d: Disposable) {
                                    addDisposable(d)
                                }

                                override fun onNext(t: MessageResponseBean) {
                                    println("${msec2date()} sendTextMessage $t")
                                }

                                override fun onError(e: Throwable) {
                                    e.printStackTrace()
                                }
                            })
                }
    }
}
复制代码

其他说明

钉钉消息有个限制, 因此我在所有消息文本中添加服务器当前时间,尽量确保每条消息都不同:

forbiddenUserId: 因发送消息过于频繁或超量而被流控过滤后实际未发送的userid。未被限流的接收者仍会被成功发送。
限流规则包括：
1、给同一用户发相同内容消息一天仅允许一次；
2、如果是ISV接入方式，给同一用户发消息一天不得超过50次；如果是企业接入方式，此上限为500。

jira的hook信息若是存在 changelog 则表明有用户修改了issue的状态或者内容,另外, issuse.comment 一定存在, 数组 comments 存储了用户提交的所有备注信息,按时间先后顺序排列;
accessToken的有效期为7200秒,因此项目中需要定时刷新token;
钉钉自带有 聊天机器人 , 直接支持几个平台的 webhook 消息, 不过只能转发到 群 中, 对不需要关注的成员来说, 就是垃圾消息, 而且消息格式固定死板,灵活性不强,具体操作可到钉钉开放平台搜索 机器人 查看;