Documentation ¶
Overview ¶
微信企业号SDK
Index ¶
- Constants
- Variables
- func HttpResponseWriter(w io.Writer) http.ResponseWriter
- func ServeHTTP(w http.ResponseWriter, r *http.Request, urlValues url.Values, ...)
- func WriteResponse(w http.ResponseWriter, r *Request, msg interface{}) (err error)
- type AgentServer
- type AgentServerFrontend
- type CommonMessageHeader
- type CorpClient
- func (clt *CorpClient) GetCallbackIP() (ipList []string, err error)
- func (clt *CorpClient) GetJSON(incompleteURL string, response interface{}) (err error)
- func (clt *CorpClient) PostJSON(incompleteURL string, request interface{}, response interface{}) (err error)
- func (clt *CorpClient) UploadFromReader(incompleteURL, part1FieldName, part1FileName string, ...) (err error)
- type DefaultAgentServer
- func (srv *DefaultAgentServer) AgentId() int64
- func (srv *DefaultAgentServer) CorpId() string
- func (srv *DefaultAgentServer) CurrentAESKey() (key [32]byte)
- func (srv *DefaultAgentServer) LastAESKey() (key [32]byte)
- func (srv *DefaultAgentServer) MessageHandler() MessageHandler
- func (srv *DefaultAgentServer) Token() string
- func (srv *DefaultAgentServer) UpdateAESKey(AESKey []byte) (err error)
- type DefaultTokenServer
- type Error
- type InvalidRequestHandler
- type InvalidRequestHandlerFunc
- type MessageHandler
- type MessageHandlerFunc
- type MessageServeMux
- func (mux *MessageServeMux) DefaultEventHandle(handler MessageHandler)
- func (mux *MessageServeMux) DefaultEventHandleFunc(handler func(http.ResponseWriter, *Request))
- func (mux *MessageServeMux) DefaultMessageHandle(handler MessageHandler)
- func (mux *MessageServeMux) DefaultMessageHandleFunc(handler func(http.ResponseWriter, *Request))
- func (mux *MessageServeMux) EventHandle(eventType string, handler MessageHandler)
- func (mux *MessageServeMux) EventHandleFunc(eventType string, handler func(http.ResponseWriter, *Request))
- func (mux *MessageServeMux) MessageHandle(msgType string, handler MessageHandler)
- func (mux *MessageServeMux) MessageHandleFunc(msgType string, handler func(http.ResponseWriter, *Request))
- func (mux *MessageServeMux) ServeMessage(w http.ResponseWriter, r *Request)
- type MixedMessage
- type MultiAgentServerFrontend
- func (frontend *MultiAgentServerFrontend) DeleteAgentServer(serverKey string)
- func (frontend *MultiAgentServerFrontend) DeleteAllAgentServer()
- func (frontend *MultiAgentServerFrontend) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (frontend *MultiAgentServerFrontend) SetAgentServer(serverKey string, server AgentServer)
- func (frontend *MultiAgentServerFrontend) SetInvalidRequestHandler(handler InvalidRequestHandler)
- type Request
- type RequestHttpBody
- type ResponseHttpBody
- type TokenServer
Constants ¶
const ( ErrCodeOK = 0 ErrCodeInvalidCredential = 40001 // access_token 过期(无效)返回这个错误(maybe!!!) ErrCodeTimeout = 42001 // access_token 过期(无效)返回这个错误 )
const URLQueryAgentServerKeyName = "agent_server"
回调 URL 上索引 AgentServer 的 key 的名称.
比如下面的回调地址里面就可以根据 agent1 来索引对应的 AgentServer. http://www.xxx.com/?agent_server=agent1&msg_signature=XXX×tamp=123456789&nonce=12345678
Variables ¶
var DefaultInvalidRequestHandler = InvalidRequestHandlerFunc(func(http.ResponseWriter, *http.Request, error) {})
var MediaHttpClient = &http.Client{ Transport: &http.Transport{ Proxy: http.ProxyFromEnvironment, Dial: (&net.Dialer{ Timeout: 5 * time.Second, KeepAlive: 30 * time.Second, }).Dial, TLSHandshakeTimeout: 5 * time.Second, }, Timeout: 300 * time.Second, }
多媒体上传下载请求的 http.Client
var TextHttpClient = &http.Client{ Transport: &http.Transport{ Proxy: http.ProxyFromEnvironment, Dial: (&net.Dialer{ Timeout: 5 * time.Second, KeepAlive: 30 * time.Second, }).Dial, TLSHandshakeTimeout: 5 * time.Second, }, Timeout: 15 * time.Second, }
一般请求的 http.Client
Functions ¶
func HttpResponseWriter ¶
func HttpResponseWriter(w io.Writer) http.ResponseWriter
将 io.Writer 从语义上实现 http.ResponseWriter.
某些 http 框架可能没有提供 http.ResponseWriter, 而只是提供了 io.Writer.
func ServeHTTP ¶
func ServeHTTP(w http.ResponseWriter, r *http.Request, urlValues url.Values, agentServer AgentServer, invalidRequestHandler InvalidRequestHandler)
ServeHTTP 处理 http 消息请求
NOTE: 调用者保证所有参数有效
func WriteResponse ¶
func WriteResponse(w http.ResponseWriter, r *Request, msg interface{}) (err error)
回复消息给微信服务器.
要求 msg 是有效的消息数据结构(经过 encoding/xml marshal 后符合消息的格式); 如果有必要可以修改 Request 里面的某些值, 比如 TimeStamp.
Types ¶
type AgentServer ¶
type AgentServer interface { CorpId() string // 获取应用所属的企业号Id AgentId() int64 // 获取应用的Id Token() string // 获取应用的Token CurrentAESKey() [32]byte // 获取当前有效的 AES 加密 Key LastAESKey() [32]byte // 获取最后一个有效的 AES 加密 Key MessageHandler() MessageHandler // 获取 MessageHandler }
企业号应用的服务端接口, 处理单个应用的消息(事件)请求.
type AgentServerFrontend ¶
type AgentServerFrontend struct {
// contains filtered or unexported fields
}
实现了 http.Handler, 处理一个企业号应用的消息(事件)请求.
func NewAgentServerFrontend ¶
func NewAgentServerFrontend(server AgentServer, handler InvalidRequestHandler) *AgentServerFrontend
func (*AgentServerFrontend) ServeHTTP ¶
func (frontend *AgentServerFrontend) ServeHTTP(w http.ResponseWriter, r *http.Request)
实现 http.Handler.
type CommonMessageHeader ¶
type CommonMessageHeader struct { ToUserName string `xml:"ToUserName" json:"ToUserName"` FromUserName string `xml:"FromUserName" json:"FromUserName"` CreateTime int64 `xml:"CreateTime" json:"CreateTime"` MsgType string `xml:"MsgType" json:"MsgType"` AgentId int64 `xml:"AgentID" json:"AgentID"` }
微信服务器推送过来的消息(事件)通用的消息头
type CorpClient ¶
type CorpClient struct { TokenServer HttpClient *http.Client }
企业号"主动"请求功能的基本封装.
func (*CorpClient) GetCallbackIP ¶
func (clt *CorpClient) GetCallbackIP() (ipList []string, err error)
获取微信服务器的ip段
func (*CorpClient) GetJSON ¶
func (clt *CorpClient) GetJSON(incompleteURL string, response interface{}) (err error)
GET 微信资源, 然后将微信服务器返回的 JSON 用 encoding/json 解析到 response.
NOTE: 1. 一般不用调用这个方法, 请直接调用高层次的封装方法; 2. 最终的 URL == incompleteURL + access_token; 3. response 要求是 struct 的指针, 并且该 struct 拥有属性: ErrCode int `json:"errcode"` (可以是直接属性, 也可以是匿名属性里的属性)
func (*CorpClient) PostJSON ¶
func (clt *CorpClient) PostJSON(incompleteURL string, request interface{}, response interface{}) (err error)
用 encoding/json 把 request marshal 为 JSON, 放入 http 请求的 body 中, POST 到微信服务器, 然后将微信服务器返回的 JSON 用 encoding/json 解析到 response.
NOTE: 1. 一般不用调用这个方法, 请直接调用高层次的封装方法; 2. 最终的 URL == incompleteURL + access_token; 3. response 要求是 struct 的指针, 并且该 struct 拥有属性: ErrCode int `json:"errcode"` (可以是直接属性, 也可以是匿名属性里的属性)
func (*CorpClient) UploadFromReader ¶
func (clt *CorpClient) UploadFromReader(incompleteURL, part1FieldName, part1FileName string, part1ValueReader io.Reader, part2FieldName string, part2Value []byte, response interface{}) (err error)
通用上传接口.
--BOUNDARY Content-Disposition: form-data; name="FIELDNAME"; filename="FILENAME" Content-Type: application/octet-stream FILE-CONTENT --BOUNDARY Content-Disposition: form-data; name="FIELDNAME" JSON-DESCRIPTION --BOUNDARY-- NOTE: 1. 一般不需要调用这个方法, 请直接调用高层次的封装方法; 2. 最终的 URL == incompleteURL + access_token; 3. part1 是一个文件, part2 是普通的字符串(如果不需要 part2 则把 part2FieldName 留空); 4. response 要求是 struct 的指针, 并且该 struct 拥有属性: ErrCode int `json:"errcode"` (可以是直接属性, 也可以是匿名属性里的属性)
type DefaultAgentServer ¶
type DefaultAgentServer struct {
// contains filtered or unexported fields
}
func NewDefaultAgentServer ¶
func NewDefaultAgentServer(corpId string, agentId int64, token string, AESKey []byte, messageHandler MessageHandler) (srv *DefaultAgentServer)
NewDefaultAgentServer 创建一个新的 DefaultAgentServer.
func (*DefaultAgentServer) AgentId ¶
func (srv *DefaultAgentServer) AgentId() int64
func (*DefaultAgentServer) CorpId ¶
func (srv *DefaultAgentServer) CorpId() string
func (*DefaultAgentServer) CurrentAESKey ¶
func (srv *DefaultAgentServer) CurrentAESKey() (key [32]byte)
func (*DefaultAgentServer) LastAESKey ¶
func (srv *DefaultAgentServer) LastAESKey() (key [32]byte)
func (*DefaultAgentServer) MessageHandler ¶
func (srv *DefaultAgentServer) MessageHandler() MessageHandler
func (*DefaultAgentServer) Token ¶
func (srv *DefaultAgentServer) Token() string
func (*DefaultAgentServer) UpdateAESKey ¶
func (srv *DefaultAgentServer) UpdateAESKey(AESKey []byte) (err error)
type DefaultTokenServer ¶
type DefaultTokenServer struct {
// contains filtered or unexported fields
}
TokenServer 的简单实现.
NOTE: 1. 用于单进程环境. 2. 因为 DefaultTokenServer 同时也是一个简单的中控服务器, 而不是仅仅实现 TokenServer 接口, 所以整个系统只能存在一个 DefaultTokenServer 实例!
func NewDefaultTokenServer ¶
func NewDefaultTokenServer(corpId, corpSecret string, httpClient *http.Client) (srv *DefaultTokenServer)
创建一个新的 DefaultTokenServer.
如果 httpClient == nil 则默认使用 http.DefaultClient.
func (*DefaultTokenServer) Token ¶
func (srv *DefaultTokenServer) Token() (token string, err error)
func (*DefaultTokenServer) TokenRefresh ¶
func (srv *DefaultTokenServer) TokenRefresh() (token string, err error)
type InvalidRequestHandler ¶
type InvalidRequestHandler interface { // err 是错误信息 ServeInvalidRequest(w http.ResponseWriter, r *http.Request, err error) }
无效请求(非法或者错误)的处理接口.
type InvalidRequestHandlerFunc ¶
type InvalidRequestHandlerFunc func(http.ResponseWriter, *http.Request, error)
func (InvalidRequestHandlerFunc) ServeInvalidRequest ¶
func (fn InvalidRequestHandlerFunc) ServeInvalidRequest(w http.ResponseWriter, r *http.Request, err error)
type MessageHandler ¶
type MessageHandler interface {
ServeMessage(w http.ResponseWriter, r *Request)
}
微信服务器推送过来的消息(事件)处理接口
type MessageHandlerFunc ¶
type MessageHandlerFunc func(http.ResponseWriter, *Request)
func (MessageHandlerFunc) ServeMessage ¶
func (fn MessageHandlerFunc) ServeMessage(w http.ResponseWriter, r *Request)
type MessageServeMux ¶
type MessageServeMux struct {
// contains filtered or unexported fields
}
MessageServeMux 实现了一个简单的消息路由器, 同时也是一个 MessageHandler.
func NewMessageServeMux ¶
func NewMessageServeMux() *MessageServeMux
func (*MessageServeMux) DefaultEventHandle ¶
func (mux *MessageServeMux) DefaultEventHandle(handler MessageHandler)
注册 MessageHandler, 处理未知类型的事件.
func (*MessageServeMux) DefaultEventHandleFunc ¶
func (mux *MessageServeMux) DefaultEventHandleFunc(handler func(http.ResponseWriter, *Request))
注册 MessageHandlerFunc, 处理未知类型的事件.
func (*MessageServeMux) DefaultMessageHandle ¶
func (mux *MessageServeMux) DefaultMessageHandle(handler MessageHandler)
注册 MessageHandler, 处理未知类型的消息.
func (*MessageServeMux) DefaultMessageHandleFunc ¶
func (mux *MessageServeMux) DefaultMessageHandleFunc(handler func(http.ResponseWriter, *Request))
注册 MessageHandlerFunc, 处理未知类型的消息.
func (*MessageServeMux) EventHandle ¶
func (mux *MessageServeMux) EventHandle(eventType string, handler MessageHandler)
注册 MessageHandler, 处理特定类型的事件.
func (*MessageServeMux) EventHandleFunc ¶
func (mux *MessageServeMux) EventHandleFunc(eventType string, handler func(http.ResponseWriter, *Request))
注册 MessageHandlerFunc, 处理特定类型的事件.
func (*MessageServeMux) MessageHandle ¶
func (mux *MessageServeMux) MessageHandle(msgType string, handler MessageHandler)
注册 MessageHandler, 处理特定类型的消息.
func (*MessageServeMux) MessageHandleFunc ¶
func (mux *MessageServeMux) MessageHandleFunc(msgType string, handler func(http.ResponseWriter, *Request))
注册 MessageHandlerFunc, 处理特定类型的消息.
func (*MessageServeMux) ServeMessage ¶
func (mux *MessageServeMux) ServeMessage(w http.ResponseWriter, r *Request)
MessageServeMux 实现了 MessageHandler 接口.
type MixedMessage ¶
type MixedMessage struct { XMLName struct{} `xml:"xml" json:"-"` CommonMessageHeader MsgId int64 `xml:"MsgId" json:"MsgId"` Content string `xml:"Content" json:"Content"` MediaId string `xml:"MediaId" json:"MediaId"` PicURL string `xml:"PicUrl" json:"PicUrl"` Format string `xml:"Format" json:"Format"` ThumbMediaId string `xml:"ThumbMediaId" json:"ThumbMediaId"` LocationX float64 `xml:"Location_X" json:"Location_X"` LocationY float64 `xml:"Location_Y" json:"Location_Y"` Scale int `xml:"Scale" json:"Scale"` Label string `xml:"Label" json:"Label"` Event string `xml:"Event" json:"Event"` EventKey string `xml:"EventKey" json:"EventKey"` ScanCodeInfo struct { ScanType string `xml:"ScanType" json:"ScanType"` ScanResult string `xml:"ScanResult" json:"ScanResult"` } `xml:"ScanCodeInfo" json:"ScanCodeInfo"` SendPicsInfo struct { Count int `xml:"Count" json:"Count"` PicList []struct { PicMD5Sum string `xml:"PicMd5Sum" json:"PicMd5Sum"` } `xml:"PicList>item,omitempty" json:"PicList,omitempty"` } `xml:"SendPicsInfo" json:"SendPicsInfo"` SendLocationInfo struct { LocationX float64 `xml:"Location_X" json:"Location_X"` LocationY float64 `xml:"Location_Y" json:"Location_Y"` Scale int `xml:"Scale" json:"Scale"` Label string `xml:"Label" json:"Label"` Poiname string `xml:"Poiname" json:"Poiname"` } `xml:"SendLocationInfo" json:"SendLocationInfo"` Latitude float64 `xml:"Latitude" json:"Latitude"` Longitude float64 `xml:"Longitude" json:"Longitude"` Precision float64 `xml:"Precision" json:"Precision"` }
微信服务器推送过来的消息(事件)的合集.
type MultiAgentServerFrontend ¶
type MultiAgentServerFrontend struct {
// contains filtered or unexported fields
}
多个 AgentServer 的前端, 负责处理 http 请求, net/http.Handler 的实现
NOTE: MultiAgentServerFrontend 可以处理多个企业号应用的消息(事件),但是要求在回调 URL 上加上一个 查询参数,参考常量 URLQueryAgentServerKeyName,这个参数的值就是 MultiAgentServerFrontend 索引 AgentServer 的 key。 例如回调 URL 为 http://www.xxx.com/weixin?agent_server=1234567890,那么就可以在后端调用 MultiAgentServerFrontend.SetAgentServer("1234567890", AgentServer) 来增加一个 AgentServer 来处理 agent_server=1234567890 的消息(事件)。 MultiAgentServerFrontend 并发安全,可以在运行中动态增加和删除 AgentServer。
func (*MultiAgentServerFrontend) DeleteAgentServer ¶
func (frontend *MultiAgentServerFrontend) DeleteAgentServer(serverKey string)
删除 serverKey 对应的 AgentServer
func (*MultiAgentServerFrontend) DeleteAllAgentServer ¶
func (frontend *MultiAgentServerFrontend) DeleteAllAgentServer()
删除所有的 AgentServer
func (*MultiAgentServerFrontend) ServeHTTP ¶
func (frontend *MultiAgentServerFrontend) ServeHTTP(w http.ResponseWriter, r *http.Request)
实现 http.Handler
func (*MultiAgentServerFrontend) SetAgentServer ¶
func (frontend *MultiAgentServerFrontend) SetAgentServer(serverKey string, server AgentServer)
设置 serverKey-AgentServer pair. 如果 serverKey == "" 或者 server == nil 则不做任何操作
func (*MultiAgentServerFrontend) SetInvalidRequestHandler ¶
func (frontend *MultiAgentServerFrontend) SetInvalidRequestHandler(handler InvalidRequestHandler)
设置 InvalidRequestHandler, 如果 handler == nil 则使用默认的 DefaultInvalidRequestHandler
type Request ¶
type Request struct { HttpRequest *http.Request // 可以为 nil, 因为某些 http 框架没有提供此参数 QueryValues url.Values // 回调请求 URL 中的查询参数集合 MsgSignature string // 回调请求 URL 中的消息体签名: msg_signature TimeStamp int64 // 回调请求 URL 中的时间戳: timestamp Nonce string // 回调请求 URL 中的随机数: nonce RawMsgXML []byte // 消息的"明文"XML 文本 MixedMsg *MixedMessage // RawMsgXML 解析后的消息 AESKey [32]byte // 当前消息 AES 加密的 key Random []byte // 当前消息加密时所用的 random, 16 bytes // 下面字段是企业号应用的基本信息 CorpId string // 请求消息所属企业号的 ID AgentId int64 // 请求消息所属企业号应用的 ID AgentToken string // 请求消息所属企业号应用的 Token }
消息(事件)请求信息
type RequestHttpBody ¶
type RequestHttpBody struct { XMLName struct{} `xml:"xml" json:"-"` CorpId string `xml:"ToUserName"` AgentId int64 `xml:"AgentID"` EncryptedMsg string `xml:"Encrypt"` }
微信服务器请求 http body
type ResponseHttpBody ¶
type ResponseHttpBody struct { XMLName struct{} `xml:"xml" json:"-"` EncryptedMsg string `xml:"Encrypt"` MsgSignature string `xml:"MsgSignature"` TimeStamp int64 `xml:"TimeStamp"` Nonce string `xml:"Nonce"` }
回复消息的 http body
type TokenServer ¶
type TokenServer interface { // 从中控服务器获取被缓存的 access_token. Token() (token string, err error) // 请求中控服务器到微信服务器刷新 access_token. // // 高并发场景下某个时间点可能有很多请求(比如缓存的access_token刚好过期时), 但是我们 // 不期望也没有必要让这些请求都去微信服务器获取 access_token(有可能导致api超过调用限制), // 实际上这些请求只需要一个新的 access_token 即可, 所以建议 TokenServer 从微信服务器 // 获取一次 access_token 之后的至多5秒内(收敛时间, 视情况而定, 理论上至多5个http或tcp周期) // 再次调用该函数不再去微信服务器获取, 而是直接返回之前的结果. TokenRefresh() (token string, err error) }
access_token 中控服务器接口, see token_server.png