数据库插件开发指南

概览(Overview)

数据库插件是 CodeWave 低代码平台提供的快速集成新关系型数据库品牌的解决方案，本指南旨在指导开发者实现一个 CodeWave 低代码数据库连接器，并集成到平台上进行使用。

图 1 数据库插件化架构图

快速开始(Quick Start)

1. 引入数据库插件化 sdk

当前最新版本为 1.5.2，具体可能需要根据开发时的实际版本进行修改。

xml

<dependency>
    <groupId>com.netease.cloud.lowcode</groupId>
    <artifactId>codewave-owl-plugin</artifactId>
    <version>1.5.2</version>
</dependency>

2. 实现接口或继承抽象类

实现接口 com.netease.cloud.lowcode.owl.spi.rdb.RdbDataSourcePlugin，或继承 com.netease.cloud.lowcode.owl.spi.rdb.AbstractRdbDataSourcePlugin（推荐），其中 AbstractRdbDataSourcePlugin 基于模板模式实现了大部分通用功能。

java

public class MysqlPlugin extends AbstractRdbDataSourcePlugin {
    @Override
    public String dbType() {
        return "mysql";
    }
    ...
}

3. 完成插件配置并注册

在插件工程中完成插件配置 plugin_info.yaml，并进行插件注册 META-INF/services/com.netease.cloud.lowcode.owl.spi.rdb.RdbDataSourcePlugin。

plugin_info.yaml 基本内容

yaml

# 类型映射，其中 key 为 nasl 基础类型简写，value 可一个列表表示可映射的数据库存储类型集合
columnTypeMappings:
    Double:
        - columnType: float
          defaultMapping: false
          options: { }
          alias: [ 'float' ]
        - columnType: double
          defaultMapping: true
          options: { }
          alias: [ 'double', 'real' ]
    ...
# 插件基础信息，包括插件数据库类型定义(需要全局唯一)、插件展示的数据库名称以及连接串选项定义
jdbcConnectionConfigInfo:
    databaseName: mysql
    displayName: MySQL5.7
    configList:
        - inputType: text
          name: 主机
          optionKey: host
          placeHolder: 请输入数据库主机地址
          required: true
          bind: { }
        - inputType: text

META-INF/services/com.netease.cloud.lowcode.owl.spi.rdb.RdbDataSourcePlugin 内容

plaintext

com.netease.cloud.lowcode.owl.extension.MysqlPlugin

实现指南(User Implementation Guide)

环境准备

插件开发前，请确认下述环境是否已准备好：

JDK1.8
Maven
com.netease.cloud.lowcode:codewave-owl-plugin 插件 spi 依赖（https://github.com/netease-lcap/codewave-architect-course/tree/main/example/owl/codewave-owl-mysql-8.0/jar/codewave-owl-plugin-1.5.2-SNAPSHOT.jar）

PS：这里的版本最好以开发时最新版本为准，可以二次确认下，例如 1.5.2

xml

<dependency>
    <groupId>com.netease.cloud.lowcode</groupId>
    <artifactId>codewave-owl-plugin</artifactId>
    <version>1.5.2</version>
    <scope>compile</scope>
</dependency>

可选步骤

引入平台连接器打包插件

平台 v3.6 版本之后通过下述插件打的 zip 包可直接通过资产中心上传。

xml

<plugin>
    <groupId>com.netease.lowcode</groupId>
    <artifactId>connector-package-maven-plugin</artifactId>
    <version>1.0.0</version>
    <executions>
        <execution>
            <goals>
                <goal>archive</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <!-- 这里是需要一起打包的依赖，正常 jdbc 驱动需要一起打包 -->
        <includeGroupIds>com.microsoft.sqlserver</includeGroupIds>
    </configuration>
</plugin>

开发工具推荐

推荐使用 IntelliJ IDEA，社区版即可。

插件开发

工程结构

如上图所示，第一部分是插件类实现部分，必须实现 RdbDataSourcePlugin 接口，不过开发时我们建议继承虚类 AbstractRdbDataSourcePlugin，该虚类实现了大部分通用实现，可以简化开发难度。
第二部分是 spi 注册文件，该文件固定为 /META-INF/services/com.netease.cloud.lowcode.owl.spi.rdb.RdbDataSourcePlugin，文件内容为插件实现类全限定名，如上图所示为 "com.netease.cloud.lowcode.owl.extension.MysqlPlugin"。该规范是 Java spi 机制。
第三部分为插件定义文件 plugin_info.yaml，该文件主要包括两部分内容：
- 类型系统映射
- 插件定义，包括插件 id（databaseName）、连接选项定义等
【可选】从 v3.13 版本开始平台支持插件自定义 sql 函数，所以对于平台版本 >= 3.13 的环境插件里还可能包括第四部分 function_definition.json 文件，该文件用来定义本插件对应的数据库支持的 sql 函数列表。

