企业官网建设流程全解析

NocoBase JSON 字段完全指南：结构化与半结构化数据的存储、映射与页面应用

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase

在 NocoBase 中，JSON 字段是处理结构不固定数据的关键类型，用于保存结构化对象、数组以及接口响应片段等半结构化数据。对于需要对接外部接口、保存动态扩展属性或复杂配置对象的业务系统，它是少数能兼顾灵活性与数据完整性的字段类型之一。本文基于仓库中的官方文档与源码实现，完整覆盖 JSON 字段的适用场景、创建与编辑配置、json与jsonb两种数据层类型的底层差异、校验规则，以及在表单、详情、工作流和 API 中的实际用法，帮助你在建模时准确判断"该不该用 JSON 字段、怎么用最稳妥"。

JSON 字段是什么：定位与取舍

在 NocoBase 中，JSON（JSON）字段用于保存结构化或半结构化数据。它适合保存外部接口响应片段、扩展配置、动态属性等结构不固定的数据——也就是无法用固定的列集合预先描述的数据形态。

但 JSON 字段的灵活性是有代价的：它不如普通字段（字符串、数字、日期）那样容易筛选、校验和展示。因此官方文档给出的核心建模原则是：

如果字段结构稳定，优先拆成明确字段，方便页面配置、权限、筛选和工作流使用。

这句话是理解 JSON 字段用法的钥匙：JSON 字段是"结构未知时的兜底容器"，而不是"万能字段"。

适用场景

文档明确列出的四类典型业务场景：

不适用的场景

从文档的建模建议可以推断，以下情况不建议使用 JSON 字段：

• 字段结构长期稳定（例如"收货地址"始终包含省、市、区），应拆成独立字段；
• 该字段需要频繁出现在筛选条件、排序、权限控制或工作流变量中——这些能力在普通字段上更完善。

创建 JSON 字段：完整配置项说明

在数据表的「Configure fields」页面中，点击「Add field」，选择「JSON」即可创建 JSON 字段。创建表单包含以下配置项：

:::warning 字段名创建后会被页面区块、权限、工作流和 API 引用。创建前先确认命名，避免后续修改带来配置调整成本。 :::

字段特性一览

JSON 字段的默认行为如下：

json与jsonb的底层差异：源码级解析

文档中"可选 Field type：json、jsonb，以数据库能力为准"这句话，背后对应 NocoBase 数据库层的两段精确实现。

在 packages/core/database/src/fields/json-field.ts 中，json和jsonb分别由JsonField与JsonbField两个类实现，二者的差异完全取决于数据库方言（dialect）：

export class JsonField extends Field { get dataType() { const dialect = this.context.database.sequelize.getDialect(); const { jsonb } = this.options; if (dialect === 'postgres' && jsonb) { return DataTypes.JSONB; } return DataTypes.JSON; } } export class JsonbField extends Field { get dataType() { const dialect = this.context.database.sequelize.getDialect(); if (dialect === 'postgres') { return DataTypes.JSONB; } return DataTypes.JSON; } }

从这段源码可以得出三个明确的实现事实：

1. JsonField（type 为json）：默认映射为 Sequelize 的DataTypes.JSON；只有当数据库是 PostgreSQL且显式传了jsonb: true选项时，才会升级为JSONB。
2. JsonbField（type 为jsonb）：在 PostgreSQL 上无条件映射为DataTypes.JSONB；在其他数据库（如 MySQL、MariaDB、SQLite）上则回退为DataTypes.JSON。
3. 因此"以数据库能力为准"的准确含义是：jsonb只有真正的优势（原生二进制 JSON 存储、JSON 操作函数、GIN 索引）在 PostgreSQL 上才生效；在 MySQL 等库上jsonb与json最终都落为 JSON 类型。

值解析与数据源映射

写入路径上，packages/core/database/src/value-parsers/index.ts 将json和jsonb两种类型统一注册到同一个JsonValueParser，即两种类型在值序列化/反序列化层面行为一致：

json: JsonValueParser, jsonb: JsonValueParser,

