NocoBase 整数字段完整指南从业务建模到源码级实现原理【免费下载链接】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 数据建模中的整数Integer字段展开你将掌握整数字段的适用场景、全部创建与编辑配置项、校验规则与删除注意事项并结合 NocoBase 开源仓库源码深入理解integer/bigInt两种数据层的实现方式、数据库列类型到字段类型的自动映射机制以及基于 Joi 的数值校验体系。1. 什么是整数字段在 NocoBase 中整数Integer用于保存不带小数的数值。整数字段适合数量、次数、人数、排序号等业务数据它可以参与筛选、排序、统计、权限和工作流条件。如果需要保存小数、金额、重量或比例则应选择 数字 或 百分比 字段更合适。整数字段的默认行为概览如下特性说明默认 Field interfaceinteger默认 Field typeinteger可选 Field typeinteger、bigInt页面组件编辑模式使用数字输入框筛选支持等于、不等于、大于、小于、区间、为空、不为空等数值筛选排序支持在表格区块中排序校验支持最小值、最大值、必填等数值校验2. 适用场景整数字段适合以下业务场景商品数量、库存数量、采购数量参与人数、剩余名额、次数统计工期天数、延期天数、账期天数外部系统中的整数编码。从源码结构看整数并不只是“一个输入框”它决定了数据层类型见 数据层实现 相关说明下一节展开、筛选条件的类型判断、统计聚合方式以及工作流中条件表达式的求值路径。因此选型时应优先确认数值范围是否需要bigInt例如雪花 ID、外部系统大整数编码而不是一律使用integer。3. 数据层实现integer与bigInt的源码真相整数字段在 NocoBase 数据层的实现位于 number-field.ts。该文件定义了一个抽象基类NumberFieldIntegerField与BigIntField都继承自它export abstract class NumberField extends Field {} export class IntegerField extends NumberField { get dataType() { return DataTypes.INTEGER; // 映射到数据库整型列 } } export class BigIntField extends NumberField { get dataType() { return DataTypes.BIGINT; // 映射到数据库 BIGINT 列 } }关键点integer对应 Sequelize 的DataTypes.INTEGER即标准 32 位整型列取值范围约 -21.4 亿 ~ 21.4 亿覆盖绝大多数业务计数场景bigInt对应DataTypes.BIGINT为 64 位整型适合大范围计数、外部系统大整数编码等场景同文件中还有FloatField、DoubleField、DecimalField等兄弟实现它们与IntegerField共同构成 NocoBase 的数值字段族但只有integer/bigInt属于“整数字段”的可选 Field type由于NumberField是抽象基类IntegerField的校验、序列化等行为与数字类字段共享同一套上层逻辑这也是为什么 字段校验 中整数、数字、百分比共享“大于 / 小于 / 最大值 / 最小值”这一组规则的原因。另外NocoBase 仓库中专门存在 bigint.test.ts 测试文件覆盖bigInt字段在仓储层读写、比较等行为的正确性可以作为实现事实的佐证。3.1 同步表时的列类型自动映射当整数字段来自主数据库或外部数据源已同步的表时NocoBase 会依据数据库列的原始类型推断 NocoBase 字段类型。映射规则集中定义在 field-type-map.ts 中节选如下const postgres { smallint: [integer, sort], integer: [integer, unixTimestamp, sort], bigint: [bigInt, snowflakeId, unixTimestamp, sort], // ... }; const mysql { smallint: [integer, boolean, sort], tinyint: [integer, boolean, sort], mediumint: [integer, boolean, sort], // ... };这说明两件事PostgreSQL 的integer列与 MySQL 的smallint/tinyint/mediumint列都会被推断为integer接口字段而bigint列则推断为bigInt并可进一步识别为雪花 ID、Unix 时间戳或排序字段映射结果是“候选列表”而非唯一值——同一个数据库列可能对应多种 NocoBase 字段类型例如 MySQL 的tinyint既可作整数也可作布尔。因此文档中“字段映射时 Field interface / Field type 条件可编辑”的说法本质上是这份映射表在为界面提供可选值。4. 创建整数字段在数据表的「Configure fields」页面中点击「Add field」选择「整数」即可创建整数字段。各配置项说明如下配置说明Field interface字段的界面类型。整数对应integer决定页面中如何录入和展示Field display name字段在界面中显示的名称比如「数量」「人数」「延期天数」。建议使用业务人员能直接理解的名称Field name字段标识名称用于 API、关系字段、权限、工作流等内部引用。创建后通常不再修改只支持字母、数字和下划线并且必须以字母开头Field type字段在数据层的类型。整数字段默认是integer大范围整数可以选择bigIntDefault value默认值。新增记录时如果用户没有填写可以自动带出默认值Validation rules校验规则。可以限制最小值、最大值或是否必填Description字段说明。适合写字段含义、填写要求、数据来源或维护人注意字段名创建后会被页面区块、权限、工作流和 API 引用。创建前先确认命名避免后续修改带来配置调整成本。其中 Field type 的两个取值直接对应第 3 节源码中的DataTypes.INTEGER与DataTypes.BIGINT选择bigInt时请注意它会生成 64 位列并且从源码结构看bigInt值在经 JSON API 返回时通常会以字符串形式序列化以规避 JavaScript 数字精度问题Number.MAX_SAFE_INTEGER仅为 2^53-1前端展示与二次提交需按字符串处理。5. 校验规则基于 Joi 的数值约束整数字段的「Validation rules」基于 Joi 数字校验体系实现详见 字段校验 文档。对整数字段而言通用规则整数、数字、百分比共享大于greater than小于less than最大值max最小值min整数倍multiple of整数专属规则整数验证integer强制录入值必须为整数拒绝小数不安全整数验证unsafe enabled允许超出 JS 安全整数范围±2^53-1的值通过校验。该规则通常与bigInt字段搭配使用——因为bigInt的合法取值可以远超Number.MAX_SAFE_INTEGER若不开启 unsafe 校验合法的大整数反而会被 Joi 判为非法。这两条规则正好解释了「为什么 Field type 有integer/bigInt之分」类型决定存储列宽Joi 的 unsafe 选项决定校验边界两者需要配合设置。6. 编辑整数字段配置创建后点击字段右侧的「Edit」可以编辑整数字段配置。编辑字段主要用于调整字段在 NocoBase 中的展示和使用方式比如修改显示名称、说明、默认值、校验规则或字段专属配置。如果字段来自主数据库中已经同步的表编辑时通常是在做字段映射——把数据库字段映射为 NocoBase 的 Field type 和 Field interface对应第 3.1 节的候选类型映射表。各配置项的编辑权限如下配置允许编辑说明Field display name是修改字段在界面中的显示名称不改变字段标识名称Field name否字段标识名称创建后通常不能在编辑表单中修改Field interface条件支持主数据库字段或同步字段在字段映射时可以调整。调整后会影响页面输入、展示和校验方式Field type条件支持主数据库字段或同步字段在字段映射时可以调整。调整前需要确认已有数据能否按新类型使用Default value是调整新增记录时的默认值Validation rules是调整字段校验规则Description是补充字段含义、填写要求、数据来源或维护人注意切换 Field type 或 Field interface 不等于简单改一个显示名称。它会影响字段的存储方式DataTypes.INTEGER与DataTypes.BIGINT的列宽差异、输入组件、校验规则、筛选条件和工作流变量使用方式。已有数据较多时先确认数据格式是否匹配。7. 删除整数字段点击字段右侧的「Delete」可以删除整数字段主数据库中还可以勾选多个字段后批量删除。删除主数据库中 NocoBase 新建的整数字段时通常会同时删除数据库中的真实列及该列已有数据删除从数据库同步或外部数据源映射出的字段时影响范围取决于对应数据源和字段来源映射关系被移除数据库原始列一般不受影响但具体以对应数据源行为为准。警告删除字段可能影响页面区块、表单、筛选、权限、工作流、API、导入导出和已有数据。删除前先确认字段是否仍被业务配置引用。8. 页面与工作流中的使用整数字段适合在表格、表单、统计和工作流中使用场景用途表单区块录入不带小数的数量、次数、天数等编辑模式使用数字输入框表格区块展示、排序和筛选整数等于 / 不等于 / 大于 / 小于 / 区间 / 为空 / 不为空图表区块按数量、次数等字段做统计求和、计数、平均值等聚合工作流和权限作为条件字段参与判断比如“数量是否大于 0”从实现角度看筛选与排序能力建立在第 3 节数据层类型的之上数值比较条件会直接下推为数据库层面的数值比较 SQL工作流中的条件判断则以字段值类型整数 / 大整数参与表达式求值。这也是为什么同一业务含义的数值选integer还是bigInt不仅影响存储还影响下游条件与统计行为。9. 相关链接字段 — 了解字段的作用、分类和映射逻辑普通表 — 在普通表中创建和管理字段数字 — 保存小数、金额、重量等数值百分比 — 保存比例或完成率字段校验 — 基于 Joi 的完整校验规则体系【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 NocoBase 整数字段完整指南：从业务建模到源码级实现原理
NocoBase 整数字段完整指南从业务建模到源码级实现原理【免费下载链接】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 数据建模中的整数Integer字段展开你将掌握整数字段的适用场景、全部创建与编辑配置项、校验规则与删除注意事项并结合 NocoBase 开源仓库源码深入理解integer/bigInt两种数据层的实现方式、数据库列类型到字段类型的自动映射机制以及基于 Joi 的数值校验体系。1. 什么是整数字段在 NocoBase 中整数Integer用于保存不带小数的数值。整数字段适合数量、次数、人数、排序号等业务数据它可以参与筛选、排序、统计、权限和工作流条件。如果需要保存小数、金额、重量或比例则应选择 数字 或 百分比 字段更合适。整数字段的默认行为概览如下特性说明默认 Field interfaceinteger默认 Field typeinteger可选 Field typeinteger、bigInt页面组件编辑模式使用数字输入框筛选支持等于、不等于、大于、小于、区间、为空、不为空等数值筛选排序支持在表格区块中排序校验支持最小值、最大值、必填等数值校验2. 适用场景整数字段适合以下业务场景商品数量、库存数量、采购数量参与人数、剩余名额、次数统计工期天数、延期天数、账期天数外部系统中的整数编码。从源码结构看整数并不只是“一个输入框”它决定了数据层类型见 数据层实现 相关说明下一节展开、筛选条件的类型判断、统计聚合方式以及工作流中条件表达式的求值路径。因此选型时应优先确认数值范围是否需要bigInt例如雪花 ID、外部系统大整数编码而不是一律使用integer。3. 数据层实现integer与bigInt的源码真相整数字段在 NocoBase 数据层的实现位于 number-field.ts。该文件定义了一个抽象基类NumberFieldIntegerField与BigIntField都继承自它export abstract class NumberField extends Field {} export class IntegerField extends NumberField { get dataType() { return DataTypes.INTEGER; // 映射到数据库整型列 } } export class BigIntField extends NumberField { get dataType() { return DataTypes.BIGINT; // 映射到数据库 BIGINT 列 } }关键点integer对应 Sequelize 的DataTypes.INTEGER即标准 32 位整型列取值范围约 -21.4 亿 ~ 21.4 亿覆盖绝大多数业务计数场景bigInt对应DataTypes.BIGINT为 64 位整型适合大范围计数、外部系统大整数编码等场景同文件中还有FloatField、DoubleField、DecimalField等兄弟实现它们与IntegerField共同构成 NocoBase 的数值字段族但只有integer/bigInt属于“整数字段”的可选 Field type由于NumberField是抽象基类IntegerField的校验、序列化等行为与数字类字段共享同一套上层逻辑这也是为什么 字段校验 中整数、数字、百分比共享“大于 / 小于 / 最大值 / 最小值”这一组规则的原因。另外NocoBase 仓库中专门存在 bigint.test.ts 测试文件覆盖bigInt字段在仓储层读写、比较等行为的正确性可以作为实现事实的佐证。3.1 同步表时的列类型自动映射当整数字段来自主数据库或外部数据源已同步的表时NocoBase 会依据数据库列的原始类型推断 NocoBase 字段类型。映射规则集中定义在 field-type-map.ts 中节选如下const postgres { smallint: [integer, sort], integer: [integer, unixTimestamp, sort], bigint: [bigInt, snowflakeId, unixTimestamp, sort], // ... }; const mysql { smallint: [integer, boolean, sort], tinyint: [integer, boolean, sort], mediumint: [integer, boolean, sort], // ... };这说明两件事PostgreSQL 的integer列与 MySQL 的smallint/tinyint/mediumint列都会被推断为integer接口字段而bigint列则推断为bigInt并可进一步识别为雪花 ID、Unix 时间戳或排序字段映射结果是“候选列表”而非唯一值——同一个数据库列可能对应多种 NocoBase 字段类型例如 MySQL 的tinyint既可作整数也可作布尔。因此文档中“字段映射时 Field interface / Field type 条件可编辑”的说法本质上是这份映射表在为界面提供可选值。4. 创建整数字段在数据表的「Configure fields」页面中点击「Add field」选择「整数」即可创建整数字段。各配置项说明如下配置说明Field interface字段的界面类型。整数对应integer决定页面中如何录入和展示Field display name字段在界面中显示的名称比如「数量」「人数」「延期天数」。建议使用业务人员能直接理解的名称Field name字段标识名称用于 API、关系字段、权限、工作流等内部引用。创建后通常不再修改只支持字母、数字和下划线并且必须以字母开头Field type字段在数据层的类型。整数字段默认是integer大范围整数可以选择bigIntDefault value默认值。新增记录时如果用户没有填写可以自动带出默认值Validation rules校验规则。可以限制最小值、最大值或是否必填Description字段说明。适合写字段含义、填写要求、数据来源或维护人注意字段名创建后会被页面区块、权限、工作流和 API 引用。创建前先确认命名避免后续修改带来配置调整成本。其中 Field type 的两个取值直接对应第 3 节源码中的DataTypes.INTEGER与DataTypes.BIGINT选择bigInt时请注意它会生成 64 位列并且从源码结构看bigInt值在经 JSON API 返回时通常会以字符串形式序列化以规避 JavaScript 数字精度问题Number.MAX_SAFE_INTEGER仅为 2^53-1前端展示与二次提交需按字符串处理。5. 校验规则基于 Joi 的数值约束整数字段的「Validation rules」基于 Joi 数字校验体系实现详见 字段校验 文档。对整数字段而言通用规则整数、数字、百分比共享大于greater than小于less than最大值max最小值min整数倍multiple of整数专属规则整数验证integer强制录入值必须为整数拒绝小数不安全整数验证unsafe enabled允许超出 JS 安全整数范围±2^53-1的值通过校验。该规则通常与bigInt字段搭配使用——因为bigInt的合法取值可以远超Number.MAX_SAFE_INTEGER若不开启 unsafe 校验合法的大整数反而会被 Joi 判为非法。这两条规则正好解释了「为什么 Field type 有integer/bigInt之分」类型决定存储列宽Joi 的 unsafe 选项决定校验边界两者需要配合设置。6. 编辑整数字段配置创建后点击字段右侧的「Edit」可以编辑整数字段配置。编辑字段主要用于调整字段在 NocoBase 中的展示和使用方式比如修改显示名称、说明、默认值、校验规则或字段专属配置。如果字段来自主数据库中已经同步的表编辑时通常是在做字段映射——把数据库字段映射为 NocoBase 的 Field type 和 Field interface对应第 3.1 节的候选类型映射表。各配置项的编辑权限如下配置允许编辑说明Field display name是修改字段在界面中的显示名称不改变字段标识名称Field name否字段标识名称创建后通常不能在编辑表单中修改Field interface条件支持主数据库字段或同步字段在字段映射时可以调整。调整后会影响页面输入、展示和校验方式Field type条件支持主数据库字段或同步字段在字段映射时可以调整。调整前需要确认已有数据能否按新类型使用Default value是调整新增记录时的默认值Validation rules是调整字段校验规则Description是补充字段含义、填写要求、数据来源或维护人注意切换 Field type 或 Field interface 不等于简单改一个显示名称。它会影响字段的存储方式DataTypes.INTEGER与DataTypes.BIGINT的列宽差异、输入组件、校验规则、筛选条件和工作流变量使用方式。已有数据较多时先确认数据格式是否匹配。7. 删除整数字段点击字段右侧的「Delete」可以删除整数字段主数据库中还可以勾选多个字段后批量删除。删除主数据库中 NocoBase 新建的整数字段时通常会同时删除数据库中的真实列及该列已有数据删除从数据库同步或外部数据源映射出的字段时影响范围取决于对应数据源和字段来源映射关系被移除数据库原始列一般不受影响但具体以对应数据源行为为准。警告删除字段可能影响页面区块、表单、筛选、权限、工作流、API、导入导出和已有数据。删除前先确认字段是否仍被业务配置引用。8. 页面与工作流中的使用整数字段适合在表格、表单、统计和工作流中使用场景用途表单区块录入不带小数的数量、次数、天数等编辑模式使用数字输入框表格区块展示、排序和筛选整数等于 / 不等于 / 大于 / 小于 / 区间 / 为空 / 不为空图表区块按数量、次数等字段做统计求和、计数、平均值等聚合工作流和权限作为条件字段参与判断比如“数量是否大于 0”从实现角度看筛选与排序能力建立在第 3 节数据层类型的之上数值比较条件会直接下推为数据库层面的数值比较 SQL工作流中的条件判断则以字段值类型整数 / 大整数参与表达式求值。这也是为什么同一业务含义的数值选integer还是bigInt不仅影响存储还影响下游条件与统计行为。9. 相关链接字段 — 了解字段的作用、分类和映射逻辑普通表 — 在普通表中创建和管理字段数字 — 保存小数、金额、重量等数值百分比 — 保存比例或完成率字段校验 — 基于 Joi 的完整校验规则体系【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考