钉钉组件开发（如何快速打造一款钉钉）

开发需要用到钉钉开放平台提供的接口，但是钉钉官方并没有提供 Go 语言版本的 sdk

在 GitHub 逛了一圈后，找不到满意的开源版本，有些 repo 设计不太规范，有些 repo 只实现了部分功能

于是，我决定亲手撸一个

但很快，我就发现事情并不简单：钉钉开放平台提供了超过 200 个接口！

开发一个完整的 sdk 需要阅读每一个接口的文档，理解各个参数的作用，处理各种异常和接口返回的结果，还有 access_token 管理、数据加解密等细节

即使是资深开发工程师，在这脏活累活上，恐怕也得耗上半个月的时间

太慢了，这不是我想要的

经过 30 分钟仔细阅读接口文档后，我发现了一些规律：

• 服务器地址都是 https://oApi.dingtalk.com/
• HTTP 请求方法都是 POST 或 GET
• 所有的请求都需要 access_token 参数
• 官方文档针对每一个接口都详细列出了接口简介、接口地址、Query 参数、Body 参数
• ...

一个不太成熟的小想法就浮现出脑海：

• 搞个爬虫抓取接口名称、接口简介、接口地址、Query 参数、Body 参数 等 API 元信息
• 一个 API 的规格由其元信息唯一定义
• 每个 API 都由一个 func 表示
• 用 params url.Values表示接口需要的Query 参数
• 用 payload []byte表示接口需要的Body 参数
• 用 resp []byte表示接口的返回内容
• 根据 API 分组情况，拆分 package
• 所有 API 请求由统一的 Http Client 模块处理
• access_token、错误处理和重试逻辑由 Http Client 模块处理
• 钉钉服务器发出回调由 Http Server 模块处理
• ...

至此，一个简洁但完整的架构呼之欲出：

我们将打造这样一款 sdk : 介于业务逻辑 和 钉钉 之间，将业务的指令发送到钉钉，将钉钉的响应透传给业务

按照上 part 我们的构想，就可以开始搞了

先看看钉钉文档页面结构：

启动爬虫抓回来接口元信息：

Api{ Name: "获取用户userid", Description: "通过免登授权码和access_token获取用户的userid。", Request: "GET https://oapi.dingtalk.com/user/getuserinfo?access_token=access_token&code=code", See: "https://ding-doc.dingtalk.com/doc#/serverapi2/clotub", FuncName: "GetUserInfo", GetParams: []Param{ {Name: `code`, Type: `string`}, }, }

格式化成 Go func：

package auth import ... const apiGetUserInfo = "/user/getuserinfo" /* 获取用户userid 通过免登授权码和access_token获取用户的userid。 See: https://ding-doc.dingtalk.com/doc#/serverapi2/clotub GET https://oapi.dingtalk.com/user/getuserinfo?access_token=access_token&code=code */ func GetUserInfo(ctx *dingding.App, params url.Values) (resp []byte, err error) { return ctx.Client.HTTPGet(apiGetUserInfo "?" params.Encode()) }

再搞个 test 和 example 的模板代码，当爬虫全部执行完后，我们就可以得到：

├─ai │ ai.go │ ai_test.go │ example_ai_test.go │ ├─alitrip │ alitrip.go │ alitrip_test.go │ example_alitrip_test.go │ ├─attendance │ attendance.go │ attendance_test.go │ example_attendance_test.go │ ......

Wow Amazing! 200 个接口已尽入吾彀中矣

不过，我们时间不多了：

• 部分接口文档页面不规范，导致爬虫中断了 20 分钟
• GET|POST 不同类型的请求测试函数的差异比较大，耗费了 40 分钟
• ...

所有接口调用最终都由统一的 Http Client 模块发起

由于每个接口调用都需要鉴权，所以我们把鉴权模块放在这里再好不过了

处理方式非常简单，拿到access_token，加到请求地址后即可：

accessToken, _ := client.Ctx.AccessToken.GetAccessTokenHandler() newUrl := url "?access_token=" accessToken

关键在 GetAccessTokenHandler方法，这里定义了如何获取 access_token

再处理一下其他细节，包括错误处理、单元测试等，我们的 sdk 就差不多搞定啦

现在到了 Eating your own dog food环节：

go get github.com/fastwego/dingding // 创建应用实例 app := dingding.NewApp(dingding.AppConfig{ AppKey: viper.GetString("AppKey"), AppSecret: viper.GetString("AppSecret"), }) // 调用 api params := url.Values{} params.Add("code", CODE) resp, err := auth.GetUserInfo(app, params)

如果一切正常的话，接口可以正确响应我们的请求

效果好极啦，调用简单，不仅有 Example 引导，还有文档和链接：

果然还是自己打造的工具最趁手

在同样的思路下，我又撸完了企业微信和飞书的 Go sdk

• https://github.com/fastwego/wxwork
• https://github.com/fastwego/feishu

to be continue ...