处理接口返回的 JSON 数据几乎是每个 PHP 项目的日常操作，但不少人在拿到 json_decode 的结果后就开始踩坑：明明数据就在那里，用 $data->name 取值却直接报错，或者用 $data['name'] 提示 Cannot use object of type stdClass as array。这些问题的根源在于没有弄清楚 json_decode 返回值的类型规则，以及嵌套结构访问方式的选择。本文从底层原理讲到实战写法，帮你彻底理清这个知识点。
json_decode 返回值类型：对象还是数组
首先要理解的是，json_decode 的第二个参数 $assoc 决定了返回值的形态。不传或者传 false 时，JSON 对象会被解码成 PHP 的 stdClass 实例，此时必须用箭头操作符 -> 来访问属性；传 true 时，所有 JSON 对象都会转成关联数组，用方括号语法取值。这是最基础也最容易被忽略的一条规则，很多报错都是因为在对象上调用了数组语法，或者反过来。
$json = '{"name":"Tom","age":28}';
// 默认返回 stdClass 对象
$obj = json_decode($json);
echo $obj->name; // Tom
// 传 true 返回关联数组
$arr = json_decode($json, true);
echo $arr['name']; // Tom
两种方式各有适用场景。对象写法更接近原始 JSON 结构，写起来紧凑；数组写法在遍历、合并、判断键存在时更灵活，而且和 PHP 内置的数组函数无缝配合。实际项目中建议统一使用 true 转数组，可以减少很多心智负担。另外别忘了，解码失败时 json_decode 会返回 null，所以取值前最好先判断 json_last_error() 是否等于 JSON_ERROR_NONE，否则后续所有访问都会在 null 上操作并报错。
访问嵌套数据的正确姿势
JSON 数据往往层层嵌套，比如一个用户对象里包含地址对象，地址对象里又有城市字段。解码成数组后，直接用链式方括号访问即可：$data['user']['address']['city']。如果是对象形式，则写成 $data->user->address->city。关键是要清楚每一层的类型，混合结构在真实接口中非常常见。
$json = '{
"user": {
"name": "Tom",
"address": {
"city": "Shanghai",
"geo": {"lat": 31.23, "lng": 121.47}
}
},
"tags": ["admin", "editor"]
}';
$data = json_decode($json, true);
// 多层嵌套逐级取值
echo $data['user']['address']['geo']['lat']; // 31.23
// 数组下标照常访问
echo $data['tags'][0]; // admin
有一个特殊情况需要注意：JSON 的键名如果包含空格或特殊字符，解码成对象后无法用箭头操作符直接访问，因为属性名不合法。这时要么使用数组形式访问，要么借助花括号语法 $obj->{'user name'}。这也是推荐统一转数组的又一个理由。遍历嵌套结构时，如果层级不固定，可以写一个递归函数逐层处理，遇到标量值就执行业务逻辑，遇到数组或对象就继续下钻。
安全访问：避免 Undefined index 和空指针
真实接口返回的数据不能完全信任，某层键可能缺失，某层可能是 null。直接链式访问缺失的键，PHP 7.x 会抛出 Notice，PHP 8 则直接是 Warning，而且访问 null 的下标会报错 Trying to access array offset on value of type null。安全写法有两种主流方案：老项目用 isset() 逐层判断，新项目直接用空值合并运算符 ??，后者写法简洁且短路特性保证了不会执行无效访问。
// 传统 isset 写法，层层设防
$city = isset($data['user']['address']['city'])
? $data['user']['address']['city']
: '未知城市';
// PHP 7+ 空值合并运算符，推荐
$city = $data['user']['address']['city'] ?? '未知城市';
// 封装一个取值函数，支持默认值
function getValue($arr, $keys, $default = null) {
$cur = $arr;
foreach ((array)$keys as $key) {
if (!is_array($cur) || !array_key_exists($key, $cur)) {
return $default;
}
$cur = $cur[$key];
}
return $cur;
}
$lat = getValue($data, ['user', 'address', 'geo', 'lat'], 0);
封装取值函数的好处是团队可以统一调用方式，日志和调试也更方便。如果项目已引入 Composer 依赖，也可以考虑使用函数式库提供的路径取值能力，但核心思路和上面的 getValue 一致：逐层检查、失败即返回默认值。此外，处理完 JSON 后建议对关键字段做类型校验，比如用 is_numeric、is_string 确认数据形态，避免脏数据流入业务逻辑。
完整实战示例
最后把前面的知识点串起来，模拟一次完整的接口数据处理流程：请求 JSON、校验解码结果、安全取值、处理数组字段。这段代码可以直接用到实际项目中稍加改造。
$raw = file_get_contents('https://api.ipipp.com/user/info');
$data = json_decode($raw, true);
if (json_last_error() !== JSON_ERROR_NONE) {
exit('JSON 解析失败: ' . json_last_error_msg());
}
$user = [
'name' => $data['user']['name'] ?? '游客',
'city' => $data['user']['address']['city'] ?? '未知',
'balance' => (float)($data['account']['balance'] ?? 0),
'roles' => array_values(array_filter($data['user']['roles'] ?? [])),
];
foreach ($user['roles'] as $role) {
echo "角色: {$role}\n";
}
这套写法的要点总结成三句话：解码统一加 true 转数组；取值前确保解码成功；嵌套访问一律用空值合并运算符兜底。养成这几个习惯之后，JSON 相关的取值报错基本可以从项目里清除干净。对于结构特别复杂或者需要频繁变换的 JSON，还可以结合 array_column、usort 等数组函数做二次加工，让数据在进入业务层之前就已经是干净的形态。