MySQL IS_UUID 返回一为什么不代表对应业务记录存在

排查一个“按 UUID 查不到业务记录”的接口时，最容易误判的是把 IS_UUID(input) = 1 当成“这条记录存在”。实际上，MySQL 的 IS_UUID() 只判断传入值能否按允许的字符串格式解析为 UUID：格式合法返回 1，格式不合法返回 0，传入 NULL 时返回 NULL。它不会读取业务表，也不会确认任何订单、用户或设备已经使用这个值。

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

因此，IS_UUID() 返回 1 只能说明“这个输入像一个合法 UUID”，不能说明“对应业务记录存在”。真正的存在性必须由业务表上的精确查询、唯一键约束和必要的状态条件共同判断。

影响面：格式校验通过，但业务查询返回空集

这类故障通常表现为接口先通过参数校验，随后返回“资源不存在”或空结果。日志里能看到 IS_UUID('6ccd780c-baba-1026-9564-5b8c656024db') 得到 1，但 orders、users 或 devices 表没有匹配行。两条结论并不矛盾：前者是字符串分类结果，后者是当前数据集上的查找结果。

把问题拆成两条独立证据，排查会更快：

时间线：先通过输入校验，后在业务表中找不到行

一次典型请求可以还原为下面的事实顺序，但这里的“时间线”是故障复盘叙事，不代表 IS_UUID() 内部执行了查询：

1. 客户端提交一个带连字符的 UUID 字符串。
2. 参数层调用 IS_UUID(input)，得到 1，请求继续向下处理。
3. 数据访问层使用该值查询业务表，结果集为空。
4. 接口把空结果映射为“资源不存在”，于是开发者误以为 MySQL 前后结论冲突。

真正的分界点在第二步和第三步之间：格式校验只决定输入能否进入后续处理，业务查询才决定当前数据中是否存在对应记录。

触发条件：合法 UUID 与业务主键不是同一件事

官方手册允许多种可解析写法，包括带连字符的形式、不带连字符的 32 位十六进制形式，以及用大括号包裹的形式。字母大小写也不改变“可解析”这一判断。下面的示例只用于观察返回值，不代表表里已有任何数据。

-- 这些表达式只检查字符串形状，不读取业务表
SELECT
    IS_UUID('6ccd780c-baba-1026-9564-5b8c656024db') AS dashed_uuid,
    IS_UUID('6ccd780cbaba102695645b8c656024db') AS compact_uuid,
    IS_UUID('{6ccd780c-baba-1026-9564-5b8c656024db}') AS braced_uuid,
    IS_UUID(NULL) AS null_input,
    IS_UUID('6ccd780c-baba-1026-9564-5b8c6560') AS short_value;

预期语义是前三个格式返回 1，NULL 保持为 NULL，长度不足的值返回 0。即使第一列返回 1，数据库也没有因此创建或查找一条业务记录。格式合法只是一项输入属性，不能替代业务键映射、租户范围、软删除状态或权限范围。

根因：把“可解析”误当成“存在”

根因通常不是 IS_UUID() 失效，而是校验层和数据访问层承担了不同职责却共用了一个布尔变量。例如下面的写法把格式判断当成了资源存在判断，日志只能告诉我们输入像 UUID，无法告诉我们查询是否命中：

-- 错误边界：格式通过就直接当成资源存在
SELECT IS_UUID(:input) AS resource_exists;

-- 正确边界：先判断格式，再让业务表回答是否命中
SELECT
    u.id,
    u.external_uuid,
    u.status
FROM app_user AS u
WHERE u.external_uuid = :input
  AND u.tenant_id = :tenant_id
  AND u.deleted_at IS NULL;

第二个查询仍然可能返回 0 行，这恰恰是有价值的事实：输入格式合法，但在指定租户、未删除范围内没有对应用户。若业务采用二进制 UUID 存储，则还要让查询两侧使用同一种转换规则，不能拿字符串直接和 VARBINARY(16) 字段比较。

修复动作：把格式、规范化和存在性分成三次判断

修复时可以将请求处理拆成三个明确边界。第一步处理三值结果；第二步决定是否把大括号、大小写或无连字符形式归一化；第三步才访问业务表。

-- 先把 NULL、非法格式和合法格式分开记录
SELECT CASE
    WHEN :input IS NULL THEN 'missing'
    WHEN IS_UUID(:input) = 0 THEN 'invalid_format'
    WHEN IS_UUID(:input) = 1 THEN 'valid_format'
    ELSE 'unknown'
END AS input_state;

-- 字符串列按约定保存规范形式后，再做业务存在性查询
SELECT EXISTS (
    SELECT 1
    FROM app_user AS u
    WHERE u.external_uuid = LOWER(:canonical_uuid)
      AND u.tenant_id = :tenant_id
      AND u.deleted_at IS NULL
) AS record_exists;

如果系统允许多种外部写法，应在应用层或入库边界生成一个明确的规范值，并把“原始输入”和“规范值”分开记录。不要临时在不同查询里分别去掉连字符、转换大小写、包裹函数，导致索引使用和业务含义不一致。

若使用二进制存储，可以让字符串 UUID 先经过 UUID_TO_BIN()，再和二进制列比较：

-- 二进制列的比较必须与写入时采用同一 swap 约定
SELECT id, status
FROM app_user
WHERE uuid_bin = UUID_TO_BIN(:canonical_uuid, 1)
  AND tenant_id = :tenant_id;

这里的第二个参数不是装饰项：如果写入时使用了时间部分交换，查询时也必须使用相同约定，否则即使输入格式正确，也可能得到空结果。

防复发：日志和约束要记录真正的判定结果

防止同类误判，至少保留以下信息：

• 输入状态：missing、invalid_format 或 valid_format，不要只记录一个“校验成功”。
• 规范化策略：是否允许大括号、无连字符和大小写差异，以及字符串 UUID 与二进制 UUID 的存储约定。
• 业务查询结果：命中行数、租户范围、软删除过滤和状态过滤，明确区分“格式合法但未命中”。
• 数据约束：业务 UUID 列按实际唯一范围建立唯一索引；如果唯一性只在租户内成立，就把租户列纳入约束设计。

一个简洁的复盘结论是：IS_UUID() 可以挡住明显格式错误，却不能替代 SELECT、EXISTS 或唯一键。把这三层证据分别写入日志，下一次看到“返回 1 但查不到”时，就能直接判断是数据不存在、租户范围不对、规范化不一致，还是二进制转换约定不一致。

相关问题

IS_UUID(NULL) 为什么不是 0？

因为参数是 SQL NULL，表示缺失或未知值；官方定义返回 NULL。接口层通常应把它单独映射为“未提供”，不要把缺失值和格式错误混在一起。

IS_UUID 返回 1 后还需要查表吗？

需要。只有业务表查询或等价的数据访问逻辑才能判断当前业务范围内是否存在记录。

为什么 UUID_TO_BIN 的参数必须保持一致？

当写入时使用时间部分交换，读取时也应使用相同的交换约定；两侧不一致会得到不同的二进制排列，格式判断仍可能为 1，但索引查询无法命中。