dingding

README

fastwego/dingding

A fast dingding development sdk written in Golang

快速开始 & demo

go get github.com/fastwego/dingding

// 创建应用实例
app := dingding.New(dingding.Config{
    AppKey:         viper.GetString("AppKey"),
    AppSecret:      viper.GetString("AppSecret"),
})

// 调用 api
resp, err := microapp.List(App, []byte(``))
fmt.Println(string(resp), err)

完整的演示项目：

https://github.com/fastwego/dingding-demo

接口列表：

doc/apilist.md

架构设计

框架特点

快速

「快」作为框架设计的核心理念，体现在方方面面：

• 使用 Go 语言，开发快、编译快、部署快、运行快，轻松服务海量用户
• 丰富的文档 和 演示代码 ，快速上手，5 分钟即可搭建一套完整的钉钉服务
• 独立清晰的模块划分，快速熟悉整个框架，没有意外，一切都是你期望的样子
• 甚至连框架自身的大部分代码也是自动生成的，维护更新快到超乎想象

符合直觉

作为第三方开发框架，尽可能贴合官方文档和设计，不引入新的概念，不给开发者添加学习负担

简洁而不过度封装

作为具体业务和钉钉之间的中间层，专注于通道的角色：帮业务把配置/材料投递到，将响应/推送透传回业务

至于 AccessToken 管理 和 消息加解密处理，框架内部完成得干净利落，开发者甚至觉察不到存在

官方文档就是最好的文档

每个接口的注释都附带官方文档的链接，让你随时翻阅，省时省心

完备的单元测试

100% 覆盖每一个接口，让你每一次调用都信心满满

详细的日志

每个关键环节都为你完整记录，Debug 倍轻松，你可以自由定义日志输出，甚至可以关闭日志

活跃的开发者社区

FastWeGo 是一套丰富的 Go 开发框架，钉钉、飞书、微信等服务，拥有庞大的开发者用户群体

你遇到的所有问题几乎都可以在社区找到解决方案

参与贡献

欢迎提交 pull request / issue / 文档，一起让钉钉开发更快更好！

Faster we go together!

Documentation

Overview

钉钉开发 SDK

See: https://ding-doc.dingtalk.com/

Index

• Variables
• type AccessToken
• type App
  • func NewApp(config AppConfig) (app *App)
  • func (app *App) GetAccessToken() (accessToken string, err error)
  • func (app *App) SetAccessTokenCacheDriver(driver cachego.Cache)
  • func (app *App) SetGetAccessTokenHandler(f GetAccessTokenFunc)
  • func (app *App) SetLogger(logger *log.Logger)
• type AppConfig
• type Client
  • func (client *Client) HTTPGet(uri string) (resp []byte, err error)
  • func (client *Client) HTTPPost(uri string, payload io.Reader, contentType string) (resp []byte, err error)
• type GetAccessTokenFunc
• type Server
  • func (s *Server) CheckUrl(writer http.ResponseWriter, request *http.Request)
  • func (s *Server) ParseEvent(body []byte) (eventType string, err error)

Variables

var DingdingServerUrl = "https://oapi.dingtalk.com"

钉钉 api 服务器地址

var UserAgent = "[fastwego/dingding] A fast dingding development sdk written in Golang"

Types

type AccessToken

type AccessToken struct {
	Cache                 cachego.Cache
	GetAccessTokenHandler GetAccessTokenFunc
}

AccessToken 管理器 处理缓存 和 刷新 逻辑

type App

type App struct {
	Config      AppConfig
	AccessToken AccessToken
	Client      Client
	Server      Server
	Logger      *log.Logger
}

App 实例

func NewApp

func NewApp(config AppConfig) (app *App)

创建 企业自建应用 实例

func (*App) GetAccessToken

func (app *App) GetAccessToken() (accessToken string, err error)

从 应用 实例 的 TenantAccessToken 管理器 获取 access_token

如果没有 access_token 或者 已过期，那么刷新

func (*App) SetAccessTokenCacheDriver

func (app *App) SetAccessTokenCacheDriver(driver cachego.Cache)

SetAccessTokenCacheDriver 设置 AccessToken 缓存器 默认为文件缓存：目录 os.TempDir()

驱动接口类型 为 cachego.Cache

func (*App) SetGetAccessTokenHandler

func (app *App) SetGetAccessTokenHandler(f GetAccessTokenFunc)

SetGetAccessTokenHandler 设置 AccessToken 获取方法。默认 从本地缓存获取（过期从钉钉接口刷新）

如果有多实例服务，可以设置为 Redis 或 RPC 等中控服务器 获取 就可以避免 AccessToken 刷新冲突

func (*App) SetLogger

func (app *App) SetLogger(logger *log.Logger)

SetLogger 日志记录 默认输出到 os.Stdout

可以新建 logger 输出到指定文件

如果不想开启日志，可以 SetLogger(nil)

type AppConfig

type AppConfig struct {
	CorpId         string
	AgentId        string
	AppKey         string
	AppSecret      string
	Token          string
	EncodingAESKey string
}

配置

type Client

type Client struct {
	Ctx *App
}

HttpClient 用于向接口发送请求

func (*Client) HTTPGet

func (client *Client) HTTPGet(uri string) (resp []byte, err error)

HTTPGet GET 请求

func (*Client) HTTPPost

func (client *Client) HTTPPost(uri string, payload io.Reader, contentType string) (resp []byte, err error)

HTTPPost POST 请求

type GetAccessTokenFunc

type GetAccessTokenFunc func() (accessToken string, err error)

GetAccessTokenFunc 获取 access_token 方法接口

type Server

type Server struct {
	Ctx *App
}

响应钉钉请求 或 推送消息/事件 的服务器

func (*Server) CheckUrl

func (s *Server) CheckUrl(writer http.ResponseWriter, request *http.Request)

CheckUrl 服务器接口校验

func (*Server) ParseEvent

func (s *Server) ParseEvent(body []byte) (eventType string, err error)

ParseEvent 解析钉钉推送过来的消息/事件