PHP数组应语义化键名、控制嵌套≤3层、避免混合结构、统一命名风格、显式表达空值，并配合类型注解提升可读性与可维护性。
PHP 数组结构直接影响代码是否容易理解、维护和协作。结构混乱的数组会让后续开发者（包括未来的你）花大量时间猜键名含义、嵌套层级或数据类型，甚至引发隐性 bug。
键名语义化比“能用”更重要
使用 ['u' => 'admin', 'p' => '123'] 看似省字符，但没人能立刻看出含义；换成 ['username' => 'admin', 'password' => '123']，意图一目了然。尤其在函数返回值、API 响应或配置数组中，清晰键名本身就是文档。
- 避免缩写（如
usr、cfg），除非是团队广泛共识的简写（如ID、URL） - 统一命名风格：全小写+下划线（
user_role）或驼峰（userRole），整个项目保持一致 - 对布尔型字段，用肯定式命名（
is_active比active更安全，避免if ($arr['active'] === false)的歧义）
嵌套层级不宜过深
超过 3 层嵌套（如 $data['response']['body']['items'][0]['meta']['author']['name']）会显著增加阅读负担和出错概率。深层嵌套常源于未及时拆分职责或过度“扁平化失败”。
- 考虑将深层结构拆成独立数组变量（如先提取
$item = $data['response']['body']['items'][0];，再取$item['meta']['author']['name']） - 用对象替代深度数组（如
new User($item['meta']['author'])），让 IDE 能提示属性、类型更明确 - 若必须嵌套，确保每层有明确业务边界（如
['user' => [...], 'permissions' => [...], 'settings' => [...]]），而非随意堆叠
同构数组优先于混合结构
一个索引数组里混着字符串、数字、子数组甚至 null（如 [1, 'pending', ['at' => '2024-01-01'], null]），会让 foreach 循环逻辑臃肿且易漏判。理想情况是每个数组代表单一概念的数据集合。
立即学习“PHP免费学习笔记（深入）”；
- 用关联数组代替“位置约定”：不要依赖
$row[0]是 ID、$row[1]是名称；改用['id' => 1, 'name' => 'xxx'] - 批量数据统一结构：数据库查询结果用
fetch_all(MYSQLI_ASSOC)，避免MYSQLI_NUM导致键名丢失 - 空值显式表达：用
'status' => null或'status' => 'unknown'，而不是留空或跳过键，减少 isset() 判断泛滥
配合类型声明与文档强化可读性
PHP 7.4+ 支持数组键/值类型注解（PHPDoc）和返回类型声明，它们不运行时强制，但极大提升静态分析和 IDE 支持效果。
- 在函数上标注返回结构：
/** @return array{id: int, name: string, tags: string[]} */ - 对配置类使用
array{host: string, port: int}形式，在 PhpStorm 中悬停即见结构 - 关键数组变量加内联注释：
$user = [/* id: int, email: string, roles: string[] */];
数组不是数据容器的默认选项，而是设计决策的结果。花两分钟想清楚结构，比花二十分钟调试 key_exists 错误更高效。
