在使用 Redis‑OM 做对象映射开发时，很多同学都会卡在第一道选择题：到底该用 HashModel 还是 JsonModel？
同样是 Redis‑OM 的核心模型，二者 API 看似接近，但底层存储结构差异巨大。选错模型，后续会遇到无法嵌套对象、不能使用列表字典、索引失效等各种棘手问题，后期重构成本很高。
本文就从实际开发角度，带你理清 HashModel 和 JsonModel 的适用场景、字段定义方式、默认值配置以及数据校验规则，帮你避开选型踩坑，快速上手 Redis‑OM 的模型开发工作。
一、HashModel 与 JsonModel 选型
- JsonModel支持嵌套模型、列表、字典等容器类型，可对列表、内嵌模型建立索引；底层通过 Pydantic 做 JSON 序列化存入 Redis。如果业务需要内嵌子模型（比如客户模型嵌套订单列表），优先选它。
- HashModel存储在 Redis Hash 扁平结构，不支持列表、集合、字典、其他模型这类容器类型；未来版本可能把容器字段序列化为 JSON 字符串，但无法建立索引。没有嵌套需求时优先选用。
二、模型与字段基础用法
- 创建模型通过继承
HashModel或JsonModel定义模型，使用 Python 类型注解声明字段，语法和 Pydantic 保持一致。 - 默认值字段可以直接赋值设置默认值。实例化对象不传该字段，会自动读取默认值，调用
save()会把默认值持久化到 Redis。 - 可选字段使用
Optional[类型]标记可选字段；没有设置默认值的字段属于必填字段。
三、数据校验能力（底层依赖 Pydantic）
- Redis‑OM 模型同时也是 Pydantic 模型，会在运行时依据类型注解自动校验数据。
- 基础校验基础类型
str/int/date等自动校验类型，保证存入数据类型合规。 - 复杂校验可直接使用 Pydantic 校验器，例如
EmailStr校验邮箱格式。 - 实例化传入非法数据，直接抛出
ValidationError； - 修改实例字段为非法值，调用
save()保存的时候同样触发校验报错。
- 值约束复用 Pydantic 的约束注解，可以实现小写字符串、正则匹配、数值区间、倍数限制等更多字段约束。
简短一句话概括
HashModel 适合简单扁平对象；JsonModel 支持嵌套和容器。依托 Pydantic，用类型注解完成字段定义、默认值、可选配置以及丰富的数据校验，自动在实例创建和保存时拦截非法数据。
今天我们对于OM中主要的几个内容做深度讲解，这一期我们来讲解一下OM中最重要的models（模型）。
模型与字段：
Redis OM 的对象映射、数据校验和持久化功能的核心是两种声明式模型：HashModel 和 JsonModel。两者提供的 API 大体相同，但在 Redis 中存储数据的方式不一样。
1.HashModel 与 JsonModel 的对比
首先，该如何选择？
选择逻辑比较简单：如果你想在一个模型中嵌套另一个模型（例如给 Customer（客户）模型增加一个 Order（订单）模型列表），那就要用 JsonModel。只有 JsonModel 支持内嵌模型。
除此之外的场景，使用 HashModel。
2.创建模型
创建 Redis OM 模型的方式是继承 HashModel 或者 JsonModel，示例：
3.字段
在Redis OM 模型中，使用 Python 类型注解来定义字段。如果你不熟悉类型注解，可以看这份教程。它的用法和 Pydantic 完全一致。
4.使用HashModel
HashModel 将数据存储在 Redis 的哈希结构里，哈希是扁平结构。这意味着 Redis Hash 不能包含 Redis 的集合、列表或者其他哈希。
受这个限制，HashModel 不支持容器类型，包括：
l集合（Sets）
l列表（Lists）
l字典以及其他“映射类型”
l其他 Redis OM 模型
lPydantic 模型
注：未来版本可能会把这类值序列化为 JSON 字符串，和 JsonModel 的实现类似。区别在于：HashModel 无法对这些字段建立索引，只能随模型存取；而 JsonModel 可以对列表字段和内嵌的 JsonModel 创建索引。
简单总结：如果你需要使用容器类型，就选用 JsonModel。
5.使用JsonModel
好消息！JsonModel 支持容器类型。底层会使用 Pydantic 的 JSON 序列化
与编码能力，把你的 JsonModel 序列化后存入 Redis。
6.默认值
字段可以设置默认值，直接给字段赋值即可。
现在，如果创建 Customer 对象时不传 bio 字段，会自动使用默认值。
之后调用 save() 时，模型会把这个默认值保存到 Redis。
7.可选字段
没有设置默认值的字段是必填字段。想要让字段变成可选，请使用 Optional：
8.数据校验
Redis OM 在底层依靠 Pydantic，根据模型的类型注解在运行时校验数据。
每一个 Redis OM 模型同时也是 Pydantic 模型，所以你可以使用 Pydantic 的校验器，例如 EmailStr、Pattern 等，实现复杂校验逻辑。
9.基础类型校验
基础类型注解（例如 str）会自动开启校验：
Redis OM 会保证 first_name 永远是字符串，age 永远是整数，以此类推。
10.复杂校验
我们看下：尝试创建一个 Customer 对象，但传入非法邮箱时会发生什么：
如果你修改模型实例的字段为非法值，然后尝试保存，同样会触发校验错误：
11.约束值
Pydantic 提供了大量类型注解，可以为模型字段增加值约束：
l始终小写的字符串
l必须匹配正则表达式的字符串
l在指定区间内的整数
l必须是某个数字倍数的整数
所有这些约束类型都可以在 Redis OM 模型中使用。
持续更新精彩内容中，欢迎点关注哟！
