338 lines
10 KiB
Python
338 lines
10 KiB
Python
|
"""微信 SDK 最小集成层（T8.2）
|
|||
|
|
|
|||
|
|
目标：不依赖第三方微信 SDK，仅用标准库封装两类常用能力：
|
|||
|
|
- 订阅消息推送（/cgi-bin/message/subscribe/send）
|
|||
|
|
- 客服文本消息（/cgi-bin/message/custom/send）
|
|||
|
|
|
|||
|
|
设计取向：
|
|||
|
|
- access_token 自动缓存与过期刷新
|
|||
|
|
- 纯标准库 HTTP 传输，便于单测注入 fake transport
|
|||
|
|
- 上游 errcode / HTTP 状态统一包装为结构化异常
|
|||
|
|
"""
|
|||
|
|
|
|||
|
|
from __future__ import annotations
|
|||
|
|
|
|||
|
|
import json
|
|||
|
|
import os
|
|||
|
|
import time
|
|||
|
|
from collections.abc import Callable
|
|||
|
|
from dataclasses import dataclass
|
|||
|
|
from typing import Any, Optional, Protocol
|
|||
|
|
from urllib import error, parse, request
|
|||
|
|
|
|||
|
|
|
|||
|
|
DEFAULT_API_BASE = "https://api.weixin.qq.com"
|
|||
|
|
DEFAULT_TIMEOUT_SECONDS = 5.0
|
|||
|
|
DEFAULT_TOKEN_REFRESH_SKEW_SECONDS = 60.0
|
|||
|
|
|
|||
|
|
|
|||
|
|
class WeChatConfigError(ValueError):
|
|||
|
|
"""微信配置缺失或非法。"""
|
|||
|
|
|
|||
|
|
|
|||
|
|
class WeChatAPIError(RuntimeError):
|
|||
|
|
"""微信接口返回错误。"""
|
|||
|
|
|
|||
|
|
def __init__(
|
|||
|
|
self,
|
|||
|
|
message: str,
|
|||
|
|
*,
|
|||
|
|
errcode: Optional[int] = None,
|
|||
|
|
errmsg: Optional[str] = None,
|
|||
|
|
http_status: Optional[int] = None,
|
|||
|
|
endpoint: Optional[str] = None,
|
|||
|
|
) -> None:
|
|||
|
|
super().__init__(message)
|
|||
|
|
self.errcode = errcode
|
|||
|
|
self.errmsg = errmsg
|
|||
|
|
self.http_status = http_status
|
|||
|
|
self.endpoint = endpoint
|
|||
|
|
|
|||
|
|
|
|||
|
|
@dataclass(frozen=True)
|
|||
|
|
class WeChatConfig:
|
|||
|
|
app_id: str
|
|||
|
|
app_secret: str
|
|||
|
|
api_base: str = DEFAULT_API_BASE
|
|||
|
|
timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS
|
|||
|
|
token_refresh_skew_seconds: float = DEFAULT_TOKEN_REFRESH_SKEW_SECONDS
|
|||
|
|
|
|||
|
|
def __post_init__(self) -> None:
|
|||
|
|
if not self.app_id:
|
|||
|
|
raise WeChatConfigError("GAOKAO_WECHAT_APP_ID 未设置")
|
|||
|
|
if not self.app_secret:
|
|||
|
|
raise WeChatConfigError("GAOKAO_WECHAT_APP_SECRET 未设置")
|
|||
|
|
if self.timeout_seconds <= 0:
|
|||
|
|
raise WeChatConfigError("timeout_seconds 必须大于 0")
|
|||
|
|
if self.token_refresh_skew_seconds < 0:
|
|||
|
|
raise WeChatConfigError("token_refresh_skew_seconds 不能为负")
|
|||
|
|
|
|||
|
|
|
|||
|
|
@dataclass
|
|||
|
|
class AccessToken:
|
|||
|
|
token: str
|
|||
|
|
expires_at: float
|
|||
|
|
|
|||
|
|
def valid(self, now: float, skew_seconds: float) -> bool:
|
|||
|
|
return bool(self.token) and now < (self.expires_at - skew_seconds)
|
|||
|
|
|
|||
|
|
|
|||
|
|
class Transport(Protocol):
|
|||
|
|
def request(
|
|||
|
|
self,
|
|||
|
|
method: str,
|
|||
|
|
url: str,
|
|||
|
|
*,
|
|||
|
|
headers: Optional[dict[str, str]] = None,
|
|||
|
|
body: Optional[bytes] = None,
|
|||
|
|
timeout: float = DEFAULT_TIMEOUT_SECONDS,
|
|||
|
|
) -> tuple[int, bytes]: ...
|
|||
|
|
|
|||
|
|
|
|||
|
|
class UrllibTransport:
|
|||
|
|
"""基于 urllib 的标准库 HTTP 传输实现。"""
|
|||
|
|
|
|||
|
|
def request(
|
|||
|
|
self,
|
|||
|
|
method: str,
|
|||
|
|
url: str,
|
|||
|
|
*,
|
|||
|
|
headers: Optional[dict[str, str]] = None,
|
|||
|
|
body: Optional[bytes] = None,
|
|||
|
|
timeout: float = DEFAULT_TIMEOUT_SECONDS,
|
|||
|
|
) -> tuple[int, bytes]:
|
|||
|
|
req = request.Request(url=url, method=method.upper(), data=body)
|
|||
|
|
for key, value in (headers or {}).items():
|
|||
|
|
req.add_header(key, value)
|
|||
|
|
try:
|
|||
|
|
with request.urlopen(req, timeout=timeout) as resp:
|
|||
|
|
return int(resp.status), resp.read()
|
|||
|
|
except error.HTTPError as e:
|
|||
|
|
return int(e.code), e.read()
|
|||
|
|
|
|||
|
|
|
|||
|
|
class WeChatClient:
|
|||
|
|
"""微信开放接口最小客户端。"""
|
|||
|
|
|
|||
|
|
def __init__(
|
|||
|
|
self,
|
|||
|
|
*,
|
|||
|
|
config: WeChatConfig,
|
|||
|
|
transport: Optional[Transport] = None,
|
|||
|
|
clock: Optional[Callable[[], float]] = None,
|
|||
|
|
) -> None:
|
|||
|
|
self._config = config
|
|||
|
|
self._transport = transport or UrllibTransport()
|
|||
|
|
self._clock = clock or time.time
|
|||
|
|
self._access_token: Optional[AccessToken] = None
|
|||
|
|
|
|||
|
|
@classmethod
|
|||
|
|
def from_env(
|
|||
|
|
cls,
|
|||
|
|
*,
|
|||
|
|
transport: Optional[Transport] = None,
|
|||
|
|
clock: Optional[Callable[[], float]] = None,
|
|||
|
|
) -> "WeChatClient":
|
|||
|
|
return cls(
|
|||
|
|
config=WeChatConfig(
|
|||
|
|
app_id=os.environ.get("GAOKAO_WECHAT_APP_ID", ""),
|
|||
|
|
app_secret=os.environ.get("GAOKAO_WECHAT_APP_SECRET", ""),
|
|||
|
|
api_base=os.environ.get("GAOKAO_WECHAT_API_BASE", DEFAULT_API_BASE),
|
|||
|
|
timeout_seconds=float(
|
|||
|
|
os.environ.get(
|
|||
|
|
"GAOKAO_WECHAT_TIMEOUT_SECONDS", DEFAULT_TIMEOUT_SECONDS
|
|||
|
|
)
|
|||
|
|
),
|
|||
|
|
token_refresh_skew_seconds=float(
|
|||
|
|
os.environ.get(
|
|||
|
|
"GAOKAO_WECHAT_TOKEN_REFRESH_SKEW_SECONDS",
|
|||
|
|
DEFAULT_TOKEN_REFRESH_SKEW_SECONDS,
|
|||
|
|
)
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
transport=transport,
|
|||
|
|
clock=clock,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
def _now(self) -> float:
|
|||
|
|
return float(self._clock())
|
|||
|
|
|
|||
|
|
def _api_url(self, path: str) -> str:
|
|||
|
|
base = self._config.api_base.rstrip("/")
|
|||
|
|
return f"{base}/{path.lstrip('/')}"
|
|||
|
|
|
|||
|
|
def _request_json(
|
|||
|
|
self,
|
|||
|
|
method: str,
|
|||
|
|
path: str,
|
|||
|
|
*,
|
|||
|
|
query: Optional[dict[str, Any]] = None,
|
|||
|
|
payload: Optional[dict[str, Any]] = None,
|
|||
|
|
) -> dict[str, Any]:
|
|||
|
|
url = self._api_url(path)
|
|||
|
|
if query:
|
|||
|
|
url = f"{url}?{parse.urlencode(query)}"
|
|||
|
|
body = None
|
|||
|
|
headers: dict[str, str] = {}
|
|||
|
|
if payload is not None:
|
|||
|
|
body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
|
|||
|
|
headers["Content-Type"] = "application/json; charset=utf-8"
|
|||
|
|
try:
|
|||
|
|
status, raw = self._transport.request(
|
|||
|
|
method.upper(),
|
|||
|
|
url,
|
|||
|
|
headers=headers,
|
|||
|
|
body=body,
|
|||
|
|
timeout=self._config.timeout_seconds,
|
|||
|
|
)
|
|||
|
|
except Exception as e:
|
|||
|
|
raise WeChatAPIError(
|
|||
|
|
f"微信接口 transport_error: {type(e).__name__}: {e}",
|
|||
|
|
endpoint=path,
|
|||
|
|
) from e
|
|||
|
|
try:
|
|||
|
|
data = json.loads(raw.decode("utf-8") or "{}")
|
|||
|
|
except Exception as e: # pragma: no cover - defensive
|
|||
|
|
raise WeChatAPIError(
|
|||
|
|
f"微信接口返回非 JSON: {e}", http_status=status, endpoint=path
|
|||
|
|
) from e
|
|||
|
|
if status >= 400:
|
|||
|
|
raise WeChatAPIError(
|
|||
|
|
f"微信接口 HTTP {status}",
|
|||
|
|
http_status=status,
|
|||
|
|
endpoint=path,
|
|||
|
|
errmsg=data.get("errmsg") if isinstance(data, dict) else None,
|
|||
|
|
errcode=data.get("errcode") if isinstance(data, dict) else None,
|
|||
|
|
)
|
|||
|
|
if not isinstance(data, dict):
|
|||
|
|
raise WeChatAPIError(
|
|||
|
|
"微信接口返回结构非法",
|
|||
|
|
http_status=status,
|
|||
|
|
endpoint=path,
|
|||
|
|
)
|
|||
|
|
errcode = data.get("errcode", 0)
|
|||
|
|
if errcode not in (0, None):
|
|||
|
|
raise WeChatAPIError(
|
|||
|
|
f"微信接口错误: {errcode} {data.get('errmsg', '')}".strip(),
|
|||
|
|
errcode=int(errcode),
|
|||
|
|
errmsg=str(data.get("errmsg", "")),
|
|||
|
|
http_status=status,
|
|||
|
|
endpoint=path,
|
|||
|
|
)
|
|||
|
|
return data
|
|||
|
|
|
|||
|
|
def _get_access_token(self, *, force_refresh: bool = False) -> str:
|
|||
|
|
now = self._now()
|
|||
|
|
if (
|
|||
|
|
not force_refresh
|
|||
|
|
and self._access_token is not None
|
|||
|
|
and self._access_token.valid(now, self._config.token_refresh_skew_seconds)
|
|||
|
|
):
|
|||
|
|
return self._access_token.token
|
|||
|
|
|
|||
|
|
data = self._request_json(
|
|||
|
|
"GET",
|
|||
|
|
"/cgi-bin/token",
|
|||
|
|
query={
|
|||
|
|
"grant_type": "client_credential",
|
|||
|
|
"appid": self._config.app_id,
|
|||
|
|
"secret": self._config.app_secret,
|
|||
|
|
},
|
|||
|
|
)
|
|||
|
|
token = str(data.get("access_token", ""))
|
|||
|
|
if not token:
|
|||
|
|
raise WeChatAPIError(
|
|||
|
|
"微信接口未返回 access_token",
|
|||
|
|
http_status=200,
|
|||
|
|
endpoint="/cgi-bin/token",
|
|||
|
|
)
|
|||
|
|
expires_in = float(data.get("expires_in", 7200))
|
|||
|
|
self._access_token = AccessToken(token=token, expires_at=now + expires_in)
|
|||
|
|
return token
|
|||
|
|
|
|||
|
|
@staticmethod
|
|||
|
|
def _normalize_msg_data(data: dict[str, Any]) -> dict[str, dict[str, Any]]:
|
|||
|
|
normalized: dict[str, dict[str, Any]] = {}
|
|||
|
|
for key, value in data.items():
|
|||
|
|
if isinstance(value, dict) and "value" in value:
|
|||
|
|
normalized[key] = {"value": value["value"]}
|
|||
|
|
else:
|
|||
|
|
normalized[key] = {"value": value}
|
|||
|
|
return normalized
|
|||
|
|
|
|||
|
|
def send_subscribe_message(
|
|||
|
|
self,
|
|||
|
|
*,
|
|||
|
|
openid: str,
|
|||
|
|
template_id: str,
|
|||
|
|
data: dict[str, Any],
|
|||
|
|
page: Optional[str] = None,
|
|||
|
|
miniprogram_state: Optional[str] = None,
|
|||
|
|
lang: Optional[str] = None,
|
|||
|
|
) -> dict[str, Any]:
|
|||
|
|
token = self._get_access_token()
|
|||
|
|
payload: dict[str, Any] = {
|
|||
|
|
"touser": openid,
|
|||
|
|
"template_id": template_id,
|
|||
|
|
"data": self._normalize_msg_data(data),
|
|||
|
|
}
|
|||
|
|
if page:
|
|||
|
|
payload["page"] = page
|
|||
|
|
if miniprogram_state:
|
|||
|
|
payload["miniprogram_state"] = miniprogram_state
|
|||
|
|
if lang:
|
|||
|
|
payload["lang"] = lang
|
|||
|
|
return self._request_json(
|
|||
|
|
"POST",
|
|||
|
|
"/cgi-bin/message/subscribe/send",
|
|||
|
|
query={"access_token": token},
|
|||
|
|
payload=payload,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
def send_custom_message(
|
|||
|
|
self,
|
|||
|
|
*,
|
|||
|
|
openid: str,
|
|||
|
|
msgtype: str,
|
|||
|
|
payload: dict[str, Any],
|
|||
|
|
kf_account: Optional[str] = None,
|
|||
|
|
) -> dict[str, Any]:
|
|||
|
|
token = self._get_access_token()
|
|||
|
|
body: dict[str, Any] = {"touser": openid, "msgtype": msgtype, msgtype: payload}
|
|||
|
|
if kf_account:
|
|||
|
|
body["customservice"] = {"kf_account": kf_account}
|
|||
|
|
return self._request_json(
|
|||
|
|
"POST",
|
|||
|
|
"/cgi-bin/message/custom/send",
|
|||
|
|
query={"access_token": token},
|
|||
|
|
payload=body,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
def send_custom_text(
|
|||
|
|
self,
|
|||
|
|
*,
|
|||
|
|
openid: str,
|
|||
|
|
content: str,
|
|||
|
|
kf_account: Optional[str] = None,
|
|||
|
|
) -> dict[str, Any]:
|
|||
|
|
return self.send_custom_message(
|
|||
|
|
openid=openid,
|
|||
|
|
msgtype="text",
|
|||
|
|
payload={"content": content},
|
|||
|
|
kf_account=kf_account,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
|
|||
|
|
__all__ = [
|
|||
|
|
"AccessToken",
|
|||
|
|
"DEFAULT_API_BASE",
|
|||
|
|
"DEFAULT_TIMEOUT_SECONDS",
|
|||
|
|
"DEFAULT_TOKEN_REFRESH_SKEW_SECONDS",
|
|||
|
|
"Transport",
|
|||
|
|
"UrllibTransport",
|
|||
|
|
"WeChatAPIError",
|
|||
|
|
"WeChatClient",
|
|||
|
|
"WeChatConfig",
|
|||
|
|
"WeChatConfigError",
|
|||
|
|
]
|