PHP数组应作为有契约的数据容器，用关联数组明确语义、嵌套≤2层、空数组表无数据、白名单过滤输入、序列化前净化结构。
PHP 数组是 API 开发中最常用的数据结构，但随意使用容易导致接口混乱、类型不明确、维护困难。关键在于把数组当作有契约的数据容器，而非万能的“筐”。
用关联数组表达资源结构，别用索引数组模拟对象
API 返回用户数据时，应始终用键名明确语义：
- ✅ 推荐：
['id' => 123, 'name' => '张三', 'email' => 'zhang@example.com']—— 键即字段名，前端可直接解构，文档易写易读 - ❌ 避免：
[123, '张三', 'zhang@example.com']—— 顺序依赖强，加个手机号就得改所有调用方，且无法生成 OpenAPI schema
嵌套结构要控制深度，避免“数组套数组套数组”
三级以上嵌套（如 $data['user']['profile']['address']['city']）会让消费方难以预测和测试：
- 保持嵌套 ≤ 2 层：资源主体 + 一级子资源（如
'user' => [...], 'posts' => [...]） - 子资源超 3 个字段或含复杂逻辑时，拆成独立端点（如
/users/123/profile），而非全塞进主响应 - 用空数组
[]表示“无数据”，不用null或缺失键 —— 保证结构稳定，客户端无需反复isset()
输入验证前先规范数组格式，别让脏数据进业务层
客户端传来的 JSON 到 PHP 是 $_POST 或 json_decode($raw, true)，但原始数组可能缺键、类型错、多冗余字段：
立即学习“PHP免费学习笔记（深入）”；
- 用白名单过滤：只保留预定义键（如
array_intersect_key($input, array_flip(['name', 'email', 'age']))） - 强制类型转换：
'age' => (int)($input['age'] ?? 0)，比运行时抛 Notice 更可控 - 对可选数组字段（如
'tags' => ['php', 'api']），检查是否为数组：is_array($input['tags'] ?? null)，再处理
序列化前做一次结构净化，别直接 json_encode($rawArray)
开发中常把调试用的 _debug_info、数据库原始 DateTime 对象、资源句柄等意外塞进响应数组：
- 统一用辅助函数清理：
array_map('strval', $arr)处理简单值；日期转 ISO8601 字符串；对象转 toArray() - 敏感字段（如
'password_hash'）在组装响应数组时就 unset，别依赖前端“自觉不读” - 对分页数据，固定返回
'data'、'meta'两键，不因结果为空而省略'data'—— 客户端解析逻辑不变
数组不是语法糖，而是 API 的协议载体。约束越清晰，集成越顺畅。
