Flutter/Dart中如何为Uri查询参数数组添加方括号

你遇到的问题很常见——Dart的Uri类默认会把数组类型的查询参数展开为重复键（比如scopes=xxx&scopes=yyy），但PHP后端期望的是带[]后缀的键名来识别数组参数。下面是两种实用的解决方法：

方法一：手动修改数组参数的键名 #

最直接的方式就是给数组类型的参数键名加上[]，这样Uri生成的查询参数就会符合PHP的要求：

Map<String, dynamic> queryParameters = {
  'include': 'messages',
  // 给数组参数的键名加上[]
  'scopes[]': ['withHasUnreadMessages', 'withSubscriberUserIds'],
};
Uri uri = Uri.https(_getBaseUrl(), '/mypath', queryParameters);

生成的Uri解码后会是：
https://your-base-url/mypath?include=messages&scopes[]=withHasUnreadMessages&scopes[]=withSubscriberUserIds

PHP后端接收到后会自动将scopes[]解析为数组，完美适配你的API要求。

方法二：写工具函数自动处理所有数组参数 #

如果你的请求中有多个数组参数，手动修改键名会很繁琐，可以写一个工具函数自动给所有数组类型的参数键名加上[]：

Map<String, dynamic> adaptToPhpQueryParams(Map<String, dynamic> originalParams) {
  final adaptedParams = <String, dynamic>{};
  
  originalParams.forEach((key, value) {
    if (value is List) {
      // 数组类型参数，给键名添加[]
      adaptedParams['$key[]'] = value;
    } else {
      // 非数组参数直接保留
      adaptedParams[key] = value;
    }
  });
  
  return adaptedParams;
}

// 使用示例
Map<String, dynamic> queryParameters = {
  'include': 'messages',
  'scopes': ['withHasUnreadMessages', 'withSubscriberUserIds'],
  // 可以添加更多数组参数测试
  'tags': ['new', 'unread']
};

final phpCompatibleParams = adaptToPhpQueryParams(queryParameters);
Uri uri = Uri.https(_getBaseUrl(), '/mypath', phpCompatibleParams);

这个函数会遍历所有参数，自动识别数组类型并修改键名，让你不用重复手动调整每个参数。

原理说明 #

Dart的Uri类在处理List类型的查询参数值时，会将列表中的每个元素转换为单独的查询项，而我们指定的带[]的键名会被正确URL编码（变为scopes%5B%5D），当PHP后端接收到请求时，会按照默认规则将这类带[]的参数解析为数组，正好匹配你的API需求。

内容的提问来源于stack exchange，提问作者Chuck Norton