officialaccount

Documentation

Index

• type AccessToken
  • func NewAccessToken(appID, appSecret string, cache core.Cache, httpClient *http.Client, ...) *AccessToken
  • func (at *AccessToken) GetToken(ctx context.Context) (string, error)
  • func (at *AccessToken) RefreshToken(ctx context.Context) (string, error)
• type Config
• type GetTicketRequest
• type GetTicketResponse
• type JssdkSignRequest
• type JssdkSignResponse
• type OfficialAccount
  • func New(cfg *Config) *OfficialAccount
  • func (oa *OfficialAccount) Get(ctx context.Context, path string, query map[string]string, result any) error
  • func (oa *OfficialAccount) GetAccessToken() *AccessToken
  • func (oa *OfficialAccount) GetClient() *core.Client
  • func (oa *OfficialAccount) GetConfig() *Config
  • func (oa *OfficialAccount) GetJssdkSign(ctx context.Context, req *JssdkSignRequest) (*JssdkSignResponse, error)
  • func (oa *OfficialAccount) GetRaw(ctx context.Context, path string, query map[string]string, withToken bool) ([]byte, error)
  • func (oa *OfficialAccount) GetTicket(ctx context.Context, req *GetTicketRequest) (*GetTicketResponse, error)
  • func (oa *OfficialAccount) GetWithoutToken(ctx context.Context, path string, query map[string]string, result any) error
  • func (oa *OfficialAccount) Post(ctx context.Context, path string, reqBody any, result any) error
  • func (oa *OfficialAccount) PostRaw(ctx context.Context, path string, body any, withToken bool) ([]byte, error)
  • func (oa *OfficialAccount) RefreshTicket(ctx context.Context, ticketType TicketType) (*GetTicketResponse, error)
• type Response
  • func NewResponse[T any](body []byte) *Response[T]
  • func (r *Response[T]) Decode() (T, error)
  • func (r *Response[T]) DecodeInto(v any) error
  • func (r *Response[T]) Error() error
  • func (r *Response[T]) IsSuccess() bool
  • func (r *Response[T]) Map() (map[string]any, error)
  • func (r *Response[T]) String() string
• type TicketType

Types

type AccessToken

type AccessToken struct {
	// contains filtered or unexported fields
}

AccessToken 公众号 AccessToken 管理

func NewAccessToken

func NewAccessToken(appID, appSecret string, cache core.Cache, httpClient *http.Client, logger *slog.Logger) *AccessToken

NewAccessToken 创建 AccessToken 实例

func (*AccessToken) GetToken

func (at *AccessToken) GetToken(ctx context.Context) (string, error)

GetToken 获取 AccessToken（优先从缓存获取）

func (*AccessToken) RefreshToken

func (at *AccessToken) RefreshToken(ctx context.Context) (string, error)

RefreshToken 强制刷新 AccessToken

type Config

type Config struct {
	// AppID 公众号 AppID（必填）
	AppID string
	// AppSecret 公众号 AppSecret（必填）
	AppSecret string
	// Cache 缓存实现（可选，默认使用内存缓存）
	Cache core.Cache
	// HTTPClient 自定义 HTTP 客户端（可选）
	HTTPClient *http.Client
	// Logger 日志记录器（可选，默认使用 slog.Default()）
	Logger *slog.Logger
}

Config 公众号配置

type GetTicketRequest

type GetTicketRequest struct {
	// Type ticket 类型，默认为 jsapi
	Type TicketType
}

GetTicketRequest 获取 ticket 请求参数

type GetTicketResponse

type GetTicketResponse struct {
	// Ticket 临时票据
	Ticket string `json:"ticket"`
	// ExpiresIn 有效期（秒）
	ExpiresIn int `json:"expires_in"`
}

GetTicketResponse 获取 ticket 响应结果

type JssdkSignRequest

type JssdkSignRequest struct {
	// URL 当前网页的完整 URL（不包含 hash，即去掉 # 及其后面的部分）
	URL string
}

JssdkSignRequest JS-SDK 签名请求参数

type JssdkSignResponse

type JssdkSignResponse struct {
	// AppID 公众号 AppID
	AppID string `json:"appId"`
	// Timestamp 时间戳（秒）
	Timestamp int64 `json:"timestamp"`
	// NonceStr 随机字符串
	NonceStr string `json:"nonceStr"`
	// Signature 签名
	Signature string `json:"signature"`
}

JssdkSignResponse JS-SDK 签名响应结果

type OfficialAccount

type OfficialAccount struct {
	// contains filtered or unexported fields
}

OfficialAccount 公众号实例

func New

func New(cfg *Config) *OfficialAccount

New 创建公众号实例

func (*OfficialAccount) Get

func (oa *OfficialAccount) Get(ctx context.Context, path string, query map[string]string, result any) error

