4.3 二次开发：自制积木

4.3 二次开发：自制积木

本节摘要：从脚手架建工程、写一枚最小的服务端插件（一个自定义工作流节点），到联调与交付归仓，本节把二次开发的完整过程走一遍。目标不是教你所有接口，而是让你掌握「照着官方插件抄结构」的自学方法——接口会变，方法不会。

前三节把车间看明白了，这一节开机床。案例来自 3.2 埋的伏笔：审批流需要一个平台没预装的节点——按业务规则自动计算两个日期之间的工作日天数。规则简单、需求真实，正好当第一枚练习件。

一、开工前的环境纪律

插件开发的环境纪律比代码本身更决定成败。第一条：生产实例零改动——按 2.1 的脚手架路线另起一个开发工程，生产库的数据用备份脱敏后灌一份进开发库。第二条：版本对齐——开发工程的版本与生产实例保持一致，跨版本开发的插件会在升级日还债。第三条：仓库隔离——插件代码放独立仓库，通过包引用进工程，而不是把代码摊在工程目录里改到分不清谁是谁。

# 开发工程与插件的初始化序列（在开发机上执行）
npx create-nocobase-app my-dev          # 创建开发工程，选中文与 PG
cd my-dev
yarn install                             # 安装依赖，首次较慢属正常
yarn pm create plugin-workdays           # 创建插件骨架，包名自动归入你的命名空间
cd packages/plugins/@my-org/plugin-workdays
yarn build                               # 首次构建，产物进 dist 目录
​

骨架生成后的目录值得逐个认识：清单文件声明插件名、版本与依赖；服务端入口注册服务端能力；客户端入口注册界面组件；迁移目录放表结构演进脚本。本节练习只碰服务端，客户端两处先不惊动。

二、写一枚最小的工作流节点

工作流插件给节点留了注册口。一个节点要向引擎交代三件事：标题与配置面板（让人能配）、参数定义（配置了什么）、执行逻辑（配置了什么就做什么）。下面是工作日节点的核心实现，摘掉琐碎的类型细节后约三十行：

// 服务端：注册「工作日计算」节点（示意骨架，字段名以当版接口文档为准）
export class WorkdaysPlugin extends Plugin {
  async load() {
    // 注册口的函数名随版本演进，以当版工作流插件的接口为准；
    // 结构上分两步：先声明节点，再给执行器
    // 1. 声明节点类型
    //    title: '工作日计算'
    //    type: 'workdays-calc'
    //    fieldset: { startDate: 日期, endDate: 日期, targetField: 单行文本 }
    // 2. 执行器：读节点配置 → 计算 → 写入流程变量
    const execute = async (node, input, processor) => {
      const { startDate, endDate } = node.config
      let days = 0
      const cur = new Date(startDate)
      while (cur <= new Date(endDate)) {
        const w = cur.getDay()
        if (w !== 0 && w !== 6) days++      // 跳过周六周日；法定节假日另行配置
        cur.setDate(cur.getDate() + 1)
      }
      processor.setResult(node.id, { workdays: days })
      return { status: 'resolved' }
    }
  }
}
​

写完后在开发工程里把插件声明为启用，启动开发服务。预期看到控制台输出插件加载成功的日志行；若报错，多数是清单字段拼写或依赖缺失——报错信息会直指文件与行号。

联调三步：
  1. 启动开发服务后，工作流画布的节点列表里应出现「工作日计算」
  2. 拖一条测试流程：手动触发 → 工作日计算 → 待办节点回显结果
  3. 造一条跨周末的数据（周五到下周二）→ 预期结果为三天
     跑偏了就回执行记录看该节点的输入输出，逐变量核对
​

三、把节点接回真实流程

练习件通过联调后，接回 3.2 的请假流程：提交后加一枚「工作日计算」节点，起点与终点分别引用表单的开始、结束日期字段，计算结果写回「天数」字段——手填误差从流程上根除。这个接回动作只花十分钟，却是二次开发最有仪式感的一刻：你造的零件与官方零件在画布上平起平坐，配置员根本分不出谁是谁。

交付归仓按仓库规矩走：代码评审、版本号、更新日志，然后按 4.2 的插件台账登记——谁申请、为什么写、数据落在哪。自研插件最容易断档的是维护：人员离职后没人敢动。台账里加一列「维护人」，交接时连人带代码一起交。

四、自学方法：照着官方插件抄结构

本节真正想教的是这句标题。平台接口会随版本演进，文档永远滞后于代码，但官方插件永远同步——它是活的接口示例。要写什么能力，先找一个做了类似事情的官方插件，读它的清单、注册方式、目录组织，然后把骨架抄进自己的插件里改实现。这个「抄结构、换实现」的方法让接口变化的学习成本大幅下降：新版接口怎么用，官方插件就是标准答案。

进阶方向按需取用：服务端自定义 API 资源、客户端自定义区块组件、监听数据钩子做联动计算、接入外部认证。每个方向的入门路径相同——找官方同类插件、抄结构、最小实现、联调、归仓。第一次走全程要一两天，第三次之后，多数需求半天可交付。

⚠️ 常见坑：插件里直接读写别的插件的内部表。表结构是插件私有契约，人家升级改表你就崩。跨插件取数走公开接口或事件钩子——协议之内是生态，协议之外是地雷。

💡 关键直觉：二次开发的成本大头不在写代码，在「跟版本」。自研插件要像自家产品一样做版本管理，每次平台升级前，先过一遍自研插件的兼容核对清单。

装配要点回顾

• 环境三纪律：生产零改动、版本对齐、插件独立仓库，缺一都是升级日的事故；
• 节点三交代：配置面板、参数定义、执行逻辑，工作流节点的全部骨架；
• 联调靠记录：执行记录里的节点输入输出是调试的主战场，造跨边界数据验证；
• 接回流程：自研零件与官方零件在画布上平起平坐，这是框架级平台的核心回报；
• 抄结构方法论：官方插件是活的接口文档，抄结构、换实现、联调、归仓；
• 下一站：4.4 看材料学——这套体系底层用什么搭成，代码住在哪里。