UDC应用源码扩展

• 1: 后端源码扩展
• 1.1: 后端手写代码准备工作
• 1.2: 自定义定时任务微流程
• 1.3: 自定义服务定义微流程
• 1.4: 自定义事件监听微流程
• 1.5: 后端自定义函数扩展
• 1.5.1: 表达式自定义函数自定义语法校验规则
• 1.5.2: 表达式组件自定义函数手册
• 2: 前端源码扩展
• 3: 实体对应的数据库、应用jar包版本

1 - 后端源码扩展

1.1 - 后端手写代码准备工作

找到当前环境低代码应用源码的仓库地址

我们都知道低代码平台制作的业务应用在发布之后，会自动生成前、后端源代码，生成好这些源代码之后会自动提交到当前环境对应的gitlab仓库中，我们的手写代码也不例外，需要提交到当前环境的gitlab仓库中。我们可以找到当前环境的运维管理员，登录Nacos查看当前环境Data Id为public的配置，其中seeyon.repo就是当前环境的仓库信息配置，例如：

• seeyon.repo.gitlab.parentGroupPath为自动生成的前后端源码存放的分组；
• seeyon.repo.gitlab.parentExtendGroupPath为后端扩展代码存放的分组；

如何找到自动生成的前后端源码

应用做了测试发布或者正式发布之后，我们可以从gitlab中将该应用的前、后端源码clone到本地。

找到前面seeyon.repo.gitlab.parentGroupPath配置的分组，打开该分组，通过应用的appName即可检索出应用前后端源码，例如：

找到应用后端扩展工程，创建对应版本号的分支

1.找到前面seeyon.repo.gitlab.parentExtendGroupPath配置的扩展代码分组，打开该分组，通过应用appName找到后端扩展源码工程，例如：

2.打开扩展工程，复制clone链接地址

3.通过步骤3得到的链接地址，将应用扩展工程clone到本地，根据当前应用发布的版本号前两位创建扩展工程分支名称，例如：

4.在扩展工程中创建相同名称的分支，例如：

后端扩展工程pom文件编写

后端扩展工程是个独立的工程，它和自动生成出来的源码工程的关系是通过pom文件进行定义的，我们在编写后端java源码之前，需要先将pom.xml编写好，以下是个示例，如果是其他应用，可以将其中的appName替换为您应用的appName即可，您的扩展工程如果需要依赖第三方jar包，也可以在该文件中用< dependency >标签进行依赖，此处需要特别注意的是< parent >标签中的定义的版本号，该版本号需要查看该应用对应的自动生成的源码中pom的版本号，示例：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.seeyon</groupId>
    <artifactId>edoc335172694483814428-ext</artifactId>
    <version>${parent.version}</version>
    <packaging>jar</packaging>
    <parent>
        <groupId>com.seeyon</groupId>
        <artifactId>edoc335172694483814428</artifactId>
        <version>3.6.39</version>
    </parent>

    <dependencies>
        <!-- 依赖自动生成的当前应用jar包 -->
        <dependency>
            <groupId>com.seeyon</groupId>
            <artifactId>edoc335172694483814428-biz</artifactId>
            <version>${parent.version}</version>
        </dependency>
        <dependency>
            <groupId>com.seeyon</groupId>
            <artifactId>edoc335172694483814428-web</artifactId>
            <version>${parent.version}</version>
        </dependency>
        <dependency>
            <groupId>com.seeyon</groupId>
            <artifactId>edoc335172694483814428-facade</artifactId>
            <version>${parent.version}</version>
        </dependency>
    </dependencies>
</project>

本地Maven setting文件配置

Maven 是一个基于项目对象模型 (POM) 的项目管理和构建工具，主要用于 Java 项目。它提供了一种标准化的方式来管理项目的构建、报告和文档。Maven 的核心功能包括依赖管理、构建自动化和项目生命周期管理，更多Maven使用请查阅其他资料。低代码平台创建的应用就是通过Maven进行管理的。

1.联系运维从Nacos配置中查找到当前环境对应的Maven仓库配置

2.根据配置修改本地Maven的setting配置文件

可以联系当前环境运维工程师配合给出当前Maven库的setting配置文件

1.2 - 自定义定时任务微流程

步骤

1. 按需新增一个自定义定时任务类型的微流程，微流程会为您自动生成一个编码，不过我们还是建议您按照语义自己定义编码，比如当前示例中的sendMsgPerMounth。

   

2. 点击第一个节点，按需设置循环周期

   

3. 保存该微流程为正式态（应用发布的时候只会为正式态的微流程生成代码）

4. 测试发布该应用，等待应用测试发布成功

