Redis Key 命名规范文档

开发过程中为确保 Redis 键名的一致性、可读性和易维护性，本规范旨在指导开发团队在使用 Redis 时设计合理的键名格式。

---

1. 命名格式

采用 模块:子模块:业务描述:标识 的分层格式，明确数据来源和用途。

• 层次清晰：从全局到具体逐步细化。
• 唯一性：标识符确保键名在全局范围内唯一。

格式模板：

<module>:<submodule>:<description>:<identifier>

示例：

• 用户信息：user:profile:id:12345
• 订单状态：order:status:order_id:98765
• 商品库存：product:inventory:item_id:67890

---

2. 具体规范

2.1 小写命名

• Redis 键名必须使用 小写字母，避免大小写混淆问题。
• 小写命名与 Redis 社区实践保持一致，方便管理和排查。

2.2 使用冒号分隔层级

• 使用冒号（:）作为分隔符表示逻辑层次关系。
• 每个部分表述一个独立的含义，冒号分隔便于阅读和自动化解析。

2.3 标识符命名

• 唯一标识符部分（如 id, order_id 等）应明确表达其意义。
• 使用 下划线（_） 分隔复合单词，而非驼峰命名（camelCase）。

---

3. 数据类型扩展命名

针对不同的数据结构（如 list, set, hash），可以在业务描述部分或标识符后添加类型信息：

数据类型	格式示例
字符串（String）	user:profile:id:12345
列表（List）	chat:messages:list:room_id:56789
哈希（Hash）	user:profile:hash:id:12345
集合（Set）	product:categories:set:item_id:67890
有序集合（ZSet）	leaderboard:score:zset:game_id:11111

---

4. 时间敏感型键名

对于有时间属性或需要自动过期的数据，可在键名中包含时间信息：

• 日期信息：<description>:date:<YYYYMMDD>
  示例：order:summary:date:20241122
• 时间戳信息：<description>:ts:<timestamp>
  示例：session:token:uid:abc123:ts:1692806400

---

5. 规范总结

5.1 推荐的键名风格

• 使用小写字母。
• 冒号分隔逻辑层次。
• 下划线分隔单词，清晰表达数据意义。

5.2 避免的问题

• 避免过长的键名 ：键名越长，内存占用越多，效率越低。
  • 不推荐：user:profile:personal:information:unique:identifier:12345
  • 推荐：user:profile:id:12345
• 避免缩写模糊 ：缩写可能导致键名难以理解。
  • 不推荐：usr:prf:id:12345
  • 推荐：user:profile:id:12345
• 避免使用驼峰命名 ：小写和下划线分隔的风格更适合 Redis 键名。
  • 不推荐：orderStatusOrderId98765
  • 推荐：order:status:order_id:98765

---

6. 实际应用示例

6.1 Java 中的 Redis Key 工具类

public class RedisKeyUtil {

    // 用户资料键名
    public static String userProfileKey(String userId) {
        return String.format("user:profile:id:%s", userId);
    }

    // 订单状态键名
    public static String orderStatusKey(String orderId) {
        return String.format("order:status:order_id:%s", orderId);
    }

    // 聊天记录列表键名
    public static String chatMessagesKey(String roomId) {
        return String.format("chat:messages:list:room_id:%s", roomId);
    }
}

6.2 常见 Redis 键名

用途	键名
用户资料	user:profile:id:12345
用户登录状态	user:session:uid:abc123
商品库存	product:inventory:item_id:67890
订单状态	order:status:order_id:98765
聊天消息队列	chat:messages:list:room_id:12345
排行榜	leaderboard:score:zset:game_id:1

---

7. FAQ

为什么推荐小写和下划线分隔？

• 小写命名避免大小写混淆。
• 下划线分隔的风格更易读，尤其是复合单词。

键名长度如何控制？

• 避免超过 128 字符。
• 在确保键名含义清晰的前提下，尽量简洁。

是否需要统一团队风格？

• 是。制定和遵循统一的命名规范，便于团队协作和后期维护。

---

通过以上规范，团队可以提高 Redis 数据的可读性和可维护性，同时避免常见的命名问题。建议结合实际业务情况，适当调整以满足具体需求。