1. 临时素材上传到底难在哪企业微信的临时素材上传看起来只是调一个接口的事但真到业务里跑起来坑比想象中多。我前后在三个项目里踩过这个环节从最开始用最朴素的方式硬怼到后来逐步抽象出一套相对优雅的方案中间交了不少学费。这篇文章就把这些经验完整拆开讲一遍适合正在对接企业微信素材能力、或者已经对接但被各种边界情况折腾过的开发者参考。先把概念理清楚。企业微信的临时素材指的是上传后只在服务端保留三天的媒体文件包括图片、语音、视频和普通文件。它和永久素材最大的区别就是生命周期短但胜在上传接口简单、不需要额外的素材管理逻辑。典型使用场景是客服系统里发送一张工单截图、审批流里附带一个PDF附件、机器人推送一段语音通知。这些场景的共同特点是文件用完即弃不需要长期存储临时素材刚好匹配。那难点在哪我总结下来主要是四块第一上传接口用的是multipart/form-data和普通JSON请求的封装方式完全不同很多HTTP工具类默认不支持或者支持得别扭第二media_id这个返回值有有效期业务侧如果缓存了它过期后发送会直接失败第三文件类型和大小有硬性限制图片不能超过10MB、语音不能超过2MB且只支持AMR和MP3、视频不能超过10MB超了接口直接报错第四并发上传时如果多个请求同时拿同一个文件流会出现流被消费完导致后续请求拿到空内容的问题。这四点里前两点是认知问题后两点是实打实的技术坑。我见过不少项目在这块的处理方式是写一个工具方法每次要发文件就现读现传传完拿到media_id立刻用掉。这种方式在低频场景下没问题但一旦量上来比如一天几千次上传就会暴露出重复上传、流管理混乱、错误处理缺失等一系列问题。所以“优雅”这个词在这里不是锦上添花而是有明确的工程价值——它意味着可复用、可观测、可容错。下面我会从整体设计思路开始一步步拆到具体实现把每个决策背后的理由讲清楚。你如果只是想快速抄个能跑的代码可以直接跳到第三节但如果你想搞清楚为什么这么设计建议从头看。2. 整体方案设计与选型考量2.1 为什么不用现成的SDK企业微信官方提供了多语言SDKJava、Python、PHP都有。我最初也想过直接用SDK省事但实际用下来发现两个问题。一是SDK往往把access_token的管理和素材上传耦合在一起而access_token本身需要全局缓存和刷新如果每个上传请求都去触发一次token获取在高并发下会频繁打企业微信的接口触发频率限制。二是SDK的封装层次比较深出问题的时候排查链路长比如上传失败你很难快速判断是token问题、网络问题还是文件本身的问题。所以我的选择是access_token自己管上传逻辑自己写只依赖一个通用的HTTP客户端。这样每一层都是透明的出问题能快速定位。当然这不是说SDK不好如果你的项目规模小、上传频率低用SDK完全没问题。但如果你追求可控性和可观测性自己封装是更稳的路。2.2 核心设计原则整个方案我定了三条原则。第一条是流的一次性消费文件流从磁盘或网络读进来之后只允许被消费一次避免重复读取导致的性能损耗和状态混乱。第二条是media_id不跨请求缓存每次上传拿到media_id后立即返回给调用方由调用方在本次业务逻辑内用完即弃不做全局缓存。第三条是错误分层把网络错误、接口错误、文件校验错误分开处理每类错误有不同的重试策略和日志级别。这三条原则看起来简单但落地的时候需要一些设计上的取舍。比如第一条如果调用方传进来的是一个InputStream那上传完之后这个流就关了调用方不能再读。所以我在接口设计上要求调用方传文件路径或者字节数组而不是流。字节数组适合小文件文件路径适合大文件这样内部可以自己控制流的生命周期。2.3 模块划分整个上传能力我拆成了四个模块。TokenManager负责access_token的获取、缓存和刷新用双检锁加过期时间控制保证多线程下只有一个线程去刷新。MediaValidator负责文件校验包括类型、大小、扩展名校验不通过直接抛业务异常不走网络请求。MediaUploader是核心上传逻辑负责组装multipart请求、发送、解析响应。UploadResult是统一的返回结构包含media_id、类型、创建时间以及一个isSuccess的标志。这四个模块之间是单向依赖Uploader依赖Validator和TokenManagerValidator和TokenManager互不依赖。这样的好处是每个模块可以单独测试比如Validator的测试不需要mock网络TokenManager的测试不需要真实文件。2.4 关于multipart的选型multipart/form-data的组装我试过三种方式。第一种是手写boundary拼接字节流灵活但容易出错尤其是boundary和内容里出现冲突的时候。第二种是用Apache HttpClient的MultipartEntityBuilder封装好、稳定但引入了一个比较重的依赖。第三种是用OkHttp的MultipartBody轻量、API清晰我最终选了这个。选OkHttp的理由是它的MultipartBody.Builder用起来很直观addFormDataPart可以同时指定name、filename和RequestBody而且RequestBody可以基于文件或字节数组创建天然支持流式上传。另外OkHttp的连接池和超时控制也比较成熟不需要自己再造轮子。如果你用的是Java生态里的其他HTTP客户端思路是一样的关键是找到支持流式multipart的API。3. 核心细节与实操要点拆解3.1 access_token的管理策略access_token是企业微信所有接口的通行证有效期7200秒也就是两小时。它的获取接口有频率限制而且新获取的token会让旧的失效。这意味着你不能每个请求都去获取也不能缓存太久导致过期。我的做法是用一个带过期时间的缓存key是应用的corpId和secret的组合value是token和过期时间戳。获取token的时候先查缓存如果存在且距离过期还有300秒以上直接用否则加锁去刷新。加锁用双检锁避免多个线程同时刷新。刷新成功后更新缓存失败则抛异常让上层决定是否重试。这里有个细节过期时间不要设成7200秒整要留出网络延迟和时钟偏差的余量。我一般设成6900秒也就是提前300秒过期。另外如果企业微信返回的token过期时间字段和预期不一致以返回的为准不要硬编码。注意access_token的缓存不要用本地Map简单存多实例部署的时候每个实例都会各自刷新导致token频繁失效。生产环境建议用Redis之类的集中式缓存或者至少保证同一时间只有一个实例在刷新。3.2 文件校验的边界条件文件校验看起来简单但边界条件不少。企业微信对临时素材的限制是这样的图片支持JPG、PNG、GIF、BMP、JPEG大小不超过10MB语音支持AMR、MP3大小不超过2MB播放长度不超过60秒视频支持MP4大小不超过10MB普通文件大小不超过20MB。校验的时候要注意几点。第一扩展名和实际内容可能不一致比如一个exe文件改名为jpg光看扩展名是拦不住的。如果业务安全要求高需要读文件头做魔数校验。第二大小校验要在读取文件之前做用File.length()获取避免把大文件读进内存才发现超限。第三语音的时长校验比较麻烦需要解析音频文件头如果业务不强制可以只校验大小和格式时长交给企业微信接口去判断。我一般把校验规则做成配置用枚举定义每种类型的允许扩展名和大小上限这样新增类型的时候只改配置不改代码。校验失败的时候抛出带明确错误码的异常比如FILE_TOO_LARGE、UNSUPPORTED_TYPE方便上层做不同的提示。3.3 multipart请求的组装细节组装multipart请求的时候有几个细节容易忽略。第一boundary的生成要用随机字符串不要用固定值避免和文件内容冲突。OkHttp会自动生成不用自己管。第二Content-Type要设成multipart/form-data并且带上boundary参数这个OkHttp的MultipartBody会自动处理。第三每个part的name要和接口文档一致企业微信上传接口的字段名是media类型是filefilename要带上原始文件名和扩展名。代码大概长这样RequestBody fileBody RequestBody.create(file, MediaType.parse(application/octet-stream)); MultipartBody body new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart(media, file.getName(), fileBody) .build(); Request request new Request.Builder() .url(uploadUrl ?access_token token type type) .post(body) .build();这里type参数是素材类型取值是image、voice、video、file。注意type要放在URL的query参数里不是放在body里这是企业微信接口的设计。3.4 响应解析与错误处理企业微信上传接口的响应是JSON成功的时候返回media_id、type、created_at。失败的时候返回errcode和errmsg。解析的时候要先判断HTTP状态码再判断errcode。有些错误是HTTP 200但errcode非0比如40001表示token无效40004表示媒体文件类型不合法40005表示文件大小超限。我的处理方式是HTTP非200直接抛网络异常HTTP 200但errcode非0则根据errcode映射成业务异常。40001这种token失效的错误触发一次token刷新后重试一次其他错误直接抛给上层不重试。重试只做一次避免无限循环。提示errcode的映射表建议做成常量类不要散落在代码里。企业微信的错误码有几百个常用的就那几十个维护一份自己的映射表比每次查文档快得多。3.5 并发场景下的流管理并发上传同一个文件的时候如果多个线程共享一个InputStream会出现流被消费完的问题。我的做法是接口只接受File或byte[]不接受InputStream。如果是File每个线程自己打开一个新的FileInputStream如果是byte[]每个线程自己创建一个新的ByteArrayInputStream。这样每个上传请求都有独立的流互不干扰。如果是大文件用File的方式更省内存因为OkHttp会流式读取文件不会一次性加载到内存。如果是小文件用byte[]更方便因为可以复用不需要反复读磁盘。我一般设一个阈值比如1MB以下的用byte[]以上的用File。4. 完整实操流程与关键环节4.1 环境准备与依赖引入先说一下环境。我用的是Java 8加OkHttp 4.x构建工具是Maven。依赖只需要两个OkHttp和Jackson前者做HTTP请求后者解析JSON。如果你用的是Gradle换成对应的坐标就行。dependency groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId version4.9.3/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.13.0/version /dependencyOkHttp 4.x需要Kotlin标准库Maven会自动带上不用手动加。如果你用的是Java 11以上也可以考虑用Java自带的HttpClient但multipart的支持不如OkHttp方便需要自己拼boundary。4.2 TokenManager的实现TokenManager的核心是一个带过期时间的缓存和一个刷新锁。我用ConcurrentHashMap存tokenkey是corpId加secretvalue是一个包含token和过期时间的对象。获取token的方法先查缓存判断是否过期过期则加锁刷新。public String getToken(String corpId, String secret) { String key corpId : secret; TokenCache cache tokenMap.get(key); if (cache ! null !cache.isExpired()) { return cache.getToken(); } synchronized (this) { cache tokenMap.get(key); if (cache ! null !cache.isExpired()) { return cache.getToken(); } String token fetchTokenFromApi(corpId, secret); tokenMap.put(key, new TokenCache(token, System.currentTimeMillis() 6900 * 1000)); return token; } }fetchTokenFromApi就是调企业微信的gettoken接口解析返回的access_token和expires_in。注意expires_in是秒要转成毫秒。如果接口返回errcode非0抛异常。注意synchronized锁的是this如果TokenManager是单例没问题如果是多例锁不住。生产环境建议用分布式锁或者保证TokenManager是单例。4.3 MediaValidator的实现Validator的职责是校验文件是否符合企业微信的要求。我用一个枚举定义每种类型的规则public enum MediaType { IMAGE(image, Arrays.asList(jpg, jpeg, png, gif, bmp), 10 * 1024 * 1024), VOICE(voice, Arrays.asList(amr, mp3), 2 * 1024 * 1024), VIDEO(video, Arrays.asList(mp4), 10 * 1024 * 1024), FILE(file, Collections.emptyList(), 20 * 1024 * 1024); private final String type; private final ListString allowedExtensions; private final long maxSize; // 构造方法和getter省略 }校验方法接收File和MediaType先判断文件是否存在再判断大小再判断扩展名。FILE类型不限制扩展名只限制大小。校验不通过抛MediaValidationException带上错误码。4.4 MediaUploader的核心逻辑Uploader是核心流程是校验文件、获取token、组装multipart、发送请求、解析响应、返回结果。我把它写成一个方法接收File、MediaType、corpId、secret返回UploadResult。public UploadResult upload(File file, MediaType type, String corpId, String secret) { validator.validate(file, type); String token tokenManager.getToken(corpId, secret); String url UPLOAD_URL ?access_token token type type.getType(); RequestBody fileBody RequestBody.create(file, MediaType.parse(application/octet-stream)); MultipartBody body new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart(media, file.getName(), fileBody) .build(); Request request new Request.Builder().url(url).post(body).build(); try (Response response client.newCall(request).execute()) { String responseBody response.body().string(); return parseResponse(responseBody, type); } catch (IOException e) { throw new MediaUploadException(NETWORK_ERROR, e); } }parseResponse解析JSON如果errcode是0返回成功的UploadResult如果是40001刷新token后重试一次其他错误抛异常。4.5 重试机制的实现重试只针对token失效和网络超时两种情况。token失效的重试逻辑是捕获到40001错误后强制刷新token重新组装请求再发一次。网络超时的重试是捕获IOException后判断是否是超时是则重试一次不是则直接抛。重试次数我设成1次也就是最多发两次请求。为什么不设更多因为企业微信的接口本身有频率限制重试太多会触发限流反而更慢。而且如果是文件本身的问题重试多少次都没用。private UploadResult uploadWithRetry(File file, MediaType type, String corpId, String secret, int retryCount) { try { return doUpload(file, type, corpId, secret); } catch (TokenExpiredException e) { if (retryCount 0) { tokenManager.refresh(corpId, secret); return uploadWithRetry(file, type, corpId, secret, retryCount - 1); } throw e; } catch (IOException e) { if (retryCount 0 isTimeout(e)) { return uploadWithRetry(file, type, corpId, secret, retryCount - 1); } throw new MediaUploadException(NETWORK_ERROR, e); } }4.6 调用示例与结果处理调用的时候业务代码只需要三行MediaUploader uploader new MediaUploader(); UploadResult result uploader.upload(new File(/path/to/image.jpg), MediaType.IMAGE, corpId, secret); String mediaId result.getMediaId();拿到mediaId后立即在本次业务逻辑里用掉比如调发送消息接口。不要存到数据库或者缓存里因为三天后就失效了。如果业务需要长期保存应该把文件存到自己的对象存储需要发送的时候再上传一次。提示media_id的有效期是三天但实际使用中建议按两天半来规划留出余量。如果业务逻辑比较复杂从上传到发送之间可能间隔很久那就要考虑重新上传。5. 常见问题与排查技巧实录5.1 上传失败排查速查表错误现象可能原因排查方法解决方案返回40001token无效或过期检查token缓存是否过期是否被其他实例刷新覆盖刷新token后重试检查缓存策略返回40004文件类型不合法检查扩展名和实际类型是否匹配修正文件类型或做魔数校验返回40005文件大小超限检查文件实际大小压缩文件或分片上传返回41001缺少access_token参数检查URL拼接确认token不为空连接超时网络问题或企业微信侧限流检查网络连通性查看是否触发频率限制增加超时时间降低并发流被关闭多线程共享InputStream检查是否传入了共享流改用File或byte[]中文文件名乱码编码问题检查filename的编码用URLEncoder编码文件名5.2 我踩过的三个坑第一个坑是token缓存用了本地Map结果多实例部署的时候A实例刷新了tokenB实例还在用旧的导致间歇性40001。后来改成Redis集中缓存问题解决。这个坑的教训是任何有状态的东西在多实例环境下都要考虑一致性问题。第二个坑是文件校验只看了扩展名结果有个用户上传了一个改名为jpg的文本文件企业微信返回40004。后来加了魔数校验读文件前几个字节判断真实类型。魔数校验的规则是JPG开头是FFD8PNG开头是89504E47GIF开头是47494638。读前8个字节就够了。第三个坑是并发上传同一个文件时多个线程共享了一个FileInputStream导致部分请求拿到空内容。后来改成每个请求自己打开流问题解决。这个坑的教训是流是有状态的不能跨线程共享。5.3 性能优化的几个点如果上传频率很高有几个优化点可以考虑。第一用连接池OkHttp默认有连接池复用TCP连接减少握手开销。第二大文件用流式上传不要读进内存OkHttp的RequestBody.create(File)就是流式的。第三token缓存用集中式缓存避免每个实例都去刷新。第四批量上传的时候用异步OkHttp的enqueue方法可以并发发送但要注意控制并发数避免触发限流。我实测下来单实例每秒上传10个1MB的文件CPU和内存都很平稳。如果超过这个量建议做队列削峰把上传请求放到队列里慢慢消费。5.4 日志与监控上传这种外部依赖的操作日志一定要打全。我一般记录这几个字段请求ID、文件大小、文件类型、耗时、结果码。请求ID用于串联上下游日志文件大小和类型用于分析失败分布耗时用于发现性能问题结果码用于统计成功率。监控方面我会统计上传成功率、平均耗时、失败原因分布。成功率低于99%就告警平均耗时超过2秒也告警。失败原因分布能帮你快速定位是token问题还是文件问题。注意日志里不要打media_id的完整值打前几位就行避免泄露。也不要打access_token这个是敏感信息。5.5 关于素材类型的几个疑问有人问过图片能不能当文件上传可以type传file就行但这样企业微信不会做图片处理发送的时候也是当文件发。反过来文件能不能当图片上传不行企业微信会校验实际类型不匹配会返回40004。还有人问视频的封面怎么处理企业微信上传视频接口支持传封面但临时素材接口不支持只有永久素材接口才支持。如果业务需要封面要么用永久素材要么自己在发送的时候处理。语音的时长限制是60秒这个是在上传的时候校验的超过会返回错误。如果你不确定音频时长可以用FFmpeg之类的工具先探测一下或者干脆只校验大小让企业微信去判断。6. 一些个人体会这套方案我在两个项目里用过整体稳定性不错。最大的感受是对接外部接口优雅的关键不在于代码写得多漂亮而在于对边界情况的覆盖。token过期、文件超限、网络抖动、并发冲突这些才是真正消耗精力的地方。把这些问题处理好了代码自然就优雅了。另外一点是不要过度设计。我见过有的项目为了上传一个文件搞了一套复杂的责任链加策略模式结果维护成本比收益还高。我的建议是先跑通再抽象。等你在三个地方写了重复的上传逻辑再考虑抽成公共模块。过早抽象比不抽象更可怕。最后分享一个小技巧如果你不确定企业微信的接口行为可以用curl先手动调一次把请求和响应都打出来看。比在代码里调试快得多。比如上传接口你可以这样调curl -X POST https://qyapi.weixin.qq.com/cgi-bin/media/upload?access_tokenYOUR_TOKENtypeimage \ -F media/path/to/image.jpg把YOUR_TOKEN换成真实的token就能看到完整的响应。这个方式在排查40004、40005这类错误的时候特别有用因为你能直接看到企业微信返回的errmsg比看代码猜快多了。 企业微信临时素材上传：从踩坑到优雅实现
1. 临时素材上传到底难在哪企业微信的临时素材上传看起来只是调一个接口的事但真到业务里跑起来坑比想象中多。我前后在三个项目里踩过这个环节从最开始用最朴素的方式硬怼到后来逐步抽象出一套相对优雅的方案中间交了不少学费。这篇文章就把这些经验完整拆开讲一遍适合正在对接企业微信素材能力、或者已经对接但被各种边界情况折腾过的开发者参考。先把概念理清楚。企业微信的临时素材指的是上传后只在服务端保留三天的媒体文件包括图片、语音、视频和普通文件。它和永久素材最大的区别就是生命周期短但胜在上传接口简单、不需要额外的素材管理逻辑。典型使用场景是客服系统里发送一张工单截图、审批流里附带一个PDF附件、机器人推送一段语音通知。这些场景的共同特点是文件用完即弃不需要长期存储临时素材刚好匹配。那难点在哪我总结下来主要是四块第一上传接口用的是multipart/form-data和普通JSON请求的封装方式完全不同很多HTTP工具类默认不支持或者支持得别扭第二media_id这个返回值有有效期业务侧如果缓存了它过期后发送会直接失败第三文件类型和大小有硬性限制图片不能超过10MB、语音不能超过2MB且只支持AMR和MP3、视频不能超过10MB超了接口直接报错第四并发上传时如果多个请求同时拿同一个文件流会出现流被消费完导致后续请求拿到空内容的问题。这四点里前两点是认知问题后两点是实打实的技术坑。我见过不少项目在这块的处理方式是写一个工具方法每次要发文件就现读现传传完拿到media_id立刻用掉。这种方式在低频场景下没问题但一旦量上来比如一天几千次上传就会暴露出重复上传、流管理混乱、错误处理缺失等一系列问题。所以“优雅”这个词在这里不是锦上添花而是有明确的工程价值——它意味着可复用、可观测、可容错。下面我会从整体设计思路开始一步步拆到具体实现把每个决策背后的理由讲清楚。你如果只是想快速抄个能跑的代码可以直接跳到第三节但如果你想搞清楚为什么这么设计建议从头看。2. 整体方案设计与选型考量2.1 为什么不用现成的SDK企业微信官方提供了多语言SDKJava、Python、PHP都有。我最初也想过直接用SDK省事但实际用下来发现两个问题。一是SDK往往把access_token的管理和素材上传耦合在一起而access_token本身需要全局缓存和刷新如果每个上传请求都去触发一次token获取在高并发下会频繁打企业微信的接口触发频率限制。二是SDK的封装层次比较深出问题的时候排查链路长比如上传失败你很难快速判断是token问题、网络问题还是文件本身的问题。所以我的选择是access_token自己管上传逻辑自己写只依赖一个通用的HTTP客户端。这样每一层都是透明的出问题能快速定位。当然这不是说SDK不好如果你的项目规模小、上传频率低用SDK完全没问题。但如果你追求可控性和可观测性自己封装是更稳的路。2.2 核心设计原则整个方案我定了三条原则。第一条是流的一次性消费文件流从磁盘或网络读进来之后只允许被消费一次避免重复读取导致的性能损耗和状态混乱。第二条是media_id不跨请求缓存每次上传拿到media_id后立即返回给调用方由调用方在本次业务逻辑内用完即弃不做全局缓存。第三条是错误分层把网络错误、接口错误、文件校验错误分开处理每类错误有不同的重试策略和日志级别。这三条原则看起来简单但落地的时候需要一些设计上的取舍。比如第一条如果调用方传进来的是一个InputStream那上传完之后这个流就关了调用方不能再读。所以我在接口设计上要求调用方传文件路径或者字节数组而不是流。字节数组适合小文件文件路径适合大文件这样内部可以自己控制流的生命周期。2.3 模块划分整个上传能力我拆成了四个模块。TokenManager负责access_token的获取、缓存和刷新用双检锁加过期时间控制保证多线程下只有一个线程去刷新。MediaValidator负责文件校验包括类型、大小、扩展名校验不通过直接抛业务异常不走网络请求。MediaUploader是核心上传逻辑负责组装multipart请求、发送、解析响应。UploadResult是统一的返回结构包含media_id、类型、创建时间以及一个isSuccess的标志。这四个模块之间是单向依赖Uploader依赖Validator和TokenManagerValidator和TokenManager互不依赖。这样的好处是每个模块可以单独测试比如Validator的测试不需要mock网络TokenManager的测试不需要真实文件。2.4 关于multipart的选型multipart/form-data的组装我试过三种方式。第一种是手写boundary拼接字节流灵活但容易出错尤其是boundary和内容里出现冲突的时候。第二种是用Apache HttpClient的MultipartEntityBuilder封装好、稳定但引入了一个比较重的依赖。第三种是用OkHttp的MultipartBody轻量、API清晰我最终选了这个。选OkHttp的理由是它的MultipartBody.Builder用起来很直观addFormDataPart可以同时指定name、filename和RequestBody而且RequestBody可以基于文件或字节数组创建天然支持流式上传。另外OkHttp的连接池和超时控制也比较成熟不需要自己再造轮子。如果你用的是Java生态里的其他HTTP客户端思路是一样的关键是找到支持流式multipart的API。3. 核心细节与实操要点拆解3.1 access_token的管理策略access_token是企业微信所有接口的通行证有效期7200秒也就是两小时。它的获取接口有频率限制而且新获取的token会让旧的失效。这意味着你不能每个请求都去获取也不能缓存太久导致过期。我的做法是用一个带过期时间的缓存key是应用的corpId和secret的组合value是token和过期时间戳。获取token的时候先查缓存如果存在且距离过期还有300秒以上直接用否则加锁去刷新。加锁用双检锁避免多个线程同时刷新。刷新成功后更新缓存失败则抛异常让上层决定是否重试。这里有个细节过期时间不要设成7200秒整要留出网络延迟和时钟偏差的余量。我一般设成6900秒也就是提前300秒过期。另外如果企业微信返回的token过期时间字段和预期不一致以返回的为准不要硬编码。注意access_token的缓存不要用本地Map简单存多实例部署的时候每个实例都会各自刷新导致token频繁失效。生产环境建议用Redis之类的集中式缓存或者至少保证同一时间只有一个实例在刷新。3.2 文件校验的边界条件文件校验看起来简单但边界条件不少。企业微信对临时素材的限制是这样的图片支持JPG、PNG、GIF、BMP、JPEG大小不超过10MB语音支持AMR、MP3大小不超过2MB播放长度不超过60秒视频支持MP4大小不超过10MB普通文件大小不超过20MB。校验的时候要注意几点。第一扩展名和实际内容可能不一致比如一个exe文件改名为jpg光看扩展名是拦不住的。如果业务安全要求高需要读文件头做魔数校验。第二大小校验要在读取文件之前做用File.length()获取避免把大文件读进内存才发现超限。第三语音的时长校验比较麻烦需要解析音频文件头如果业务不强制可以只校验大小和格式时长交给企业微信接口去判断。我一般把校验规则做成配置用枚举定义每种类型的允许扩展名和大小上限这样新增类型的时候只改配置不改代码。校验失败的时候抛出带明确错误码的异常比如FILE_TOO_LARGE、UNSUPPORTED_TYPE方便上层做不同的提示。3.3 multipart请求的组装细节组装multipart请求的时候有几个细节容易忽略。第一boundary的生成要用随机字符串不要用固定值避免和文件内容冲突。OkHttp会自动生成不用自己管。第二Content-Type要设成multipart/form-data并且带上boundary参数这个OkHttp的MultipartBody会自动处理。第三每个part的name要和接口文档一致企业微信上传接口的字段名是media类型是filefilename要带上原始文件名和扩展名。代码大概长这样RequestBody fileBody RequestBody.create(file, MediaType.parse(application/octet-stream)); MultipartBody body new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart(media, file.getName(), fileBody) .build(); Request request new Request.Builder() .url(uploadUrl ?access_token token type type) .post(body) .build();这里type参数是素材类型取值是image、voice、video、file。注意type要放在URL的query参数里不是放在body里这是企业微信接口的设计。3.4 响应解析与错误处理企业微信上传接口的响应是JSON成功的时候返回media_id、type、created_at。失败的时候返回errcode和errmsg。解析的时候要先判断HTTP状态码再判断errcode。有些错误是HTTP 200但errcode非0比如40001表示token无效40004表示媒体文件类型不合法40005表示文件大小超限。我的处理方式是HTTP非200直接抛网络异常HTTP 200但errcode非0则根据errcode映射成业务异常。40001这种token失效的错误触发一次token刷新后重试一次其他错误直接抛给上层不重试。重试只做一次避免无限循环。提示errcode的映射表建议做成常量类不要散落在代码里。企业微信的错误码有几百个常用的就那几十个维护一份自己的映射表比每次查文档快得多。3.5 并发场景下的流管理并发上传同一个文件的时候如果多个线程共享一个InputStream会出现流被消费完的问题。我的做法是接口只接受File或byte[]不接受InputStream。如果是File每个线程自己打开一个新的FileInputStream如果是byte[]每个线程自己创建一个新的ByteArrayInputStream。这样每个上传请求都有独立的流互不干扰。如果是大文件用File的方式更省内存因为OkHttp会流式读取文件不会一次性加载到内存。如果是小文件用byte[]更方便因为可以复用不需要反复读磁盘。我一般设一个阈值比如1MB以下的用byte[]以上的用File。4. 完整实操流程与关键环节4.1 环境准备与依赖引入先说一下环境。我用的是Java 8加OkHttp 4.x构建工具是Maven。依赖只需要两个OkHttp和Jackson前者做HTTP请求后者解析JSON。如果你用的是Gradle换成对应的坐标就行。dependency groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId version4.9.3/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.13.0/version /dependencyOkHttp 4.x需要Kotlin标准库Maven会自动带上不用手动加。如果你用的是Java 11以上也可以考虑用Java自带的HttpClient但multipart的支持不如OkHttp方便需要自己拼boundary。4.2 TokenManager的实现TokenManager的核心是一个带过期时间的缓存和一个刷新锁。我用ConcurrentHashMap存tokenkey是corpId加secretvalue是一个包含token和过期时间的对象。获取token的方法先查缓存判断是否过期过期则加锁刷新。public String getToken(String corpId, String secret) { String key corpId : secret; TokenCache cache tokenMap.get(key); if (cache ! null !cache.isExpired()) { return cache.getToken(); } synchronized (this) { cache tokenMap.get(key); if (cache ! null !cache.isExpired()) { return cache.getToken(); } String token fetchTokenFromApi(corpId, secret); tokenMap.put(key, new TokenCache(token, System.currentTimeMillis() 6900 * 1000)); return token; } }fetchTokenFromApi就是调企业微信的gettoken接口解析返回的access_token和expires_in。注意expires_in是秒要转成毫秒。如果接口返回errcode非0抛异常。注意synchronized锁的是this如果TokenManager是单例没问题如果是多例锁不住。生产环境建议用分布式锁或者保证TokenManager是单例。4.3 MediaValidator的实现Validator的职责是校验文件是否符合企业微信的要求。我用一个枚举定义每种类型的规则public enum MediaType { IMAGE(image, Arrays.asList(jpg, jpeg, png, gif, bmp), 10 * 1024 * 1024), VOICE(voice, Arrays.asList(amr, mp3), 2 * 1024 * 1024), VIDEO(video, Arrays.asList(mp4), 10 * 1024 * 1024), FILE(file, Collections.emptyList(), 20 * 1024 * 1024); private final String type; private final ListString allowedExtensions; private final long maxSize; // 构造方法和getter省略 }校验方法接收File和MediaType先判断文件是否存在再判断大小再判断扩展名。FILE类型不限制扩展名只限制大小。校验不通过抛MediaValidationException带上错误码。4.4 MediaUploader的核心逻辑Uploader是核心流程是校验文件、获取token、组装multipart、发送请求、解析响应、返回结果。我把它写成一个方法接收File、MediaType、corpId、secret返回UploadResult。public UploadResult upload(File file, MediaType type, String corpId, String secret) { validator.validate(file, type); String token tokenManager.getToken(corpId, secret); String url UPLOAD_URL ?access_token token type type.getType(); RequestBody fileBody RequestBody.create(file, MediaType.parse(application/octet-stream)); MultipartBody body new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart(media, file.getName(), fileBody) .build(); Request request new Request.Builder().url(url).post(body).build(); try (Response response client.newCall(request).execute()) { String responseBody response.body().string(); return parseResponse(responseBody, type); } catch (IOException e) { throw new MediaUploadException(NETWORK_ERROR, e); } }parseResponse解析JSON如果errcode是0返回成功的UploadResult如果是40001刷新token后重试一次其他错误抛异常。4.5 重试机制的实现重试只针对token失效和网络超时两种情况。token失效的重试逻辑是捕获到40001错误后强制刷新token重新组装请求再发一次。网络超时的重试是捕获IOException后判断是否是超时是则重试一次不是则直接抛。重试次数我设成1次也就是最多发两次请求。为什么不设更多因为企业微信的接口本身有频率限制重试太多会触发限流反而更慢。而且如果是文件本身的问题重试多少次都没用。private UploadResult uploadWithRetry(File file, MediaType type, String corpId, String secret, int retryCount) { try { return doUpload(file, type, corpId, secret); } catch (TokenExpiredException e) { if (retryCount 0) { tokenManager.refresh(corpId, secret); return uploadWithRetry(file, type, corpId, secret, retryCount - 1); } throw e; } catch (IOException e) { if (retryCount 0 isTimeout(e)) { return uploadWithRetry(file, type, corpId, secret, retryCount - 1); } throw new MediaUploadException(NETWORK_ERROR, e); } }4.6 调用示例与结果处理调用的时候业务代码只需要三行MediaUploader uploader new MediaUploader(); UploadResult result uploader.upload(new File(/path/to/image.jpg), MediaType.IMAGE, corpId, secret); String mediaId result.getMediaId();拿到mediaId后立即在本次业务逻辑里用掉比如调发送消息接口。不要存到数据库或者缓存里因为三天后就失效了。如果业务需要长期保存应该把文件存到自己的对象存储需要发送的时候再上传一次。提示media_id的有效期是三天但实际使用中建议按两天半来规划留出余量。如果业务逻辑比较复杂从上传到发送之间可能间隔很久那就要考虑重新上传。5. 常见问题与排查技巧实录5.1 上传失败排查速查表错误现象可能原因排查方法解决方案返回40001token无效或过期检查token缓存是否过期是否被其他实例刷新覆盖刷新token后重试检查缓存策略返回40004文件类型不合法检查扩展名和实际类型是否匹配修正文件类型或做魔数校验返回40005文件大小超限检查文件实际大小压缩文件或分片上传返回41001缺少access_token参数检查URL拼接确认token不为空连接超时网络问题或企业微信侧限流检查网络连通性查看是否触发频率限制增加超时时间降低并发流被关闭多线程共享InputStream检查是否传入了共享流改用File或byte[]中文文件名乱码编码问题检查filename的编码用URLEncoder编码文件名5.2 我踩过的三个坑第一个坑是token缓存用了本地Map结果多实例部署的时候A实例刷新了tokenB实例还在用旧的导致间歇性40001。后来改成Redis集中缓存问题解决。这个坑的教训是任何有状态的东西在多实例环境下都要考虑一致性问题。第二个坑是文件校验只看了扩展名结果有个用户上传了一个改名为jpg的文本文件企业微信返回40004。后来加了魔数校验读文件前几个字节判断真实类型。魔数校验的规则是JPG开头是FFD8PNG开头是89504E47GIF开头是47494638。读前8个字节就够了。第三个坑是并发上传同一个文件时多个线程共享了一个FileInputStream导致部分请求拿到空内容。后来改成每个请求自己打开流问题解决。这个坑的教训是流是有状态的不能跨线程共享。5.3 性能优化的几个点如果上传频率很高有几个优化点可以考虑。第一用连接池OkHttp默认有连接池复用TCP连接减少握手开销。第二大文件用流式上传不要读进内存OkHttp的RequestBody.create(File)就是流式的。第三token缓存用集中式缓存避免每个实例都去刷新。第四批量上传的时候用异步OkHttp的enqueue方法可以并发发送但要注意控制并发数避免触发限流。我实测下来单实例每秒上传10个1MB的文件CPU和内存都很平稳。如果超过这个量建议做队列削峰把上传请求放到队列里慢慢消费。5.4 日志与监控上传这种外部依赖的操作日志一定要打全。我一般记录这几个字段请求ID、文件大小、文件类型、耗时、结果码。请求ID用于串联上下游日志文件大小和类型用于分析失败分布耗时用于发现性能问题结果码用于统计成功率。监控方面我会统计上传成功率、平均耗时、失败原因分布。成功率低于99%就告警平均耗时超过2秒也告警。失败原因分布能帮你快速定位是token问题还是文件问题。注意日志里不要打media_id的完整值打前几位就行避免泄露。也不要打access_token这个是敏感信息。5.5 关于素材类型的几个疑问有人问过图片能不能当文件上传可以type传file就行但这样企业微信不会做图片处理发送的时候也是当文件发。反过来文件能不能当图片上传不行企业微信会校验实际类型不匹配会返回40004。还有人问视频的封面怎么处理企业微信上传视频接口支持传封面但临时素材接口不支持只有永久素材接口才支持。如果业务需要封面要么用永久素材要么自己在发送的时候处理。语音的时长限制是60秒这个是在上传的时候校验的超过会返回错误。如果你不确定音频时长可以用FFmpeg之类的工具先探测一下或者干脆只校验大小让企业微信去判断。6. 一些个人体会这套方案我在两个项目里用过整体稳定性不错。最大的感受是对接外部接口优雅的关键不在于代码写得多漂亮而在于对边界情况的覆盖。token过期、文件超限、网络抖动、并发冲突这些才是真正消耗精力的地方。把这些问题处理好了代码自然就优雅了。另外一点是不要过度设计。我见过有的项目为了上传一个文件搞了一套复杂的责任链加策略模式结果维护成本比收益还高。我的建议是先跑通再抽象。等你在三个地方写了重复的上传逻辑再考虑抽成公共模块。过早抽象比不抽象更可怕。最后分享一个小技巧如果你不确定企业微信的接口行为可以用curl先手动调一次把请求和响应都打出来看。比在代码里调试快得多。比如上传接口你可以这样调curl -X POST https://qyapi.weixin.qq.com/cgi-bin/media/upload?access_tokenYOUR_TOKENtypeimage \ -F media/path/to/image.jpg把YOUR_TOKEN换成真实的token就能看到完整的响应。这个方式在排查40004、40005这类错误的时候特别有用因为你能直接看到企业微信返回的errmsg比看代码猜快多了。