低代码扩展与二次开发指南

Forge 低代码平台在四个层面提供扩展能力，从「零代码配置」到「改源码」逐级递进：

扩展层	方式	是否改源码	适用场景
应用级配置	应用设置（主题/水印/导航/权限）	否	定制应用外观与访问控制
服务端扩展处理器	实现 LowcodeExtensionHandler	是（写 Java）	动作节点调用自定义业务逻辑
流程服务增强	@FlowBind 等注解	是（写 Java）	审批流程节点回调
前端字段组件	扩展组件目录	是（写 Vue）	新增平台没有的字段控件

此外，平台支持把低代码应用导出为真实源码（代码生成），脱离低代码运行时继续手工开发，这是最终的二次开发出口。

服务端扩展处理器

业务流程画布的「执行动作」节点可以调用服务端扩展处理器。处理器是注册为 Spring Bean 的 LowcodeExtensionHandler 实现：

package com.example.forge.extension;

import com.mdframe.forge.plugin.generator.service.businessapp.extension.*;
import org.springframework.stereotype.Component;
import java.util.Map;
import java.util.Set;

@Component
public class InventoryCheckHandler implements LowcodeExtensionHandler {

    @Override
    public String handlerCode() {
        return "inventory_check";   // 小写字母开头，允许小写字母、数字、下划线，2-64 位
    }

    @Override
    public String handlerName() {
        return "库存校验";
    }

    @Override
    public Set<String> allowedHooks() {
        return Set.of("approval_callback");   // 允许被调用的钩子
    }

    @Override
    public Map<String, ExtensionInputField> inputSchema() {
        return Map.of();   // 声明入参结构，供配置界面渲染
    }

    @Override
    public ExtensionExecutionResult execute(ExtensionExecutionContext context) {
        // context 携带 hookCode、业务数据等上下文
        // 在这里执行自定义业务逻辑
        return null;
    }
}

接口方法与约束：

方法	说明
handlerCode()	处理器唯一编码，格式 ^[a-z][a-z0-9_]{1,63}$，重复注册启动即报错
handlerName()	显示名称
allowedHooks()	允许执行的钩子白名单；调用时钩子不在白名单内会拒绝执行
inputSchema() / outputSchema()	入参/出参结构声明
timeoutMs()	执行超时，默认 1000ms
riskLevel()	风险等级，默认 MEDIUM
requiredPermission()	需要的权限标识，默认无

详细开发流程、契约规则与安全边界见低代码 Java 服务增强开发指南。

流程服务增强

审批流程（Flowable）节点需要执行业务逻辑时，使用服务增强注解：

注解	作用
@FlowBind(processKey, nodeKey)	绑定到 BPMN 节点，节点执行时回调
@FlowStart(processKey)	流程启动时回调
@FlowCallback(processKey)	审批结果回调（通过/驳回）

注解参数、FlowContext 常用方法和接口规范见Java 服务增强公开契约。

前端字段组件扩展

页面设计器左侧组件库内置 33 种字段组件（输入/选择/业务三组），由组件目录统一管理。新增一种字段组件需要修改三处（均在 forge-admin-ui）：

1. 组件目录注册

src/views/app-center/components/designer/form-first/fieldComponentCatalog.js：

• 在 FIELD_COMPONENT_PALETTE_GROUPS 对应分组添加 { componentKey, label }
• 在 FIELD_COMPONENT_DEFAULTS 添加该组件的字段默认值：

'myComponent': {
  fieldType: 'TEXT',            // 业务字段类型
  businessFieldType: 'TEXT',
  dataType: 'varchar',          // 自动建列时的数据库类型
  componentType: 'myComponent', // 运行时渲染使用的组件类型
  length: 128,
  precision: 2,
  queryType: 'like',            // 作为查询条件时的匹配方式
}

拖入画布时，系统按这份默认值自动创建业务对象字段和数据库列。

2. 运行时渲染

src/components/ai-form/AiFormItem.vue：为新的 componentType 添加渲染分支，否则设计器能拖入但运行时渲染不出来。

3. 契约测试

src/views/app-center/components/designer/__tests__/business-form-runtime-compile.spec.js 校验「左侧货架每个组件都有字段模型默认值」的契约。组件数量变化时同步更新断言（当前为 33 个），并跑通该测试：

pnpm vitest run business-form-runtime-compile

平台配置项

低代码相关的后端配置（application.yml）：

配置项	默认值	说明
forge.business.datasource.enabled	false	是否启用业务侧租户数据源路由
forge.business.datasource.tenant-routing-enabled-default	false	sys_config 未配置时是否默认启用租户路由
forge.business-trigger.schedule.enabled	-	是否启用定时触发扫描调度
forge.business-trigger.schedule.max-triggers-per-run	100	单次扫描最大触发数
forge.business-trigger.schedule.cluster-lock-enabled	true	集群部署时是否启用分布式扫描锁
forge.business-trigger.schedule.lock-wait-ms	0	扫描锁等待时间（毫秒）

应用级配置（主题、水印、导航、访问地址、权限、全球化、代码生成前缀、缓存策略、版本保留数量）统一在应用设置中维护，随发布快照生效，不需要改配置文件。

代码生成出口

低代码应用、对象和页面都支持导出真实源码（Java + Vue）。导出的代码遵循框架标准结构，可以直接纳入工程手工迭代。应用设置中的「代码生成前缀」控制生成物命名。

下一步

• 低代码 Java 服务增强开发指南
• Java 服务增强公开契约
• 业务流程画布
• 代码生成器