5. 应用发布成功之后，按照后端手写代码准备工作中的步骤将扩展工程准备好

6. 刷新本地maven仓库，确保已经将该应用最新版本的jar包更新到了本地，maven刷新成功之后可以看到该应用的{appName}-facade.jar中CustomMicroFlowAppService这个interface中已经有我们的sendMsgPerMounth方法，编写一个实现类，实现该接口之后提交到源码仓库重新发布该应用即可。

1.3 - 自定义服务定义微流程

步骤

1. 按照需要，在规则-微流程菜单中新增一个自定义的服务定义微流程：
   
2. 根据实际需要配置微流程参数
   
3. 保存该微流程（注意需要保存为正式态）
   
4. 测试发布应用，平台会在应用发布的时候为此微流程生成对应的Interface以及Interface中的方法，并且进行编译打包，上传maven仓库
   
5. 按照后端手写代码准备工作说明的步骤，将该应用的扩展工程创建准备好
6. 在扩展工程中新增包路径com.seeyon.{appName}.extend.appservice,在此包中新增微流程实现类，类名称自定，该新增的实现类实现微流程的Interface

package com.seeyon.renshiguanli4146632722591861173.extend.appservice;

import com.seeyon.boot.annotation.AppService;
import com.seeyon.boot.annotation.AppServiceOperation;
import com.seeyon.boot.transport.SingleRequest;
import com.seeyon.boot.transport.SingleResponse;
import com.seeyon.renshiguanli4146632722591861173.api.microflow.CustomMicroFlowAppService;
import com.seeyon.renshiguanli4146632722591861173.extend.service.ResumeService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.transaction.annotation.Transactional;

/**
 * 微流程AppService
 **/
@AppService(value = "自定义人事管理接口")
@Transactional(rollbackFor = Exception.class)
@Slf4j
public class CustomMicroFlowAppServiceImpl implements CustomMicroFlowAppService {
    
}

7. 编写该微流程的方法实现，注意实现类的@AppService、@Transactional等注解一定要打上

package com.seeyon.renshiguanli4146632722591861173.extend.appservice;

import com.seeyon.boot.annotation.AppService;
import com.seeyon.boot.annotation.AppServiceOperation;
import com.seeyon.boot.transport.SingleRequest;
import com.seeyon.boot.transport.SingleResponse;
import com.seeyon.renshiguanli4146632722591861173.api.microflow.CustomMicroFlowAppService;
import com.seeyon.renshiguanli4146632722591861173.extend.service.ResumeService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.transaction.annotation.Transactional;

/**
 * 微流程AppService
 **/
@AppService(value = "自定义人事管理接口")
@Transactional(rollbackFor = Exception.class)
@Slf4j
public class CustomMicroFlowAppServiceImpl implements CustomMicroFlowAppService {

    @Autowired
    private ResumeService resumeService;

    /**
     * 简历解析
     *
     * @param request
     * @return
     */
    @Override
    @AppServiceOperation(value = "简历解析", returnValue = "简历解析")
    public SingleResponse<Void> parseResume(SingleRequest<String> request) {
        if (log.isDebugEnabled()) {
            log.debug("简历解析入参:{}", request.getData());
        }
        resumeService.parse(request.getData());
        return SingleResponse.ok();
    }


}

8. 编写好之后确保本地没有任何编译错误即可将代码提交到代码仓库中，如果将有编译错误的代码提交到代码仓库中会导致您的应用发布失败

9. 微流程实现代码提交之后，再次测试发布应用，即可将实现打包到应用中，其他的前/后端微流程都可以对此微流程进行调用

   

1.4 - 自定义事件监听微流程

步骤

1. 在点击规则-微流程菜单中的+号，新增一个自定义事件监听类型的微流程
   
2. 点击第一个节点，为该事件监听类型微流程配置监听哪个应用的哪个实体的哪个事件
   
   本案例选择监听物资信息实体的新增前事件，平台为每个实体预制了9种事件，您可以按需进行选取，注意事项：监听xxx（操作成功）事件的行为动作和实体本身的新增、修改、删除的行为动作，在数据库事务层面，不是同一个数据库事务
   
3. 设置好事件并且为改节点取名之后，点击微流程的保存，将该微流程保存为正式态
   
4. 测试发布该应用
   
5. 应用发布成功之后，按照后端手写代码准备工作中的步骤将扩展工程准备好
6. 刷本地maven仓库，确保已经将该应用最新版本的jar包更新到了本地
7. 如果还没有为CustomMicroFlowAppService添加实现类，则添加一个实现类（注意实现类的@AppService、@Transactional等注解一定要打上），如果已经有实现类实现了CustomMicroFlowAppService，则直接在你的实现类中@Override该方法,提交源码，然后重新发布应用即可
   

