wego

package module
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 25, 2025 License: Apache-2.0 Imports: 9 Imported by: 0

README

WeGo - 微信开发封装库

WeGo是一个模块化的微信开发封装库,专门为微信开放平台第三方平台开发和微信公众号开发设计。该库提供了完整的微信开放平台API封装、微信公众号API封装、消息处理、授权管理等功能。

特性

  • 🏗️ 模块化设计 - 按功能模块组织代码,便于扩展和维护
  • 🔐 完整的API封装 - 支持微信开放平台和微信公众号所有核心API
  • 📨 消息处理 - 支持微信消息的接收、解析和处理
  • 🔑 授权管理 - 提供完整的授权流程管理
  • 🔒 安全加密 - 支持微信消息的加密和解密
  • 💾 存储抽象 - 支持多种存储后端(内存、文件、数据库等)
  • 📚 类型安全 - 完整的类型定义和错误处理
  • 🔄 稳定版Token - 支持稳定版access_token获取和管理
  • 📢 订阅消息 - 支持订阅通知消息功能

项目结构

wego/
├── core/           # 核心配置和客户端
├── crypto/         # 加密解密功能
├── message/        # 消息处理功能
├── officialaccount/ # 公众号开发功能
├── openplatform/   # 开放平台功能
├── storage/        # 存储抽象层
├── types/          # 类型定义
└── doc/           # 技术文档

导出类型

type (
    // API通用响应
    APIResponse = core.APIResponse

    // 存储相关类型
    TokenStorage          = storage.TokenStorage
    MemoryStorage         = storage.MemoryStorage
    DBStorage             = storage.DBStorage
    FileStorage           = storage.FileStorage
    ComponentAccessToken  = storage.ComponentAccessToken
    PreAuthCode           = storage.PreAuthCode
    AuthorizerAccessToken = storage.AuthorizerAccessToken

    // 开放平台相关类型
    OpenPlatformConfig            = openplatform.Config
    OpenPlatformAuthorizationInfo = openplatform.AuthorizationInfo
    OpenPlatformAuthorizerInfo    = openplatform.AuthorizerInfo

    // 微信公众号相关类型
    OfficialAccountConfig         = official_account.Config
    OfficialAccountClient         = official_account.Client
    OfficialAccountAPIClient      = official_account.APIClient
    OfficialAccountMenuClient     = official_account.MenuClient
    OfficialAccountMessageClient  = official_account.MessageClient
    OfficialAccountTemplateClient = official_account.TemplateClient
    OfficialAccountCustomClient   = official_account.CustomClient
    OfficialAccountMaterialClient = official_account.MaterialClient

    // 微信公众号消息与数据结构
    OfficialAccountMenu                   = official_account.Menu
    OfficialAccountButton                 = official_account.Button
    OfficialAccountTemplateMessageRequest = official_account.TemplateMessageRequest
    OfficialAccountTemplateMessageData    = official_account.TemplateMessageData
    OfficialAccountMessageText            = official_account.MessageText
    OfficialAccountMessageImage           = official_account.MessageImage
    OfficialAccountMessageVoice           = official_account.MessageVoice
    OfficialAccountMessageVideo           = official_account.MessageVideo
    OfficialAccountMusicMessage           = official_account.MessageMusic
    OfficialAccountNewsMessage            = official_account.MessageNews
    OfficialAccountWXCardMessage          = official_account.MessageWXCard
    OfficialAccountMiniProgramPageMessage = official_account.MessageMiniProgramPage
    OfficialAccountNewsArticle            = official_account.NewsArticle
    UserInfo                              = types.OAuthUserInfoResponse
)

快速开始

安装
go get github.com/jcbowen/wego
存储说明

WeGo库提供多种存储后端支持:

  • 文件存储(默认):使用wego_storage目录保存Token数据
  • 内存存储:适合开发和测试环境,重启后数据丢失
  • 数据库存储:支持GORM数据库存储
  • 自定义存储:支持自定义存储实现

默认存储策略:

  • 默认使用文件存储,数据持久化到本地文件
  • 如果文件存储创建失败,会自动回退到内存存储并记录警告日志
  • 可通过NewWeGoWithStorage方法指定自定义存储
稳定版Token说明

WeGo库支持稳定版access_token功能:

  • 普通模式:优先使用缓存的token,避免频繁刷新
  • 强制刷新模式:强制刷新获取新的token
  • 自动刷新:在token即将过期时自动刷新
  • 存储支持:支持稳定版token的持久化存储(当前版本存储接口正在扩展中)
