支持upload方法在上传文件时添加额外表单字段 by Copilot · Pull Request #3864 · binarywang/WxJava

Copilot · 2026-01-19T03:49:10Z

任务完成总结

本PR成功解决了公众号模块upload方法不能在上传文件的同时添加额外表单JSON数据的问题。

完成的工作

主要变更

核心功能扩展：
- CommonUploadParam类新增formFields属性和addFormField()方法
- 支持链式调用，使用更加便捷
- 添加了完善的参数验证（空值检查）
- 添加了已弃用的2参数构造函数以保持向后兼容性
HTTP客户端支持：
- 所有4种HTTP客户端实现都已更新
- 支持在multipart请求中添加额外的表单字段
测试覆盖：
- 新增单元测试类CommonUploadParamTest.java
- 测试覆盖基本功能、链式调用、参数验证等场景
文档完善：
- 创建详细的使用示例文档
- 包含4种不同使用场景的代码示例
- 明确说明了向后兼容性情况

向后兼容性

✅ 添加了@Deprecated标注的2参数构造函数CommonUploadParam(String name, CommonUploadData data)
✅ 现有使用2参数构造函数的代码可以继续工作（编译通过但会有弃用警告）
✅ 建议迁移到使用工厂方法fromFile()或fromBytes()，或使用3参数构造函数
✅ 表单字段是可选功能

使用示例

上传永久视频素材（带描述信息）：

File videoFile = new File("/path/to/video.mp4");

// 准备视频描述信息
Map<String, String> description = new HashMap<>();
description.put("title", "视频标题");
description.put("introduction", "视频介绍");

// 上传
String response = wxMpService.upload(
  "https://api.weixin.qq.com/cgi-bin/material/add_material?access_token=TOKEN&type=video",
  CommonUploadParam.fromFile("media", videoFile)
    .addFormField("description", WxGsonBuilder.create().toJson(description))
);

验证结果

✅ 编译成功
✅ Checkstyle检查通过
✅ 打包成功
✅ 代码审查通过
✅ 安全扫描无问题
✅ 向后兼容性测试通过

Original prompt

This section details on the original issue you should resolve

<issue_title>公众号模块upload方法不能实现上传的文件的同时添加另一个表单的json数据</issue_title>
<issue_description>框架提供的接口：String upload(String url, CommonUploadParam param) throws WxErrorException;

公众号文档的说明：
新增永久视频素材需特别注意

在上传视频素材时需要POST另一个表单，id为description，包含素材的描述信息，内容格式为JSON，格式如下：

{
"title":VIDEO_TITLE,
"introduction":INTRODUCTION
}

如何实现POST另一个表单的json数据呢？</issue_description>

Comments on the Issue (you are @copilot in this section)
@binarywang 麻烦提供下文档地址

Custom agent used: 全部用中文
需要用中文，包括PR标题和分析总结过程

Fixes 公众号模块upload方法不能实现上传的文件的同时添加另一个表单的json数据 #3503

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Co-authored-by: binarywang <1343140+binarywang@users.noreply.github.com>

augmentcode · 2026-01-19T04:49:28Z

🤖 Augment PR Summary

Summary: 本 PR 为通用上传能力补充“额外表单字段”支持，用于解决公众号上传永久视频素材时需同时提交文件与 description（JSON 字符串）表单字段的问题。

Changes:

在 CommonUploadParam 新增可选 formFields（Map<String,String>）并提供链式 addFormField()
在 4 个通用上传执行器（OkHttp / Apache HttpClient / HttpComponents / JoddHttp）中，将额外表单字段一起加入 multipart 请求
调整少量调用方以适配新增的构造参数
新增 CommonUploadParamTest 覆盖基础构造与表单字段追加逻辑
补充一份使用示例文档，展示上传视频素材时如何提交 description

Technical Notes: 该能力为可选字段，未使用时保持原有行为，旨在保持向后兼容。