1.5 - 后端自定义函数扩展

1.5.1 - 表达式自定义函数自定义语法校验规则

注：需要低代码平台版本2.8.0以上或表达式组件版本2.8.0以上支持

在表达式组件自定义函数时，某些场景下我们需要对函数定义特定的语法规则，比如，虽然函数的入参都是Long, 但是在V8平台中关联实体、枚举的实际类型都是Long ,如果我们要求入参只能是关联实体的Long , 那么就需要自定义语法规则限制参数的类型。

再比如，我们定义的函数的返回值类型可能是不固定的，比如绝对值函数，如果入参是整数，那么返回结果就是整数，如果入参是小数，返回结果则是小数，此时我们的静态函数的入参和返回值可能都是Object类型。自定义语法校验不仅可以校验参数的类型，还可以定义返回结果的类型。

1.代码示例

自定义校验示例代码:

@Slf4j
@FunctionSupporter(functions = {FunctionConstant.ABS_FUNCTION })
public class AbsFunctionSemanticAnalyzer implements FunctionSemanticAnalyzer {

    @Override
    public ExpressionDataType analyze(ASTNode astNode, SemanticAnalyzer semanticAnalyzer) {
        ASTNode paramNode = astNode.getChild(0);
        ExpressionDataType paramExpressionDataType = semanticAnalyzer.analyze(paramNode);
        DataType originDataType = paramExpressionDataType.getOriginDataType();

        if(DataType.INTEGER != originDataType && DataType.BIGINTEGER != originDataType &&
           DataType.DECIMAL != originDataType ){
            throw BusinessException.message("绝对值函数参数必须为数字类型!");
        }
        //注意：这里返回当前AST节点预期返回的类型，不是入参的类型
        return paramExpressionDataType;
    }


}

绝对值函数的自定义函数代码如下(自定义函数的规范参考《表达式组件自定义函数手册》 )：

@Function( category = FormulaFunctionCategoryEnum.Constants.MATH, displayName = ABS_DISPLAYNAME ,
            description = ABS_DESCRIPTION ,
            sort = 1 )
    @Parameters( value = {@Parameter(displayName = ABS_PARAM0_DISPLAYNAME, description = ABS_PARAM0_DESCRIPTION)})
    @ReturnValue( dataType = FormulaDataTypeEnum.Constants.DECIMAL, description = ABS_RESULT_DESCRIPTION )
    public static Object abs(Object number) {
        return number;
    }

2.定义规范

上述代码定义了绝对值函数abs(xxx) 的语法校验规则， 首页我们看到自定义函数abs的入参和返回值都是Object类型，这是为了同时兼容整数、长整数、小数这几种类型。在自定义语法校验逻辑中，我们定义一个类并实现FunctionSemanticAnalyzer接口 ， 并在该类上打上**@FunctionSupporter注解， 其属性functions**表示该语法校验规则支持的函数，该属性为字符串数组 ，您可以将多个参数和返回值相似的函数定义为同一个语法校验规则，functions的值为自定义函数的方法名，比如这里的：abs 。

除了实现FunctionSemanticAnalyzer接口外，还需要将该类的全包名注册到项目工程的

META-INF/spring.factories 文件中， 这是因为自定义函数校验规则使用了spring-boot的SPI机制。如下所示:

com.seeyon.boot.starter.formula.parser.semantic.function.FunctionSemanticAnalyzer=\
com.seeyon.boot.starter.formula.parser.semantic.function.AbsFunctionSemanticAnalyzer

3.校验实现

我们可以看到FunctionSemanticAnalyzer接口有两个参数 ， astNode 和 semanticAnalyzer 。

astNode: 表达式当前自定义函数的抽象语法树节点对象，您可以通过astNode.getLexeme().getValue()和astNode.getLexeme().getDesc() 获取到函数名称(abs)和函数的显示名称(取绝对值) 。

astNode.getChild(index)可以获取到函数对应下标的参数节点， 比如这里的abs函数只有一个参数，所以可以通过 astNode.getChild(0)的方式获取到参数节点，其也为一个ASTNode对象。

semanticAnalyzer： 如果需要分析参数的类型，可以通过semanticAnalyzer.analyze(paramNode)的方式，获取到参数的类型ExpressionDataType , 通过paramExpressionDataType.getOriginDataType()可以获取参数的实际类型。

