Flutter用ConvertApi Rest API时PDF合并接口返回原文件异常

核心异常根因 #

问题本质是复用单格式转换的请求逻辑调用PDF合并接口时，触发了服务端的兜底直通逻辑，服务端因为无法识别合法的合并入参，不会执行合并操作，直接将上传的首个原始PDF编码为返回结果输出，最终表现为接口未返回合并后的文件，只回传了原始上传文件。 #

分步骤定位排查路径 #

• 校验请求路由的匹配规则：之前DOCX/Excel/PPT转PDF的逻辑，适配的是「单源格式转目标格式」的接口路由规则，但PDF合并属于多输入的文档处理类操作，不属于pdf/to/{操作类型}的单文档转换路由范畴。如果路由路径不匹配合法的合并接口定义，服务端不会抛出明确的400错误，而是自动路由到PDF转PDF的直通兜底接口，直接返回上传的单文件内容。
• 校验表单文件字段的传参格式：PDF合并接口要求多文件通过数组形式的表单字段传递，原代码中所有文件都统一传入名为Files的字段，没有标记数组属性，HTTP Multipart协议在解析无数组标记的同名字段时，会出现参数覆盖、仅识别首个文件的问题，服务端凑不齐待合并的多文件入参，自然无法触发合并流程。
• 校验认证信息的传递有效性：原代码将Secret放在URL查询参数中传递，如果出现URL编码兼容问题导致服务端无法识别认证信息，会触发匿名请求的限流兜底逻辑，直接返回无加工的上传文件内容，不会执行付费的合并处理流程。

可直接落地的修复操作 #

• 修正请求路由路径，摒弃单文档转换的路径拼接规则，使用PDF合并专属的接口端点发送请求。
• 调整文件上传的字段命名规则，将原代码中MultipartFile.fromPath的第一个参数从"Files"修改为"Files[]"，显式标记数组类型的入参，确保服务端可以正确识别全部待合并的PDF文件列表。修正后的代码片段参考：

for (int i = 0; i < len; i++) {
  final element = widget.docs[i];
  request.files.add(
    await MultipartFile.fromPath(
      "Files[]", // 替换原字段名"Files"
      element.path,
      filename: element.name,
    ),
  );
}

• 增加返回结果的前置校验：解码返回的文件流前，先对比接口返回的文件大小与单份原始PDF的大小，如果数值完全一致，说明合并流程未实际触发，可直接判定为请求参数不合法，无需再执行解码操作。
• 优化Secret的传递方式，将硬编码在URL查询参数中的Secret替换为请求头传递，避免URL编码、长度限制导致的认证失效问题。

常见踩坑提示：Flutter的http类MultipartRequest实现，不会自动将多个同名字段转换为服务端识别的数组入参，必须在字段名后显式添加[]后缀，否则服务端只会解析单个文件字段的内容，完全跳过合并操作。

内容的提问来源于stack exchange，提问作者Ahmet Yusuf