array_merge_recursive 合并同名键时会将值自动转为数组，即使原值是字符串，这是其设计行为而非 bug；需手动扁平化或改用自定义合并函数。
用 array_merge_recursive 合并时为什么值变数组了
这是最常踩的坑：直接用 array_merge_recursive 合并结构不一致的数组，同名键（比如都叫 name）的值会被自动包进一个数组里，哪怕原来只是字符串。比如 $arr1 = ['user' => ['name' => 'Alice']] 和 $arr2 = ['user' => ['email' => 'a@b.com']] 合并后，$result['user']['name'] 变成 ['Alice'] 而不是 'Alice'。
这不是 bug，是函数设计行为——它优先保全所有数据，不覆盖。如果你后续还要取 $result['user']['name'] 当字符串用，就会报错或逻辑异常。
- 用前先判断目标键是否可能重复：如果确定两个数组的
user结构互斥（一个有name，另一个有email），那没问题；如果都有name，就得手动扁平化，比如用array_shift()取第一个值 - 别依赖返回值类型稳定：合并后要对值做
is_array($v) ? $v[0] : $v这类兜底处理 - 替代方案：改用自定义递归合并函数，遇到同名键且类型冲突时主动选择保留左/右/拼接，而不是交给
array_merge_recursive硬塞
怎么让缺失字段自动填默认值
结构不一致的本质常是「某些数组缺键」。比如一批用户数据，有的带 avatar，有的没有，但业务逻辑要求必须有该字段。硬写 isset($user['avatar']) ?: 'default.png' 太散，容易漏。
推荐封装一个 fillMissingKeys 函数，传入模板数组（含默认值）和待填充数组：
立即学习“PHP免费学习笔记（深入）”；
function fillMissingKeys(array $template, array $data): array {
$result = $data;
foreach ($template as $key => $default) {
if (!array_key_exists($key, $data)) {
$result[$key] = $default;
} elseif (is_array($default) && is_array($data[$key])) {
$result[$key] = fillMissingKeys($default, $data[$key]);
}
}
return $result;
}
- 模板数组结构要和目标层级对齐，比如
['profile' => ['avatar' => 'default.png']] - 只填「不存在的键」，不覆盖已有值，也不修改类型（
$data['id'] = '123'不会因为模板里是0就被转成整数） - 如果默认值是
null，而你想区分「没传」和「明确传了 null」，得加个标记位，比如用NULL_PLACEHOLDER常量代替
字段名不同但语义相同，怎么统一映射
真实场景中更麻烦的是字段名不一致：API A 返回 user_name，API B 返回 full_name，但都是用户名。这时候不能靠合并或填空，得做语义对齐。
建一张键映射表，把不同来源的字段路径映射到统一模型字段：
$map = [
'name' => ['user_name', 'full_name', 'displayName'],
'email' => ['user_email', 'mail', 'contact.email'],
];
- 提取时遍历映射表，对每个目标字段（如
name），按顺序查源数组是否存在对应路径，找到第一个就用：array_key_exists('user_name', $src) ? $src['user_name'] : ($src['full_name'] ?? '') - 路径支持点号嵌套，比如
'contact.email'需要额外写个getNestedValue($arr, 'contact.email')辅助函数 - 映射表本身可配置化，不同数据源加载不同规则，避免硬编码散落在各处
结构差异太大时，别硬合并，先标准化再操作
当两个数组像「JSON API 响应」和「数据库查询结果」那样根本不是一个物种时，强行用 array_merge_recursive 或填空只会让代码越来越难维护。
真正省事的做法是：在入口处就把它转成统一结构。比如定义一个 UserModel 数组格式，所有外部数据进来第一件事就是调用 normalizeToUserModel($raw) 转换。
- 转换函数内部用上面提到的映射 + 填空 + 类型转换组合，一次收口
- 后续所有业务逻辑（排序、过滤、导出）都基于这个标准结构写，不用再关心来源差异
- 如果某天新增一个数据源，只改
normalizeToUserModel一个函数，其他代码完全不动
结构不一致问题最难缠的点不在技术实现，而在边界模糊——没人说清「哪些字段必须有」「哪些可以缺」「同义字段以谁为准」。动手前先和产品/接口方对齐这些规则，比写十个递归函数都管用。
