core

Documentation

Index

• Constants
• func DecodeWechat[T any](statusCode int, body []byte) (T, error)
• func IsTokenError(err error) bool
• func RedactQueryMap(query map[string]string) map[string]string
• func RedactURLQuery(rawURL string) string
• type AccessTokenProvider
• type Cache
• type Client
  • func NewClient(cfg ClientConfig) (*Client, error)
  • func (c *Client) Logger() *slog.Logger
  • func (c *Client) Request() *RequestBuilder
• type ClientConfig
• type MemoryCache
  • func NewMemoryCache() *MemoryCache
  • func (c *MemoryCache) Cleanup()
  • func (c *MemoryCache) Delete(ctx context.Context, key string) error
  • func (c *MemoryCache) Get(ctx context.Context, key string) (string, bool)
  • func (c *MemoryCache) Set(ctx context.Context, key string, value string, ttl time.Duration) error
• type RawResponse
• type RequestBuilder
  • func (b *RequestBuilder) Body(body any) *RequestBuilder
  • func (b *RequestBuilder) Get(ctx context.Context) (RawResponse, error)
  • func (b *RequestBuilder) Path(path string) *RequestBuilder
  • func (b *RequestBuilder) Post(ctx context.Context) (RawResponse, error)
  • func (b *RequestBuilder) Query(key, value string) *RequestBuilder
  • func (b *RequestBuilder) QueryMap(query map[string]string) *RequestBuilder
  • func (b *RequestBuilder) UploadField(key, value string) *RequestBuilder
  • func (b *RequestBuilder) UploadFile(field, fileName string, r io.Reader) *RequestBuilder
  • func (b *RequestBuilder) WithoutToken() *RequestBuilder
• type TokenFetchResult
• type TokenFetcher
• type TokenManager
  • func NewTokenManager(cfg TokenManagerConfig) (*TokenManager, error)
  • func (m *TokenManager) GetToken(ctx context.Context) (string, error)
  • func (m *TokenManager) RefreshToken(ctx context.Context) (string, error)
• type TokenManagerConfig
• type TypedRequest
  • func NewTypedRequest[T any](client *Client) *TypedRequest[T]
  • func (r *TypedRequest[T]) Body(body any) *TypedRequest[T]
  • func (r *TypedRequest[T]) Get(ctx context.Context) (T, error)
  • func (r *TypedRequest[T]) Path(path string) *TypedRequest[T]
  • func (r *TypedRequest[T]) Post(ctx context.Context) (T, error)
  • func (r *TypedRequest[T]) Query(key, value string) *TypedRequest[T]
  • func (r *TypedRequest[T]) QueryMap(query map[string]string) *TypedRequest[T]
  • func (r *TypedRequest[T]) UploadField(key, value string) *TypedRequest[T]
  • func (r *TypedRequest[T]) UploadFile(field, fileName string, reader io.Reader) *TypedRequest[T]
  • func (r *TypedRequest[T]) WithoutToken() *TypedRequest[T]
• type WechatError
  • func NewWechatError(code int, msg string) *WechatError
  • func (e *WechatError) Error() string

Constants

const (
	DefaultBaseURL = "https://api.weixin.qq.com"
	DefaultTimeout = 30 * time.Second
)

const (
	ErrCodeSuccess          = 0
	ErrCodeBusy             = -1
	ErrCodeInvalidToken     = 40001
	ErrCodeExpiredToken     = 42001
	ErrCodeInvalidAppID     = 40013
	ErrCodeInvalidAppSecret = 40125
	ErrCodeInvalidCode      = 40029
	ErrCodeCodeUsed         = 40163
	ErrCodeFreqLimit        = 45011
	ErrCodeAPIUnauthorized  = 48001
)

Functions

func DecodeWechat

func DecodeWechat[T any](statusCode int, body []byte) (T, error)

func IsTokenError

func IsTokenError(err error) bool

func RedactQueryMap

func RedactQueryMap(query map[string]string) map[string]string

RedactQueryMap 脱敏查询参数，返回拷贝，原 map 不会被修改。

func RedactURLQuery

func RedactURLQuery(rawURL string) string

RedactURLQuery 脱敏 URL 查询参数中的敏感字段。

Types

type AccessTokenProvider

type AccessTokenProvider interface {
	// GetToken 获取 AccessToken
	// 实现应处理缓存和自动刷新逻辑
	//
	// 参数:
	//   - ctx: 上下文
	//
	// 返回:
	//   - string: 可用于调用微信 API 的 access_token
	//   - error: 可能的错误
	//
	// 错误:
	//   - 获取或刷新 token 失败
	//   - 配置缺失导致无法获取 token
	GetToken(ctx context.Context) (string, error)

	// RefreshToken 强制刷新 AccessToken
	// 用于 token 失效时主动刷新
	//
	// 参数:
	//   - ctx: 上下文
	//
	// 返回:
	//   - string: 新的 access_token
	//   - error: 可能的错误
	//
	// 错误:
	//   - 向微信服务端刷新 token 失败
	//   - 微信接口限频导致刷新失败
	RefreshToken(ctx context.Context) (string, error)
}

AccessTokenProvider AccessToken 提供者接口 各产品（小程序、企业微信、公众号）需实现此接口

type Cache