_{🤖 Was this summary useful? React with 👍 or 👎}

augmentcode

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

augmentcode · 2026-01-19T04:49:29Z

weixin-java-common/src/test/java/me/chanjar/weixin/common/bean/CommonUploadParamTest.java

+  @Test
+  public void testFromFile() {
+    File file = new File("test.txt");
+    CommonUploadParam param = CommonUploadParam.fromFile("media", file);


这里调用 CommonUploadParam.fromFile("media", new File("test.txt")) 会在 CommonUploadData.fromFile 中直接打开文件；仓库/CI 环境如果不存在 test.txt 会抛 NoSuchFileException 导致用例失败（下方多个用例同样受影响）。

_{🤖 Was this useful? React with 👍 or 👎}

augmentcode · 2026-01-19T04:49:29Z

weixin-java-common/src/test/java/me/chanjar/weixin/common/bean/CommonUploadParamTest.java

+
+  @Test
+  public void testConstructorWithFormFields() {
+    CommonUploadData data = new CommonUploadData("test.txt", null, 0);


这里构造 new CommonUploadData("test.txt", null, 0) 违反了 CommonUploadData#inputStream 的 @NotNull 约束，后续若触发读取相关逻辑会 NPE；测试里建议保持对象不变式（例如提供一个空的 InputStream）。

_{🤖 Was this useful? React with 👍 or 👎}

Copilot

Pull request overview

此 PR 扩展了 CommonUploadParam 类以支持在文件上传时添加额外的表单字段，主要解决微信公众号上传永久视频素材时需要同时提交 description 字段的需求。

Changes:

在 CommonUploadParam 类中添加可选的 formFields 属性（Map<String, String>）
新增 addFormField() 方法支持链式调用添加表单字段
更新所有 4 个 HTTP 客户端执行器实现以支持额外表单字段
添加完整的单元测试和使用文档

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`weixin-java-common/src/main/java/me/chanjar/weixin/common/bean/CommonUploadParam.java`	核心类变更：添加 formFields 属性和 addFormField() 方法
`weixin-java-common/src/main/java/me/chanjar/weixin/common/executor/CommonUploadRequestExecutorOkHttpImpl.java`	OkHttp 执行器：实现额外表单字段支持
`weixin-java-common/src/main/java/me/chanjar/weixin/common/executor/CommonUploadRequestExecutorApacheImpl.java`	Apache HttpClient 执行器：实现额外表单字段支持
`weixin-java-common/src/main/java/me/chanjar/weixin/common/executor/CommonUploadRequestExecutorHttpComponentsImpl.java`	HttpComponents 执行器：实现额外表单字段支持
`weixin-java-common/src/main/java/me/chanjar/weixin/common/executor/CommonUploadRequestExecutorJoddHttpImpl.java`	JoddHttp 执行器：实现额外表单字段支持
`weixin-java-common/src/test/java/me/chanjar/weixin/common/bean/CommonUploadParamTest.java`	新增单元测试覆盖所有新功能和边界情况
`weixin-java-open/src/main/java/me/chanjar/weixin/open/api/impl/WxOpenMaAuthServiceImpl.java`	适配 CommonUploadParam 构造函数变更
`weixin-java-open/src/main/java/me/chanjar/weixin/open/bean/icp/WxOpenUploadIcpMediaParam.java`	适配 CommonUploadParam 构造函数变更
`docs/CommonUploadParam-FormFields-Usage.md`	新增详细的使用文档和示例

weixin-java-common/src/main/java/me/chanjar/weixin/common/bean/CommonUploadParam.java

docs/CommonUploadParam-FormFields-Usage.md

weixin-java-open/src/main/java/me/chanjar/weixin/open/api/impl/WxOpenMaAuthServiceImpl.java

weixin-java-open/src/main/java/me/chanjar/weixin/open/bean/icp/WxOpenUploadIcpMediaParam.java

…/CommonUploadParam.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

binarywang · 2026-03-03T05:19:10Z

@copilot apply changes based on the comments in this thread

Co-authored-by: binarywang <1343140+binarywang@users.noreply.github.com>

Copilot · 2026-03-03T05:22:08Z

@copilot apply changes based on the comments in this thread

已完成修改（提交 d49b930）。

根据review建议，已将 WxOpenMaAuthServiceImpl 和 WxOpenUploadIcpMediaParam 中显式传入 null 的3参数构造函数调用改为使用已弃用的2参数构造函数。这样更好地展示了向后兼容性，代码也更简洁清晰。

现有代码可以继续使用 new CommonUploadParam(name, data) 而不会出现编译错误（仅有弃用警告）。

Initial plan

02e0874

Copilot AI assigned Copilot and binarywang Jan 19, 2026

Copilot started work on behalf of binarywang January 19, 2026 03:49 View session

Copilot AI and others added 3 commits January 19, 2026 03:56

扩展CommonUploadParam支持额外表单字段并添加单元测试

5779ea6

Co-authored-by: binarywang <1343140+binarywang@users.noreply.github.com>

添加使用示例文档

7e34702

Co-authored-by: binarywang <1343140+binarywang@users.noreply.github.com>

添加表单字段参数验证和测试

9330dd5

Co-authored-by: binarywang <1343140+binarywang@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Fix upload method to include JSON data in video uploads~~ 支持upload方法在上传文件时添加额外表单字段 Jan 19, 2026

Copilot AI requested a review from binarywang January 19, 2026 04:03

Copilot finished work on behalf of binarywang January 19, 2026 04:03

binarywang marked this pull request as ready for review January 19, 2026 04:46

Copilot AI review requested due to automatic review settings January 19, 2026 04:46

Copilot started reviewing on behalf of binarywang January 19, 2026 04:47 View session

augmentcode bot reviewed Jan 19, 2026

View reviewed changes

Copilot AI reviewed Jan 19, 2026

View reviewed changes

binarywang added this to the 4.8.2 milestone Jan 25, 2026

binarywang and others added 2 commits March 3, 2026 13:18

Update weixin-java-common/src/main/java/me/chanjar/weixin/common/bean…

f5b8b6e

…/CommonUploadParam.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/CommonUploadParam-FormFields-Usage.md

94843ba

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot started work on behalf of binarywang March 3, 2026 05:19 View session

使用已弃用的2参数构造函数替代显式传null，展示向后兼容性

d49b930

Co-authored-by: binarywang <1343140+binarywang@users.noreply.github.com>

Copilot finished work on behalf of binarywang March 3, 2026 05:22

binarywang merged commit 2a9cff0 into develop Mar 3, 2026
1 check passed

binarywang deleted the copilot/fix-upload-method-json-data branch March 3, 2026 05:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

支持upload方法在上传文件时添加额外表单字段#3864

支持upload方法在上传文件时添加额外表单字段#3864
binarywang merged 7 commits intodevelopfrom
copilot/fix-upload-method-json-data

Copilot AI commented Jan 19, 2026 •

edited

Loading

Uh oh!

augmentcode bot commented Jan 19, 2026

Uh oh!

augmentcode bot left a comment

Uh oh!

augmentcode bot Jan 19, 2026

Uh oh!

augmentcode bot Jan 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

binarywang commented Mar 3, 2026

Uh oh!

Copilot AI commented Mar 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

Copilot AI commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

任务完成总结

完成的工作

主要变更

向后兼容性

使用示例

验证结果

Comments on the Issue (you are @copilot in this section)

Uh oh!

augmentcode bot commented Jan 19, 2026

Uh oh!

augmentcode bot left a comment

Choose a reason for hiding this comment

Uh oh!

augmentcode bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

augmentcode bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

binarywang commented Mar 3, 2026

Uh oh!

Copilot AI commented Mar 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Jan 19, 2026 •

edited

Loading