基本使用
只使用开放平台
package main

import (
	"fmt"
	"github.com/jcbowen/wego"
)

func main() {
	// 配置微信开放平台参数
	openPlatformConfig := &wego.OpenPlatformConfig{
		ComponentAppID:     "your_component_app_id",
		ComponentAppSecret: "your_component_app_secret",
		ComponentToken:     "your_component_token",
		EncodingAESKey:     "your_encoding_aes_key",
		RedirectURI:        "your_redirect_uri",
	}

    // 创建WeGo实例(只初始化开放平台)
    wegoClient := wego.New(openPlatformConfig)

    // 使用开放平台功能
    authClient := wegoClient.OpenPlatformAuth()
    messageClient := wegoClient.OpenPlatformMessage()
    // 需要直接调用开放平台API时可使用底层客户端:
    // wegoClient.OpenPlatformClient.GetComponentAccessToken(ctx, "...")

	fmt.Println("开放平台客户端初始化成功!")
}
只使用公众号
package main

import (
	"fmt"
	"github.com/jcbowen/wego"
)

func main() {
	// 配置公众号参数
	officialAccountConfig := &wego.MPConfig{
		AppID:     "your_mp_app_id",
		AppSecret: "your_mp_app_secret",
		Token:     "your_mp_token",
		AESKey:    "your_mp_aes_key",
	}

    // 创建WeGo实例(只初始化公众号)
    wegoClient := wego.New(officialAccountConfig)

	// 使用公众号功能
	apiClient := wegoClient.OfficialAccountAPI()
	menuClient := wegoClient.OfficialAccountMenu()
	messageClient := wegoClient.OfficialAccountMessage()

	fmt.Println("公众号客户端初始化成功!")
}
同时使用开放平台和公众号
package main

import (
	"fmt"
	"github.com/jcbowen/wego"
)

func main() {
	// 配置开放平台参数
	openPlatformConfig := &wego.OpenPlatformConfig{
		ComponentAppID:     "your_component_app_id",
		ComponentAppSecret: "your_component_app_secret",
		ComponentToken:     "your_component_token",
		EncodingAESKey:     "your_encoding_aes_key",
		RedirectURI:        "your_redirect_uri",
	}

	// 配置公众号参数
	officialAccountConfig := &wego.MPConfig{
		AppID:     "your_mp_app_id",
		AppSecret: "your_mp_app_secret",
		Token:     "your_mp_token",
		AESKey:    "your_mp_aes_key",
	}

    // 创建WeGo实例(同时初始化开放平台和公众号)
    wegoClient := wego.New(openPlatformConfig, officialAccountConfig)

	// 检查客户端是否初始化
	fmt.Printf("开放平台已初始化: %v\n", wegoClient.OpenPlatformClient != nil)
	fmt.Printf("公众号已初始化: %v\n", wegoClient.OfficialAccountClient != nil)

    // 使用开放平台功能
    openPlatformAuth := wegoClient.OpenPlatformAuth()
    openPlatformMessage := wegoClient.OpenPlatformMessage()

	// 使用公众号功能
	officialAccountAPI := wegoClient.OfficialAccountAPI()
	
	// 使用通用功能
	cryptoClient := wegoClient.Crypto()
	storageClient := wegoClient.Storage()

	fmt.Println("所有客户端初始化成功!")
}
使用稳定版Token功能
package main

import (
	"context"
	"fmt"
	"github.com/jcbowen/wego"
)

func main() {
	// 配置公众号参数
	config := &wego.MPConfig{
		AppID:     "your_mp_app_id",
		AppSecret: "your_mp_app_secret",
		Token:     "your_mp_token",
		AESKey:    "your_mp_aes_key",
	}

    // 创建WeGo实例
    wegoClient := wego.New(config)

    // 获取公众号API客户端
    apiClient := wegoClient.OfficialAccountAPI()

    // 使用稳定版token发送请求
	ctx := context.Background()
	
    // 普通模式获取稳定版token(通过底层Client访问稳定版客户端)
    tokenInfo, err := apiClient.Client.GetStableTokenClient().GetStableAccessTokenNormal(ctx)
	if err != nil {
		fmt.Printf("获取稳定版token失败: %v\n", err)
		return
	}
	fmt.Printf("稳定版token: %s, 过期时间: %v\n", tokenInfo.AccessToken, tokenInfo.ExpiresAt)

    // 使用稳定版token发送API请求
	var result map[string]interface{}
    err = apiClient.Client.GetStableTokenClient().MakeRequestWithStableToken(ctx, "GET", 
        "https://api.weixin.qq.com/cgi-bin/user/get", nil, &result)
	if err != nil {
		fmt.Printf("API请求失败: %v\n", err)
		return
	}
	fmt.Printf("API响应: %+v\n", result)
}
使用订阅消息功能
package main

