比较 sys.format_bytes 与内置 FORMAT_BYTES 的单位和迁移注意事项

如果你的监控视图、容量报表或诊断 SQL 还在调用 sys.format_bytes()，迁移方向很明确：在支持内置函数的 MySQL 版本中改用 FORMAT_BYTES()。两者都把字节数转换成人类可读字符串，但不能把它们当成完全相同的文本函数，尤其要注意 EiB 单位和旧报表的固定字符串判断。

官方地址：https://dev.mysql.com/doc/refman/8.4/en/performance-schema-functions.html#function_format-bytes

本文只讨论从旧 sys 函数迁移到内置函数，不讨论原始字节值排序。排序时仍应使用数值列，而不是格式化后的字符串。

先看清两个函数的调用范围

sys.format_bytes() 是 sys schema 中的存储函数，调用时通常要写出 sys. 前缀；内置 FORMAT_BYTES() 属于 MySQL 的 Performance Schema 函数，可以在任意 schema 中直接调用。MySQL 8.4 文档已经将 sys 版本标记为弃用，并建议应用迁移到内置版本。

官方地址：https://dev.mysql.com/doc/refman/8.4/en/sys-format-bytes.html

-- 旧写法：依赖 sys schema 中的存储函数
SELECT sys.format_bytes(total_bytes) AS readable_size
FROM storage_summary;

-- 新写法：使用内置函数，不需要 sys. 前缀
SELECT FORMAT_BYTES(total_bytes) AS readable_size
FROM storage_summary;

如果 SQL 是视图、存储过程或应用内的固定模板，优先检查函数名是否被字符串拼接、权限配置或单元测试断言引用。单纯把函数名替换掉，通常不会改变列名，但可能改变极大字节数的单位文本。

单位相同的地方与真正不同的地方

两种函数都以 1024 为进位基准：较小的数显示为 bytes，再依次进入 KiB、MiB、GiB、TiB 和 PiB。内置 FORMAT_BYTES() 还会继续使用 EiB，这是迁移时最容易漏掉的差异。

例如，MySQL 8.4 官方示例中，FORMAT_BYTES(512) 返回 512 bytes；对很大的无符号字节计数，内置函数可以返回带 EiB 的结果，而 sys.format_bytes() 的对应示例最高显示为 PiB。因此，旧程序若只允许 bytes|KiB|MiB|GiB|TiB|PiB，迁移后要补上 EiB，或者把单位解析改成不依赖固定枚举。

另外，两个函数都把 NULL 输入保留为 NULL。这和把缺失值格式化成“0 bytes”不是一回事，报表层不要用无条件的 COALESCE 改写业务含义。

迁移报表和视图时，先保留数值列

容量报表最好同时保留原始数值和展示列。原始列用于排序、阈值判断和二次计算，格式化列只负责给人阅读。这样即使内置函数在极大值上显示 EiB，也不会破坏业务排序。

-- 原始字节列负责排序，格式化列只负责展示
SELECT
    object_name,
    total_bytes,
    FORMAT_BYTES(total_bytes) AS total_bytes_text
FROM storage_summary
ORDER BY total_bytes DESC;

-- 迁移旧视图时只替换显示表达式，保留原始列和列别名
CREATE OR REPLACE VIEW storage_report AS
SELECT
    object_name,
    total_bytes,
    FORMAT_BYTES(total_bytes) AS readable_size
FROM storage_summary;

如果下游接口把展示字符串当作协议字段，迁移前应搜索以下几类耦合：按单位后缀分支、正则只接受 PiB、快照测试写死小数位、以及把展示列再次转换成数字。能改成传原始数值和单位字段的，优先拆开；暂时不能改的，至少增加 EiB 兼容分支。

上线前的迁移清单

1. 把 sys.format_bytes() 的调用点替换为 FORMAT_BYTES()，同时保留原有列别名。
2. 确认执行环境支持该内置函数，不要把函数迁移和跨大版本升级混成一次不可回滚的改动。
3. 用小于 1024、跨越 1024 边界、极大值和 NULL 四组输入更新快照测试。
4. 检查接口、前端和导出脚本是否把单位当成固定枚举，特别是是否遗漏 EiB。
5. 确认排序和阈值判断使用原始数值列；格式化字符串只放在展示位置。

一句话总结：迁移的主线不是把 sys. 删除这么简单，而是确认调用范围、接受 EiB 新单位，并让业务逻辑继续依赖原始字节数。

相关问题

FORMAT_BYTES() 使用十进制 1000 还是二进制 1024？

按 MySQL 8.4 文档的单位表，它使用 1024 的二进制进位，并用 KiB、MiB、GiB 等单位标识。

能不能用格式化后的列做容量排序？

不建议。格式化结果是带单位的字符串，正确做法是按原始字节数排序，再把 FORMAT_BYTES() 的结果作为展示列。

迁移后发现下游不认识 EiB 怎么办？

先让下游按数值和单位分离的结构接收；如果短期只能接收字符串，就明确增加 EiB 分支，并保留原始数值字段用于回溯。