MySQL 8.0+ 查询 JSON 字段最稳用 whereJsonContains，它底层调用 JSON_CONTAINS，要求字段为原生 JSON 类型；查数组元素如 ['admin'] 或嵌套对象如 ['country' => 'CN'] 均可，但不支持模糊匹配，空值、null 或非 JSON 字符串会导致查询失效。
直接用 whereJsonContains 或 whereRaw 查 JSON 字段，但必须清楚字段类型、数据库驱动限制和 Laravel 版本差异——否则查不到数据或报错。
MySQL 8.0+ 的 JSON 字段查询：用 whereJsonContains 最稳
MySQL 原生支持 JSON 函数，Laravel 封装了 whereJsonContains，它底层调用 JSON_CONTAINS，适合查数组元素或对象子值。
- 查 JSON 数组中是否含某个 ID：
->whereJsonContains('permissions', 'admin')（permissions是JSON类型字段，值如["user","admin"]） - 查嵌套对象的字段值：
->whereJsonContains('profile', ['country' => 'CN'])（profile值如{"name":"A","country":"CN"}） - 不支持模糊匹配或正则；若要查
country以C开头，得换whereRaw - 字段必须是 MySQL 的
JSON类型，不是TEXT；否则JSON_CONTAINS返回NULL，查询失效
PostgreSQL 或旧版 MySQL：用 whereRaw + 数据库原生函数
PostgreSQL 用 ->> 提取文本，MySQL 5.7 用 JSON_EXTRACT，Laravel 不封装这些，只能手写 whereRaw。
- PostgreSQL 示例（查
settings->>'theme'等于dark）：->whereRaw("settings->>'theme' = ?", ['dark']) - MySQL 5.7 示例（查
config中timeout大于 30）：->whereRaw('JSON_EXTRACT(config, "$.timeout") > ?', [30]) - 注意单引号双引号：MySQL 的 JSON 路径字符串必须用双引号，如
"$.timeout"；PostgreSQL 的->>右侧键名用单引号 - 所有
whereRaw参数必须用?占位并传入数组，否则 SQL 注入风险拉满
模型访问器里解析 JSON？别在查询时做
有人在模型里加 getMetadataAttribute 访问器自动 json_decode，这会导致两个问题：一是访问器只对已查出的数据生效，无法用于 where 查询；二是如果字段是 TEXT 类型且未 cast，Eloquent 默认当字符串处理，访问器才起作用——但你没法拿访问器结果去 where。
- 想按 JSON 内容筛选，必须在数据库层查，不能靠 PHP 解码后 in_array 或 foreach
- 如果字段定义了
$casts = ['metadata' => 'array']，那$model->metadata是数组，但Model::where('metadata', ...)还是查原始字符串，行为不一致，极易踩坑 - 真正需要“查完再结构化”的场景，用
map或transform在集合上处理，而不是塞进查询条件
JSON 字段为空或 null 时的查询陷阱
whereJsonContains 对 null、空对象 {}、空数组 [] 全部返回 false，但 whereRaw 行为取决于数据库——比如 MySQL 的 JSON_CONTAINS(NULL, ...) 直接返回 NULL，导致整条记录被过滤掉。
- 明确业务是否允许空值：若允许，查之前先
whereNotNull('field')或where('field', '!=', 'null') - MySQL 中
"null"（字符串）和NULL（数据库空值）完全不同；插入时若传了字符串"null"，JSON_CONTAINS会报Invalid JSON text - 最保险的做法：统一约定空 JSON 存为
{}，并在迁移里设默认值DB::raw('(JSON_OBJECT())')（MySQL 5.7+）或'{}'
JSON 查询的关键不在 PHP 层多绕几道，而在清楚数据库能做什么、字段存的是什么、Laravel 封装到哪一层——漏掉任一环，whereJsonContains 就像没写。