插件实现类

插件实现类主要需要实现包括：

插件基本信息（插件数据库类型、驱动类、jdbc 连接串生成等）
元数据查询（连通性测试、数据表集合、表结构查询等）
sql 生成（ddl、dml）、sql 解析（主要为 create table）
方言处理（关键字包装、常量格式等）

插件方法说明

下面是插件方法的详细说明，以 Mysql8.0 (https://github.com/netease-lcap/codewave-architect-course/tree/main/example/owl/codewave-owl-mysql-8.0)插件为例。

`getPluginJdbcInfo`

非必须实现，抽象类已经实现统一的方法。

`dbType`

非必须实现，抽象类已经实现统一的方法。默认读取插件定义文件中的 databaseName。

`getJdbcUrl`

必须实现。 jdbc 的连接串一般有单节点和多节点两种模式，多节点一般为 "jdbc:mysql://host1:port1,host2,port2/database?option1=value1&option2=value2"，入参为 RdbDataSource，值得注意的是 host 的格式，多节点情况下 host 格式分两种，一种是 host1+port1,host2+port2，一种是 host1,host2，port 放在 port 参数中，两种方式都需要兼容。

java

public String getJdbcUrl(RdbDataSource dataSourceParam) {
    StringBuilder jdbcBuilder = new StringBuilder(JDBC_PREFIX);
    String[] hosts = dataSourceParam.getHost().split(",");
    String hyper = "";
    for (String host : hosts) {
        jdbcBuilder.append(hyper).append(host.contains(":") ? host : host + ":" + dataSourceParam.getPort());
        hyper = ",";
    }
    if (!PluginUtils.isEmpty(dataSourceParam.getDbname())) {
        jdbcBuilder.append("/").append(dataSourceParam.getDbname());
    }
    hyper = "?";
    Map<String, String> options = dataSourceParam.getOptions();
    if (!PluginUtils.isEmpty(options)) {
        for (Map.Entry<String, String> entry : options.entrySet()) {
            jdbcBuilder.append(hyper).append(entry.getKey()).append("=").append(entry.getValue());
            hyper = "&";
        }
    }
    jdbcBuilder.append(hyper).append(JDBC_SUFFIX);
    return jdbcBuilder.toString();
}

`getJdbcDriver`

必须实现。该方法会用于获取 Connection，必须实现。方法入参和获取 jdbc 的完全一致，注意先手动加载驱动类。

java

try {
    return new com.mysql.cj.jdbc.Driver();
} catch (Exception e) {
    throw new LcapRdbPluginException("Get jdbc driver error", e);
}

`mavenDependence`

必须实现。数据源 JDBC 驱动对应的 maven 坐标，例如 mysql 则需要根据引入的驱动版本。

java

public class MavenDependence {
    private String groupId;
    private String artifactId;
    private String version;
}

xml

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.20</version>
</dependency>

`showDatabases`

必须实现。展示数据库列表，数据源的 ping 方法依赖该方法的实现。 mysql 支持语法 "SHOW DATABASES"，但是其他数据源未必支持这类语法，则需要了解对应数据源如何获取数据库列表，注意对返回结果进行排序。

java

@Override
public List<String> showDatabases(Connection connection) {
    List<String> databaseNames = new ArrayList<>();
    String sql = "SHOW DATABASES";
    try (Statement stmt = connection.createStatement();
         ResultSet rs = stmt.executeQuery(sql)) {
        while (rs.next()) {
            String dbName = rs.getString(1);
            databaseNames.add(dbName);
        }
    } catch (Exception e) {
        throw new LcapRdbPluginException("Show databases error", e);
    }
    return databaseNames.stream().sorted(String::compareToIgnoreCase).collect(Collectors.toList());
}

`showTables`

必须实现。展示数据表的列表，websql 界面的数据表列表依赖该方法。入参多了一个 schemaName，因为有些数据源需要模式名，另外注意返回结果排序。

java

@Override
public List<String> showTables(Connection connection, String schemaName) {
    List<String> tableNames = new ArrayList<>();
    String sql = "SHOW TABLES";
    try (Statement stmt = connection.createStatement();
         ResultSet rs = stmt.executeQuery(sql)) {
        while (rs.next()) {
            String tableName = rs.getString(1);
            tableNames.add(tableName);
        }
    } catch (Exception e) {
        throw new LcapRdbPluginException("Show tables error", e);
    }
    return tableNames.stream().sorted(String::compareToIgnoreCase).collect(Collectors.toList());
}

`showIndexes`

必须实现。查询出 tableName 对应的表的索引信息并按格式返回即可，返回格式为索引列表，元素对应 RdbIndexInfo。以 Mysql 为例，可以使用 “SHOW INDEXES FROM table_name” 获取索引相关信息，其他数据源如不支持此语法则需要使用其他查询方案。注意：因为查询结果一般是以列为单位，但是返回结果是以索引为单位，需要进行聚合处理，例如索引 A 包含列 a 和列 b，则上述查询语句可能是索引 A、列 a 和索引 A、列 b 两行数据，因此需要合并列。

java

@Override
public List<RdbIndexInfo> showIndexes(Connection connection, String schemaName, String tableName) {
    String sql = "SHOW INDEXES FROM " + wrapKeyword(tableName);
    Map<String, RdbIndexInfo> indexMap = new HashMap<>();
    try (Statement stmt = connection.createStatement();
         ResultSet rs = stmt.executeQuery(sql)) {
        while (rs.next()) {
            String indexName = rs.getString("Key_name");
            String columnName = rs.getString("Column_name");
            RdbIndexInfo index;
            if (indexMap.containsKey(indexName)) {
                index = indexMap.get(indexName);
                List<String> columnNames = index.getColumnNames();
                columnNames.add(columnName);
                index.setColumnNames(columnNames);
            } else {
                index = new RdbIndexInfo();
                index.setIndexName(indexName);
                List<String> columnNames = new ArrayList<>();
                columnNames.add(columnName);
                index.setColumnNames(columnNames);
                index.setPrimary(indexName.equalsIgnoreCase("PRIMARY"));
                index.setUnique(rs.getString("Non_unique").equalsIgnoreCase("0"));
                index.setComment(rs.getString("Index_comment"));
            }
            indexMap.put(indexName, index);
        }
    } catch (Exception e) {
        throw new LcapRdbPluginException("Show indexes error", e);
    }
    return new ArrayList<>(indexMap.values());
}

`describeTable`

必须实现。查询出 tableName 对应的表并返回对应的列信息、索引信息和表信息即可，返回格式为表信息，对应 RdbTableInfo。以 Mysql 为例，可以使用 “SHOW TABLE STATUS WHERE Name = 'table_name'” 获取表相关信息，其他数据源如不支持此语法则需要使用其他查询方案。

java

@Override
public RdbTableInfo describeTable(Connection connection, String schemaName, String tableName) {
    RdbTableInfo tableInfo = new RdbTableInfo();
    String sql = "SHOW TABLE STATUS WHERE Name = '" + tableName + "'";
    try (Statement stmt = connection.createStatement();
         ResultSet rs = stmt.executeQuery(sql)) {
        while (rs.next()) {
            tableInfo.setTableName(rs.getString("Name"));
            tableInfo.setComment(rs.getString("Comment"));
            tableInfo.setColumns(showColumns(connection, tableName));
            tableInfo.setIndexes(showIndexes(connection, schemaName, tableName));
        }
    } catch (Exception e) {
        throw new LcapRdbPluginException("Describe table error", e);
    }
    return tableInfo;
}

private List<RdbColumnInfo> showColumns(Connection connection, String tableName) {
    List<RdbColumnInfo> columnInfoList = new ArrayList<>();
    String sql = "SHOW FULL COLUMNS FROM " + wrapKeyword(tableName);
    try (Statement stmt = connection.createStatement();
         ResultSet rs = stmt.executeQuery(sql)) {
        while (rs.next()) {
            RdbColumnInfo columnInfo = new RdbColumnInfo();
            columnInfo.setColumnName(rs.getString("Field"));
            String columnType = rs.getString("Type");
            columnInfo.setColumnType(columnType);
            columnInfo.setDefaultValue(rs.getString("Default"));
            columnInfo.setComment(rs.getString("Comment"));
            columnInfo.setPrimaryKey(rs.getString("Key").equalsIgnoreCase("PRI"));
            columnInfo.setNotNull(rs.getString("Null").equalsIgnoreCase("NO"));
            columnInfo.setAutoIncrement(rs.getString("Extra").contains("auto_increment"));
            columnInfoList.add(columnInfo);
        }
    } catch (Exception e) {
        throw new LcapRdbPluginException("Show columns error", e);
    }
    return columnInfoList;
}

`showSequences`

非必须实现。在 owl 中，sequence 是和自增息息相关的，如果数据源本身支持自增，比如 mysql 既可以通过建表指定，又可以通过新增/变更列的时候指定自增，是没必要实现该方法的。 mysql 不支持序列，不过整体上查询思路和索引类似，入参和索引相同，返回结果为序列列表，序列类 RdbSequenceInfo。