Nette\Schema 是专为 PHP 配置设计的轻量级、类型严格的结构定义与校验工具，核心价值是提前声明配置约束并在运行时立即报错，而非延迟到使用时崩溃；它只校验结构存在性、类型合法性与嵌套格式，不处理业务逻辑规则，可独立于 Nette 框架使用。
什么是 Nette Schema，它和普通数组校验有什么区别
直接说结论：Nette\Schema 是一个轻量但类型严格的配置结构定义与校验工具，不是通用数据验证库（比如 Symfony Validator），也不依赖注解或 YAML schema 文件。它专为 PHP 配置设计，核心价值在于——把 config.php 或 neon 配置的结构约束提前声明，并在运行时立刻报错，而不是等后续代码用到某个缺失字段时才崩。
它不处理业务逻辑校验（比如“密码长度必须大于8”），而是管“这个配置项是否存在”“类型对不对”“嵌套结构是否合法”。常见于 Nette 框架的 Configurator、DI\Container，但完全可以单独使用。
如何定义一个基础配置 Schema 并加载配置文件
假设你有一个 app.neon：
database:
host: localhost
port: 3306
user: root
password: ""
对应 Schema 定义（PHP 代码）：
立即学习“PHP免费学习笔记（深入）”；
use Nette\Schema\Expect;
use Nette\Schema\Schema;
$schema = Expect::structure([
'database' => Expect::structure([
'host' => Expect::string()->required(),
'port' => Expect::int()->default(3306),
'user' => Expect::string()->required(),
'password' => Expect::string()->default(''),
])->required(),
]);
然后加载并校验：
使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。
use Nette\Neon\Neon;
$config = Neon::decode(file_get_contents('app.neon'));
$validated = $schema->validate($config); // 返回 array，已做类型转换和默认值填充
-
Expect::structure()是定义嵌套结构的入口，必须显式调用 -
->required()表示该键必须存在；没加就是可选（但访问时仍可能为null） -
->default(...)在键缺失时提供回退值，且会参与类型检查（比如Expect::int()->default('123')会失败） -
$schema->validate()不修改原数组，返回新数组，所有类型都已强制转换（如"3306"→3306）
常见错误：Schema 校验通过但运行时报错
典型现象是 $validated['database']['port'] 看起来是整数，但实际是 string，或者 undefined index —— 这往往是因为：
- 漏写
->required()，而配置里又恰好没提供该字段，导致校验后该键根本不存在（不是null，是彻底 missing） - 用了
Expect::array()却没进一步约束子项，结果传入了对象或非数组值，校验通过但后续foreach报错 - 配置文件里写了
port: "3306"，Schema 声明为Expect::int()，校验会成功（自动 cast），但如果底层组件明确要求is_int()，某些严格环境可能出问题（比如 PDO DSN 构造） - NEON 文件用了缩进错误或注释格式不兼容（如
#后少了空格），Neon::decode()解析失败，但错误发生在validate()之前，容易误判为 Schema 问题
如何处理动态键名或列表结构
比如配置中要支持多个数据库连接：
databases:
primary:
host: localhost
replica:
host: 192.168.1.10
Schema 写法：
'databases' => Expect::array()
->each(Expect::structure([
'host' => Expect::string()->required(),
'port' => Expect::int()->default(3306),
])),
注意：->each() 是关键，它表示“每个数组元素都必须符合这个 structure”，而不是“整个数组是一个 structure”。如果误写成 Expect::structure(...)->each(...)，会报错。
另外，Expect::list() 和 Expect::array() 有区别：list 要求键是连续数字索引（0,1,2…），array 允许任意字符串键（即 map / associative array）。选错会导致校验失败。
复杂嵌套、条件必填（比如 “如果 type=redis，则 require host+port”）这类需求，Nette\Schema 本身不支持——它不提供条件逻辑。此时要么拆成多个独立 Schema 分别校验，要么在 validate() 后手动补一层业务校验。
