wxpusher 实现个人微信收消息推送提醒

这是一份使用 wxpusher Python 库（pip install -U wxpusher）进行操作的简单实用教程。这个库封装了对 WxPusher API 的直接调用，使得在 Python 中发送通知更加便捷。

前提条件

1. WxPusher 账户与应用:
   • 已在 WxPusher 官网 注册并登录。
   • 已创建一个 WxPusher 应用，并获取了该应用的 appToken。请务必保管好你的 appToken！
2. 获取接收者信息:
   • UID: 让接收者（可以是自己）扫描你的应用二维码关注，然后在 WxPusher 网站 “我的” -> “我的 UID” 处获取，或在应用后台 “用户管理” 查看。
   • (可选) Topic ID: 如需按主题发送，需在后台创建主题获取 Topic ID，并让用户扫描主题二维码订阅。
3. 安装 wxpusher 库:

   pip install -U wxpusher
   

   (-U 确保安装最新版本)

教程内容

1. 引入库和初始化

在使用库之前，你需要导入 WxPusher 类，并使用你的 appToken 来实例化它。

from wxpusher import WxPusher

# 强烈建议：不要将 AppToken 直接硬编码在代码中
# 可以考虑使用环境变量、配置文件等方式管理
# 例如:
# import os
# APP_TOKEN = os.environ.get("WXPUSHER_APP_TOKEN", "AT_YourAppTokenIfNotSet") # 从环境变量读取
APP_TOKEN = "AT_xxxxxxxxx"  # <--- 在这里替换成你真实的 AppToken

# 初始化 WxPusher 实例
# WxPusher 构造函数接受 token 参数
try:
    pusher = WxPusher(token=APP_TOKEN)
    print("WxPusher 初始化成功!")
except Exception as e:
    print(f"WxPusher 初始化失败: {e}")
    # 在实际应用中，初始化失败应该阻止后续操作
    exit() # 或者根据你的错误处理逻辑进行操作

重要提示: appToken 是敏感信息，避免直接写入代码并提交到公共仓库。优先使用环境变量或配置文件。

2. 发送消息 (send_message)

这是最核心的功能。send_message 方法封装了发送消息的 API 调用。

主要参数:

• content (str, 必填): 消息正文。
• uids (list[str], 可选): 接收消息用户的 UID 列表。
• topic_ids (list[int], 可选): 接收消息主题的 Topic ID 列表。
  • 注意: uids 和 topic_ids 必须至少提供一个。
• content_type (int, 可选, 默认 WxPusher.CONTENT_TYPE_MD): 内容类型。库提供了常量：
  • WxPusher.CONTENT_TYPE_TEXT (1): 纯文本
  • WxPusher.CONTENT_TYPE_HTML (2): HTML
  • WxPusher.CONTENT_TYPE_MD (3): Markdown (推荐)
• summary (str, 可选): 消息摘要，显示在微信通知列表。
• url (str, 可选): 点击消息卡片后跳转的 URL。

返回值:

• 一个字典，包含了 WxPusher API 的原始响应结果。你需要检查其中的 code 字段（1000 表示成功）来判断发送状态。

示例 2.1: 发送 Markdown 消息给指定用户 (UID)

# --- 准备要发送的数据 ---
message = """
### :bell: 新订单提醒

一个新订单刚刚创建！

- **订单号:** ORD123456789
- **金额:** <font color='red'>￥199.00</font>
- **客户:** 测试用户 (@UID_xxxxxxxxxxxxxxx)  *(Markdown内@无效, 仅作文本说明)*

请尽快处理。

[查看订单详情](https://your-order-system.com/orders/123456789)
"""
# 替换成你要发送的目标用户的 UID 列表
target_uids = ["UID_xxxxxxxxxxxxxxx", "UID_yyyyyyyyyyyyyyy"]
# 如果只想发给自己测试：
# target_uids = ["UID_你的UID"] # <--- 替换成你自己的 UID

try:
    # --- 调用 send_message 发送 ---
    response = pusher.send_message(
        content=message,
        uids=target_uids,
        content_type=WxPusher.CONTENT_TYPE_MD, # 使用 Markdown
        summary="收到一个新订单！" # 消息摘要
    )

    # --- 检查发送结果 ---
    print("API 响应:", response)
    if response.get('code') == 1000:
        print("消息发送成功！")
        # 可以进一步检查 data 字段获取每个 uid 的发送状态
        for item in response.get("data", []):
             print(f"  -> UID: {item.get('uid')}, 状态: {item.get('status')}")
    else:
        print(f"消息发送失败: Code={response.get('code')}, Msg={response.get('msg')}")

