PHP array_is_list 与 JSON 数组对象编码的区别

PHP 里的数组既能表示列表，也能表示带字段名的关联数据。array_is_list() 只负责判断键是否为从 0 到 count($array) - 1 的连续整数；json_encode() 再根据这个结构决定更像 JSON 数组还是 JSON 对象。两者相关，但不是同一个函数。

官方文档：https://www.php.net/manual/en/function.array-is-list.php、https://www.php.net/manual/en/function.json-encode.php

判断接口数据形状时，先看 array_is_list($value) 的键结构，再看 json_encode($value) 的输出；列表通常编码成 []，非列表通常编码成带键的对象，但空数组和 JSON_FORCE_OBJECT 是需要单独记住的边界。

array_is_list 到底检查什么

官方定义很具体：数组只有在键依次为 0、1、直到 count($array) - 1 时，才被视为 list。它检查的是键，不是值的类型，也不是变量名。空数组没有反例，因此 array_is_list([]) 返回 true。

 [],
    'list' => ['red', 'green'],
    'starts-at-one' => [1 => 'red', 2 => 'green'],
    'has-gap' => [0 => 'red', 2 => 'green'],
    'associative' => ['color' => 'red'],
];

foreach ($samples as $name => $value) {
    // array_is_list() 只回答“键是否连续”，不比较元素内容。
    printf("%s: %s%s", $name, array_is_list($value) ? 'list' : 'not-list', PHP_EOL);
}
?>

这里的 list 和 not-list 是示例自行约定的文本。关键在于：['red', 'green'] 的键是 0, 1，而从 1 开始、出现跳号或出现字符串键，都会使结果变成 false。

为什么同样是 PHP array，JSON 结果会不同

json_encode() 会递归把数组或对象转换成 JSON。对于 PHP 数组，连续的列表键通常对应 JSON 数组；非连续或带字符串的键则保留键名，编码成 JSON 对象。

 'red',
    2 => 'green',
];

$record = [
    'primary' => 'red',
    'secondary' => 'green',
];

// 用 JSON_UNESCAPED_UNICODE 只影响中文转义，不改变数组或对象的形状。
echo json_encode($list, JSON_UNESCAPED_UNICODE), PHP_EOL;
echo json_encode($withGap, JSON_UNESCAPED_UNICODE), PHP_EOL;
echo json_encode($record, JSON_UNESCAPED_UNICODE), PHP_EOL;
?>

["red","green"]
{"0":"red","2":"green"}
{"primary":"red","secondary":"green"}

第一个结果是 JSON 数组，因为 PHP 键完整覆盖了 0 和 1。第二个结果虽然键看起来像数字，但缺少 1，所以不能安全地表达为按位置排列的 JSON 数组；json_encode() 保留键并输出对象。

先用 array_is_list 判断，再决定接口字段形状

在接口响应、缓存序列化或日志格式中，最容易出现的变化是删除了一个元素，PHP 数组留下了间隔键，JSON 形状就从数组变成了对象。把判断写在输出边界，可以让这种变化被明确处理，而不是由下游客户端偶然发现。

 $shape, 'data' => $value],
        JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR
    );

    return $json;
}

$items = ['red', 'green'];
unset($items[0]);

// 删除首项后键只剩 1，数据已不是 list；这里不会把它伪装成 JSON 数组。
echo encodeCollection($items), PHP_EOL;
?>

如果业务契约要求 data 永远是 JSON 数组，应该在业务层明确重新组织数据，而不是把 array_is_list() 当作自动修复函数。判断函数只告诉你当前形状，不会替你重新编号、排序或补齐缺失元素。

空数组和 JSON_FORCE_OBJECT 要单独处理

空数组是最容易让人误记的一种情况。array_is_list([]) 是 true，普通的 json_encode([]) 输出 []；如果传入 JSON_FORCE_OBJECT，同一个空数组会被强制编码成 {}。

JSON_FORCE_OBJECT 是编码选项，不是对数组调用 array_is_list() 后得到的结论。若客户端需要区分“无项目的列表”和“无字段的对象”，要把这个约定写进接口文档，并在测试数据里同时覆盖空数组、正常列表和跳号数组。

发布接口前的速查表

可以把这张表当作排查接口响应的第一步：先看 PHP 键，再看是否允许对象形状，最后决定是否在业务层转换数据。不要只看 count()，因为 [0 => 'a', 2 => 'b'] 的数量是 2，但它仍然不是列表。

常见问题

array_is_list() 返回 true，就一定会输出 JSON 数组吗？

在普通 json_encode() 下，连续列表会按 JSON 数组表达；但编码选项仍可能改变结果，例如 JSON_FORCE_OBJECT 会强制数组形式改为对象形式。

数字字符串键会被当成列表位置吗？

不要用“看起来像数字”来推断。列表判断的可靠依据是 PHP 实际保存的键是否严格覆盖从 0 开始的连续整数；应直接调用 array_is_list()，再根据结果设计输出。

删除元素后怎么保证仍是 JSON 数组？

这已经属于业务层的数据整理问题。先明确删除后的顺序和标识语义，再选择重新组织为列表或保留键值对象；不要把编码选项当成修复缺失键的工具。

归纳起来，array_is_list() 是结构判断，json_encode() 是序列化动作。把两者放在接口输出边界一起考虑，就能解释 JSON 数组与对象的切换，也能提前发现删除元素、起点变化和关联键带来的契约风险。