MySQL STATEMENT_DIGEST 遇到无法解析的 SQL 时怎样返回错误

我第一次把 STATEMENT_DIGEST() 放进 SQL 采集链路时，最容易误判的一点是：无法解析的 SQL 不会“返回一个空摘要”，而是直接产生错误。官方文档说明，这个函数和 STATEMENT_DIGEST_TEXT() 都会使用 MySQL parser；解析失败时发生错误，只有参数是字面量字符串时，错误信息才会带上解析错误细节。

官方地址：https://dev.mysql.com/doc/refman/8.4/en/encryption-functions.html

把结果分成三类就不容易写错处理逻辑：参数为 NULL 时结果为 NULL；合法 SQL 得到摘要值；无法解析的 SQL 走数据库错误分支。不要把第三类当成“没有采集到摘要”。

先把返回结果分成 NULL、摘要和错误

我通常先记录一条基线：输入类型、是否能解析、调用是否返回结果、错误是否被客户端捕获。这样比只盯着摘要列是否为空更可靠。一个最小对照可以写成下面这样，SQL 注释只说明每组输入的意图。

-- 合法 SQL：应进入摘要结果分支
SELECT STATEMENT_DIGEST('SELECT id FROM orders WHERE user_id = 10');

-- NULL 输入：结果语义与解析失败不同
SELECT STATEMENT_DIGEST(NULL);

-- 语法不完整：应产生数据库错误，而不是普通 NULL 摘要
SELECT STATEMENT_DIGEST('SELECT FROM orders');

这里的“基线”不是某个固定耗时数字，而是三种输入的结果分类。压测或批量采集时，可以按成功摘要数、NULL 数和解析错误数分别计数；如果三类被合并成一个空值计数，后续就无法判断是数据缺失还是 SQL 本身不完整。

字面量与变量输入的错误细节不是同一层

实际接入时，我更倾向于把待分析 SQL 放在用户变量或应用参数里，而不是把它直接拼进函数调用。这样便于统一处理输入，但要注意：官方手册特别区分了字面量字符串和变量等非字面量输入。前者的错误消息可以包含具体解析错误，后者不要假定一定能拿到同样细的语法位置。

-- 字面量：用于说明文档中的解析错误细节边界
SELECT STATEMENT_DIGEST('SELECT FROM orders');

-- 变量：模拟采集链路中的动态 SQL 输入
SET @sql_text = 'SELECT FROM orders';
SELECT STATEMENT_DIGEST(@sql_text);

我的处理方式是把“数据库返回的错误码/SQLSTATE”和“脱敏后的原始输入摘要”分开记录。不要依赖错误文案做程序分支；MySQL 的错误接口建议程序使用错误码或符号，而不是把可变化的消息文本当作稳定协议。

把失败输入从摘要统计中单独计数

如果你的任务是归一化 SQL 形状，最稳妥的假设是：STATEMENT_DIGEST() 只负责“可解析输入的摘要”，不负责替你修复 SQL。应用层应在调用函数的地方捕获数据库错误，记录输入来源、错误码和脱敏后的样本，然后让这条输入进入失败计数或人工排查队列。

-- 采集表只保存摘要结果；失败输入应由调用方错误处理链路记录
INSERT INTO digest_samples (source_name, digest_value)
SELECT 'api', STATEMENT_DIGEST(@sql_text);

-- 语法错误不会生成正常摘要，调用方应在客户端捕获错误后单独计数
-- 不要用“digest_value IS NULL”代替数据库错误判断

指标上，我会至少保留三个维度：合法输入摘要数、NULL 输入数、解析错误数。改动采集逻辑后，用同一组样本比较三者的数量变化；如果错误数下降只是因为异常被吞掉，摘要覆盖率并没有真正改善。

几个容易混淆的边界

• NULL 不是语法错误。函数对 NULL 参数有独立的返回语义，不能用它代表 parser 失败。
• 摘要值不是原 SQL。它用于归一化识别，不能据此恢复所有原始文本；需要排查时要保留经过脱敏的输入线索。
• 错误文案不是稳定接口。程序分支用错误码或 SQLSTATE，展示层再使用消息文本。
• 不要虚构固定性能数字。解析开销与输入长度、SQL 复杂度和采集频率有关，应在自己的样本上对比，而不是把示例结果写成通用基线。

相关问题

STATEMENT_DIGEST_TEXT() 也会在 SQL 无法解析时返回空字符串吗？

不能这样假设。官方文档把它和 STATEMENT_DIGEST() 放在同一解析语义下；解析失败时应按错误处理，而不是把它当成正常空文本。

为什么变量输入看不到和字面量一样的解析细节？

因为错误信息中包含解析细节的条件与输入是否是字面量有关。变量输入适合动态采集，但应用层应该自行保留脱敏后的输入摘要和稳定错误字段。