数据类型
在配置数据模型和声明运行期变量（如客户端变量、页面变量、行为参数）时，必须选择正确的数据类型。
Zion 的底层基于企业级关系型数据库 PostgreSQL 构建。为了让你的系统具有高运行性能、强数据完整性和精确的科学计算，本手册列出平台支持的全部数据类型及其取值约束；数据库层面的对应关系集中在文末的数据库对照。
基础类型
基础类型共 12 种，是类型系统中最小的可用单位：
| 类型 | 格式与限制 |
|---|---|
| 文本 | 最大 1 GB |
| 长整数 | 8 字节整数，-9,223,372,036,854,775,808 到 +9,223,372,036,854,775,807 |
| 无限精度小数 | 可变长度，最大 131072 位；十进制精确运算，无浮点舍入误差 |
| 布尔值 | true / false |
| 日期时间（带时区） | YYYY-MM-DDTHH:mm:ss.sssZ；绝对时间戳，按客户端本地时区显示 |
| 日期 | YYYY-MM-DD；不含时分秒，不受时区影响 |
| 时间（带时区） | HH:mm:ss.sssZ；仅表示一天中的某个时刻 |
| 图片 | 文件上传到对象存储，字段保存的是媒体记录的引用；支持 .jpg、.jpeg、.png、.gif、.webp、.svg、.ico |
| 视频 | 文件上传到对象存储，字段保存的是媒体记录的引用；支持 .mp4、.mov、.webm |
| 文件 | 文件上传到对象存储，字段保存的是媒体记录的引用；不限文件类型 |
| 经纬度 | [经度, 纬度]；支持距离计算与按距离排序 |
| JSON | 任意类型的数据，既可以是基础类型，也可以是对象或数组，结构可以不固定 |
⚠️
为什么有了小数，还必须强调“无限精度”？
在一般的 JavaScript 或大部分高级语言中，小数默认以双精度浮点数（Float）在内存中表示。计算 0.1 + 0.2 时，因为二进制转换问题会产生微小误差，输出 0.30000000000000004。
在 Zion 中，数据库层采用标准的 Postgres numeric (无限精度小数) 类型，它会在数据库中强制执行完全精确的十进制数字计算，绝不损失任何精度，完美契合商业、电商及银行级财务账单审计要求。
数组
数组表示一组同类型的值，显示为 [元素类型]，例如 [文本]、[对象]、[订单]。元素类型可以是任意类型。
自定义对象
自定义对象是由若干属性构成的结构化类型。
- 属性：每个属性有自己的名称、类型和可空性。属性的类型可以是基础类型、数组、枚举、数据表类型，或另一个自定义对象，因此对象可以逐层嵌套。
- 与 JSON 的区别：JSON 的内容对类型系统不透明，只能在运行时按路径取值；自定义对象的每个属性都是类型系统中的一等成员，可被数据绑定直接引用，并参与类型校验。结构已经确定的数据应当用自定义对象表达，JSON 只承担结构确实不固定的部分。
- 具名对象：项目级定义，有名称，可被项目内任何位置引用。所有具名对象可以在数据页下的对象中查看和编辑。
- 私有对象：由 API 请求体、响应体等配置就地产生，没有名称，类型统一显示为「对象」，只属于产生它的那个位置，无法被别处引用。需要在多处共用同一结构时只能使用具名对象。
枚举
枚举是取值被限定在一组预定义枚举值内的类型，用于表达状态、分类这类有限取值域，例如订单状态、审核结果、会员等级。
- 枚举值名称：标识符，只能由字母、数字、下划线组成，不能以数字开头，且在同一枚举内唯一。
- 顺序：枚举值在类型中是有序的，这个顺序会带到所有引用该枚举的位置。
- 存储：枚举字段在数据库中存储的是枚举值名称，因此这些名称属于项目对外契约的一部分。
⚠️
正因为线上数据存的是枚举值名称，改动一个已被使用的枚举值会改写既有数据：
- 删除枚举值：部署后，持有该值的行会被置为空；若该字段为必填，部署会直接失败。
- 重命名枚举值：部署会同步迁移既有数据，但依赖该字符串的外部消费方（自定义代码、对外接口的调用方）不会被一并迁移。
数据库对照
以下是各类型作为数据表字段时，在 PostgreSQL 中实际建出来的列。
| 类型 | 数据库中的类型 |
|---|---|
| 文本 | TEXT |
| 长整数 | BIGINT（主键 id 为 BIGSERIAL） |
| 无限精度小数 | DECIMAL（即 numeric） |
| 布尔值 | BOOLEAN |
| 日期时间（带时区） | TIMESTAMPTZ |
| 日期 | DATE |
| 时间（带时区） | TIMETZ |
| 图片 | bigint，列名为 字段名_id，外键指向 fz_stored_image |
| 视频 | bigint，列名为 字段名_id，外键指向 fz_stored_video |
| 文件 | bigint，列名为 字段名_id，外键指向 fz_stored_file |
| 经纬度 | geography(Point, 4326) |
| JSON | JSONB |
| 枚举 | TEXT，存的是枚举值名称 |
| 自定义对象 | 无对应列 |
| 数组 | 无单独列；一对多、多对多关联由关联表实现 |
几点由此而来的行为：
- 媒体字段存的是媒体记录 id，文件与访问 URL 保存在
fz_stored_image等表中（不对外暴露），因此媒体记录被引用时无法在数据库层面直接删除，需要前往资源管理器删除。 - 枚举字段存的是枚举值名称，所以重命名或删除枚举值会改写既有数据。
Last updated on