Dragonfly 与 Redis 的关键行为差异指南字符串边界、过期时间与 Lua 脚本【免费下载链接】dragonflyA modern replacement for Redis and Memcached项目地址: https://gitcode.com/GitHub_Trending/dr/dragonfly本文基于 Dragonfly 官方文档 docs/differences.md系统梳理 Dragonfly 与 Redis 在字符串长度与索引、过期TTL/EXPIRE语义、以及 Lua 脚本运行时这三个维度的行为差异。Dragonfly 是一个定位为 A modern replacement for Redis and Memcached 的内存数据库它在绝大多数命令上保持与 Redis 协议兼容但在少数边界语义上做了有意的取舍与扩展。读完本文你将清楚了解哪些用法在迁移到 Dragonfly 时需要特别留意、哪些用法反而是 Dragonfly 相对 Redis 的增强能力。字符串长度与索引范围差异字符串大小上限256MBDragonfly 将单个字符串String值的大小限制为256MB。这意味着所有以字符串为载体的命令SET、SETRANGE、APPEND、GETRANGE等在处理超过 256MB 的数据时都会受到该上限约束。该限制在源码与测试中有多处印证src/server/string_family_test.cc 中的测试注释明确写道 we support only 256MB string并注释掉了SETRANGE到268435456即 2^28 字节 256MB偏移量的用例src/server/bitops_family_test.cc 中针对位操作的测试也指出 2200000000 bits 275MB, above the 256MB cap确认对超出上限的操作会按 256MB 封顶处理从底层存储看src/server/tiering/external_alloc.h 与 src/server/tiering/external_alloc.cc 表明外置存储按256MB 一个 segment组织字符串上限与段粒度保持对齐。迁移建议如果你的应用依赖超过 256MB 的单个字符串值例如超大缓存对象直接塞进一个 key在 Dragonfly 上需要改为分片存储或改用其他数据结构承载。GETRANGE / SETRANGE 的索引类型GETRANGE、SETRANGE等命令的索引参数必须是有符号 32 位整数取值范围为[-2147483647, 2147483648]。超出该范围的索引会被拒绝或按边界处理而不是像 Redis 那样接受更宽的整数。src/server/string_family_test.cc 中对GETRANGE/SETRANGE的边界行为做了充分覆盖例如负索引从字符串尾部计数、start end时返回空串、SETRANGE偏移超过当前长度时以零字节填充等。SORT 不区分 localeSORT命令在排序字符串时不考虑任何 locale区域设置即按固定的字节序比较而不是按语言/区域的字典序排序。这与 Redis 的行为一致Redis 同样不按 locale 排序文档在此特别列出是为了提醒依赖 locale 感知排序的应用Dragonfly 不提供 locale-aware 的SORT语义如果需要语言化排序请在客户端自行处理。过期Expire语义差异EXPIRE 系列命令的 NX/GT/LT 组合有意的扩展Dragonfly 的EXPIRE、PEXPIRE、EXPIREAT、PEXPIREAT允许NX 与 GT 或 LT 同时出现而 Redis 会拒绝这些组合视为不兼容。具体语义如下当 key没有过期时间时NX 生效即按 NX 语义设置过期时间当 key已有过期时间时忽略 NX仅由GT 或 LT单独决定——GT 表示仅当新过期时间晚于当前过期时间才设置LT 表示仅当新过期时间早于当前过期时间才设置。该扩展并非文档的孤证在实现中有明确的注释标注。查看 src/server/generic_family.cc 的ParseExpireArgs// NX with GT/LT is allowed as a deliberate extension, see docs/differences.md. if ((args.flags ExpireFlags::EXPIRE_NX) (args.flags ExpireFlags::EXPIRE_XX)) parser-ReportCustom(NX and XX, GT or LT options at the same time are not compatible); if ((args.flags ExpireFlags::EXPIRE_GT) (args.flags ExpireFlags::EXPIRE_LT)) parser-ReportCustom(GT and LT options at the same time are not compatible);可以看到NX 与 XX 组合、GT 与 LT 组合仍然是被拒绝的只有 NX GT 或 NX LT 这种组合被放行且源码注释直接指向本文档docs/differences.md作为设计依据。在底层执行层面src/server/db_slice.cc 的UpdateExpire也对这一扩展做了逐字对应的注释与实现// Every given flag must hold. Exception: NX with GT/LT (deliberate extension) sets the // expiry when there is none, otherwise GT/LT alone decides. int32_t opts params.expire_options; if ((opts ExpireFlags::EXPIRE_NX) (opts (ExpireFlags::EXPIRE_GT | ExpireFlags::EXPIRE_LT))) { opts has_expire ? opts ~ExpireFlags::EXPIRE_NX : int32_t{ExpireFlags::EXPIRE_ALWAYS}; }即当 NX 与 GT/LT 并存时若 key 已有过期时间则剥离 NX 位由 GT/LT 决定若 key 无过期时间则退化为无条件设置。使用示例EXPIRE key 100 NX GT表示仅当 key 不存在过期时间时设置为 100 秒或者若已有过期时间仅当 100 秒晚于当前过期时间时更新。这类组合在 Redis 上会直接报错在 Dragonfly 上则可正常执行迁移时需要注意这一增强行为。过期时间上限约 8 年毫秒精度命令静默降精度Dragonfly 的过期时间被限制在8 年以内。具体地源码中定义了src/server/common.hconstexpr int64_t kMaxExpireDeadlineSec (1u 28) - 1; // 8.5 years constexpr int64_t kMaxExpireDeadlineMs kMaxExpireDeadlineSec * 1000;即相对过期时间的上限为 2^28 - 1 秒约 8.5 年。对于PEXPIRE、PSETEX 这类毫秒精度命令当设置的过期时间大于 2^28 毫秒约 3 天多不2^28 ms ≈ 3.1 天需按秒级上限处理时会被静默四舍五入到最近的秒引入的精度损失小于 0.001%。实现上src/server/db_slice.cc 的ExpireParams构造函数处理了静默封顶逻辑当cap为真且毫秒值超过kMaxExpireDeadlineMs时直接钳制到该上限该上限是整秒的整数倍因此毫秒精度在此被丢弃if (cap now_ms 0 ms_value kMaxExpireDeadlineMs) { ms_value kMaxExpireDeadlineMs; }而绝对时间戳EXPIREAT/PEXPIREAT与相对 TTL 的行为有所不同测试 src/server/generic_family_test.cc 验证了两类边界巨大的绝对时间戳会溢出kMaxExpireDeadlineMs上限命令返回OUT_OF_RANGE错误巨大的相对 TTL会被静默封顶到kMaxExpireDeadlineSec约 8.5 年随后TTL/PTTL返回该封顶值。// Huge absolute timestamps overflow the kMaxExpireDeadlineMs cap and surface OUT_OF_RANGE. // Huge relative TTLs are silently capped to kMaxExpireDeadlineSec (~8.5 years). EXPECT_EQ(CheckedInt({ttl, key}), kMaxExpireDeadlineSec); EXPECT_THAT(Run({pexpire, key, absl::StrCat(int64_t{kMaxExpireDeadlineMs} * 10)}), IntArg(1)); EXPECT_EQ(CheckedInt({pttl, key}), kMaxExpireDeadlineMs);迁移建议如果你在 Redis 上设置了远超 8 年的过期时间例如使用绝对时间戳做永不过期的替代方案在 Dragonfly 上要么改用PERSIST要么接受 8.5 年上限同时注意绝对时间戳形式在超限时会报错而相对 TTL 是静默封顶。Lua 脚本运行时差异Dragonfly 内置的 Lua 解释器版本为Lua 5.4.42022 年发布而 Redis 长期使用的 Lua 5.1 已经较为陈旧。这一版本升级带来最直接的差异是Dragonfly 的 Lua 脚本支持 Lua 5.4 的整数类型integer包括math.maxinteger、math.mininteger、整数除法//、位运算等 5.3 特性这也是 Redis 社区长期讨论的 lua integers 议题所倡导的方向。在实现层面src/core/interpreter.cc 的错误提示直接引用了 Lua 5.4 官方手册的整数语义章节同时 src/core/interpreter.cc 展示了浮点转整数时对lua_Integer边界INT64_MIN/INT64_MAX的显式检查if (abs(fractpart) kConvertEps intpart double(std::numeric_limitslua_Integer::max()) intpart std::numeric_limitslua_Integer::min()) lua_pushinteger(lua_, static_castlua_Integer(d));此外interpreter.cc还通过luaopen_base、luaopen_table等标准库加载方式初始化运行时src/core/interpreter.cc并在脚本执行中对math.randomstring等扩展函数设置了明确的资源上限如单次随机字符串 16MiB、单次最多 32k 个随机串见 src/core/interpreter.cc防止脚本过度消耗内存。迁移建议如果迁移过来的 Redis Lua 脚本依赖 5.1 的老式行为例如math.random的种子行为、浮点/整数隐式转换的差异建议先用 Dragonfly 的EVAL做一遍脚本回归测试反之如果你此前受困于 Lua 5.1 缺少 64 位整数Dragonfly 的 5.4.4 会带来更自然的整数处理能力。总结迁移前需要对照的三张差异清单维度Redis 行为Dragonfly 行为迁移关注点字符串大小上限 512MB上限256MB超大字符串值需重新设计GETRANGE/SETRANGE 索引64 位有符号整数有符号 32 位[-2147483647, 2147483648]超大偏移量用法需调整SORT 排序无 locale 感知无 locale 感知文档明确列出语言化排序需在客户端实现EXPIRE NXGT/LT拒绝该组合允许无过期时 NX 生效有过期时 GT/LT 决定属于增强特性注意行为差异NXXX、GTLT拒绝同样拒绝与 Redis 保持一致过期时间上限无明确 8 年限制约8 年2^28-1 秒相对 TTL 静默封顶绝对时间戳超限报OUT_OF_RANGE毫秒精度命令超 2^28ms 静默降精度0.001%超长过期时间需改用PERSISTLua 运行时Lua 5.1Lua 5.4.4支持整数类型math.maxinteger等5.1 老脚本需回归测试可受益于整数能力Dragonfly 与 Redis 的协议兼容度很高真正的差异集中在上述少数边界语义上。无论是从 Redis 迁移到 Dragonfly还是双写/混合部署建议将本文的差异点整理进自己的兼容性测试矩阵并参照 docs/differences.md 与 tests/dragonfly 下的测试用例做针对性验证。【免费下载链接】dragonflyA modern replacement for Redis and Memcached项目地址: https://gitcode.com/GitHub_Trending/dr/dragonfly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Dragonfly 与 Redis 的关键行为差异指南：字符串边界、过期时间与 Lua 脚本
Dragonfly 与 Redis 的关键行为差异指南字符串边界、过期时间与 Lua 脚本【免费下载链接】dragonflyA modern replacement for Redis and Memcached项目地址: https://gitcode.com/GitHub_Trending/dr/dragonfly本文基于 Dragonfly 官方文档 docs/differences.md系统梳理 Dragonfly 与 Redis 在字符串长度与索引、过期TTL/EXPIRE语义、以及 Lua 脚本运行时这三个维度的行为差异。Dragonfly 是一个定位为 A modern replacement for Redis and Memcached 的内存数据库它在绝大多数命令上保持与 Redis 协议兼容但在少数边界语义上做了有意的取舍与扩展。读完本文你将清楚了解哪些用法在迁移到 Dragonfly 时需要特别留意、哪些用法反而是 Dragonfly 相对 Redis 的增强能力。字符串长度与索引范围差异字符串大小上限256MBDragonfly 将单个字符串String值的大小限制为256MB。这意味着所有以字符串为载体的命令SET、SETRANGE、APPEND、GETRANGE等在处理超过 256MB 的数据时都会受到该上限约束。该限制在源码与测试中有多处印证src/server/string_family_test.cc 中的测试注释明确写道 we support only 256MB string并注释掉了SETRANGE到268435456即 2^28 字节 256MB偏移量的用例src/server/bitops_family_test.cc 中针对位操作的测试也指出 2200000000 bits 275MB, above the 256MB cap确认对超出上限的操作会按 256MB 封顶处理从底层存储看src/server/tiering/external_alloc.h 与 src/server/tiering/external_alloc.cc 表明外置存储按256MB 一个 segment组织字符串上限与段粒度保持对齐。迁移建议如果你的应用依赖超过 256MB 的单个字符串值例如超大缓存对象直接塞进一个 key在 Dragonfly 上需要改为分片存储或改用其他数据结构承载。GETRANGE / SETRANGE 的索引类型GETRANGE、SETRANGE等命令的索引参数必须是有符号 32 位整数取值范围为[-2147483647, 2147483648]。超出该范围的索引会被拒绝或按边界处理而不是像 Redis 那样接受更宽的整数。src/server/string_family_test.cc 中对GETRANGE/SETRANGE的边界行为做了充分覆盖例如负索引从字符串尾部计数、start end时返回空串、SETRANGE偏移超过当前长度时以零字节填充等。SORT 不区分 localeSORT命令在排序字符串时不考虑任何 locale区域设置即按固定的字节序比较而不是按语言/区域的字典序排序。这与 Redis 的行为一致Redis 同样不按 locale 排序文档在此特别列出是为了提醒依赖 locale 感知排序的应用Dragonfly 不提供 locale-aware 的SORT语义如果需要语言化排序请在客户端自行处理。过期Expire语义差异EXPIRE 系列命令的 NX/GT/LT 组合有意的扩展Dragonfly 的EXPIRE、PEXPIRE、EXPIREAT、PEXPIREAT允许NX 与 GT 或 LT 同时出现而 Redis 会拒绝这些组合视为不兼容。具体语义如下当 key没有过期时间时NX 生效即按 NX 语义设置过期时间当 key已有过期时间时忽略 NX仅由GT 或 LT单独决定——GT 表示仅当新过期时间晚于当前过期时间才设置LT 表示仅当新过期时间早于当前过期时间才设置。该扩展并非文档的孤证在实现中有明确的注释标注。查看 src/server/generic_family.cc 的ParseExpireArgs// NX with GT/LT is allowed as a deliberate extension, see docs/differences.md. if ((args.flags ExpireFlags::EXPIRE_NX) (args.flags ExpireFlags::EXPIRE_XX)) parser-ReportCustom(NX and XX, GT or LT options at the same time are not compatible); if ((args.flags ExpireFlags::EXPIRE_GT) (args.flags ExpireFlags::EXPIRE_LT)) parser-ReportCustom(GT and LT options at the same time are not compatible);可以看到NX 与 XX 组合、GT 与 LT 组合仍然是被拒绝的只有 NX GT 或 NX LT 这种组合被放行且源码注释直接指向本文档docs/differences.md作为设计依据。在底层执行层面src/server/db_slice.cc 的UpdateExpire也对这一扩展做了逐字对应的注释与实现// Every given flag must hold. Exception: NX with GT/LT (deliberate extension) sets the // expiry when there is none, otherwise GT/LT alone decides. int32_t opts params.expire_options; if ((opts ExpireFlags::EXPIRE_NX) (opts (ExpireFlags::EXPIRE_GT | ExpireFlags::EXPIRE_LT))) { opts has_expire ? opts ~ExpireFlags::EXPIRE_NX : int32_t{ExpireFlags::EXPIRE_ALWAYS}; }即当 NX 与 GT/LT 并存时若 key 已有过期时间则剥离 NX 位由 GT/LT 决定若 key 无过期时间则退化为无条件设置。使用示例EXPIRE key 100 NX GT表示仅当 key 不存在过期时间时设置为 100 秒或者若已有过期时间仅当 100 秒晚于当前过期时间时更新。这类组合在 Redis 上会直接报错在 Dragonfly 上则可正常执行迁移时需要注意这一增强行为。过期时间上限约 8 年毫秒精度命令静默降精度Dragonfly 的过期时间被限制在8 年以内。具体地源码中定义了src/server/common.hconstexpr int64_t kMaxExpireDeadlineSec (1u 28) - 1; // 8.5 years constexpr int64_t kMaxExpireDeadlineMs kMaxExpireDeadlineSec * 1000;即相对过期时间的上限为 2^28 - 1 秒约 8.5 年。对于PEXPIRE、PSETEX 这类毫秒精度命令当设置的过期时间大于 2^28 毫秒约 3 天多不2^28 ms ≈ 3.1 天需按秒级上限处理时会被静默四舍五入到最近的秒引入的精度损失小于 0.001%。实现上src/server/db_slice.cc 的ExpireParams构造函数处理了静默封顶逻辑当cap为真且毫秒值超过kMaxExpireDeadlineMs时直接钳制到该上限该上限是整秒的整数倍因此毫秒精度在此被丢弃if (cap now_ms 0 ms_value kMaxExpireDeadlineMs) { ms_value kMaxExpireDeadlineMs; }而绝对时间戳EXPIREAT/PEXPIREAT与相对 TTL 的行为有所不同测试 src/server/generic_family_test.cc 验证了两类边界巨大的绝对时间戳会溢出kMaxExpireDeadlineMs上限命令返回OUT_OF_RANGE错误巨大的相对 TTL会被静默封顶到kMaxExpireDeadlineSec约 8.5 年随后TTL/PTTL返回该封顶值。// Huge absolute timestamps overflow the kMaxExpireDeadlineMs cap and surface OUT_OF_RANGE. // Huge relative TTLs are silently capped to kMaxExpireDeadlineSec (~8.5 years). EXPECT_EQ(CheckedInt({ttl, key}), kMaxExpireDeadlineSec); EXPECT_THAT(Run({pexpire, key, absl::StrCat(int64_t{kMaxExpireDeadlineMs} * 10)}), IntArg(1)); EXPECT_EQ(CheckedInt({pttl, key}), kMaxExpireDeadlineMs);迁移建议如果你在 Redis 上设置了远超 8 年的过期时间例如使用绝对时间戳做永不过期的替代方案在 Dragonfly 上要么改用PERSIST要么接受 8.5 年上限同时注意绝对时间戳形式在超限时会报错而相对 TTL 是静默封顶。Lua 脚本运行时差异Dragonfly 内置的 Lua 解释器版本为Lua 5.4.42022 年发布而 Redis 长期使用的 Lua 5.1 已经较为陈旧。这一版本升级带来最直接的差异是Dragonfly 的 Lua 脚本支持 Lua 5.4 的整数类型integer包括math.maxinteger、math.mininteger、整数除法//、位运算等 5.3 特性这也是 Redis 社区长期讨论的 lua integers 议题所倡导的方向。在实现层面src/core/interpreter.cc 的错误提示直接引用了 Lua 5.4 官方手册的整数语义章节同时 src/core/interpreter.cc 展示了浮点转整数时对lua_Integer边界INT64_MIN/INT64_MAX的显式检查if (abs(fractpart) kConvertEps intpart double(std::numeric_limitslua_Integer::max()) intpart std::numeric_limitslua_Integer::min()) lua_pushinteger(lua_, static_castlua_Integer(d));此外interpreter.cc还通过luaopen_base、luaopen_table等标准库加载方式初始化运行时src/core/interpreter.cc并在脚本执行中对math.randomstring等扩展函数设置了明确的资源上限如单次随机字符串 16MiB、单次最多 32k 个随机串见 src/core/interpreter.cc防止脚本过度消耗内存。迁移建议如果迁移过来的 Redis Lua 脚本依赖 5.1 的老式行为例如math.random的种子行为、浮点/整数隐式转换的差异建议先用 Dragonfly 的EVAL做一遍脚本回归测试反之如果你此前受困于 Lua 5.1 缺少 64 位整数Dragonfly 的 5.4.4 会带来更自然的整数处理能力。总结迁移前需要对照的三张差异清单维度Redis 行为Dragonfly 行为迁移关注点字符串大小上限 512MB上限256MB超大字符串值需重新设计GETRANGE/SETRANGE 索引64 位有符号整数有符号 32 位[-2147483647, 2147483648]超大偏移量用法需调整SORT 排序无 locale 感知无 locale 感知文档明确列出语言化排序需在客户端实现EXPIRE NXGT/LT拒绝该组合允许无过期时 NX 生效有过期时 GT/LT 决定属于增强特性注意行为差异NXXX、GTLT拒绝同样拒绝与 Redis 保持一致过期时间上限无明确 8 年限制约8 年2^28-1 秒相对 TTL 静默封顶绝对时间戳超限报OUT_OF_RANGE毫秒精度命令超 2^28ms 静默降精度0.001%超长过期时间需改用PERSISTLua 运行时Lua 5.1Lua 5.4.4支持整数类型math.maxinteger等5.1 老脚本需回归测试可受益于整数能力Dragonfly 与 Redis 的协议兼容度很高真正的差异集中在上述少数边界语义上。无论是从 Redis 迁移到 Dragonfly还是双写/混合部署建议将本文的差异点整理进自己的兼容性测试矩阵并参照 docs/differences.md 与 tests/dragonfly 下的测试用例做针对性验证。【免费下载链接】dragonflyA modern replacement for Redis and Memcached项目地址: https://gitcode.com/GitHub_Trending/dr/dragonfly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考