offiaccount

README

fastwego/offiaccount

A fast wechat offiaccount development sdk written in Golang

快速开始 & demo

go get github.com/fastwego/offiaccount

// 创建公众号实例
app := offiaccount.New(offiaccount.Config{
    Appid:  "APPID",
    Secret: "SECRET",
})

// 调用 api
payload := []byte(`
{
     "button":[
     {
           "name":"菜单",
           "sub_button":[
           {	
               "type":"view",
               "name":"搜索",
               "url":"http://www.baidu.com/"
            }]
       }]
}`)

resp, err := menu.Create(app, payload)
fmt.Println(resp, err)

完整的演示项目：

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

接口列表：

doc/apilist.md

架构设计

框架特点

快速

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

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

符合直觉

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

简洁而不过度封装

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

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

官方文档就是最好的文档

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

完备的单元测试

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

详细的日志

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

多账号支持

一套服务支持多个微信公众号账号，轻松成为第三方开发服务平台，业务节节高

支持服务集群

单台服务器支撑不住访问流量/想提高服务可用性？

只需 设置 GetAccessTokenFunc 方法 ，从中控服务获取 AccessToken，即可解决多实例刷新冲突/覆盖的问题

活跃的开发者社区

FastWeGo 是一套完整的微信开发框架，包括公众号、开放平台、微信支付、企业微信、小程序、小游戏等微信服务，拥有庞大的开发者用户群体

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

参与贡献

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

Faster we go together!

加入开发者交流群

Documentation

Overview

微信公众平台开发 SDK

See: https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Overview.html

Index

• Variables
• func GetAccessToken(ctx *OffiAccount) (accessToken string, err error)
• func NoticeAccessTokenExpire(ctx *OffiAccount) (err error)
• type AccessToken
• 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 Config
• type GetAccessTokenFunc
• type NoticeAccessTokenExpireFunc
• type OffiAccount
  • func New(config Config) (offiAccount *OffiAccount)
  • func (offiAccount *OffiAccount) SetAccessTokenCacheDriver(driver cachego.Cache)
  • func (offiAccount *OffiAccount) SetGetAccessTokenHandler(f GetAccessTokenFunc)
  • func (offiAccount *OffiAccount) SetLogger(logger *log.Logger)
  • func (offiAccount *OffiAccount) SetNoticeAccessTokenExpireHandler(f NoticeAccessTokenExpireFunc)
• type Server
  • func (s *Server) EchoStr(writer http.ResponseWriter, request *http.Request)
  • func (s *Server) ParseXML(body []byte) (m interface{}, err error)
  • func (s *Server) Response(writer http.ResponseWriter, request *http.Request, reply interface{}) (err error)

Examples

• OffiAccount.SetAccessTokenCacheDriver
• OffiAccount.SetGetAccessTokenHandler
• OffiAccount.SetLogger

Variables

var (
	WXServerUrl            = "https://api.weixin.qq.com" // 微信 api 服务器地址
	UserAgent              = "fastwego/offiaccount"
	ErrorAccessTokenExpire = errors.New("access token expire")
)

Functions

func GetAccessToken

func GetAccessToken(ctx *OffiAccount) (accessToken string, err error)

从 公众号实例 的 AccessToken 管理器 获取 access_token

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

获得新的 access_token 后 过期时间设置为 0.9 * expiresIn 提供一定冗余

func NoticeAccessTokenExpire

func NoticeAccessTokenExpire(ctx *OffiAccount) (err error)

NoticeAccessTokenExpire 只需将本地存储的 access_token 删除，即完成了 access_token 已过期的 主动通知

retry 请求的时候，会发现本地没有 access_token ，从而触发refresh

Types

type AccessToken

type AccessToken struct {
	Cache                          cachego.Cache
	GetAccessTokenHandler          GetAccessTokenFunc
	NoticeAccessTokenExpireHandler NoticeAccessTokenExpireFunc
}

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

type Client

