Python FastAPI开发微信公众号全流程实战

一、用FastAPI搭建开发环境与项目初始化

本文将带你用Python异步框架完成公众号从接入校验到线上部署的全流程。示例选用FastAPI（Python 3.10+）配合Uvicorn ASGI服务器，其原生异步支持能够高效处理微信服务器发起的并发回调，尤其适合频繁请求微信接口的场景。

创建虚拟环境与安装依赖

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install fastapi uvicorn httpx python-dotenv

生成requirements.txt：

fastapi==0.111.0
uvicorn[standard]==0.30.1
httpx==0.27.0
python-dotenv==1.0.1

目录结构建议

• config/：存放AppID、AppSecret、Token等，通过.env文件注入，切勿提交到版本库；
• handlers/：消息回调、网页授权等路由处理器；
• services/：封装微信接口交互逻辑（获取token、创建菜单等）；
• utils/：签名校验、XML解析、缓存工具。

二、微信公众号接入验证与签名校验

在公众号后台配置服务器URL、Token与消息加密方式后，微信会发来GET请求，携带signature、timestamp、nonce、echostr四个参数。校验规则如下：

1. 将Token、timestamp、nonce按字典序排序；
2. 拼接为字符串；
3. 使用SHA1哈希计算；
4. 比对结果与signature，一致则返回echostr。

FastAPI路由示例：

import hashlib
from fastapi import FastAPI, Request
app = FastAPI()
TOKEN = "your_token"
@app.get("/wechat")
async def verify(request: Request):
    params = await request.query_params()
    sig = params.get("signature")
    timestamp = params.get("timestamp")
    nonce = params.get("nonce")
    echostr = params.get("echostr")
    tmp_list = sorted([TOKEN, timestamp, nonce])
    raw = "".join(tmp_list)
    calc = hashlib.sha1(raw.encode()).hexdigest()
    if calc == sig:
        return echostr
    return "verify failed"

注意：GET用于校验，POST用于消息回调；若启用加密模式，还需在此阶段解密验证。

三、接收事件推送与自动回复处理

微信推送事件包括关注、取消关注、菜单点击、扫码等，消息类型有文本、图片、语音等。服务端根据MsgType和Event字段区分处理。

XML回复模板（关注事件）

<xml>
  <ToUserName><![CDATA[用户OpenID]]></ToUserName>
  <FromUserName><![CDATA[公众号原始ID]]></FromUserName>
  <CreateTime>1700000000</CreateTime>
  <MsgType><![CDATA[text]]></MsgType>
  <Content><![CDATA[欢迎关注！]]></Content>
</xml>

分层处理伪代码

def parse_xml(body: str) -> dict:
    """解析微信XML，返回字典"""
    ...
def handle_message(msg: dict) -> str:
    if msg["MsgType"] == "event" and msg["Event"] == "subscribe":
        return build_welcome_xml(msg)
    elif msg["MsgType"] == "text":
        return build_text_reply(msg)
    ...

解析时注意：XML采用UTF-8编码需显式指定；特殊字符需转义；To/FromUserName不可颠倒。

四、定时刷新access_token与jsapi_ticket

access_token有效期7200秒，需提前刷新。建议提前100–300秒刷新，以应对接口响应延迟与网络抖动。获取失败时应重试3次并记录错误码（如40001表示appsecret错误）。

import httpx, asyncio
async def get_access_token(app_id: str, secret: str, cache: dict):
    if cache.get("token") and cache["expires_at"] > time.time() + 300:
        return cache["token"]
    url = f"https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid={app_id}&secret={secret}"
    async with httpx.AsyncClient() as client:
        r = await client.get(url)
        data = r.json()
        if data.get("errcode"):
            raise Exception(f"获取token失败: {data}")
        cache["token"] = data["access_token"]
        cache["expires_at"] = time.time() + data["expires_in"] - 200
        return data["access_token"]

多实例部署时使用Redis等共享缓存+分布式锁控制并发刷新。凭证不要输出到日志，存储时启用访问控制。

安全提示：若AppSecret泄露，应立即在公众号后台重置AppSecret，并同步更新所有环境配置。

五、自定义菜单创建与配置

菜单可通过后台手动配置，也可通过接口动态创建（便于版本化管理）。接口需携带access_token，菜单类型包括点击推事件、跳转网页、扫码推事件等。

调用频率有限制，建议将菜单结构沉淀为代码常量，仅在变更时调用更新接口。点击菜单后微信推送Event=CLICK事件，根据菜单标识执行对应逻辑。

六、网页授权获取用户openid与JS-SDK签名

菜单配置为跳转网页类型时，用户点击后进入授权流程，可获取用户openid（仅对当前公众号有效）。

JS-SDK签名步骤

1. 用access_token获取jsapi_ticket；
2. 拼接字符串：jsapi_ticket=xxx&noncestr=xxx&timestamp=xxx&url=xxx；
3. SHA1哈希得到signature；
4. 前端注入appId、timestamp、nonceStr、signature完成配置。

注意：URL必须完整且不含#后内容；单页应用路由变化时需重新签名。建议服务端统一提供签名接口。

七、测试验证与服务器部署

部署前检查清单：

• 域名已备案且支持HTTPS（微信强制要求）；
• 后台配置与代码一致；
• 生产证书、密钥已注入；
• HTTPS证书到期前需提前续期，否则回调将全部失败。

使用nginx反向代理，基础配置：

server {
    listen 443 ssl;
    server_name your-domain.com;
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_read_timeout 30s;
    }
}

配合systemd或supervisor管理进程，保证高可用。上线后验证接入校验、消息收发、菜单点击、JS-SDK等环节，逐步关闭调试日志并收紧接口暴露。通过以上步骤，你即可完成从本地开发到线上稳定运行的完整闭环。