简介面向需要在业务系统中接入微信公众号消息推送的C/C开发者这份资源以libcurl为基础实现了向粉丝微信账号主动发送报警或通知消息的功能可直接借鉴其接口封装与HTTP请求流程。压缩包共106个文件包体约3.59MB除85个.h头文件外还提供lib、dll、cpp源文件及Visual Studio工程文件sln/vcxproj覆盖调用声明、静态/动态库及示例代码便于在Windows或Linux环境下备齐依赖并编译运行。包内包含关键源文件与辅助脚本展示消息POST逻辑与运行方式并附带SSL和Libcurl相关动态库有助于开发者理解HTTPS通信和参数构造细节。通过这些文件可以清楚看到Libcurl的初始化、回调设置、消息体封装以及微信接口的响应解析实现从普通报警到微信触达的完整链路。资源目前已有319人学习适合具备基础C网络编程经验、希望快速落地微信告警推送的研发人员参考。1. 微信公众号推送消息为什么用 libcurl做后台服务的人迟早会撞上这样一个需求服务器告警、订单通知、活动进度都要第一时间推到用户微信上。微信公众号推送消息的标准路径是调用微信的模板消息接口本质就是一个带 access_token 的 HTTPS 请求。很多开发者第一反应是去找第三方 SDK但实际项目里我越来越倾向直接用 libcurl 裸调因为它够轻、够稳不引入额外依赖出问题也好查。libcurl 是老牌 HTTP 客户端库支持 HTTPS、POST、自定义 Header配合 cJSON 处理返回体微信推送的整个链路在纯 C 环境里不超过 200 行代码。这篇文章就把整个接入过程拆开讲从 token 获取到模板消息发送再到那些没人提醒你的坑全部用可复现的代码说话。2. 接入前先想清楚access_token 的获取与缓存策略2.1 获取 access_token 的接口与参数微信公众平台所有接口都要求先拿到 access_token这是一个全局唯一凭证有效期为 7200 秒。获取它的接口是一个标准的 GET 请求地址是https://api.weixin.qq.com/cgi-bin/token?grant_typeclient_credentialappidAPPIDsecretAPPSECRET其中 APPID 和 APPSECRET 在公众平台的「基本配置」里可以看到。用 libcurl 发送这个请求很简单下面这段代码演示了完整流程#include stdio.h #include curl/curl.h #include string.h #include stdlib.h // 回调函数把响应数据拼到字符串里 size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata) { size_t total size * nmemb; char **buf (char **)userdata; char *tmp realloc(*buf, strlen(*buf) total 1); if (!tmp) return 0; *buf tmp; strncat(*buf, ptr, total); return total; } int get_access_token(const char *appid, const char *secret, char *out_token, size_t out_size) { char url[512]; snprintf(url, sizeof(url), https://api.weixin.qq.com/cgi-bin/token?grant_typeclient_credentialappid%ssecret%s, appid, secret); CURL *curl curl_easy_init(); if (!curl) return -1; char *response malloc(1); response[0] \0; curl_easy_setopt(curl, CURLOPT_URL, url); curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_callback); curl_easy_setopt(curl, CURLOPT_WRITEDATA, response); curl_easy_setopt(curl, CURLOPT_TIMEOUT, 10L); CURLcode res curl_easy_perform(curl); curl_easy_cleanup(curl); // 这里用 cJSON 解析简化起见直接演示字符串匹配 char *token_pos strstr(response, \access_token\:\); if (token_pos) { token_pos strlen(\access_token\:\); char *end strchr(token_pos, ); if (end (size_t)(end - token_pos) out_size) { memcpy(out_token, token_pos, end - token_pos); out_token[end - token_pos] \0; free(response); return 0; } } free(response); return -1; }这段代码的逻辑很直白构造 URL 后交给 libcurl用 write_callback 把响应内容累积到一个动态字符串里。之所以要回调是因为 libcurl 默认把响应体丢到 stdout而我们是要拿 token 的。这里的 CURLOPT_TIMEOUT 设成 10 秒避免网络异常时卡死业务线程。注意我在代码里刻意没用第三方 JSON 库解析是因为这个场景只取一个 token 字段字符串匹配足够。但如果你的项目里已经用了 cJSON那就改用 cJSON 解析更保险。2.2 缓存 access_token有效期 7200 秒不能每次现取微信官方对 token 接口有每天 2000 次的调用上限而且每次调用都会使旧的 token 失效。如果你每发一条消息就去取一次 token高峰期很快被打出 45009 限流错误。所以实际工程里必须做缓存。常见做法是存到本地文件或共享内存里带时间戳判断是否过期。我一般会让 token 提前 5 分钟过期也就是把 7200 秒当成 7140 秒用防止在临界时刻微信端已经失效但本地还没到期的尴尬。// 简化版缓存逻辑读文件判断时间戳 int get_cached_token(const char *appid, char *out_token, size_t size) { FILE *fp fopen(token_cache.dat, r); if (!fp) return -1; char cached_appid[128] {0}; char token[512] {0}; time_t saved_time 0; fscanf(fp, %s %s %ld, cached_appid, token, saved_time); fclose(fp); if (strcmp(cached_appid, appid) ! 0) return -1; if (time(NULL) - saved_time 7140) return -1; // 提前5分钟过期 strncpy(out_token, token, size); return 0; }写入缓存时把 appid、token、时间戳三者一起存避免多账号切换时读到别人的 token。这里的 7140 是我在实际项目里调出来的值官方 7200 秒提前 300 秒基本能躲开边界问题。如果你跑的进程是多实例部署建议用 Redis 存 token把 appid 当 keytoken 当 value配合过期时间比文件锁省心。3. 用 libcurl 发送模板消息POST 请求与 JSON 构造3.1 模板消息接口和必要参数拿到 token 之后推送消息就走这个接口https://api.weixin.qq.com/cgi-bin/message/template/send?access_tokenACCESS_TOKEN请求方法是 POSTbody 是 JSON包含这几个字段字段必填说明touser是接收用户的 openidtemplate_id是模板 ID在公众平台「模板消息」里申请url否点击消息后跳转的链接data是模板中的变量值键值对形式举个例子假设模板内容是「您的订单 {{order_id.DATA}} 已发货」那么 data 就写成{ touser: oXXXXXX, template_id: XXXXXX, url: https://example.com/order, data: { order_id: { value: JD123456 } } }这里有一个最容易踩的坑data 里的键名必须和模板里的变量名完全一致多一个空格都不行。后面避坑章会展开讲。3.2 libcurl 发送 POST 的完整代码发送模板消息的 libcurl 代码比获取 token 多两步设置 POST 方法和设置 Content-Type 头。下面这段可以直接抄int send_template_message(const char *access_token, const char *json_body, char *out_resp, size_t resp_size) { char url[512]; snprintf(url, sizeof(url), https://api.weixin.qq.com/cgi-bin/message/template/send?access_token%s, access_token); CURL *curl curl_easy_init(); if (!curl) return -1; struct curl_slist *headers NULL; headers curl_slist_append(headers, Content-Type: application/json); char *response malloc(1); response[0] \0; curl_easy_setopt(curl, CURLOPT_URL, url); curl_easy_setopt(curl, CURLOPT_POST, 1L); curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json_body); curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_callback); curl_easy_setopt(curl, CURLOPT_WRITEDATA, response); curl_easy_setopt(curl, CURLOPT_TIMEOUT, 10L); CURLcode res curl_easy_perform(curl); if (res ! CURLE_OK) { snprintf(out_resp, resp_size, curl error: %s, curl_easy_strerror(res)); free(response); curl_slist_free_all(headers); curl_easy_cleanup(curl); return -1; } strncpy(out_resp, response, resp_size - 1); out_resp[resp_size - 1] \0; free(response); curl_slist_free_all(headers); curl_easy_cleanup(curl); return 0; }几个关键点说下CURLOPT_POST设为 1Llibcurl 才会用 POST 方法。如果不设置默认是 GET。CURLOPT_POSTFIELDS直接传 JSON 字符串libcurl 不会对里面的中文做转义所以 json_body 必须是合法的 UTF-8 编码。CURLOPT_HTTPHEADER必须加Content-Type: application/json微信服务端靠这个头判断 body 格式。漏掉的话会返回 47001 错误。响应体是 JSON里面会带 errcode 和 errmsg调用完记得解析。3.3 解析返回码 errcode 与 errmsg微信接口的返回格式是统一的{errcode:0,errmsg:ok}errcode 为 0 表示成功其他都是错误码。这里有一段解析逻辑// 检查响应里的 errcode int check_weixin_response(const char *resp) { char *pos strstr(resp, \errcode\:); if (!pos) return -2; pos strlen(\errcode\:); if (*pos -) return atoi(pos); return atoi(pos); }这个解析很粗糙但对 errcode 这种纯数字字段够用。要注意的是 errcode 可能是负值比如-1表示系统繁忙所以不能只判断!strstr(resp, \errcode\:0)。实际项目里我把 errcode 非 0 的响应都按失败处理打印 errmsg 到日志然后把错误码映射成业务提示比如 40001 就触发重新获取 token 的逻辑。4. 避坑与排查token 过期、参数不匹配与编码问题4.1 返回 40001 或 42001access_token 失效现象调用模板消息接口返回{errcode:40001,errmsg:invalid credential}或者42001 access_token expired。原因大部分情况是本地缓存的 token 过期了或者你在别的地方比如微信公众平台调试工具重新获取了 token导致旧 token 被强制失效。还有一种隐蔽场景多实例部署时两个进程各自去取 token后取到的会把先取到的顶掉。解决拿到 40001 时删除本地缓存重新调用获取 token 的接口然后用新 token 重试刚才的请求。在代码里做一个「一次失败后自动刷新重试」的封装int send_with_retry(const char *json_body, char *resp, size_t size) { char token[512]; get_cached_token(appid, token, sizeof(token)); int ret send_template_message(token, json_body, resp, size); if (check_weixin_response(resp) 40001 || check_weixin_response(resp) 42001) { refresh_access_token(appid, secret); // 重新获取并更新缓存 get_cached_token(appid, token, sizeof(token)); ret send_template_message(token, json_body, resp, size); } return ret; }这种重试逻辑只能做一次如果第二次还返回 40001说明 token 缓存写入有问题别死循环。4.2 返回 47003模板参数不匹配现象请求发出后返回{errcode:47003,errmsg:argument invalid! at data.order_id has empty value}。原因data 里的字段跟模板定义不一致。常见的有三种字段名拼错、字段多余或缺少、value 值为空字符串。微信的模板消息对参数校验非常严格data 里多一个模板里没有的字段也会报错。解决去公众平台的模板详情页对照每个变量名。我遇到过最坑的一次是模板里变量叫order_id.DATA我写成了order_id平台报错不明显最后是逐个删字段定位出来的。建议在本地写一个模板字段字典提前校验// 校验 data 的必要字段 int validate_template_data(const char *json_body, const char *required_fields[], int count) { // 用 cJSON 解析 json_body检查每个 required_fields 是否存在且 value 非空 // 具体代码略思路就是逐字段检查 return 1; }这个校验能在发送前发现问题而不是等到微信返回错误才排查。4.3 中文内容乱码现象消息推送成功但用户在微信里看到的中文是乱码或者直接变成\uXXXX形式。原因微信要求 POST body 必须是 UTF-8 编码的原始中文不是 Unicode 转义字符串。如果你的 JSON 是用snprintf手动拼接的而终端环境是 GBK就会把 GBK 字节直接塞进请求微信解析后当然乱码。解决源码文件保存为 UTF-8编译时加-finput-charsetUTF-8 -fexec-charsetUTF-8GCC 环境或者统一用 cJSON 的cJSON_CreateString生成字符串它会自动处理转义。另外注意 libcurl 的CURLOPT_POSTFIELDS不会对中文做任何处理你传什么它就发什么所以编码责任完全在业务代码上。4.4 返回 45009接口调用超限现象发送间歇性失败返回{errcode:45009,errmsg:reach max api daily quota limit}。原因模板消息接口有每日调用次数上限具体数量跟公众号认证类型有关。线上业务如果频繁推送很容易在下午就把额度用光。解决没有特别好的解药只能从业务侧控制。一个是把多条消息合并成一条比如把多笔订单通知合并到一个模板里另一个是改用一次性订阅消息接口。另外给推送服务加一个流量闸门比如每分钟最多发 50 条超过的直接进队列等下一分钟。这个限流值要自己压测调别拍脑袋。5. 进阶把推送模块封装成异步任务队列5.1 用生产者消费者模型解耦业务如果你的推送不是低频的那直接在业务线程里同步调接口会拖慢主流程。我习惯的做法是起一个独立的推送线程业务侧只负责把消息塞进队列推送线程循环取队列里的消息调 libcurl 发送。这样即使微信接口变慢了也不会阻塞订单处理。队列可以用互斥锁加条件变量实现。下面是一个最小实现typedef struct { char json_body[2048]; } push_task_t; typedef struct { push_task_t tasks[1000]; int head, tail, count; pthread_mutex_t mutex; pthread_cond_t cond; } push_queue_t; void *push_worker(void *arg) { push_queue_t *q (push_queue_t *)arg; while (1) { pthread_mutex_lock(q-mutex); while (q-count 0) { pthread_cond_wait(q-cond, q-mutex); } push_task_t task q-tasks[q-head]; q-head (q-head 1) % 1000; q-count--; pthread_mutex_unlock(q-mutex); // 发送前把 token 拿出来 send_task_with_retry(task); } return NULL; }队列长度固定 1000生产者往队列里放任务时如果满了就丢弃并记日志保证老任务优先被处理。实际项目中我还加了一个信号量来统计队列堆积量超过一定阈值就告警。5.2 失败重试用指数退避别扎堆重试微信接口偶尔会返回-1系统繁忙或40001token 失效这时候直接重发往往还是失败。我见过有人写了个for循环连续重试 10 次结果把接口限流打得死死的。正确的做法是退避重试第一次失败等 1 秒第二次等 2 秒第三次等 4 秒最多等 64 秒。void send_task_with_retry(push_task_t *task) { int max_retry 5; int delay 1; for (int i 0; i max_retry; i) { char resp[1024]; int ret send_with_retry(task-json_body, resp, sizeof(resp)); if (ret 0 check_weixin_response(resp) 0) { return; // 发送成功 } if (check_weixin_response(resp) 45009) { // 限流了说明整体频率太高干脆不重试等下一轮 break; } sleep(delay); delay * 2; if (delay 64) delay 64; } log_push_failure(task-json_body); }这个函数的逻辑是正常情况下 5 次内总能成功如果遇到 45009 限流直接放弃重试因为继续重试只会加重限流最终失败的消息记录到本地文件等人肉补发或人工处理。5.3 验证推送效果的几点习惯写完这套推送系统后我每次上线前都会走一遍完整验证流程先拿测试 openid 发一条模板消息确认微信客户端能收到并且样式正确然后把 access_token 手动改错一位确认错误重试链路能自动恢复 token最后模拟队列满了的情况确认不会丢线程也不会崩。从那以后我每次接入微信推送都强制走这一套流程先拿 curl 手动验证接口和模板参数再封装成 libcurl 代码最后放进队列里压一遍。这套流程帮我绕过了至少三次线上事故。希望帮到你。本文还有配套的精品资源点击获取
简介面向需要在业务系统中接入微信公众号消息推送的C/C开发者这份资源以libcurl为基础实现了向粉丝微信账号主动发送报警或通知消息的功能可直接借鉴其接口封装与HTTP请求流程。压缩包共106个文件包体约3.59MB除85个.h头文件外还提供lib、dll、cpp源文件及Visual Studio工程文件sln/vcxproj覆盖调用声明、静态/动态库及示例代码便于在Windows或Linux环境下备齐依赖并编译运行。包内包含关键源文件与辅助脚本展示消息POST逻辑与运行方式并附带SSL和Libcurl相关动态库有助于开发者理解HTTPS通信和参数构造细节。通过这些文件可以清楚看到Libcurl的初始化、回调设置、消息体封装以及微信接口的响应解析实现从普通报警到微信触达的完整链路。资源目前已有319人学习适合具备基础C网络编程经验、希望快速落地微信告警推送的研发人员参考。1. 微信公众号推送消息为什么用 libcurl做后台服务的人迟早会撞上这样一个需求服务器告警、订单通知、活动进度都要第一时间推到用户微信上。微信公众号推送消息的标准路径是调用微信的模板消息接口本质就是一个带 access_token 的 HTTPS 请求。很多开发者第一反应是去找第三方 SDK但实际项目里我越来越倾向直接用 libcurl 裸调因为它够轻、够稳不引入额外依赖出问题也好查。libcurl 是老牌 HTTP 客户端库支持 HTTPS、POST、自定义 Header配合 cJSON 处理返回体微信推送的整个链路在纯 C 环境里不超过 200 行代码。这篇文章就把整个接入过程拆开讲从 token 获取到模板消息发送再到那些没人提醒你的坑全部用可复现的代码说话。2. 接入前先想清楚access_token 的获取与缓存策略2.1 获取 access_token 的接口与参数微信公众平台所有接口都要求先拿到 access_token这是一个全局唯一凭证有效期为 7200 秒。获取它的接口是一个标准的 GET 请求地址是https://api.weixin.qq.com/cgi-bin/token?grant_typeclient_credentialappidAPPIDsecretAPPSECRET其中 APPID 和 APPSECRET 在公众平台的「基本配置」里可以看到。用 libcurl 发送这个请求很简单下面这段代码演示了完整流程#include stdio.h #include curl/curl.h #include string.h #include stdlib.h // 回调函数把响应数据拼到字符串里 size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata) { size_t total size * nmemb; char **buf (char **)userdata; char *tmp realloc(*buf, strlen(*buf) total 1); if (!tmp) return 0; *buf tmp; strncat(*buf, ptr, total); return total; } int get_access_token(const char *appid, const char *secret, char *out_token, size_t out_size) { char url[512]; snprintf(url, sizeof(url), https://api.weixin.qq.com/cgi-bin/token?grant_typeclient_credentialappid%ssecret%s, appid, secret); CURL *curl curl_easy_init(); if (!curl) return -1; char *response malloc(1); response[0] \0; curl_easy_setopt(curl, CURLOPT_URL, url); curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_callback); curl_easy_setopt(curl, CURLOPT_WRITEDATA, response); curl_easy_setopt(curl, CURLOPT_TIMEOUT, 10L); CURLcode res curl_easy_perform(curl); curl_easy_cleanup(curl); // 这里用 cJSON 解析简化起见直接演示字符串匹配 char *token_pos strstr(response, \access_token\:\); if (token_pos) { token_pos strlen(\access_token\:\); char *end strchr(token_pos, ); if (end (size_t)(end - token_pos) out_size) { memcpy(out_token, token_pos, end - token_pos); out_token[end - token_pos] \0; free(response); return 0; } } free(response); return -1; }这段代码的逻辑很直白构造 URL 后交给 libcurl用 write_callback 把响应内容累积到一个动态字符串里。之所以要回调是因为 libcurl 默认把响应体丢到 stdout而我们是要拿 token 的。这里的 CURLOPT_TIMEOUT 设成 10 秒避免网络异常时卡死业务线程。注意我在代码里刻意没用第三方 JSON 库解析是因为这个场景只取一个 token 字段字符串匹配足够。但如果你的项目里已经用了 cJSON那就改用 cJSON 解析更保险。2.2 缓存 access_token有效期 7200 秒不能每次现取微信官方对 token 接口有每天 2000 次的调用上限而且每次调用都会使旧的 token 失效。如果你每发一条消息就去取一次 token高峰期很快被打出 45009 限流错误。所以实际工程里必须做缓存。常见做法是存到本地文件或共享内存里带时间戳判断是否过期。我一般会让 token 提前 5 分钟过期也就是把 7200 秒当成 7140 秒用防止在临界时刻微信端已经失效但本地还没到期的尴尬。// 简化版缓存逻辑读文件判断时间戳 int get_cached_token(const char *appid, char *out_token, size_t size) { FILE *fp fopen(token_cache.dat, r); if (!fp) return -1; char cached_appid[128] {0}; char token[512] {0}; time_t saved_time 0; fscanf(fp, %s %s %ld, cached_appid, token, saved_time); fclose(fp); if (strcmp(cached_appid, appid) ! 0) return -1; if (time(NULL) - saved_time 7140) return -1; // 提前5分钟过期 strncpy(out_token, token, size); return 0; }写入缓存时把 appid、token、时间戳三者一起存避免多账号切换时读到别人的 token。这里的 7140 是我在实际项目里调出来的值官方 7200 秒提前 300 秒基本能躲开边界问题。如果你跑的进程是多实例部署建议用 Redis 存 token把 appid 当 keytoken 当 value配合过期时间比文件锁省心。3. 用 libcurl 发送模板消息POST 请求与 JSON 构造3.1 模板消息接口和必要参数拿到 token 之后推送消息就走这个接口https://api.weixin.qq.com/cgi-bin/message/template/send?access_tokenACCESS_TOKEN请求方法是 POSTbody 是 JSON包含这几个字段字段必填说明touser是接收用户的 openidtemplate_id是模板 ID在公众平台「模板消息」里申请url否点击消息后跳转的链接data是模板中的变量值键值对形式举个例子假设模板内容是「您的订单 {{order_id.DATA}} 已发货」那么 data 就写成{ touser: oXXXXXX, template_id: XXXXXX, url: https://example.com/order, data: { order_id: { value: JD123456 } } }这里有一个最容易踩的坑data 里的键名必须和模板里的变量名完全一致多一个空格都不行。后面避坑章会展开讲。3.2 libcurl 发送 POST 的完整代码发送模板消息的 libcurl 代码比获取 token 多两步设置 POST 方法和设置 Content-Type 头。下面这段可以直接抄int send_template_message(const char *access_token, const char *json_body, char *out_resp, size_t resp_size) { char url[512]; snprintf(url, sizeof(url), https://api.weixin.qq.com/cgi-bin/message/template/send?access_token%s, access_token); CURL *curl curl_easy_init(); if (!curl) return -1; struct curl_slist *headers NULL; headers curl_slist_append(headers, Content-Type: application/json); char *response malloc(1); response[0] \0; curl_easy_setopt(curl, CURLOPT_URL, url); curl_easy_setopt(curl, CURLOPT_POST, 1L); curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json_body); curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_callback); curl_easy_setopt(curl, CURLOPT_WRITEDATA, response); curl_easy_setopt(curl, CURLOPT_TIMEOUT, 10L); CURLcode res curl_easy_perform(curl); if (res ! CURLE_OK) { snprintf(out_resp, resp_size, curl error: %s, curl_easy_strerror(res)); free(response); curl_slist_free_all(headers); curl_easy_cleanup(curl); return -1; } strncpy(out_resp, response, resp_size - 1); out_resp[resp_size - 1] \0; free(response); curl_slist_free_all(headers); curl_easy_cleanup(curl); return 0; }几个关键点说下CURLOPT_POST设为 1Llibcurl 才会用 POST 方法。如果不设置默认是 GET。CURLOPT_POSTFIELDS直接传 JSON 字符串libcurl 不会对里面的中文做转义所以 json_body 必须是合法的 UTF-8 编码。CURLOPT_HTTPHEADER必须加Content-Type: application/json微信服务端靠这个头判断 body 格式。漏掉的话会返回 47001 错误。响应体是 JSON里面会带 errcode 和 errmsg调用完记得解析。3.3 解析返回码 errcode 与 errmsg微信接口的返回格式是统一的{errcode:0,errmsg:ok}errcode 为 0 表示成功其他都是错误码。这里有一段解析逻辑// 检查响应里的 errcode int check_weixin_response(const char *resp) { char *pos strstr(resp, \errcode\:); if (!pos) return -2; pos strlen(\errcode\:); if (*pos -) return atoi(pos); return atoi(pos); }这个解析很粗糙但对 errcode 这种纯数字字段够用。要注意的是 errcode 可能是负值比如-1表示系统繁忙所以不能只判断!strstr(resp, \errcode\:0)。实际项目里我把 errcode 非 0 的响应都按失败处理打印 errmsg 到日志然后把错误码映射成业务提示比如 40001 就触发重新获取 token 的逻辑。4. 避坑与排查token 过期、参数不匹配与编码问题4.1 返回 40001 或 42001access_token 失效现象调用模板消息接口返回{errcode:40001,errmsg:invalid credential}或者42001 access_token expired。原因大部分情况是本地缓存的 token 过期了或者你在别的地方比如微信公众平台调试工具重新获取了 token导致旧 token 被强制失效。还有一种隐蔽场景多实例部署时两个进程各自去取 token后取到的会把先取到的顶掉。解决拿到 40001 时删除本地缓存重新调用获取 token 的接口然后用新 token 重试刚才的请求。在代码里做一个「一次失败后自动刷新重试」的封装int send_with_retry(const char *json_body, char *resp, size_t size) { char token[512]; get_cached_token(appid, token, sizeof(token)); int ret send_template_message(token, json_body, resp, size); if (check_weixin_response(resp) 40001 || check_weixin_response(resp) 42001) { refresh_access_token(appid, secret); // 重新获取并更新缓存 get_cached_token(appid, token, sizeof(token)); ret send_template_message(token, json_body, resp, size); } return ret; }这种重试逻辑只能做一次如果第二次还返回 40001说明 token 缓存写入有问题别死循环。4.2 返回 47003模板参数不匹配现象请求发出后返回{errcode:47003,errmsg:argument invalid! at data.order_id has empty value}。原因data 里的字段跟模板定义不一致。常见的有三种字段名拼错、字段多余或缺少、value 值为空字符串。微信的模板消息对参数校验非常严格data 里多一个模板里没有的字段也会报错。解决去公众平台的模板详情页对照每个变量名。我遇到过最坑的一次是模板里变量叫order_id.DATA我写成了order_id平台报错不明显最后是逐个删字段定位出来的。建议在本地写一个模板字段字典提前校验// 校验 data 的必要字段 int validate_template_data(const char *json_body, const char *required_fields[], int count) { // 用 cJSON 解析 json_body检查每个 required_fields 是否存在且 value 非空 // 具体代码略思路就是逐字段检查 return 1; }这个校验能在发送前发现问题而不是等到微信返回错误才排查。4.3 中文内容乱码现象消息推送成功但用户在微信里看到的中文是乱码或者直接变成\uXXXX形式。原因微信要求 POST body 必须是 UTF-8 编码的原始中文不是 Unicode 转义字符串。如果你的 JSON 是用snprintf手动拼接的而终端环境是 GBK就会把 GBK 字节直接塞进请求微信解析后当然乱码。解决源码文件保存为 UTF-8编译时加-finput-charsetUTF-8 -fexec-charsetUTF-8GCC 环境或者统一用 cJSON 的cJSON_CreateString生成字符串它会自动处理转义。另外注意 libcurl 的CURLOPT_POSTFIELDS不会对中文做任何处理你传什么它就发什么所以编码责任完全在业务代码上。4.4 返回 45009接口调用超限现象发送间歇性失败返回{errcode:45009,errmsg:reach max api daily quota limit}。原因模板消息接口有每日调用次数上限具体数量跟公众号认证类型有关。线上业务如果频繁推送很容易在下午就把额度用光。解决没有特别好的解药只能从业务侧控制。一个是把多条消息合并成一条比如把多笔订单通知合并到一个模板里另一个是改用一次性订阅消息接口。另外给推送服务加一个流量闸门比如每分钟最多发 50 条超过的直接进队列等下一分钟。这个限流值要自己压测调别拍脑袋。5. 进阶把推送模块封装成异步任务队列5.1 用生产者消费者模型解耦业务如果你的推送不是低频的那直接在业务线程里同步调接口会拖慢主流程。我习惯的做法是起一个独立的推送线程业务侧只负责把消息塞进队列推送线程循环取队列里的消息调 libcurl 发送。这样即使微信接口变慢了也不会阻塞订单处理。队列可以用互斥锁加条件变量实现。下面是一个最小实现typedef struct { char json_body[2048]; } push_task_t; typedef struct { push_task_t tasks[1000]; int head, tail, count; pthread_mutex_t mutex; pthread_cond_t cond; } push_queue_t; void *push_worker(void *arg) { push_queue_t *q (push_queue_t *)arg; while (1) { pthread_mutex_lock(q-mutex); while (q-count 0) { pthread_cond_wait(q-cond, q-mutex); } push_task_t task q-tasks[q-head]; q-head (q-head 1) % 1000; q-count--; pthread_mutex_unlock(q-mutex); // 发送前把 token 拿出来 send_task_with_retry(task); } return NULL; }队列长度固定 1000生产者往队列里放任务时如果满了就丢弃并记日志保证老任务优先被处理。实际项目中我还加了一个信号量来统计队列堆积量超过一定阈值就告警。5.2 失败重试用指数退避别扎堆重试微信接口偶尔会返回-1系统繁忙或40001token 失效这时候直接重发往往还是失败。我见过有人写了个for循环连续重试 10 次结果把接口限流打得死死的。正确的做法是退避重试第一次失败等 1 秒第二次等 2 秒第三次等 4 秒最多等 64 秒。void send_task_with_retry(push_task_t *task) { int max_retry 5; int delay 1; for (int i 0; i max_retry; i) { char resp[1024]; int ret send_with_retry(task-json_body, resp, sizeof(resp)); if (ret 0 check_weixin_response(resp) 0) { return; // 发送成功 } if (check_weixin_response(resp) 45009) { // 限流了说明整体频率太高干脆不重试等下一轮 break; } sleep(delay); delay * 2; if (delay 64) delay 64; } log_push_failure(task-json_body); }这个函数的逻辑是正常情况下 5 次内总能成功如果遇到 45009 限流直接放弃重试因为继续重试只会加重限流最终失败的消息记录到本地文件等人肉补发或人工处理。5.3 验证推送效果的几点习惯写完这套推送系统后我每次上线前都会走一遍完整验证流程先拿测试 openid 发一条模板消息确认微信客户端能收到并且样式正确然后把 access_token 手动改错一位确认错误重试链路能自动恢复 token最后模拟队列满了的情况确认不会丢线程也不会崩。从那以后我每次接入微信推送都强制走这一套流程先拿 curl 手动验证接口和模板参数再封装成 libcurl 代码最后放进队列里压一遍。这套流程帮我绕过了至少三次线上事故。希望帮到你。本文还有配套的精品资源点击获取
