企业官网建设流程全解析

NocoBase 序列字段（Sequence Field）完整指南：业务编号规则配置、生成原理与实战用法

【免费下载链接】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

序列（Sequence）是 NocoBase 中用于生成业务编号的字段类型，适合订单号、合同号、工单号、申请单号等需要可读规则编号的场景。本文以 docs/docs/cn/data-sources/field-sequence/index.md 为核心，结合plugin-field-sequence插件的源码与测试，讲解字段的创建、规则配置、底层生成原理与页面使用方式，帮助你快速落地一套可维护的业务编号体系。

什么是序列字段

在 NocoBase 中，序列（Sequence）用于生成业务编号。它和数据库主键有本质区别：

• 序列字段面向业务展示和人工识别，编号带有前缀、日期、自增数字等可读规则，例如SO-20240101-0001；
• 主键（如 Snowflake ID、UUID、Nano ID）只承担内部唯一标识职责，不追求可读性。

如果业务只需要内部唯一标识、不需要可读规则，应优先使用 Snowflake ID；如果需要人工可读、可按规则检索的编号，则使用序列字段。

适用场景

序列字段适合以下业务场景：

• 订单号、合同号
• 工单号、申请单号
• 资产编号、设备编号
• 带前缀、日期或递增规则的编号

创建序列字段

在数据表的「Configure fields」页面中，点击「Add field」，选择「序列」即可创建序列字段。

创建时涉及以下配置项：

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

字段特性

序列字段的默认行为如下：

从源码结构看，客户端接口定义 interface.tsx 中明确设置了filterable.operators = 'string'，即序列字段默认按字符串操作符进行筛选，并在「Unique」配置项中以复选框形式提供唯一性约束开关；服务端SequenceField.dataType固定返回DataTypes.STRING（见 sequence-field.ts），这印证了「常见存储类型为 string」的默认行为。

序列规则（Sequence Rules）详解

序列字段的核心是规则（patterns）：编号由一条或多条规则拼接生成。配置界面中的「Sequence rules」项允许你组合以下四种规则类型（定义见 interface.tsx）：

一个典型的组合示例是「固定文本 + 日期 + 自增」生成形如SO-20240101-0001的订单号。在配置界面中，你可以增删规则并调整顺序，最终编号即按顺序拼接各规则生成的值。

integer规则的cycle（重置周期）配置项在 SequenceRulesConfigureField.tsx 中提供了以下预置选项，也可以选择「Customize」自定义 cron 表达式：

序列字段的默认规则为一条integer规则，参数为digits: 4, start: 1，即生成0001、0002这样的四位自增编号。

编号生成原理：源码级解析

序列字段的实现集中在插件@nocobase/plugin-field-sequence的 sequence-field.ts 中，核心要点如下：

1. 规则注册表（Registry）：服务端通过sequencePatterns注册表统一注册了string、integer、date、randomChar四种 Pattern，每种 Pattern 至少实现generate（单条生成）、batchGenerate（批量生成）、getLength、getMatcher（正则匹配片段）四个方法。创建字段时如果patterns为空，或使用了未注册的规则类型、参数校验不通过，构造器会直接抛出错误——这一点在 sequence-field.test.ts 中有明确测试用例覆盖（"without any pattern will throw error"）。

2. 编号状态表sequences：递增计数不依赖业务表本身，而是存放在一张系统共享表sequences中（定义见 sequences.ts），字段包括：collection（所属数据表）、field（所属字段）、key（规则键）、current（当前计数值，bigInt类型）、lastGeneratedAt（最近生成时间）。每条「数据表 + 字段 + key」对应一行记录，计数器在生成编号的事务内完成查询、自增与保存，从而保证并发下的递增唯一性。

3. 生命周期 Hook：SequenceField在bind()中注册了四个钩子：

• beforeValidate→validate：当字段配置为inputable（允许手工输入）且要求match（必须匹配规则）时，手工输入的值必须符合规则拼接出的正则，否则抛出校验错误；
• beforeCreate→setValue：单条创建时按规则逐个生成并拼接编号；
• beforeBulkCreate→setGroupValue：批量创建时一次性推进计数器并批量赋值，避免逐条生成带来的性能损耗；
• afterBulkCreate→cleanHook：清理批量钩子标记。

4. 自增与重置逻辑：integer规则每次生成时读取sequences表中的current，执行current + 1，若超过base^digits - 1则回到start；若配置了cycle（cron 表达式），则通过cron-parser计算下一个周期时间点，当记录时间跨过周期边界时自动从start重新开始。测试用例（如 "default start from 0, digits as 1, no cycle"）验证了默认行为：连续创建两条记录，编号依次为0、1。

5. 手工录入的计数器回填：integer规则的update方法在手工输入编号且命中规则时，会用输入值回填计数器（只有更大的值才会更新current），并支持overwrite强制覆盖，保证后续自动生成不会产生重复编号。

编辑序列字段

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

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

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

删除序列字段

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

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

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

页面配置与使用

序列字段适合在业务编号和人工检索场景中使用：

结合序列字段「支持文本筛选」「可作为可读标识」的特性，建议在表格区块中为编号列开启筛选，方便业务人员按编号快速定位记录；在工作流节点中引用编号变量，让审批通知带上可读的单号，提升协作效率。

相关文档

• 字段 — 了解字段的作用、分类和映射逻辑
• 普通表 — 在普通表中创建和管理字段
• 单行文本 — 手工维护业务编号
• Snowflake ID — 使用内部主键 ID

【免费下载链接】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