analyze方法的返回值类型即为该自定义函数的实际返回类型，比如我们已经通过semanticAnalyzer.analyze分析到了abs函数的入参类型，这里绝对值函数的返回类型就应该是入参的类型，所以直接返回paramExpressionDataType。

此外，如果返回值的类型需要自行定义，可以使用ExpressionDataType的构造方法返回一个新的数据类型，示例如下：

@Override
public ExpressionDataType analyze(ASTNode astNode, SemanticAnalyzer semanticAnalyzer) {
    ASTNode paramNode = astNode.getChild(0);
    ExpressionDataType paramNodeDataType = semanticAnalyzer.analyze(paramNode);
    if(paramNodeDataType.isMultiSelect()){
        return ExpressionDataType.ofDataType(DataType.STRING);
    }else{
        return ExpressionDataType.ofDataType(DataType.BIGINTEGER);
    }
}

在上面的示例中，我们判断参数是否是多选(枚举、关联实体)类型，如果是多选我们返回了一个String类型的返回值，如果是单选我们返回了一个Long类型的返回值。

1.5.2 - 表达式组件自定义函数手册

一.静态函数定义示例

@FunctionClass
public class UdcBasicFunction {

    @Function(category = FormulaFunctionCategoryEnum.Constants.TEXT, displayName = ENDSWITH_DISPLAYNAME,
            description = ENDSWITH_DESCRIPTION , sort = 3)
    @Parameters(value = {@Parameter(displayName = ENDSWITH_PARAM0_DISPLAYNAME, description = ENDSWITH_PARAM0_DESCRIPTION) ,
            @Parameter(displayName = ENDSWITH_PARAM1_DISPLAYNAME, description = ENDSWITH_PARAM1_DESCRIPTION)})
    @ReturnValue(dataType = FormulaDataTypeEnum.Constants.BOOLEAN, description = ENDSWITH_RESULT_DESCRIPTION)
    public static Boolean endsWith(String str, String suffix) {
        return StringUtils.endsWith(str, suffix);
    }

}

二、注解含义

三、V8平台数据类型和java数据类型映射

在V8的体系中，函数定义、校验（见: 《表达式自定义函数自定义语法校验规则》） 以及字段的数据类型元数据描述都是使用： com.seeyon.boot.enums.DataType 这个枚举类。其枚举类型和java的数据类型有如下映射关系

四、国际化规范

1.函数分类国际化规范

在定义函数的注解@Function中 ， category属性用来描述函数的分类， 该属性是一个整数code , 所以需要自定义国际化词条。目前预置的函数分类提供了以下几种:

但是以编码可能不满用户自定义的函数分类，所以可以单独指定一个整数编码，并提取为自定义的常量(建议自定编码从100开始，避免和预制函数分类编码冲突)。同时需要在项目的 resources/i18n 目录下， 增加国际化词条， 规则如下： formula.function.category. + 自定义的函数分类编码。

formula.function.category.100=自定义函数分类

2.函数参数、返回值描述国际化规范

函数入参和返回值的国际化规范适用于 **@Function.displayName 、@Function. description、 @Parameter.displayName 、@Parameter.description、@ReturnValue.description **

比如, 静态函数定义示例中的以上属性可以抽取为国际化词条:

formula.function.endsWith.displayName=以指定文本结尾
formula.function.endsWith.description=判断一个文本是否已指定文本结果
formula.function.endsWith.param0.displayName=当前文本
formula.function.endsWith.param0.description=需要判断的文本
formula.function.endsWith.param1.displayName=结尾文本
formula.function.endsWith.param1.description=是否已该文本结尾
formula.function.endsWith.result.description=如果结尾文本结尾，则返回truy，否则返回false

词条同样需要放到 **resources/i18n 目录下 , **如果不定义国际化词条，也可以直接在注解中定义上述属性的值，表达式引擎会直接将该属性的值不经过国际化处理显示到页面。

3.函数用法描述

函数用法的定义主要是针对如图所示的场景，用于描述函数的一个具体使用案例

定义用法如下：

在手写工程的resources根目录下添加一个名为: formula-functions.xml 的文件

xml文件内容示例:

注意函数用法并没有做国际化处理，指定定义一套语言环境下的用法描述。后续版本会根据 formula-functions_en.xml 、formula-functions_zh_CN.xml 等文件后缀的方式区分国际化内容。

<functions>
  <!-- 函数示例配置 -->
  <function>
    <name>round</name>
    <args>
      <arg>3.14159</arg>
      <arg>3</arg>
    </args>
    <tips>返回3.142</tips>
    <link>可以忽略</link>
  </function>
<functions>

2 - 前端源码扩展