import (
	"context"
	"fmt"
	"github.com/jcbowen/wego"
)

func main() {
	// 配置公众号参数
	config := &wego.MPConfig{
		AppID:     "your_mp_app_id",
		AppSecret: "your_mp_app_secret",
		Token:     "your_mp_token",
		AESKey:    "your_mp_aes_key",
	}

	// 创建WeGo实例
	wegoClient := wego.NewWeGo(config)

	// 获取订阅消息客户端
	subscribeClient := wegoClient.OfficialAccountSubscribe()

	// 获取订阅通知分类列表
	ctx := context.Background()
	categoryResp, err := subscribeClient.GetCategory(ctx)
	if err != nil {
		fmt.Printf("获取分类列表失败: %v\n", err)
		return
	}
	fmt.Printf("分类列表: %+v\n", categoryResp.Data)

	// 获取公共模板标题列表
	titlesResp, err := subscribeClient.GetPubNewTemplateTitles(ctx, 1, 0, 10)
	if err != nil {
		fmt.Printf("获取模板标题失败: %v\n", err)
		return
	}
	fmt.Printf("模板标题列表: %+v\n", titlesResp.Data)
}

模块说明

Core 模块

核心配置和客户端实现,包含:

  • OpenPlatformConfig - 开放平台配置结构体
  • WegoClient - 主客户端
  • 令牌管理和HTTP客户端
OpenPlatform 模块

微信开放平台功能,包含:

  • APIClient - 开放平台API客户端
  • AuthClient - 授权管理客户端
  • API地址常量定义
  • API响应结构体
  • 授权信息数据结构
  • 事件处理器接口
OfficialAccount 模块

微信公众号开发功能,包含:

  • MPClient - 公众号主客户端
  • MPAPIClient - 公众号API客户端
  • MenuClient - 菜单管理客户端
  • MessageClient - 消息处理客户端
  • TemplateClient - 模板消息客户端
  • CustomClient - 客服消息客户端
  • MaterialClient - 素材管理客户端
  • StableTokenClient - 稳定版access_token客户端
  • SubscribeClient - 订阅消息客户端

客户端获取方法:

  • OfficialAccountAPI() - 获取公众号API客户端
  • OfficialAccountMenu() - 获取菜单管理客户端
  • OfficialAccountMessage() - 获取消息处理客户端
  • OfficialAccountTemplate() - 获取模板消息客户端
  • OfficialAccountCustom() - 获取客服消息客户端
  • OfficialAccountMaterial() - 获取素材管理客户端
  • OfficialAccountSubscribe() - 获取订阅消息客户端(通过MPAPIClient的GetSubscribeClient()方法)
  • GetStableTokenClient() - 获取稳定版Token客户端(通过MPAPIClient的GetStableTokenClient()方法)
Message 模块

消息处理功能,包含:

  • 消息类型常量
  • 消息结构体定义
  • 消息处理器接口
Crypto 模块

加密解密功能,包含:

  • AES密钥解码
  • 消息加密和解密
  • PKCS7填充处理
Storage 模块

存储抽象层,包含:

  • TokenStorage 接口 - 定义组件令牌、预授权码、验证票据、授权方令牌等存储方法
  • MemoryStorage 内存存储实现 - 基于内存的临时存储
  • FileStorage 文件存储实现(默认存储) - 基于本地文件的持久化存储
  • DBStorage 数据库存储实现 - 基于数据库的持久化存储
  • 支持自定义存储后端

默认存储策略:

  • 默认存储为文件存储
  • 文件存储使用./runtime/wego_storage目录保存Token数据
  • 如果文件存储创建失败,会自动回退到内存存储并记录警告日志
  • 可通过NewWithStorage方法指定自定义存储
  • 稳定版token的持久化存储支持后续扩展

示例

查看 doc/ 目录获取完整的使用示例和技术文档:

文档

详细的技术文档请查看 doc/ 目录:

  • 授权流程技术说明
  • 消息加解密说明
  • Token生成介绍
  • 消息与事件处理

依赖

  • Go 1.23.0+
  • gorm.io/gorm v1.31.0
  • github.com/jcbowen/jcbaseGo v0.13.6