Get 发送 GET 请求并解析响应到 result（带 access_token）

func (*OfficialAccount) GetAccessToken

func (oa *OfficialAccount) GetAccessToken() *AccessToken

GetAccessToken 获取 AccessToken 管理器

func (*OfficialAccount) GetClient

func (oa *OfficialAccount) GetClient() *core.Client

GetClient 获取 HTTP 客户端

func (*OfficialAccount) GetConfig

func (oa *OfficialAccount) GetConfig() *Config

GetConfig 获取配置

func (*OfficialAccount) GetJssdkSign

func (oa *OfficialAccount) GetJssdkSign(ctx context.Context, req *JssdkSignRequest) (*JssdkSignResponse, error)

GetJssdkSign 生成 JS-SDK 签名 用于前端调用 wx.config 时所需的签名参数

接口文档: https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html#62

签名算法:

1. 获取 jsapi_ticket
2. 生成随机字符串 noncestr
3. 获取当前时间戳 timestamp
4. 按照固定格式拼接字符串并做 SHA1 签名

参数:

• ctx: 上下文
• req: 请求参数，包含当前页面 URL

返回:

• *JssdkSignResponse: 响应结果，包含 appId, timestamp, nonceStr, signature
• error: 可能的错误

示例:

resp, err := oa.GetJssdkSign(ctx, &officialaccount.JssdkSignRequest{
    URL: "https://example.com/path",
})
if err != nil {
    return err
}
// 返回给前端用于 wx.config
// {appId, timestamp, nonceStr, signature}

func (*OfficialAccount) GetRaw

func (oa *OfficialAccount) GetRaw(ctx context.Context, path string, query map[string]string, withToken bool) ([]byte, error)

GetRaw 获取原始响应

func (*OfficialAccount) GetTicket

func (oa *OfficialAccount) GetTicket(ctx context.Context, req *GetTicketRequest) (*GetTicketResponse, error)

GetTicket 获取 JS-SDK 临时票据 接口文档: https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html#62

Api_ticket 是用于调用 js-sdk 的临时票据，有效期为 7200 秒，通过 access_token 来获取。

参数:

• ctx: 上下文
• req: 请求参数，包含 Type（默认 jsapi）

返回:

• *GetTicketResponse: 响应结果，包含 ticket 和 expires_in
• error: 可能的错误

示例:

resp, err := oa.GetTicket(ctx, &officialaccount.GetTicketRequest{
    Type: officialaccount.TicketTypeJSAPI,
})
if err != nil {
    return err
}
fmt.Println("Ticket:", resp.Ticket)

func (*OfficialAccount) GetWithoutToken

func (oa *OfficialAccount) GetWithoutToken(ctx context.Context, path string, query map[string]string, result any) error

GetWithoutToken 发送 GET 请求（不带 access_token）并解析响应到 result

func (*OfficialAccount) Post

func (oa *OfficialAccount) Post(ctx context.Context, path string, reqBody any, result any) error

Post 发送 POST 请求并解析响应到 result（带 access_token）

func (*OfficialAccount) PostRaw

func (oa *OfficialAccount) PostRaw(ctx context.Context, path string, body any, withToken bool) ([]byte, error)

PostRaw 发送 POST 请求获取原始响应

func (*OfficialAccount) RefreshTicket

func (oa *OfficialAccount) RefreshTicket(ctx context.Context, ticketType TicketType) (*GetTicketResponse, error)

RefreshTicket 强制刷新 ticket

type Response

type Response[T any] struct {
	Body []byte
	Data T
	// contains filtered or unexported fields
}

Response 公众号 API 响应封装

func NewResponse

func NewResponse[T any](body []byte) *Response[T]

NewResponse 创建响应实例

func (*Response[T]) Decode

func (r *Response[T]) Decode() (T, error)

Decode 一次性完成： 1. 先探测 errcode/errmsg 2. 再解析到业务模型 T

func (*Response[T]) DecodeInto

func (r *Response[T]) DecodeInto(v any) error

DecodeInto 解析响应到指定的变量

func (*Response[T]) Error

func (r *Response[T]) Error() error

Error 检查响应是否包含微信错误

func (*Response[T]) IsSuccess

func (r *Response[T]) IsSuccess() bool

IsSuccess 判断响应是否成功

func (*Response[T]) Map

func (r *Response[T]) Map() (map[string]any, error)

Map 解析响应为 map

func (*Response[T]) String

func (r *Response[T]) String() string

String 返回响应字符串

type TicketType

type TicketType string

TicketType ticket 类型

const (
	// TicketTypeJSAPI JS-SDK 票据
	TicketTypeJSAPI TicketType = "jsapi"
	// TicketTypeWxCard 微信卡券票据
	TicketTypeWxCard TicketType = "wx_card"
)