⚠️ 注：平台提供了多层次扩展能力，组件的扩展、Iframe的嵌套等，若存在无法实现的场景和交互时，优先考虑通过扩展局部的方式实现。 这种模式下，页面的其他控件依旧可以享受平台后续迭代带来的便利。 若一旦使用了自定义页面，则后续的页面的维护只能通过代码的方式进行维护。 故，慎用！！！

1. 开发前序准备

1. 使用 React.js 进行基本开发
2. 对应环境的Git仓库,账号,密码（需要授权申请，找对应的负责人沟通申请）
3. 基本的前端开发环境(Node,VSCode……..)

2. 开发流程

自定义页面的开发流程核心分为是五个步骤

2.1. 生成代码工程

在 低代码设计器中创建页面

1. 首先进入 UDC 页面设计器. 在设计器中创建实体,以及自定义页面。
2. 保存页面后，点击页面右上角 “测试” 即可进行应用发布。
3. 发布成功后 生成好的 React 源码 就会上传到 GIT 仓库。

2.2. Git拉取源码

从 GIT 仓库 获取生成好的应用源代码

获取应用的源代码前，我们需要拿到应用的唯一标识“应用ID(appId)”或 “应用名称(appName)”，可通过下面图示获取

接下来我们进入 GIT 仓库， 通过 “应用名称(appName)” 找到对应的前端代码仓库，将代码克隆到本

⚠️Git的账号密码，需要单独的授权开通，故若没有账号密码，可找对应的技术负责人沟通

华为云仓库地址 : https://code.seeyoncloud.com/

运维负责人: 周龙波

2.3. 本地代码调试

2.3.1. 确定页面标识/页面URI

首先我们找到在设计器中定义的页面的 URL ， 在设计器-菜单-“查看页面属性” 中 找到页面标识 页面URI

2.3.2. 确定代码目录

进入 应用源代码目录后， 就可以看到 pc/mobile 两个终端的 代码。

比如我们进入 PC 目录中 ，根据页面标识 找到 customPage.tsx 文件， 此文件就是 支持 开发者实现自定义代码的文件。

小贴士: 自定义页面/栏目 只能在 pages/xxx 目录下 加 自定义代码，避免与自动生成的代码产生冲突, 导致自定义代码被冲掉

2.3.3. 安装依赖

1. 如果 调试 PC 端代码 则进入 pc 目录执行 yarn install 以便安装前端 NPM 包
2. 如果 调试 Mobile 端代码 则进入 mobile 目录执行 yarn install 以便安装前端 NPM 包

2.3.4. 调整 webpack 代理

修改 webpack-params.js 的 LOCAL_RUNTIME_ENV 变量

LOCAL_RUNTIME_ENV 变量的值参考 webpack-proxy.js 中的 键

2.3.5. 本地启动

1. 如果 调试 PC 端代码 则进入 pc 目录执行 yarn start
2. 如果 调试 Mobile 端代码 则进入 mobile 目录执行 yarn start

启动成功后进入浏览器输入地址就可以访问了

下面是一个示例:

1. 本地登录: http://localhost:3000/login
2. 登录成功后,访问具体的页面：http://localhost:3000/main/portal/hh3881652103519948446/zidingyiyemian

• main/portal: 固定的主应用地址
• hh3881652103519948446: 当前应用的英文名称
• zidingyiyemian: 当前应用下某个具体页面的 URL

2.3.6. 前后端接口交互

1. 后端提供 restFull API
2. 前端通过 fetch 等工具 调用 restFull API

2.4. Git推送页面代码

自己添加的自定义代码 调试完成后， 重新 push 到 远程 GIT 仓库

使用正常的 GIT 提交 推送流程, 将代码推送到远程仓库中

2.5. 打包构建

回到设计态重新 点击 “发布/构建/测试” 按钮

3 - 实体对应的数据库、应用jar包版本

如何确认低代码平台应用中实体对应的表名是什么

对于这个问题，您只需要使用浏览器登录到环境中，新开浏览器页签，访问以下url即可查看某应用中所有的实体对应的表名称

https://{环境域名:端口}/service/udc/udc-app-info/entity-table/{appName}

例如：https://pre.seeyonv8.com/service/udc/udc-app-info/entity-table/renshiguanli4146632722591861173

如何查看当前环境某个应用的版本号以及构建的时间点

对于这个问题，您只需要使用浏览器登录到环境中，新开浏览器页签，访问以下url即可查看到该应用的jar包的版本以及构建时间

查看地址：https://{环境域名:端口}/service/{appName}monitor/jar-info

例如：https://pre.seeyonv8.com/service/renshiguanli4146632722591861173/monitor/jar-info