许可证

MIT License

贡献

欢迎提交Issue和Pull Request!

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIResponse

type APIResponse = core.APIResponse

导出常用结构体类型

type AuthorizerAccessToken

type AuthorizerAccessToken = storage.AuthorizerAccessToken

导出常用结构体类型

type ComponentAccessToken

type ComponentAccessToken = storage.ComponentAccessToken

导出常用结构体类型

type DBStorage

type DBStorage = storage.DBStorage

导出常用结构体类型

type FileStorage

type FileStorage = storage.FileStorage

导出常用结构体类型

type OfficialAccountAPIClient

type OfficialAccountAPIClient = official_account.APIClient

导出常用结构体类型

type OfficialAccountButton

type OfficialAccountButton = official_account.Button

导出常用结构体类型

type OfficialAccountClient

type OfficialAccountClient = official_account.Client

导出常用结构体类型

type OfficialAccountConfig

type OfficialAccountConfig = official_account.Config

微信公众号开发相关类型

type OfficialAccountCustomClient

type OfficialAccountCustomClient = official_account.CustomClient

导出常用结构体类型

type OfficialAccountMaterialClient

type OfficialAccountMaterialClient = official_account.MaterialClient

导出常用结构体类型

type OfficialAccountMenu

type OfficialAccountMenu = official_account.Menu

微信公众号数据结构体

type OfficialAccountMenuClient

type OfficialAccountMenuClient = official_account.MenuClient

导出常用结构体类型

type OfficialAccountMessageClient

type OfficialAccountMessageClient = official_account.MessageClient

导出常用结构体类型

type OfficialAccountMessageImage

type OfficialAccountMessageImage = official_account.MessageImage

导出常用结构体类型

type OfficialAccountMessageText

type OfficialAccountMessageText = official_account.MessageText

导出常用结构体类型

type OfficialAccountMessageVideo

type OfficialAccountMessageVideo = official_account.MessageVideo

导出常用结构体类型

type OfficialAccountMessageVoice

type OfficialAccountMessageVoice = official_account.MessageVoice

导出常用结构体类型

type OfficialAccountMiniProgramPageMessage

type OfficialAccountMiniProgramPageMessage = official_account.MessageMiniProgramPage

导出常用结构体类型

type OfficialAccountMusicMessage

type OfficialAccountMusicMessage = official_account.MessageMusic

导出常用结构体类型

type OfficialAccountNewsArticle

type OfficialAccountNewsArticle = official_account.NewsArticle

导出常用结构体类型

type OfficialAccountNewsMessage

type OfficialAccountNewsMessage = official_account.MessageNews

导出常用结构体类型

type OfficialAccountTemplateClient

type OfficialAccountTemplateClient = official_account.TemplateClient

导出常用结构体类型

type OfficialAccountTemplateMessageData

type OfficialAccountTemplateMessageData = official_account.TemplateMessageData

导出常用结构体类型

type OfficialAccountTemplateMessageRequest

type OfficialAccountTemplateMessageRequest = official_account.TemplateMessageRequest

导出常用结构体类型

type OfficialAccountWXCardMessage

type OfficialAccountWXCardMessage = official_account.MessageWXCard

导出常用结构体类型

type OpenPlatformAuthorizationInfo

type OpenPlatformAuthorizationInfo = openplatform.AuthorizationInfo

导出常用结构体类型

type OpenPlatformAuthorizerInfo

type OpenPlatformAuthorizerInfo = openplatform.AuthorizerInfo

导出常用结构体类型

type OpenPlatformConfig

type OpenPlatformConfig = openplatform.Config

开放平台相关类型

type PreAuthCode

type PreAuthCode = storage.PreAuthCode

导出常用结构体类型

type TokenStorage

type TokenStorage = storage.TokenStorage

存储相关类型

type UserInfo

type UserInfo = types.OAuthUserInfoResponse

导出常用结构体类型

type WeGo

type WeGo struct {
	// 开放平台客户端
	OpenPlatformClient *openplatform.Client

	// 公众号客户端
	OfficialAccountClient *official_account.Client
}

WeGo 微信开发封装库主结构体

func New

func New(params ...any) *WeGo

New 创建新的WeGo实例,支持多种客户端配置和可选参数 同类型的客户端只能初始化一个,比如第一个参数是微信公众号,后面的不管还有几个公众号配置都忽略掉 @param configParams ...any 配置参数,支持以下类型:

  • openplatform.Config 或 *openplatform.Config: 开放平台配置
  • official_account.Config 或 *official_account.Config: 公众号配置

