Postman中API正常为何Flutter用Dio发POST请求始终返回500错误

问题表现 #

• REST API服务本身运行正常，使用Postman发起POST请求可获得正常响应
• Flutter项目中集成Dio网络库发起同接口POST请求时，服务端固定返回500 Internal Server Error
• 参考截图：
  • 请求头header参考
  • 正常POST请求示例
  • Dio Options配置参考

核心排查方向&修复方法 #

1. Content-Type与服务端预期不匹配（最高发原因） #

绝大多数该类问题都是请求头的Content-Type配置和Postman不一致导致：

• 若服务端要求接收JSON格式参数：
  显式在Dio请求配置中指定Content-Type为application/json，直接传入Map类型参数即可，不要做表单编码：

  // 正确JSON请求配置示例
  final response = await dio.post(
    '/your/api/path',
    data: {
      "username": "test",
      "password": "123456"
    },
    options: Options(
      headers: {
        "Content-Type": "application/json",
        // 其他鉴权类header和Postman中保持完全一致
      }
    )
  );
  

• 若服务端要求接收表单格式参数：
  不要直接传入裸Map，使用FormData包裹参数，或显式指定Content-Type为application/x-www-form-urlencoded：

  // 正确表单请求配置示例
  final formData = FormData.fromMap({
    "username": "test",
    "password": "123456"
  });
  final response = await dio.post('/your/api/path', data: formData);
  

快速验证方法：抓包对比Postman正常请求和Dio请求的原始请求头、请求体内容，保证两者完全一致即可排除该类问题。

2. 参数序列化规则不匹配 #

• 传参时不要手动将Map类型参数转成JSON字符串传入，Dio会根据配置的Content-Type自动完成序列化，手动转字符串会导致请求体格式异常，服务端解析失败。
• 若接口有数组、嵌套对象类型参数，在Options中配置listFormat: ListFormat.multiCompatible，适配绝大多数服务端的参数解析规则，避免默认序列化格式和Postman不一致。

3. 其他配置差异 #

• 检查Dio全局配置是否开启了自定义请求编码、gzip压缩，Postman默认不会压缩请求体，若服务端未适配压缩请求，会直接解析失败返回500，可临时关闭自定义请求编码器测试。
• 全量复制Postman中的请求header到Dio配置中，再逐个移除测试，排查是否有服务端强校验的字段（比如部分服务端会校验Accept、User-Agent字段）缺失。

内容的提问来源于stack exchange，提问作者Süleyman Tülbür