diff --git a/.idea/workspace.xml b/.idea/workspace.xml index 1086c6a..8aabe6c 100644 --- a/.idea/workspace.xml +++ b/.idea/workspace.xml @@ -5,13 +5,34 @@ - - - + + + + + + + + + + + + + + - - - + + + + + + + + + + + + + + - + - @@ -128,6 +150,14 @@ + + + + + + + + @@ -155,4 +185,19 @@ + + + + + file://$PROJECT_DIR$/node_modules/@docusaurus/theme-classic/src/theme/CodeBlock/index.tsx + 7 + + + file://$PROJECT_DIR$/src/components/Contact/index.js + + + + \ No newline at end of file diff --git a/docs/develop/compile-running.mdx b/docs/develop/compile-running.mdx index bf9b85d..8737740 100755 --- a/docs/develop/compile-running.mdx +++ b/docs/develop/compile-running.mdx @@ -1,5 +1,5 @@ --- -title: 编译&运行 +title: TIS编译&运行 date: 2020-03-22 type: book weight : 10 @@ -18,7 +18,7 @@ weight : 10 一个完整的TIS应用，由以下三个子工程构成： -1. TIS主干逻辑 [https://github.com/qlangtech/tis](https://github.com/qlangtech/tis) +1. TIS主干逻辑 [https://github.com/datavane/tis](https://github.com/datavane/tis) 2. TIS插件 [https://github.com/qlangtech/plugins](https://github.com/qlangtech/plugins) 3. 前端逻辑 [https://github.com/qlangtech/ng-tis](https://github.com/qlangtech/ng-tis) @@ -26,7 +26,7 @@ weight : 10 ``` bash - git clone git@github.com:qlangtech/tis.git + git clone git@github.com:datavane/tis.git git clone git@github.com:qlangtech/plugins.git @@ -44,15 +44,15 @@ weight : 10 TIS使用的Maven推荐使用**v3.8.1** 版本 --> -#### 编译 qlangtech/tis 项目 +#### 编译 datavane/tis 项目 ```shell script cd tis -mvn clean install -Dmaven.test.skip=true +mvn clean install -Dmaven.test.skip=true -Ptis-repo ``` :::caution - 由于qlangtech/plugins 项目需要依赖 qlangtech/tis 中的artifact，因此以上Maven执行命令中需要使用**install** + 由于qlangtech/plugins 项目需要依赖 datavane/tis 中的artifact，因此以上Maven执行命令中需要使用**install** ::: @@ -60,7 +60,7 @@ mvn clean install -Dmaven.test.skip=true ```shell script cd plugins -mvn clean package -Dmaven.test.skip=true -Dappname=all +mvn clean package -Dmaven.test.skip=true -Dappname=all -Ptis-repo ``` :::caution @@ -116,7 +116,8 @@ npm uninstall -g @angular/cli 具体执行命令为： ```shell script -for f in `find ./plugins -name '*.tpi' -print` +cd 'path of qlangtech/plugins项目' +for f in `find ./ -name '*.tpi' -print` do echo " ln -s $f " ln -s $f /opt/data/tis/libs/plugins/${f##*/} @@ -126,7 +127,11 @@ done ; ### 启动TIS Console 1. cd tis/tis-console/src/test/java/ -2. 运行 `StartTISWeb` 单元测试 +2. 创建初始化token文件： + ```shell + touch /opt/data/tis/system_initialized_token + ``` +3. 运行 `StartTISWeb` 单元测试 ```shell script mvn compile test -Dtest=StartTISWeb @@ -142,11 +147,16 @@ done ; ### 启动TIS Web 1. cd ng-tis -2. 运行 - +2. 编译： + ```shell + npm run ng:serve-aot + ``` +3. 运行 ```shell npm run ng:serve-jit --scripts-prepend-node-path=auto ``` +4. 打开 web 入口：`http://localhost:4200/` + ### 启动Assemble Web diff --git a/docs/develop/img/add-new-plugin.png b/docs/develop/img/add-new-plugin.png new file mode 100644 index 0000000..9c53d24 Binary files /dev/null and b/docs/develop/img/add-new-plugin.png differ diff --git a/docs/develop/img/description.md.png b/docs/develop/img/description.md.png new file mode 100644 index 0000000..b6b5ac2 Binary files /dev/null and b/docs/develop/img/description.md.png differ diff --git a/docs/develop/img/mysqlv5datasourcefactory-inherit-diagram.png b/docs/develop/img/mysqlv5datasourcefactory-inherit-diagram.png new file mode 100644 index 0000000..31a4280 Binary files /dev/null and b/docs/develop/img/mysqlv5datasourcefactory-inherit-diagram.png differ diff --git a/docs/develop/img/plugin-mysql-datasource.png b/docs/develop/img/plugin-mysql-datasource.png new file mode 100644 index 0000000..d931f30 Binary files /dev/null and b/docs/develop/img/plugin-mysql-datasource.png differ diff --git a/docs/develop/img/plugin-verify-validateAll.png b/docs/develop/img/plugin-verify-validateAll.png new file mode 100644 index 0000000..7a58b0d Binary files /dev/null and b/docs/develop/img/plugin-verify-validateAll.png differ diff --git a/docs/develop/img/plugins-arch.png b/docs/develop/img/plugins-arch.png new file mode 100644 index 0000000..e8df84a Binary files /dev/null and b/docs/develop/img/plugins-arch.png differ diff --git a/docs/develop/img/plugins-relation.png b/docs/develop/img/plugins-relation.png new file mode 100644 index 0000000..234ec83 Binary files /dev/null and b/docs/develop/img/plugins-relation.png differ diff --git a/docs/develop/img/plugins-ui.png b/docs/develop/img/plugins-ui.png new file mode 100644 index 0000000..c1fd968 Binary files /dev/null and b/docs/develop/img/plugins-ui.png differ diff --git a/docs/develop/img/properties-desc.png b/docs/develop/img/properties-desc.png new file mode 100644 index 0000000..ef968aa Binary files /dev/null and b/docs/develop/img/properties-desc.png differ diff --git a/docs/develop/plugin-develop-detail.mdx b/docs/develop/plugin-develop-detail.mdx new file mode 100644 index 0000000..28f1e18 --- /dev/null +++ b/docs/develop/plugin-develop-detail.mdx @@ -0,0 +1,400 @@ +--- +title: 插件实现开发详细说明 +date: 2023-04-12 +type: book +weight : 11 +--- + +import Link from '/src/components/Link'; +import Figure from '/src/components/Figure'; +import CodeBlock from '@theme/CodeBlock'; + +为了直观地说明如何编写一个TIS扩展点实现，我们以一个最经典的例子来讲解，那就是MySQL DataSource + +
+ +从以下[MySQLV5DataSourceFactory](https://tis.pub/docs/plugin/plugins#comqlangtechtisplugindsmysqlmysqlv5datasourcefactory)类图的继承链来看， +它扩展于`com.qlangtech.tis.plugin.ds.DataSourceFactory`,为了最大限度地为基于JDBC的数据源提供代码复用，`MySQLV5DataSourceFactory`与扩展点`DataSourceFactory`继承链中间，加入了两个中间类， +`MySQLDataSourceFactory` 与 `BasicDataSourceFactory`。 + +
+ +假若，现在TIS中还没有MySQL（5.7版本）的JDBC DataSource的插件，需要新添加一个新的扩展实现。我们可以按以下步骤来创建脚手架工程： + +首先需要在 `$MAVEN_HOME/conf/setting.xml` 文件中添加 TIS的私有仓库Profile，配置如下所示： +```xml + + + + + tis + + + tis-releases + http://mvn-repo.oss-cn-hangzhou.aliyuncs.com/release/ + + + + + tis-releases + http://mvn-repo.oss-cn-hangzhou.aliyuncs.com/release/ + + + + + +``` + + +export const CreateArchShell = () => { +return ( +
+ + mvn com.qlangtech.tis:tis-archetype-generate-plugin:{metadata.version}:generate \{'\n'} + -Drat.skip=true \{'\n'} + -Dtis.version={metadata.version} \{'\n'} + -Dtis.extendpoint="com.qlangtech.tis.plugin.ds.mysql.MySQLDataSourceFactory:MySQLV5DataSourceFactory" \{'\n'} + -Dtis.artifactId=tis-mysql-ds-v5-plugin \{'\n'} + -Ptis + +
+); +} + +然后执行以下命令创建插件骨架工程： + + + +**为了更明晰说明，我们不复用已有的代码** 修改以上`tis.extendpoint`为以下 + +```shell +-Dtis.extendpoint="com.qlangtech.tis.plugin.ds.DataSourceFactory:MySQLV5DataSourceFactory" +``` + +生成的脚手架工程文件列表： +```shell +|____pom.xml +|____src +| |____test +| | |____java +| | | |____TestAll.java +| | | |____com +| | | | |____qlangtech +| | | | | |____tis +| | | | | | |____plugin +| | | | | | | |____ds +| | | | | | | | |____mysql +| | | | | | | | | |____extend +| | | | | | | | | | |____TestMySQLV5DataSourceFactory.java +| |____main +| | |____resources +| | | |____com +| | | | |____qlangtech +| | | | | |____tis +| | | | | | |____plugin +| | | | | | | |____ds +| | | | | | | | |____mysql +| | | | | | | | | |____extend +| | | | | | | | | | |____MySQLV5DataSourceFactory.json +| | | | | | | | | | |____MySQLV5DataSourceFactory.md +| | |____java +| | | |____com +| | | | |____qlangtech +| | | | | |____tis +| | | | | | |____plugin +| | | | | | | |____ds +| | | | | | | | |____mysql +| | | | | | | | | |____extend +| | | | | | | | | | |____MySQLV5DataSourceFactory.java +``` +示例代码已经上传至：https://github.com/qlangtech/tis-mysql-ds-v5-plugin + +## 扩展实现功能说明 + +基于TIS扩展点`com.qlangtech.tis.plugin.ds.DataSourceFactory`的扩展实现，主要作用就是获得JDBC DataSource中的元数据信息（数据表列集合） +，为批量增量数据抽取或者写入可以创建`java.sql.Connection`对象实例。 + +## 编写扩展实现类 + +扩展实现类的编写主要是围绕`MySQLV5DataSourceFactory.java`展开, + +### 骨架代码`MySQLV5DataSourceFactory`结构说明 + +使用脚手架工具生成插件工程，之后将插件工程Import到Idea中，打开`MySQLV5DataSourceFactory.java` 将会发现除类的主体部分，内部有一个经过 +`@TISExtension`装饰的 `DefaultDescriptor`的内隐类，该类的作用是对`扩展实现`提供运行时属性描述生成，和页面表单提交执行功能校验等功能。 +```java +@Public +public class MySQLV5DataSourceFactory extends DataSourceFactory { + @TISExtension + public static class DefaultDescriptor extends BaseDataSourceFactoryDescriptor { + + } +} +``` +接下来，我们需要在骨架代码上添加功能，使之能够真正在生产环境中发挥作用。 + +### 添加属性 + +按照`MySQLV5DataSourceFactory.java`的功能描述，通过它可以创建`java.sql.Connection`实例对象，那`MySQLV5DataSourceFactory.java`内部就需要具备创建`Connection` +实例的属性成员，我们先枚举以下这些属性： 1.用户名 2.密码 3.数据库名 4.端口 5.服务IP地址。 + +除此之外，由于可以在TIS中定义多个MySQL的数据源，需要能够有一个属性来为每个数据源标记， 所以，还需要一个作为Identity的属性 + +我们将这些属性进行列表说明： + +|字段名称|作用说明| 类型 | 校验规则 | +|-|-|-|-| +|userName|用户名| 字符串| 不能为空 | +|password|密码| 加密字符串| 不能为空字符串| +|dbName|数据库名| 字符串|大小写字母加数字'-'号| +|port| 端口 | 整型数字 | 不能为空 | +|serverNode|服务IP地址| 字符串 | 不能为空，符合IP或者Host规范| +|name | 插件Identity标示属性| 字符串 |大小写字母加数字'-'号| + +基于以上这些属性描述，便可在`MySQLV5DataSourceFactory.java`类内部添加如下Java成员属性： +```java +@Public +public class MySQLV5DataSourceFactory extends DataSourceFactory { + + @FormField(ordinal = 1, type = FormFieldType.INPUTTEXT + , validate = {Validator.require, Validator.hostWithoutPort}) + public String serverNode; + + @FormField(ordinal = 2, type = FormFieldType.INPUTTEXT + , validate = {Validator.require, Validator.identity}) + public String dbName; + + @FormField(ordinal = 3, type = FormFieldType.INPUTTEXT + , validate = {Validator.require, Validator.user_name}) + public String userName; + + @FormField(ordinal = 4, type = FormFieldType.PASSWORD + , validate = {Validator.require, Validator.none_blank}) + public String password; + + @FormField(ordinal = 3, type = FormFieldType.INPUTTEXT + , validate = {Validator.require, Validator.integer}) + public Integer port; +} +``` +发现每个属性都伴有一个`@FormField`装饰器修饰，作用是为后续TIS UI-DSL自动在HTML页面自动渲染用，@FormField详细参数设置请查看 + +### 表单校验 +#### 自定义属性校验 + +通过添加`@FormField`Annotation 上设置`validate`属性可以设置字段的字面校验，例如：必须输入（Validator.require），唯一实体键（Validator.identity），整型字段（Validator.integer）等，这些是基本校验规则。 + +如开发者还需要添加额外校验可在Descriptor中添加额外校验规则，例如，`password` 需要同时有大写、小写、和数字，代码如下： + +```java + @TISExtension + public static class DefaultDescriptor extends BaseDataSourceFactoryDescriptor { + + public boolean validatePassword(IFieldErrorHandler msgHandler, Context context, String fieldName, String value) { + + Pattern p1 = Pattern.compile("[A-Z]+"); + Pattern p2 = Pattern.compile("[a-z]+"); + Pattern p3 = Pattern.compile("[0-9]+"); + if (!(p1.matcher(value).find() + && p2.matcher(value).find() + && p3.matcher(value).find())) { + msgHandler.addFieldError(context,fieldName,"需要同时有大写、小写、和数字"); + return false; + } + return true; + } + } +``` +如上，在`DefaultDescriptor`中添加校验方法，方法名需要符合规范："validate"+ capitalize(属性名称)，方法需要为`public`，返回为`boolean`类型，拥有四个参数分别为：IFieldErrorHandler, context, fieldName, value + +#### 实现插件表单`verify/validate`功能 + +除单字段值校验，还需要对表单整体内容进行业务逻辑校验，例如，验证表单能否正常创建 `java.sql.Connection`实例对象，`DefaultDescriptor`父类中的两个方法： + +```java +public abstract class Descriptor { + protected final boolean verify( + IControlMsgHandler msgHandler, Context context, PostFormVals postFormVals){ + + return true; + } + + protected boolean validateAll( + IControlMsgHandler msgHandler, Context context, PostFormVals postFormVals) { + return true; + } +} +``` +方法`verify`和`validateAll`区别是： + +* 使用`verify`对表单进行校验，服务端会校验表单是否正确，无论校验结果是否正确都不影响表单保存。这种验证场景是，当用户需要添加一个JDBC的DataSource，可能在你添加表单时候 +DBA还没有真实添加数据库实例，因此通过verify校验结果肯定会是失败的，但用户依然可以将表单进行保存。 +* 使用`validateAll`对表单进行校验，服务端校验失败，则用户无法对表单进行保存。 + +下图，表单中是如何触发 `verify` 和 `validateAll` 方法执行的 + +
+ +### 实现抽象方法 + +由于`MySQLV5DataSourceFactory`继承于 抽象类`DataSourceFactory`,子类中需要实现几个抽象方法: getDbConfig(),getConnection(),visitFirstConnection(),refresh() +通过这些方法体实现，可以通过该类创建`java.sql.Connection`实例对象 + +```java +@Public +public class MySQLV5DataSourceFactory extends DataSourceFactory { + + private transient com.mysql.jdbc.Driver driver; + + @Override + public DBConfig getDbConfig() { + final DBConfig dbConfig = new DBConfig(new JdbcUrlBuilder() { + @Override + public String buidJdbcUrl(DBConfig db, String ip, String dbName) { + return ("jdbc:mysql://" + ip + ":" + port + "/" + dbName); + } + }); + dbConfig.setName(dbName); + dbConfig.setDbEnum(DBConfigParser.parseDBEnum(this.dbName, this.serverNode)); + return dbConfig; + } + + + @Override + public JDBCConnection getConnection(String jdbcUrl) throws SQLException { + if (driver == null) { + driver = new com.mysql.jdbc.Driver(); + } + java.util.Properties info = new java.util.Properties(); + + if (this.userName != null) { + info.put("user", this.userName); + } + if (password != null) { + info.put("password", password); + } + return new JDBCConnection(driver.connect(jdbcUrl, info), jdbcUrl); + } + + @Override + public void visitFirstConnection(IConnProcessor connProcessor) { + try { + final DBConfig dbConfig = getDbConfig(); + dbConfig.vistDbName((config, jdbcUrl, ip, databaseName) -> { + try (JDBCConnection conn = getConnection(jdbcUrl)) { + connProcessor.vist(conn); + } + return true; + }); + } catch (Exception e) { + throw new RuntimeException(e); + } + } + + @Override + public void refresh() { + + } +} +``` + +以上代码中由于引入了 MySQL JDBC 驱动（`com.mysql.jdbc.Driver`）需要在`pom.xml`中引入MySQL5.7 版本的依赖： +```xml + + + mysql + mysql-connector-java + 5.1.47 + + +``` + +* 方法`getDbConfig()` 返回的DBConfig会将 dbName 与 serverNode进行封装，并且添加JDBC URL构建规则。 +* 方法`getConnection()` 返回 `JDBCConnection`对象实例，供TIS查询遍历记录，或者调用表元数据信息用。 +* 方法`visitFirstConnection()` 提供对外使用`JDBCConnection`对象实例的util方法。 + +## 编写插件属性描述文件 + +对于插件实现`MySQLV5DataSourceFactory`在 对应路径`/src/main/resources` 下的相同包路径下 `com/qlangtech/tis/plugin/ds/extend/` 有以`.json`后缀的相同文件名文件`MySQLV5DataSourceFactory.json` +内容是json格式，存放着`MySQLV5DataSourceFactory`成员属性的额外描述信息，如下： +```json +{ + "name": { + "label": "实例ID", + "help": "数据源实例名称，请起一个有意义且唯一的名称" + }, + "dbName": { + "label": "数据库名", + "help": "数据库名,创建JDBC实例时用" + }, + "userName": { + "label": "用户名", + "dftVal": "root" + }, + "password": { + "label": "密码" + }, + "port": { + "label": "端口" + }, + "serverNode": { + "label": "节点描述", + "helpUrl": "http://tis.pub/docs/guide/datasource/multi-ds-rule", + "placeholder": "127.0.0.2[32-63]" + } +} +``` +属性描述文件详细说明，可查看 + +## 编写属性富文本描述文件 + +通过以上`编写插件属性描述文件`在属性描述信息中可以设置 `help` 属性设置字段的简要说明，但是无法为设置多行有格式的描述信息，为此TIS在`MySQLV5DataSourceFactory.json`相同目录中还有一个扩展名 +为`.md`的文件，可以在该文件中设置属性的Markdown格式的Help文本信息 + +
+ +如下，每个属性对应的说明信息，以 "## + 属性名称" 独占一行开始，以下内容为该属性的说明信息，使用Markdown可以为说明内容设置高亮、链接、换行、图片等说明信息 + +```markdown +## splitTableStrategy + +如数据库中采用分表存放，可以开启此选项，默认为： `off`(不启用) + +`on`: 分表策略支持海量数据存放，每张表的数据结构需要保证相同，且有规则的后缀作为物理表的分区规则，逻辑层面视为同一张表。 +如逻辑表`order` 对应的物理分表为： `order_01`,`order_02`,`order_03`,`order_04` + +[详细说明](https://tis.pub/docs/guide/datasource/multi-table-rule/) +``` + +## 编写扩展实现类单元测试 + + 扩展实现类对应的测试类的路径为 `/src/test/java/com/qlangtech/tis/plugin/ds/extend/TestMySQLV5DataSourceFactory.java`，开发者需要补充测试代码，保证扩展实现类功能稳定。 + +## 编写插件包功能描述文件 + +工程文件`/src/main/resources/description.md`文件中填写插件功能说明，需要用最简短的语句描述插件实现功能点。后期合并到TIS插件仓库中，用户可通过插件商店列表右侧的功能描述判断 +是否需要安装。 + +
+ + +## 插件集成测试 + +可以通过以下命令测试本地编写好的插件 +``` shell +mvn compile -Ptis +mvn com.qlangtech.tis:tis-archetype-run-plugin:run -Dtis.port=8080 +``` +打开浏览器：`http://localhost:8080/` + +
+ +在TIS中（`http://localhost:8080/offline/ds` ）可添加数据源下拉框中多了一个名称为`MySQL DataSource`的数据源，这就是我在插件工程中新添加的MySQL（5.7）DataSourceFactory 扩展实现。 +接下来我们就可以在浏览器中对新添加的扩展实现进行测试了。 + +## 总结 + +以上通过扩展点`DataSourceFactory`扩展实现一个新的`MySQLV5DataSourceFactory`的扩展点作为例子，向大家介绍了如何扩展TIS扩展点功能。TIS中类似`DataSourceFactory`的扩展点还有很多，期望通过这个 +例子起到以点带面的作用。 + +用户如需要自定义现有的插件功能或者添加新的扩展点功能，都可以使用按照以上流程来实现。 diff --git a/docs/develop/plugin-develop.mdx b/docs/develop/plugin-develop.mdx index f082df6..6c85b15 100644 --- a/docs/develop/plugin-develop.mdx +++ b/docs/develop/plugin-develop.mdx @@ -1,6 +1,239 @@ --- -title: 插件开发 +title: 插件开发流程说明 date: 2023-04-12 type: book weight : 10 --- + +import Link from '/src/components/Link'; +import Figure from '/src/components/Figure'; +import CodeBlock from '@theme/CodeBlock'; + + +export const CreateArchShell = () => { +return ( +
+ + mvn com.qlangtech.tis:tis-archetype-generate-plugin:{metadata.version}:generate \{'\n'} + -Drat.skip=true \{'\n'} + -Dtis.version={metadata.version} \{'\n'} + -Dtis.extendpoint="com.qlangtech.tis.plugin.incr.TISSinkFactory:DB2SinkFactory;com.qlangtech.tis.async.message.client.consumer.impl.MQListenerFactory:FlinkCDCDB2SourceFactory" \{'\n'} + -Dtis.artifactId=tis-flink-db2-plugin \{'\n'} + -Ptis + +
+); +} + +## TIS扩展点介绍 + +### 插件体系介绍 + +TIS是基于插件体系构建的，分为TIS-Core（https://github.com/datavane/tis） 与插件Plugins实现层（[https://github.com/qlangtech/plugins](https://github.com/qlangtech/plugins)） +，如下图： + +![](./img/plugins-arch.png) + +如需要对TIS进行功能扩展，只需基于TIS提供的 插件体系提供的扩展点 进行扩展，而不需要对TIS-Core层的任何代码进行修改。 +这符合开放封闭原则(Open-Closed Principle，OCP)，即在TIS-Core不被修改的前提下被扩展新的功能。例如，需要在TIS中新添加一种新的数据类型，只需要新添加一个TPI插件包即可。 + +### 名词解释 + +* 扩展点（Extend Point） + + 抽象类继承于（[Describable.java](https://github.com/datavane/tis/blob/master/tis-plugin/src/main/java/com/qlangtech/tis/extension/Describable.java)），开发者可理解成对于TIS内核层的 + 一个扩展点，用户可以按照自己需要进行扩展 + +* 扩展实现： + + 基于扩展点的具体实现 + +具体的`扩展点`与`扩展实现` 请查看插件体系提供的扩展点 + +
+ +开发者可以点击对应连接查看该扩展点或扩展实现的具体文档说明。 + +在使用TIS过程中用户已经发现，在每个功能页面中的头部位置也有`扩展实现`的标示，例如下图： + +
+ +在每个功能页面模块的右上角有该模块的实现类标示，用户可以点击该连接，查看该插件的说明文档，还能通过链接查看该`扩展实现`的Github原代码。 + +## TIS插件体系特点 + +TIS插件体系实现参照了CI/CD领域的Jenkins实现方式，和Jenkins一样TIS的产品功能流程是基于WBE-UI实现的，TIS内部已经实现了一套强大的前端UI自动化渲染机制。 + +后端开发工程师只需按照TIS开发规约，编写新的插件代码，不需要编写一行前端html或者js代码就能轻松构建一个新的插件，从而完成对TIS的功能扩展。 + +## TIS的插件开发步骤 + + +### 确定需要扩展的扩展点 + + 通过 `名词解释` 一节中已经可以通过TIS现有的页面流程了解到，需要扩展的功能点的扩展点类的全路径。 + +### 创建插件脚手架工程 + +首先需要在 `$MAVEN_HOME/conf/setting.xml` 文件中添加 TIS的私有仓库Profile，配置如下所示： +```xml + + + + + tis + + + tis-releases + http://mvn-repo.oss-cn-hangzhou.aliyuncs.com/release/ + + + + + tis-releases + http://mvn-repo.oss-cn-hangzhou.aliyuncs.com/release/ + + + + + +``` + +然后执行以下命令创建插件骨架工程： + + + + 以上Command中两个参数需要说明 + 1. **tis.extendpoint** + + **格式为:** 扩展点:扩展实现类名称[;扩展点:扩展实现类名称]+ + + **扩展点**：插件体系提供的扩展点和扩展实现 中的 1. 扩展点类 2. 扩展实现 3. 扩展实现类的继承链中的任一父类 + + **扩展实现类名称**：新的扩展实现类名（符合Java类名命名规范即可） + 2. **tis.artifactId** + + 新插件工程的名称，注意，该名称有`命名规范`，对于不同类型的插件包有不同的命名规范: + + |插件包类型| 类型说明 |项目名称命名规范| + |-|-|-| + | 增量同步| 只包含增量同步的`扩展实现` | 需符合正则 `tis-flink-([a-z,0-9,\-]+)-plugin` | + | 批量同步| 只包含批量同步的`扩展实现` | 需符合正则 `tis-datax-([a-z,0-9,\-]+)-plugin`| + | 其他| 既不包含 `增量同步`
也不包含 `批量同步`
的 `扩展实现` | 需符合增则 `tis-([a-z,0-9,\-]+)-plugin`| + + :::caution + 此外，`增量同步` 和 `批量同步` 的扩展实现不能共存于一个 插件工程中 + ::: + + 脚手架工程目录文件列表一览 + + ```shell + . + |____pom.xml + |____src + | |____test + | | |____java + | | | |____TestAll.java + | | | |____com + | | | | |____qlangtech + | | | | | |____tis + | | | | | | |____async + | | | | | | | |____message + | | | | | | | | |____client + | | | | | | | | | |____consumer + | | | | | | | | | | |____impl + | | | | | | | | | | | |____extend + | | | | | | | | | | | | |____TestFlinkCDCDB2SourceFactory.java + | | | | | | |____plugin + | | | | | | | |____incr + | | | | | | | | |____extend + | | | | | | | | | |____TestDB2SinkFactory.java + | |____main + | | |____resources + | | | |____com + | | | | |____qlangtech + | | | | | |____tis + | | | | | | |____async + | | | | | | | |____message + | | | | | | | | |____client + | | | | | | | | | |____consumer + | | | | | | | | | | |____impl + | | | | | | | | | | | |____extend + | | | | | | | | | | | | |____FlinkCDCDB2SourceFactory.md + | | | | | | | | | | | | |____FlinkCDCDB2SourceFactory.json + | | | | | | |____plugin + | | | | | | | |____incr + | | | | | | | | |____extend + | | | | | | | | | |____DB2SinkFactory.md + | | | | | | | | | |____DB2SinkFactory.json + | | |____java + | | | |____com + | | | | |____qlangtech + | | | | | |____tis + | | | | | | |____async + | | | | | | | |____message + | | | | | | | | |____client + | | | | | | | | | |____consumer + | | | | | | | | | | |____impl + | | | | | | | | | | | |____extend + | | | | | | | | | | | | |____FlinkCDCDB2SourceFactory.java + | | | | | | |____plugin + | | | | | | | |____incr + | | | | | | | | |____extend + | | | | | | | | | |____DB2SinkFactory.java + ``` + 以上shell command 会在本地中创建一个名叫tis-flink-db4-plugin的工程，实现了两个`扩展实现` 1. FlinkCDCDB2SourceFactory 2. DB2SinkFactory 分别实现了对DB2数据库的增量读和写功能 + + |扩展点|`扩展实现`类| + |-|-| + |[MQListenerFactory](https://tis.pub/docs/plugin/plugins#comqlangtechtisasyncmessageclientconsumerimplmqlistenerfactory)|FlinkCDCDB2SourceFactory| + |[TISSinkFactory](https://tis.pub/docs/plugin/plugins#comqlangtechtispluginincrtissinkfactory)|DB2SinkFactory| + + 对于每一个扩展实现都有一组对应的文件与之对应，例如`DB2SinkFactory.java`文件来说，对应的属性描述文件有： + 1. `/src/main/resources/com/qlangtech/tis/plugin/incr/extend/DB2SinkFactory.json` + + 用于描述插件属性的，如：默认值，下拉框列表枚举，placeholder等 + 2. `/src/main/resources/com/qlangtech/tis/plugin/incr/extend/DB2SinkFactory.md` + + 用户描述属性的基于MarkDown格式的帮助信息 + 3. `/src/test/java/com/qlangtech/tis/plugin/incr/extend/TestDB2SinkFactory.java` + + 对应的单元测试文件 + +* 编写`扩展实现类`及相关 + + 以上由脚手架工程生成的三个文件，只是一个骨架，内容需要开发者进行扩充： + 1. 编写扩展实现类: 详细请查看 + 2. 编写插件属性描述文件： 详细请查看 + 3. 编写属性富文本描述文件：详细请查看 + 4. 编写扩展实现类单元测试：详细请查看 + +* 本地测试插件 + + 本地运行 + ``` shell + mvn com.qlangtech.tis:tis-archetype-run-plugin:run + ``` + 启动之后可通过 浏览器 `http://localhost:8080/` 打开TIS，在浏览器中进行集成测试 + +### 插件打包 + ``` shell + mvn package -Dmaven.test.skip=true + ``` + 在本工程 tips目录中将生成一个后缀为`.tpi` 的文件，开发者可将该文件直接拷贝到 `$TIS_HOME/data/libs/plugins` 目录下，然后将TIS重启之后就可以直接使用该插件包中定义的扩展实现啦。 + 如要实现，可以通过TIS插件池安装插件，需要转入下一步，`向TIS管理者提交合并申请` + +### 向TIS管理者提交合并申请 + + TIS每次发版会将TIS使用到的所有可用插件发布到TIS官方的插件仓库中，并且会基于这些插件包生成一份插件MetaData元数据清单文本，供后期本地TIS程序启动时加载使用。 + + 开发者如想将自己开发的插件包提交到TIS的中央插件仓库中，可以按如下流程操作： + 1. 将自己开发的插件工程提交到Github的本人拥有权限的repo中 + 2. 在 https://github.com/datavane/tis/issues 中发起一个Issue，关于 `插件包提交到TIS的中央插件仓库`的申请，在Issue中需要说明该插件 实现的功能等信息 + 3. 等待TIS管理者Review代码，如需需改代码，TIS管理者会主动通知，讨论后修改，最终由TIS管理者合并代码、发布。 + + + + + + diff --git a/docs/develop/plugin-utils-reference.mdx b/docs/develop/plugin-utils-reference.mdx new file mode 100644 index 0000000..4719efb --- /dev/null +++ b/docs/develop/plugin-utils-reference.mdx @@ -0,0 +1,16 @@ +--- +title: 插件工具类参考 +date: 2020-03-22 +type: book +weight : 10 +--- + +## @FormField + +// TODO + +## 属性描述文件内容说明 + +// TODO + +## 属性描述文件内容说明 diff --git a/docs/example/chunjun-integrate.mdx b/docs/example/chunjun-integrate.mdx index 6230369..f149220 100644 --- a/docs/example/chunjun-integrate.mdx +++ b/docs/example/chunjun-integrate.mdx @@ -231,4 +231,4 @@ StarRocks一个Sink端实现了一个基于StreamFunction的Sink实现，连开 ## 尝试TIS - TIS的最新版本 [https://github.com/qlangtech/tis/releases/tag/v3.6.0-alpha](https://github.com/qlangtech/tis/releases/tag/v3.6.0-alpha) + TIS的最新版本 [https://github.com/datavane/tis/releases/tag/v3.6.0-alpha](https://github.com/datavane/tis/releases/tag/v3.6.0-alpha) diff --git a/docs/example/mysql-hudi.mdx b/docs/example/mysql-hudi.mdx index 3894d22..60ca26c 100644 --- a/docs/example/mysql-hudi.mdx +++ b/docs/example/mysql-hudi.mdx @@ -202,5 +202,5 @@ TIS的安装非常方便，只需三个步骤：下载一个tar压缩包，解 TIS对Hudi的封装过程中还没有将Hudi的所有配置项（例如：Indexer的配置相关）开放给用户配置，后续会陆续完善。 -假如您TIS有功能需求，请在Github的Issue栏中添加：[https://github.com/qlangtech/tis/issues](https://github.com/qlangtech/tis/issues) +假如您TIS有功能需求，请在Github的Issue栏中添加：[https://github.com/datavane/tis/issues](https://github.com/datavane/tis/issues) diff --git a/docusaurus.config.js b/docusaurus.config.js index 866de38..27f3a7a 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -77,7 +77,7 @@ const config = { }, // {to: '/blog', label: 'Blog', position: 'left'}, { - href: 'https://github.com/qlangtech/tis', + href: 'https://github.com/datavane/tis', label: 'GitHub', position: 'right', }, diff --git a/src/components/Block/css.css b/src/components/Block/css.css new file mode 100644 index 0000000..a539a64 --- /dev/null +++ b/src/components/Block/css.css @@ -0,0 +1,4 @@ + +.max-block-height{ + max-height: 400px; +} diff --git a/src/components/Block/index.js b/src/components/Block/index.js new file mode 100644 index 0000000..62c270e --- /dev/null +++ b/src/components/Block/index.js @@ -0,0 +1,12 @@ + +import React from 'react'; + +import styles from './css.css'; +import clsx from "clsx"; + +export default function Block({children}) { + + return ( +
{children}
+ ); +} diff --git a/src/components/CreateArchShell/index.js b/src/components/CreateArchShell/index.js new file mode 100644 index 0000000..dbe2bac --- /dev/null +++ b/src/components/CreateArchShell/index.js @@ -0,0 +1,16 @@ +import React from 'react'; +import CodeBlock from '@theme/CodeBlock'; + +export default function CreateArchShell() { + return ( +
+ + mvn com.qlangtech.tis:tis-archetype-generate-plugin::generate \ {'\n'} + -Drat.skip=true \ {'\n'} + -Dtis.version= \ {'\n'} + -Dtis.extendpoint="com.qlangtech.tis.plugin.incr.TISSinkFactory:DB2SinkFactory;com.qlangtech.tis.async.message.client.consumer.impl.MQListenerFactory:FlinkCDCDB2SourceFactory" \ {'\n'} + -Dtis.artifactId=tis-flink-db2-plugin + +
+ ); +} diff --git a/versioned_docs/version-3.6.0-alpha/example/chunjun-integrate.mdx b/versioned_docs/version-3.6.0-alpha/example/chunjun-integrate.mdx index 6230369..f149220 100644 --- a/versioned_docs/version-3.6.0-alpha/example/chunjun-integrate.mdx +++ b/versioned_docs/version-3.6.0-alpha/example/chunjun-integrate.mdx @@ -231,4 +231,4 @@ StarRocks一个Sink端实现了一个基于StreamFunction的Sink实现，连开 ## 尝试TIS - TIS的最新版本 [https://github.com/qlangtech/tis/releases/tag/v3.6.0-alpha](https://github.com/qlangtech/tis/releases/tag/v3.6.0-alpha) + TIS的最新版本 [https://github.com/datavane/tis/releases/tag/v3.6.0-alpha](https://github.com/datavane/tis/releases/tag/v3.6.0-alpha) diff --git a/versioned_docs/version-3.6.0-alpha/example/mysql-hudi.mdx b/versioned_docs/version-3.6.0-alpha/example/mysql-hudi.mdx index 3894d22..60ca26c 100644 --- a/versioned_docs/version-3.6.0-alpha/example/mysql-hudi.mdx +++ b/versioned_docs/version-3.6.0-alpha/example/mysql-hudi.mdx @@ -202,5 +202,5 @@ TIS的安装非常方便，只需三个步骤：下载一个tar压缩包，解 TIS对Hudi的封装过程中还没有将Hudi的所有配置项（例如：Indexer的配置相关）开放给用户配置，后续会陆续完善。 -假如您TIS有功能需求，请在Github的Issue栏中添加：[https://github.com/qlangtech/tis/issues](https://github.com/qlangtech/tis/issues) +假如您TIS有功能需求，请在Github的Issue栏中添加：[https://github.com/datavane/tis/issues](https://github.com/datavane/tis/issues) diff --git a/versioned_docs/version-3.7.0/example/chunjun-integrate.mdx b/versioned_docs/version-3.7.0/example/chunjun-integrate.mdx index 6230369..f149220 100644 --- a/versioned_docs/version-3.7.0/example/chunjun-integrate.mdx +++ b/versioned_docs/version-3.7.0/example/chunjun-integrate.mdx @@ -231,4 +231,4 @@ StarRocks一个Sink端实现了一个基于StreamFunction的Sink实现，连开 ## 尝试TIS - TIS的最新版本 [https://github.com/qlangtech/tis/releases/tag/v3.6.0-alpha](https://github.com/qlangtech/tis/releases/tag/v3.6.0-alpha) + TIS的最新版本 [https://github.com/datavane/tis/releases/tag/v3.6.0-alpha](https://github.com/datavane/tis/releases/tag/v3.6.0-alpha) diff --git a/versioned_docs/version-3.7.0/example/mysql-hudi.mdx b/versioned_docs/version-3.7.0/example/mysql-hudi.mdx index 3894d22..60ca26c 100644 --- a/versioned_docs/version-3.7.0/example/mysql-hudi.mdx +++ b/versioned_docs/version-3.7.0/example/mysql-hudi.mdx @@ -202,5 +202,5 @@ TIS的安装非常方便，只需三个步骤：下载一个tar压缩包，解 TIS对Hudi的封装过程中还没有将Hudi的所有配置项（例如：Indexer的配置相关）开放给用户配置，后续会陆续完善。 -假如您TIS有功能需求，请在Github的Issue栏中添加：[https://github.com/qlangtech/tis/issues](https://github.com/qlangtech/tis/issues) +假如您TIS有功能需求，请在Github的Issue栏中添加：[https://github.com/datavane/tis/issues](https://github.com/datavane/tis/issues) diff --git a/versioned_docs/version-3.7.1/example/chunjun-integrate.mdx b/versioned_docs/version-3.7.1/example/chunjun-integrate.mdx index 6230369..f149220 100644 --- a/versioned_docs/version-3.7.1/example/chunjun-integrate.mdx +++ b/versioned_docs/version-3.7.1/example/chunjun-integrate.mdx @@ -231,4 +231,4 @@ StarRocks一个Sink端实现了一个基于StreamFunction的Sink实现，连开 ## 尝试TIS - TIS的最新版本 [https://github.com/qlangtech/tis/releases/tag/v3.6.0-alpha](https://github.com/qlangtech/tis/releases/tag/v3.6.0-alpha) + TIS的最新版本 [https://github.com/datavane/tis/releases/tag/v3.6.0-alpha](https://github.com/datavane/tis/releases/tag/v3.6.0-alpha) diff --git a/versioned_docs/version-3.7.1/example/mysql-hudi.mdx b/versioned_docs/version-3.7.1/example/mysql-hudi.mdx index 3894d22..60ca26c 100644 --- a/versioned_docs/version-3.7.1/example/mysql-hudi.mdx +++ b/versioned_docs/version-3.7.1/example/mysql-hudi.mdx @@ -202,5 +202,5 @@ TIS的安装非常方便，只需三个步骤：下载一个tar压缩包，解 TIS对Hudi的封装过程中还没有将Hudi的所有配置项（例如：Indexer的配置相关）开放给用户配置，后续会陆续完善。 -假如您TIS有功能需求，请在Github的Issue栏中添加：[https://github.com/qlangtech/tis/issues](https://github.com/qlangtech/tis/issues) +假如您TIS有功能需求，请在Github的Issue栏中添加：[https://github.com/datavane/tis/issues](https://github.com/datavane/tis/issues) diff --git a/versioned_docs/version-3.7.2/example/chunjun-integrate.mdx b/versioned_docs/version-3.7.2/example/chunjun-integrate.mdx index 6230369..f149220 100644 --- a/versioned_docs/version-3.7.2/example/chunjun-integrate.mdx +++ b/versioned_docs/version-3.7.2/example/chunjun-integrate.mdx @@ -231,4 +231,4 @@ StarRocks一个Sink端实现了一个基于StreamFunction的Sink实现，连开 ## 尝试TIS - TIS的最新版本 [https://github.com/qlangtech/tis/releases/tag/v3.6.0-alpha](https://github.com/qlangtech/tis/releases/tag/v3.6.0-alpha) + TIS的最新版本 [https://github.com/datavane/tis/releases/tag/v3.6.0-alpha](https://github.com/datavane/tis/releases/tag/v3.6.0-alpha) diff --git a/versioned_docs/version-3.7.2/example/mysql-hudi.mdx b/versioned_docs/version-3.7.2/example/mysql-hudi.mdx index 3894d22..60ca26c 100644 --- a/versioned_docs/version-3.7.2/example/mysql-hudi.mdx +++ b/versioned_docs/version-3.7.2/example/mysql-hudi.mdx @@ -202,5 +202,5 @@ TIS的安装非常方便，只需三个步骤：下载一个tar压缩包，解 TIS对Hudi的封装过程中还没有将Hudi的所有配置项（例如：Indexer的配置相关）开放给用户配置，后续会陆续完善。 -假如您TIS有功能需求，请在Github的Issue栏中添加：[https://github.com/qlangtech/tis/issues](https://github.com/qlangtech/tis/issues) +假如您TIS有功能需求，请在Github的Issue栏中添加：[https://github.com/datavane/tis/issues](https://github.com/datavane/tis/issues)