@param optParams ...any 可选参数,支持以下类型:

  • debugger.LoggerInterface: 自定义日志器
  • core.HTTPClient: 自定义HTTP客户端
  • openplatform.EventHandler: 开放平台事件处理器

@return *WeGo WeGo实例

func NewWithStorage

func NewWithStorage(storage storage.TokenStorage, params ...any) *WeGo

NewWithStorage 创建新的WeGo实例(使用自定义存储),支持可选参数 同类型的客户端只能初始化一个,比如第一个参数是微信公众号,后面的不管还有几个公众号配置都忽略掉 @param storage storage.TokenStorage 自定义存储实例 @param configParams ...any 配置参数,支持以下类型:

  • openplatform.Config 或 *openplatform.Config: 开放平台配置
  • official_account.Config 或 *official_account.Config: 公众号配置

@param optParams ...any 可选参数,支持以下类型:

  • debugger.LoggerInterface: 自定义日志器
  • core.HTTPClient: 自定义HTTP客户端
  • openplatform.EventHandler: 开放平台事件处理器

@return *WeGo WeGo实例

func (*WeGo) Crypto

func (w *WeGo) Crypto() *crypto.CryptoClient

Crypto 返回加密解密相关功能

func (*WeGo) OfficialAccountAPI

func (w *WeGo) OfficialAccountAPI() *official_account.APIClient

OfficialAccountAPI 返回公众号API相关功能

func (*WeGo) OfficialAccountCustom

func (w *WeGo) OfficialAccountCustom() *official_account.CustomClient

OfficialAccountCustom 返回公众号客服消息相关功能

func (*WeGo) OfficialAccountMaterial

func (w *WeGo) OfficialAccountMaterial() *official_account.MaterialClient

OfficialAccountMaterial 返回公众号素材管理相关功能

func (*WeGo) OfficialAccountMenu

func (w *WeGo) OfficialAccountMenu() *official_account.MenuClient

OfficialAccountMenu 返回公众号菜单相关功能

func (*WeGo) OfficialAccountMessage

func (w *WeGo) OfficialAccountMessage() *official_account.MessageClient

OfficialAccountMessage 返回公众号消息相关功能

func (*WeGo) OfficialAccountOAuth

func (w *WeGo) OfficialAccountOAuth() *official_account.OAuthClient

OfficialAccountOAuth 返回公众号网页授权相关功能

func (*WeGo) OfficialAccountSubscribe

func (w *WeGo) OfficialAccountSubscribe() *official_account.SubscribeClient

OfficialAccountSubscribe 返回公众号订阅消息相关功能 功能:获取订阅消息客户端实例,用于管理订阅消息相关功能 返回值:*official_account.SubscribeClient 订阅消息客户端指针

func (*WeGo) OfficialAccountTemplate

func (w *WeGo) OfficialAccountTemplate() *official_account.TemplateClient

OfficialAccountTemplate 返回公众号模板消息相关功能

func (*WeGo) OpenPlatformAuth

func (w *WeGo) OpenPlatformAuth() *openplatform.AuthClient

OpenPlatformAuth 返回开放平台授权相关功能

func (*WeGo) OpenPlatformMessage

func (w *WeGo) OpenPlatformMessage() *message.MessageClient

OpenPlatformMessage 返回开放平台消息处理相关功能

func (*WeGo) OpenPlatformOAuth

func (w *WeGo) OpenPlatformOAuth(redirectURI string) *openplatform.OAuthClient

OpenPlatformOAuth 返回开放平台网页授权相关功能(代公众号授权)

func (*WeGo) SetHTTPClient

func (w *WeGo) SetHTTPClient(client core.HTTPClient)

SetHTTPClient 设置自定义HTTP客户端

func (*WeGo) SetLogger

func (w *WeGo) SetLogger(log debugger.LoggerInterface)

SetLogger 设置日志记录器

func (*WeGo) Storage

func (w *WeGo) Storage() *storage.StorageClient

Storage 返回存储相关功能

Directories

Path Synopsis
Package official_account 微信公众号API - 参数二维码 本接口支持「服务号(仅认证)」账号类型调用。
Package official_account 微信公众号API - 参数二维码 本接口支持「服务号(仅认证)」账号类型调用。
Package openplatform 微信开放平台API - 调用授权方接口
Package openplatform 微信开放平台API - 调用授权方接口

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL