ThinkPHP 8.0操作MySQL原生JSON字段需同时满足五条件：MySQL≥5.7、字段类型为JSON、用->>提取纯值、写入前手动json_encode、高频查询建虚拟列+索引；否则查不到数据或报错。
在ThinkPHP 8.0中正确操作MySQL原生JSON字段并构建高效查询，必须同时满足MySQL≥5.7、字段类型为JSON、使用->>语法提取纯值、写入前手动json_encode、高频查询需建虚拟列+索引这五个硬性条件，缺一不可，否则查不到数据或直接报错。
确认JSON字段可用前提
执行SHOW COLUMNS FROM user LIKE 'info';，确认Type列显示json；再执行SELECT VERSION();，确保返回值≥5.7.0。若Type是text或varchar，【不要强行使用->>语法】，否则MySQL会报FUNCTION database.JSON_UNQUOTE does not exist错误。
字段类型不匹配时，改用whereRaw('JSON_EXTRACT(info, "$.email") = ?', [$email])，但注意此处$email必须是带双引号的合法JSON字符串，例如"\"test@example.com\""。
查询JSON对象中的键值
方法一：使用->>语法（推荐）
直接写where('info->>email', 'test@example.com')，MySQL自动调用JSON_UNQUOTE(JSON_EXTRACT(info, "$.email"))，返回无引号纯字符串，可安全用于=、>、LIKE比较。
立即学习“PHP免费学习笔记（深入）”；
方法二：用whereRaw精确控制whereRaw('info->>"$.status" = ?', ['active'])，适合需要嵌套路径或动态拼接的场景，但要自己处理引号和参数绑定。
⚠️切记：where('info->status', 'active')返回的是带引号字符串"active"，PHP中与裸字符串'active'比较永远为false——这是最常踩的坑。
查询JSON数组是否包含某元素
第一步：用户输入必须先转为合法JSON字符串$tag = json_encode($userInput, JSON_UNESCAPED_UNICODE);，否则whereJsonContains('tags', $userInput)会生成JSON_CONTAINS(tags, php)这种非法SQL，MySQL直接报错。
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
第二步：指定JSON路径防止误匹配whereRaw('JSON_CONTAINS(tags, ?, "$.skills")', [$tag])，强制只在skills子数组中查找，避免同名字段（如info.skills和profile.skills）冲突。
第三步：验证结果是否为空数组
即使语法全对，若表中该字段值为null或非JSON格式字符串，JSON_CONTAINS也返回0，查询结果为空——需提前用whereNotNull('tags')过滤。
写入JSON字段的两种方式
方式1：整字段覆盖写入Db::table('user')->json(['info'])->insert(['info' => ['email' => 'a@b.com', 'age' => 25]]);，json(['info'])声明后，框架自动对info值做json_encode并设为UTF-8无转义。
方式2：单键更新（ThinkPHP 8.0+支持）$data['info->nickname'] = 'Tinywan'; Db::name('user')->json(['info'])->where('id', 1)->update($data);，这会生成UPDATE user SET info = JSON_SET(info, "$.nickname", "Tinywan")语句。
⚠️注意：【模型中声明$type = ['info' => 'json']仅适用于TEXT/VARCHAR字段】，若info是原生JSON类型，再加该配置会导致TP重复encode，入库变成"{\"email\":\"a@b.com\"}"这样的双重JSON字符串。
提升JSON查询性能：建虚拟列+索引
对高频查询字段（如info->>status），必须执行两步：
① 添加存储型虚拟列：ALTER TABLE user ADD COLUMN status_text VARCHAR(20) AS (info->>'$.status') STORED;
② 为该列创建普通索引：CREATE INDEX idx_status_text ON user(status_text);
不做这两步，EXPLAIN显示type: ALL，哪怕SQL完全正确，也是全表扫描。虚拟列STORED表示物理存储，比VIRTUAL更利于索引利用。
建好后，查询语句仍用where('info->>status', 'active')，MySQL优化器会自动命中idx_status_text索引。
