go-workwx (v2)

本项目需要您的帮助！

import (
    "github.com/xen0n/go-workwx/v2" // package workwx
)

A Work Weixin (a.k.a. Wechat Work) client SDK for Golang, that happens to be
battle-tested and pretty serious about its types.

In production since late 2018, pushing all kinds of notifications and alerts
in at least 2 of Qiniu’s internal systems.

一个 Golang 企业微信客户端 SDK；碰巧在生产环境试炼过，还对类型很严肃。

自 2018 年末以来，在七牛至少 2 个内部系统运转至今，推送各种通知、告警。

English translation TODO for now, as the service covered here is not available
outside of China (AFAIK).

[!WARNING]
本库的 v2 版本仍可能发生不兼容的 API 变更，如字段名、方法名调整等等，请注意。在我们处理完成所有已知的边边角角之前，不会有 v2 版本的 tag。

如果您依赖本库，请在 v2 版本的跟踪工单回复或作出表情反应，以表明态度！作者现在完全以业余时间维护本项目了，非常需要您的反馈。

Why another wheel?

工作中需要用 Go 实现一个简单的消息推送，想着找个开源库算了，然而现有唯一的开源企业微信 Golang SDK 代码质量不佳。只好自己写一个。

Update: 自从这个库写出来，已经过了很久；现在（2019.08）已经有三四个同类项目了。
不过看了看这些“竞品”，发现自己这个库的类型设计、公开接口、access token 处理等方面还不赖。
为什么人们总是喜欢写死请求 Host、用全局量、为拆包而拆包甚至不惜公开内部方法呢？

Supported Go versions

本库的 v2.x 分支最低支持到 Go 的上一个稳定版本，当前为 go1.19。
如果您需要搭配更低版本的 Go 使用，请移步 v1.x 版本，那边的代码仍然最低支持到 go1.17。

CI 会在 Go 的当前稳定版本、上一个稳定版本上跑测试，只有测试全部通过才可能合并 PR。

注意：由于 Go 上游的持续发展，我们需要能够确保相对低成本地追上节奏。
如果 go.mod 指定 Go 版本相对较低，以至于会阻碍本项目自身的功能迭代或重构了，我们不会特别考虑锁定 Go 版本的下游用户而放缓十分必要的升级。
如果您确实仍然有此类需求，请提 issue 沟通。

Features

• 包名短
• 支持覆盖 API Host，用于自己拦一层网关、临时调试等等奇葩需求
• 支持使用自定义 http.Client
• access token 处理靠谱
  • 你可以直接就做 API 调用，会自动请求 access token
  • 你也可以一行代码起一个后台 access token 刷新 goroutine
  • 自带指数退避重试
• 严肃对待类型、公开接口
  • 公开暴露接口最小化，两步构造出 WorkwxApp 对象，然后直接用
  • 刻意不暴露企业微信原始接口请求、响应类型
  • 后续可能会做一个 lowlevel 包暴露裸的 API 接口，但很可能不做
  • 不为多态而多态，宁可 SDK 内部重复代码，也保证一个接口一类动作，下游用户 static dispatch
  • 个别数据模型做了调整甚至重做（如 UserInfo、Recipient），以鼓励 idiomatic Go 风格
  • 几乎不会越俎代庖，一言不合 panic。现存的少数一些情况都是要修掉的。
• 自带一个 workwxctl 命令行小工具帮助调试
  • 用起来不爽提 issue 让我知道你在想啥

详情看 godoc 文档，还提供 Examples 小段代码可以参考。

Supported APIs

• 通讯录管理 (部分支持，见下)
• 客户联系 (大部分支持，见下)
• 微信客服 (部分支持，见下)
• 应用管理
• 消息发送 (全部支持)
• 消息接收
• 素材管理 (支持上传, 见下)
• OA (大部分支持，见下)
• 会话内容存档 (大部分支持，见下)
• 企业微信登录接口 (code2Session)
• 获取访问用户身份 (code2UserInfo)

Notes

关于保密消息发送

Markdown 等类型消息目前不支持作为保密消息发送，强行发送会报错。
那么为何发送消息的方法还全部带着 isSafe 参数呢？

一方面，企业微信服务方完全可能在未来支持更多消息类型的保密发送，到时候不希望客户端代码重新编译；
另一方面，反正响应会报错，你也不会留着这种逻辑。因此不改了。

License

• MIT

Stargazers over time