type Client struct {
	Ctx *OffiAccount
}

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 Config

type Config struct {
	Appid          string
	Secret         string
	Token          string
	EncodingAESKey string
}

公众号配置

type GetAccessTokenFunc

type GetAccessTokenFunc func(ctx *OffiAccount) (accessToken string, err error)

GetAccessTokenFunc 获取 access_token 方法接口

type NoticeAccessTokenExpireFunc

type NoticeAccessTokenExpireFunc func(ctx *OffiAccount) (err error)

NoticeAccessTokenExpireFunc 通知中控 刷新 access_token

type OffiAccount

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

OffiAccount 公众号实例

func New

func New(config Config) (offiAccount *OffiAccount)

创建公众号实例

func (*OffiAccount) SetAccessTokenCacheDriver

func (offiAccount *OffiAccount) SetAccessTokenCacheDriver(driver cachego.Cache)

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

驱动接口类型 为 cachego.Cache

Example

package main

import (
	"os"

	"github.com/faabiosr/cachego/file"
	"github.com/faabiosr/cachego/sync"
	"github.com/fastwego/offiaccount"
)

func main() {
	var App *offiaccount.OffiAccount

	// 使用内存
	App.SetAccessTokenCacheDriver(sync.New())

	// 使用指定目录下的 文件
	App.SetAccessTokenCacheDriver(file.New(os.TempDir()))

	// 更多驱动 请查看 https://github.com/faabiosr/cachego
}

func (*OffiAccount) SetGetAccessTokenHandler

func (offiAccount *OffiAccount) SetGetAccessTokenHandler(f GetAccessTokenFunc)

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

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

Example

package main

import (
	"github.com/fastwego/offiaccount"
	"github.com/garyburd/redigo/redis"
)

func main() {
	var Ctx *offiaccount.OffiAccount

	conn, _ := redis.Dial("tcp", "127.0.0.1:6379")
	_, _ = conn.Do("AUTH", "PASSWORD")

	// 从远程 Redis 服务器 获取 AccessToken
	Ctx.SetGetAccessTokenHandler(func(ctx *offiaccount.OffiAccount) (accessToken string, err error) {
		accessToken, _ = redis.String(conn.Do("GET", "access_token:"+ctx.Config.Appid))
		return
	})
}

func (*OffiAccount) SetLogger

func (offiAccount *OffiAccount) SetLogger(logger *log.Logger)

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

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

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

Example

package main

import (
	"log"
	"os"

	"github.com/fastwego/offiaccount"
)

func main() {

	var Ctx *offiaccount.OffiAccount

	// 输出日志到控制台
	Ctx.SetLogger(log.New(os.Stdout, "[offiaccount]", log.LstdFlags))

	// 记录日志到指定文件
	logFile, _ := os.OpenFile("/path/to/file", os.O_WRONLY, 0644)
	Ctx.SetLogger(log.New(logFile, "[offiaccount]", log.LstdFlags))

	// 关闭日志
	Ctx.SetLogger(nil)
}

func (*OffiAccount) SetNoticeAccessTokenExpireHandler

func (offiAccount *OffiAccount) SetNoticeAccessTokenExpireHandler(f NoticeAccessTokenExpireFunc)

SetNoticeAccessTokenExpireHandler 设置 AccessToken 过期 通知

框架提供的默认机制是 删除本地缓存的 access_token，那么 retry 的时候 会触发 刷新

如果有多实例服务，可以设置为 通知 中控服务器 去刷新

type Server

type Server struct {
	Ctx *OffiAccount
}

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

func (*Server) EchoStr

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

EchoStr 服务器接口校验

func (*Server) ParseXML

func (s *Server) ParseXML(body []byte) (m interface{}, err error)

ParseXML 解析微信推送过来的消息/事件

func (*Server) Response

func (s *Server) Response(writer http.ResponseWriter, request *http.Request, reply interface{}) (err error)

Response 响应微信消息 (自动判断是否要加密)