except Exception as e:
    print(f"发送过程中出现错误: {e}")

示例 2.2: 发送纯文本消息给指定主题 (Topic ID)

# --- 准备数据 ---
plain_text_message = "【服务器通知】\n例行维护将于 20 分钟后开始，预计持续 30 分钟。\n请保存好您的工作。"
# 替换成你要发送的目标主题 ID 列表 (整数)
target_topic_ids = [101, 202] # <--- 替换成你的 Topic ID

try:
    # --- 调用 send_message ---
    response = pusher.send_message(
        content=plain_text_message,
        topic_ids=target_topic_ids,
        content_type=WxPusher.CONTENT_TYPE_TEXT, # 使用纯文本
        summary="服务器维护通知"
    )

    # --- 检查结果 ---
    print("API 响应:", response)
    if response.get('code') == 1000:
        print("消息成功发送到指定主题！")
    else:
        print(f"消息发送失败: Code={response.get('code')}, Msg={response.get('msg')}")

except Exception as e:
    print(f"发送过程中出现错误: {e}")

3. 查询消息发送状态 (query_status) (较少直接使用)

如果你需要后续跟踪某条消息的具体投递状态，可以使用 query_status 方法。你需要先从 send_message 的成功响应中获取 message_id。

# 假设你之前发送成功，并从响应中获取了 message_id
# message_id = response.get('data', [{}])[0].get('messageId') # 需要根据实际响应结构获取

message_id_to_query = 12345678 # <--- 替换成你要查询的消息 ID

if message_id_to_query:
    try:
        status_response = pusher.query_status(message_id=message_id_to_query)
        print(f"查询消息 {message_id_to_query} 状态响应:", status_response)
        if status_response.get('code') == 1000:
            print("查询成功:")
            # status_response['data'] 会包含该消息的详细状态信息
            for record in status_response.get('data', []):
                print(f"  - 用户 UID: {record.get('uid')}, 状态码: {record.get('status')}") # 状态码含义需查阅 WxPusher 文档
        else:
            print(f"查询失败: Code={status_response.get('code')}, Msg={status_response.get('msg')}")
    except Exception as e:
        print(f"查询状态时出错: {e}")
else:
    print("没有有效的 message_id 可供查询。")

4. 获取创建用户的二维码 (create_qrcode) (辅助功能)

这个方法可以帮助你获取一个临时的、带参数的关注二维码，通常用于特定场景，比如动态邀请用户关注并传递一些信息。对于简单推送，直接使用应用后台的固定二维码更常见。

try:
    # 创建一个有效期 300 秒，附加参数为 "invite_code=abc123" 的二维码
    qrcode_response = pusher.create_qrcode(valid_second=300, extra="invite_code=abc123")
    print("创建二维码响应:", qrcode_response)

    if qrcode_response.get('code') == 1000:
        print("二维码创建成功！")
        print(f"  二维码图片 URL: {qrcode_response.get('data', {}).get('url')}")
        print(f"  将在 {qrcode_response.get('data', {}).get('expires')} 秒后过期")
    else:
        print(f"二维码创建失败: Code={qrcode_response.get('code')}, Msg={qrcode_response.get('msg')}")

except Exception as e:
    print(f"创建二维码时出错: {e}")

实用建议与最佳实践

1. Token 安全: 再次强调，使用环境变量或配置文件管理 appToken。
2. 错误处理: 对 send_message 的调用进行 try...except 包裹，并检查返回的 code。对于网络错误、API 限制、无效参数等情况进行处理。
3. 日志记录: 在实际应用中，记录发送请求的参数和 WxPusher 的响应，方便排查问题。
4. 封装: 如果你在项目的多个地方需要发送通知，可以创建一个自己的发送函数，封装 WxPusher 的调用和通用的错误处理逻辑。
5. 内容格式: Markdown (CONTENT_TYPE_MD) 通常是最好的选择，因为它支持链接、加粗、颜色等，可读性强。
6. UID 与 Topic ID: 根据你的场景选择合适的发送对象。给特定人发通知用 UID，广播或分组通知用 Topic ID。
7. 官方文档: wxpusher 库是基于官方 API 的封装。如果遇到库未覆盖的功能或需要了解 API 的详细限制（如频率），请查阅 WxPusher 官方文档。

这个教程覆盖了 wxpusher 库最核心和常用的功能。希望它能帮助你快速上手，在你的 Python 项目中集成微信消息推送！