type Cache interface {
	// Get 获取缓存值
	// 根据 key 读取缓存中的字符串值，若不存在或已过期则返回空字符串与 false。
	//
	// 参数:
	//   - ctx: 上下文
	//   - key: 缓存键
	//
	// 返回:
	//   - string: 命中时的缓存值，未命中时为空字符串
	//   - bool: 是否命中缓存
	//
	// 错误:
	//   - 无: 该方法不返回 error
	Get(ctx context.Context, key string) (string, bool)

	// Set 写入缓存值
	// 将字符串值写入缓存并设置 TTL，TTL 为 0 时表示永不过期。
	//
	// 参数:
	//   - ctx: 上下文
	//   - key: 缓存键
	//   - value: 要写入的字符串值
	//   - ttl: 生存时间，0 表示永不过期
	//
	// 返回:
	//   - error: 可能的错误
	//
	// 错误:
	//   - 底层存储写入失败
	Set(ctx context.Context, key string, value string, ttl time.Duration) error

	// Delete 删除缓存值
	// 删除指定 key 的缓存项，若 key 不存在应静默成功。
	//
	// 参数:
	//   - ctx: 上下文
	//   - key: 缓存键
	//
	// 返回:
	//   - error: 可能的错误
	//
	// 错误:
	//   - 底层存储删除失败
	Delete(ctx context.Context, key string) error
}

Cache 通用缓存接口 提供基础的字符串读写与删除能力，调用方可以用来缓存 access token 等短期数据。

type Client

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

func NewClient

func NewClient(cfg ClientConfig) (*Client, error)

func (*Client) Logger

func (c *Client) Logger() *slog.Logger

func (*Client) Request

func (c *Client) Request() *RequestBuilder

type ClientConfig

type ClientConfig struct {
	BaseURL       string
	HTTPClient    *http.Client
	TokenProvider AccessTokenProvider
	Logger        *slog.Logger
}

type MemoryCache

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

MemoryCache 内存缓存实现

func NewMemoryCache

func NewMemoryCache() *MemoryCache

NewMemoryCache 创建内存缓存实例

func (*MemoryCache) Cleanup

func (c *MemoryCache) Cleanup()

Cleanup 清理过期缓存项（可选，用于定期清理）

func (*MemoryCache) Delete

func (c *MemoryCache) Delete(ctx context.Context, key string) error

Delete 删除缓存

func (*MemoryCache) Get

func (c *MemoryCache) Get(ctx context.Context, key string) (string, bool)

Get 获取缓存值

func (*MemoryCache) Set

func (c *MemoryCache) Set(ctx context.Context, key string, value string, ttl time.Duration) error

Set 设置缓存值

type RawResponse

type RawResponse struct {
	StatusCode int
	Body       []byte
}

type RequestBuilder

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

func (*RequestBuilder) Body

func (b *RequestBuilder) Body(body any) *RequestBuilder

func (*RequestBuilder) Get

func (b *RequestBuilder) Get(ctx context.Context) (RawResponse, error)

func (*RequestBuilder) Path

func (b *RequestBuilder) Path(path string) *RequestBuilder

func (*RequestBuilder) Post

func (b *RequestBuilder) Post(ctx context.Context) (RawResponse, error)

func (*RequestBuilder) Query

func (b *RequestBuilder) Query(key, value string) *RequestBuilder

func (*RequestBuilder) QueryMap

func (b *RequestBuilder) QueryMap(query map[string]string) *RequestBuilder

func (*RequestBuilder) UploadField

func (b *RequestBuilder) UploadField(key, value string) *RequestBuilder

func (*RequestBuilder) UploadFile

func (b *RequestBuilder) UploadFile(field, fileName string, r io.Reader) *RequestBuilder

func (*RequestBuilder) WithoutToken

func (b *RequestBuilder) WithoutToken() *RequestBuilder

type TokenFetchResult

type TokenFetchResult struct {
	Token     string
	ExpiresIn int
}

type TokenFetcher

type TokenFetcher func(ctx context.Context) (TokenFetchResult, error)

type TokenManager

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

func NewTokenManager

func NewTokenManager(cfg TokenManagerConfig) (*TokenManager, error)

func (*TokenManager) GetToken

func (m *TokenManager) GetToken(ctx context.Context) (string, error)

func (*TokenManager) RefreshToken

func (m *TokenManager) RefreshToken(ctx context.Context) (string, error)

type TokenManagerConfig

type TokenManagerConfig struct {
	Cache               Cache
	CacheKey            string
	Fetcher             TokenFetcher
	Logger              *slog.Logger
	ExpireBufferSeconds int
}

type TypedRequest

type TypedRequest[T any] struct {
	// contains filtered or unexported fields
}

func NewTypedRequest

func NewTypedRequest[T any](client *Client) *TypedRequest[T]

func (*TypedRequest[T]) Body

func (r *TypedRequest[T]) Body(body any) *TypedRequest[T]

func (*TypedRequest[T]) Get

func (r *TypedRequest[T]) Get(ctx context.Context) (T, error)

func (*TypedRequest[T]) Path

func (r *TypedRequest[T]) Path(path string) *TypedRequest[T]

func (*TypedRequest[T]) Post

func (r *TypedRequest[T]) Post(ctx context.Context) (T, error)

func (*TypedRequest[T]) Query

func (r *TypedRequest[T]) Query(key, value string) *TypedRequest[T]

func (*TypedRequest[T]) QueryMap

func (r *TypedRequest[T]) QueryMap(query map[string]string) *TypedRequest[T]

func (*TypedRequest[T]) UploadField

func (r *TypedRequest[T]) UploadField(key, value string) *TypedRequest[T]

func (*TypedRequest[T]) UploadFile

func (r *TypedRequest[T]) UploadFile(field, fileName string, reader io.Reader) *TypedRequest[T]

func (*TypedRequest[T]) WithoutToken

func (r *TypedRequest[T]) WithoutToken() *TypedRequest[T]

type WechatError

type WechatError struct {
	ErrCode int    `json:"errcode"`
	ErrMsg  string `json:"errmsg"`
}

WechatError 微信业务错误（errcode/errmsg）。

func NewWechatError

func NewWechatError(code int, msg string) *WechatError

func (*WechatError) Error

func (e *WechatError) Error() string