在微信个人号二次开发中，处理文件类消息是一个常见需求。当用户发送文档、压缩包、视频等文件时，回调消息中通常只包含文件的元信息和下载凭证，需要调用专门的下载接口才能获取到实际文件地址。WTAPI 提供的 下载文件 接口就是用来处理这种场景的。

调用示例

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://wx.chuapi.com/finder/v2/api/message/downloadFile")
   .header("X-finder-TOKEN", "")
   .header("Authorization", "Bearer eyJhbGciOiJIUzUxMiJ9.eyJsb2dpbl91c2VyX2tleSI6IjAxNmM2ZDQ5LWIxNWMtNGRjMy05YzQzLWZmYzZmNDhhMTg3MyJ9.1JWq9ntjam20_XDlSbklWTxbV-vg-F_dY1LYVX05BndRAuaJbv3iSwoDY-BuMwe1sdKxDXtDTMWJgXNMff4nOg")
   .header("Content-Type", "application/json")
   .body("{\n    \"appId\": \"{{appid}}\",\n    \"xml\": \"<?xml version=\\\"1.0\\\"?>\\n<msg>\\n\\t<appmsg>\\n\\t\\t<title>log_20260518.txt</title>\\n\\t\\t<type>6</type>\\n\\t\\t<appattach>\\n\\t\\t\\t<totallen>1166</totallen>\\n\\t\\t\\t<attachid>@cdn_3057020100044b304902010002048b061c0002032f57ed02049f88e67202046a0bfcd6042430393831643539302d346136662d346535382d393034392d6462623466373632653032380204051400050201000405004c4e6100_e6c413884586171496f5315ebcabbbc3_1</attachid>\\n\\t\\t\\t<cdnattachurl>3057020100044b304902010002048b061c0002032f57ed02049f88e67202046a0bfcd6042430393831643539302d346136662d346535382d393034392d6462623466373632653032380204051400050201000405004c4e6100</cdnattachurl>\\n\\t\\t\\t<aeskey>e6c413884586171496f5315ebcabbbc3</aeskey>\\n\\t\\t\\t<fileext>txt</fileext>\\n\\t\\t\\t<overwrite_newmsgid>958036977603034497</overwrite_newmsgid>\\n\\t\\t\\t<fileuploadtoken><![CDATA[v1_wjmbpLIyiKUgU1XJrV1cntgb0/WZD8AT2iw8Y33YFztnONMQ2UbR3rIX6aQS5RN3LnnqSqC+LEsQCZePFW1JRSi25m5H6GYfj3McMHZ/wfh/lmCdR8KnFin1LYLVwVZfQvLcw/mgN1pO6qojiZv+6krY9NL9s5YX3ninX22mKwDOpFWzseVPs1bMKV6usc+9VqijLLu2pAIUQrgXnY9R]]></fileuploadtoken>\\n\\t\\t</appattach>\\n\\t\\t<md5>059fe6b972e76bdbb62af5130b5252fd</md5>\\n\\t</appmsg><extcommoninfo>\\n\\t<media_expire_at>1780380118</media_expire_at>\\n</extcommoninfo>\\n\\n\\t<fromusername>wxid_tyyu4v9ykz3712</fromusername>\\n\\t<scene>0</scene>\\n\\t<appinfo>\\n\\t\\t<version>1</version>\\n\\t\\t<appname></appname>\\n\\t</appinfo>\\n\\t<commenturl></commenturl>\\n</msg>\\n\"\n}")
   .asString();

• fileUrl：文件的实际下载地址，有效期为 7 天，需要及时下载或转存到自己的存储服务中。

开发中的注意点

1. XML 必须完整：下载接口依赖 XML 中的 attachid、aeskey、cdnattachurl 等字段，任何一个缺失都会导致下载失败。建议收到文件消息回调后原样存储 XML。
2. 及时下载：返回的 fileUrl 只有 7 天有效期，过期后无法访问。如果业务需要长期保存文件，建议在拿到 URL 后立即下载并转存到本地或对象存储。
3. 文件类型判断：XML 中的 <type> 字段可以辅助判断消息类型，type=6 通常代表文件类型消息。 <fileext> 可以拿到文件后缀。
4. 大文件处理：对于较大的视频或压缩文件，下载可能耗时较长，建议异步处理，避免阻塞主流程。
5. MD5 校验：XML 中提供了 md5 字段，下载完成后可以校验文件完整性。

典型处理流程

收到文件消息回调
    ↓
提取并保存 XML
    ↓
调用 downloadFile 接口
    ↓
获取 fileUrl
    ↓
下载文件到本地 / 转存到 OSS
    ↓
记录文件元信息（文件名、大小、MD5、存储路径）

小结

下载文件接口本身不复杂，核心在于正确解析回调 XML 并及时处理返回的临时 URL。在实际项目中，建议把文件下载和存储做成异步任务，配合消息队列和对象存储，能比较好地支撑文件类消息的处理需求。