Engula 客户端兼容性指南#

Engula 被设计为 Valkey/Redis 7.2 的“即插即用”替代，目标是在不破坏 Redis 生态互操作性的前提下，让应用与客户端库可以无缝接入。 本指南面向开发者说明兼容性的含义、已验证的客户端范围，以及如何确保迁移后的行为一致。

协议与 API 兼容性#

• 协议支持：Engula 完整实现 RESP2 与 RESP3，覆盖 Valkey/Redis 7.2 的完整命令集。
• 零代码修改：已经使用 Redis/Valkey 7.2 的应用，通常无需修改代码或配置即可连接 Engula。
• Engula 扩展：部分 Engula 增强特性可能无法在原生 Redis/Valkey 上运行；如需可移植性，请避免使用 Redis/Valkey 7.2 命令面之外的调用。

生态一致性#

Engula 会紧密对齐 Valkey/Redis 7.2 的语义与行为，包括：

• 核心命令：CRUD、key 管理与各类数据结构操作
• 集群模式：slot 管理、拓扑更新与重定向语义
• Pub/Sub 与 Streams：一致的消息分发与消费者组行为
• 事务与脚本：相同的原子性、隔离性与执行语义

任何可观察到的差异都会被记录，并在可行范围内进行兼容性修复，以保证 可预测的 Redis 行为一致性。

客户端库#

由于 Engula 对齐 Valkey/Redis 7.2 的协议与 API，因此凡是支持 Redis OSS 7.2 或 Valkey 7.2 及以上的客户端，通常都可以直接与 Engula 互操作。

• Valkey 客户端目录：https://valkey.io/clients/
• Redis 客户端目录：https://redis.io/clients

这些目录包含各语言的主流客户端与其特性支持情况（例如 read-from-replica、smart backoff、client-side caching 等）。 只要某个客户端能正确连接 Valkey 或 Redis 7.2，通常就能以相同方式连接 Engula。

高级客户端特性#

Engula 支持 Valkey/Redis 7.2 定义的高级客户端行为。只要使用标准协议命令，下列能力均可互操作：

• Read from Replica：从从节点读取以分担负载
• Cluster-Aware SCAN：跨集群节点的无缝扫描
• Client-Side Caching：基于服务端协助失效的缓存一致性
• 持久连接池：复用连接提升性能

提示： 部分特性需要在客户端侧开启配置或运行时开关。 请参考具体客户端的文档进行设置；Engula 提供相应的服务端能力支持。

官方已验证客户端#

Engula 在 CI 流水线中持续对主流 Redis/Valkey 客户端进行兼容性验证。尽管几乎所有 Redis/Valkey 7.2 兼容客户端都应当可以正常工作，但以下客户端已被明确验证：

语言	常见已验证客户端
Go	go-redis, valkey-go
Java	jedis, valkey-java, redisson
JavaScript / TypeScript	node-redis, iovalkey
Python	redis-py, valkey-py
PHP	phpredis, predis

如果您使用的客户端未在列表中，但声明支持 Valkey/Redis 7.2，则通常也应当可用。 如遇到异常行为，请反馈给我们，以便评估并纳入验证覆盖集。

迁移建议#

从 Valkey/Redis 7.2 迁移到 Engula 一般非常直接：

1. 保持相同连接配置（认证、TLS、超时、连接池等）。
2. 及时升级客户端版本，以获得 Redis/Valkey 7.2 语义相关的最新修复。
3. 按客户端文档启用特性，如 client-side caching、read-from-replica、或 Pub/Sub 自动重连。 Engula 会匹配这些特性在服务端侧的预期行为。

兼容性测试覆盖#

Engula 会对主流 Redis 客户端 SDK 做自动化兼容性验证，覆盖：

• 连接建立与命令执行
• 数据结构与事务
• Pub/Sub 与 Streams
• Pipeline 与 Lua 脚本
• 集群模式处理

更多信息：

• 客户端兼容性测试概览：测试方法与覆盖的客户端范围。
• 完整测试工程说明：包含搭建步骤、测试脚本与通过/失败分析。

Engula 团队会持续完善测试套件，及时发现并修复差异。欢迎社区贡献与 PR 来扩展覆盖范围。

获取帮助#

如果您遇到客户端行为异常或协议处理差异：

• 提交包含版本信息、配置与最小复现的 issue。
• 查看客户端的 issue tracker 或 release notes，确认是否存在 Redis/Valkey 7.2 相关已知问题与修复。
• 通过 support@engula.cn 联系 Engula 团队，我们会与客户端维护者协作确保一致性与互操作。

总结#

一句话：能跑 Valkey 或 Redis 7.2，就能跑 Engula。 从官方 Valkey/Redis 客户端目录选择您偏好的客户端，即可无缝使用 Engula 的高性能与高内存效率架构。