PHP http_build_query 怎么传数组参数：为什么得到 tag[0]，接口又该怎么约定

做订单筛选接口改成支持多个标签的逻辑后，调用方传的是 ['tag' => ['php', 'api']]，本地打印出来的 URL 却变成了 tag%5B0%5D=php&tag%5B1%5D=api。下游只认 tag=php&tag=api，于是参数明明没丢，接口还是回了 400。

这不是 http_build_query 出错，而是两边对“数组参数”的传输格式没有提前说清楚。PHP 会按自己的嵌套数组规则生成带方括号的键；如果接口协议约定的是同名键重复出现，就要在边界层明确换一种编码方式，别让每个调用方各自写零散的修补逻辑。

一段看似正常的参数，为什么下游没有读到 tag

当时的请求逻辑一点都不复杂。后台列表要按标签筛选，网关层调用对应的搜索服务：

$params = [
    'page' => 1,
    'tag'  => ['php', 'api'],
];

$query = http_build_query($params, '', '&', PHP_QUERY_RFC3986);
// page=1&tag%5B0%5D=php&tag%5B1%5D=api

PHP 这一侧打印出来的输出是有完整信息的；问题出在搜索服务只把重复出现的 tag 当成多值过滤条件。它实际收到的是两个完全不同名字的键：tag[0] 和 tag[1]。接口本身当初没有约定方括号格式，自然不会自动把这两个键合并成标签列表。

先从调用方需求选参数语义，而不是先挑编码函数

同样是“传多个值”的需求，至少有三种常见的实现思路。先把对应的参数示例落到接口文档里，后续不同语言的客户端才能生成完全一致的请求。

这里没必要把所有格式都兼容收下。只要同一个字段既允许 tag[] 又允许重复 tag，不同客户端传法多了之后，签名校验、缓存键生成、日志检索和错误提示都会变得很模糊。一个版本里先确定统一的公开写法，整体维护成本通常最低。

http_build_query 的数组输出：它保留了结构，也改变了键名

PHP 官方文档里明确说明，http_build_query 可以把一维或者嵌套数组生成经过URL编码的请求字符串。数组里的下标会直接进入键名里，所以它本身更适合“要保留数组层级结构”的协议。

$query = http_build_query([
    'filter' => [
        'status' => 'paid',
        'tag' => ['php', 'api'],
    ],
], '', '&', PHP_QUERY_RFC3986);

// filter%5Bstatus%5D=paid
// &filter%5Btag%5D%5B0%5D=php
// &filter%5Btag%5D%5B1%5D=api

这个输出结果不是“数组被拆坏了”，只是把PHP数组的层级直接摊平成了查询参数的键。接收方如果也是按这种格式解析，读回 filter['tag'] 非常自然；如果接收方只认同名重复键的格式，就应该在API设计阶段就选定另一种编码逻辑。

下游要求重复键时，把转换逻辑收在一个小函数里

如果接口约定的是 tag=php&tag=api，不要先让 http_build_query 生成结果再用正则删掉下标部分。这种补丁对嵌套字段、特殊字符和后续的字段扩展都不友好。更稳妥的做法是把“重复键列表”作为一种明确的参数类型单独处理。

function buildRepeatedQuery(string $name, array $values): string
{
    $pairs = [];

    foreach ($values as $value) {
        if (!is_string($value) || $value === '') {
            throw new InvalidArgumentException('tag must be a non-empty string');
        }

        $pairs[] = rawurlencode($name) . '=' . rawurlencode($value);
    }

    return implode('&', $pairs);
}

$query = 'page=1&' . buildRepeatedQuery('tag', ['php', 'api']);
// page=1&tag=php&tag=api

调用方只需要知道：标签列表走重复键的格式就行。函数内部的百分号编码、空值过滤和拼接规则都集中在同一处维护。后续接口如果要改成走JSON Body，也只需要改这一层的逻辑，不用跑到控制器、服务类和测试代码里到处找零散的替换代码。

空格、null 和分隔符，都是接口边界的一部分

http_build_query 默认采用 PHP_QUERY_RFC1738 规则，空格会编码成 +；传入 PHP_QUERY_RFC3986 常量的时候，空格会编码成 %20。绝大多数HTTP服务都能处理这两种形式，但如果涉及签名校验、缓存键生成或者上游做严格比对，不要赌对方会自动帮你把格式归一化。

$data = ['keyword' => 'php api'];

$formStyle = http_build_query($data);
$rfc3986 = http_build_query($data, '', '&', PHP_QUERY_RFC3986);

// keyword=php+api
// keyword=php%20api

另一个很容易漏掉的细节是 null 处理逻辑。PHP官方文档的示例里，值为 null 的字段不会出现在最终生成的请求字符串里。对于“未传筛选条件”和“传了空字符串”语义完全不同的接口，要在调用前就明确规则：是直接省略这个键、传空值，还是直接抛出参数错误。

错误响应要指出哪个参数不符合协议

下游收到自己不认识的参数格式时，最差的体验就是只返回一句笼统的“请求失败”。更实用的400响应会明确告诉调用方出错的字段名、预期格式和正确示例，比如：

{
  "code": "invalid_query_parameter",
  "field": "tag",
  "message": "tag uses repeated query keys"
}

公开接口没必要把内部解析的细节全暴露出来，但至少要让SDK、前端和后端的开发同学能快速判断是值不对、类型不对还是键名格式不对。参数格式要做调整的时候，先在网关日志里统计旧格式的使用量，再给旧客户端留一段明确的兼容窗口，不要偷偷修改同一个字段的原有含义。

上线前用这四项检查把接口契约钉住

1. 接口文档里写出完整的URL示例，带上两个值的数组参数，不要只写字段类型说明。
2. 测试用例同时覆盖中文、空格、空字符串、null 和两个以上的标签值场景。
3. 如果接口要参与签名或者缓存，固定参数排序规则和编码模式，用断言直接校验最终生成的查询串。
4. 新旧格式不要长期同时存在，明确标记弃用边界，错误响应也要保留足够清晰的提示信息。

一串查询参数看起来很短，却是多个调用方共享的交互边界。先把数组的格式约定清楚，再决定用哪个PHP函数处理，能少很多“本地调试看着完全正常、线上筛选逻辑失效”的问题。

延伸问答

能否直接把数组转成逗号分隔字符串？

可以，但前提是协议里明确写成 tag=php,api，同时约定参数值本身是否允许携带逗号。如果标签值里有可能出现逗号，用重复键或者直接走JSON Body的方式更不容易产生歧义。

http_build_query 适合拼接 POST 的 JSON 请求吗？

不适合。它生成的是经过URL编码的查询字符串。请求体是JSON的时候，要按照API约定的Content-Type和JSON结构做编码，不要把两种数据表示方式混在一起。

parse_str 可以验证对方会怎么解析查询串吗？

可以用它来做PHP侧的回归测试，调用的时候记得传入结果数组参数。它只能验证PHP自己的解析规则，跨语言的接口还是要以协议示例和目标服务的实际测试结果为准。

相关阅读

• PHP PDO fetchAll 内存暴涨怎么办：从全量数组到逐行读取的排查与改造
• PHP 8.4 升级后隐式可空参数为什么报弃用：?string、null 默认值和改造顺序
• MySQL ORDER BY LIMIT 为什么有时不走过滤索引：排序索引、filesort 和核对方法

核对资料

• PHP 官方文档：http_build_query：数组输入、默认编码方式、RFC3986 模式和示例输出。
• PHP 官方文档：parse_str：查询字符串解析与结果数组参数的说明。