当 JSON 字段来源于外部数据源同步的表（字段映射场景）时，映射逻辑定义在 packages/core/database/src/view/field-type-map.ts。以 PostgreSQL 为例：

json: ['json', 'array'], jsonb: ['json', 'array', 'jsonb'],

这说明：PostgreSQL 的json列可以映射为 NocoBase 的json或array接口；jsonb列额外多一个jsonb选项。这也解释了文档中"编辑字段主要用于调整字段在 NocoBase 中的展示和使用方式，比如把数据库字段映射为 Field type 和 Field interface"的具体含义。

编辑 JSON 字段：哪些可改、哪些不可改

创建后，点击字段右侧的「Edit」可以编辑 JSON 字段配置。编辑字段主要用于调整字段在 NocoBase 中的展示和使用方式，比如修改显示名称、说明、默认值、校验规则或字段专属配置。

如果字段来自主数据库中已经同步的表，编辑时通常是在做字段映射——把数据库字段映射为 NocoBase 的 Field type 和 Field interface。

:::warning 切换 Field type 或 Field interface 不等于简单改一个显示名称。它会影响字段的存储方式、输入组件、校验规则、筛选条件和工作流变量使用方式。已有数据较多时，先确认数据格式是否匹配。 :::

结合前文的源码分析，"确认已有数据能否按新类型使用"这一点有了具体落点：在 PostgreSQL 上从json切到jsonb会触发DataTypes.JSON到DataTypes.JSONB的底层类型变化（见 json-field.ts），已有数据能否平滑迁移取决于数据是否符合目标类型的存储要求，这正是文档要求"先确认数据格式"的原因。

删除 JSON 字段的影响范围

点击字段右侧的「Delete」可以删除 JSON 字段。主数据库中还可以勾选多个字段后批量删除。

• 删除主数据库中新建的 JSON 字段时，通常会同时删除数据库中的真实列及该列已有数据；
• 删除从数据库同步或外部数据源映射出的字段时，影响范围取决于对应数据源和字段来源。

:::danger 删除字段可能影响页面区块、表单、筛选、权限、工作流、API、导入导出和已有数据。删除前先确认字段是否仍被业务配置引用。 :::

由于 JSON 字段常出现在工作流中"保存外部接口返回片段"的场景，删除前尤其应检查工作流变量是否引用了该字段——一旦引用的字段消失，相关流程节点会失败。

页面配置使用：JSON 字段的四类落地场景

JSON 字段适合在集成和扩展配置场景中使用：

客户端侧，JSON 输入组件的定义位于 packages/core/client/src/collection-manager/interfaces/json.tsx（interface 标识为json），其演示用例可见 schema-component/antd/input/demos/new-demos/json.tsx，其中字段以type: 'json'声明，与文档中"编辑模式使用 JSON 编辑组件"的描述一致。

与相邻字段类型的选型对照

从仓库文档结构看，以下相邻文档可作为选型参考（相对本仓库根目录）：

• 字段 — 了解字段的作用、分类和映射逻辑；
• 普通表 — 在普通表中创建和管理字段；
• 多行文本 — 保存纯文本长内容（结构完全不固定时的替代方案）；
• 公式 — 基于字段计算结果。

实践要点总结

1. 先问结构是否稳定：结构稳定的数据拆独立字段；结构不稳定的（接口响应、动态属性、复杂配置）才用 JSON 字段。
2. 选json还是jsonb：以数据库能力为准——PostgreSQL 上jsonb会真正映射为原生 JSONB 类型，其他数据库上二者最终都落为 JSON 类型；源码依据见 json-field.ts。
3. 命名一次定终身：Field name 创建后不可在编辑表单中修改，且会被页面区块、权限、工作流、API 多处引用。
4. 改类型前先验数据：Field type / Field interface 的切换涉及存储类型、输入组件、校验与筛选行为的连锁变化，存量数据多时务必先验证格式匹配。
5. 删除前先查引用：删除字段会联动影响页面、权限、工作流、API 与已有数据，外部数据源映射字段的影响范围另取决于数据源实现。

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase