This is an automated email from the ASF dual-hosted git repository. duanzhengqiang pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/shardingsphere-plugin.git
commit cd3fc7f9d5930fdbc2e50cd61f258a642e688126 Author: duanzhengqiang <[email protected]> AuthorDate: Wed Sep 27 16:57:15 2023 +0800 Optimize pom and add doc for spi implementation --- README.md | 218 ++++++++++++++++++++++++++++++++++++++- README_ZH.md | 217 ++++++++++++++++++++++++++++++++++++++ features/encrypt/like/pom.xml | 4 +- features/encrypt/pom.xml | 4 +- features/encrypt/rc4/pom.xml | 4 +- features/encrypt/sm/pom.xml | 4 +- features/pom.xml | 2 +- features/sharding/cosid/pom.xml | 8 +- features/sharding/nanoid/pom.xml | 4 +- features/sharding/pom.xml | 2 +- pom.xml | 3 +- 11 files changed, 450 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 5c64542..fb5f4ad 100644 --- a/README.md +++ b/README.md @@ -1 +1,217 @@ -# shardingsphere-plugin +# OVERVIEW + +ShardingSphere Plugin is designed to provide a plug-in implementation for ShardingSphere pluggable architecture. You can refer to [ShardingSphere dev manual](https://shardingsphere.apache.org/document/current/en/dev-manual/) to extend the SPI. +Developers are welcome to contribute to the implementation of plug-ins and build a distributed database ecosystem of ShardingSphere. + +[](https://github.com/apache/shardingsphere-plugin/blob/main/README.md) +[](https://github.com/apache/shardingsphere-plugin/blob/main/README_ZH.md) + +# Plug-in Implementation + +## Feature Plug-in + +### Encrypt Feature Plug-in + +#### Like Encrypt Algorithm + +* CharDigestLike Encrypt Algorithm + +Type：CHAR_DIGEST_LIKE + +Attributes： + +| *Name* | *DataType* | *Description* | +|--------|------------|-------------------------------------------------| +| delta | int | Character Unicode offset（decimal number） | +| mask | int | Character encryption mask（decimal number） | +| start | int | Ciphertext Unicode initial code（decimal number） | +| dict | String | Common words | + +#### Standard Encrypt Algorithm + +* RC4 Encrypt Algorithm + +Type: RC4 + +Attributes: + +| *Name* | *DataType* | *Description* | +|---------------|------------|---------------| +| rc4-key-value | String | RC4 KEY | + +* SM3 Encrypt Algorithm + +Type: SM3 + +Attributes: + +| *Name* | *DataType* | *Description* | +|----------|------------|--------------------------------------------| +| sm3-salt | String | SM3 SALT (should be blank or 8 bytes long) | + +* SM4 Encrypt Algorithm + +Type: SM4 + +Attributes: + +| *Name* | *DataType* | *Description* | +|-------------|------------|--------------------------------------------------------------------------| +| sm4-key | String | SM4 KEY (should be 16 bytes) | +| sm4-mode | String | SM4 MODE (should be CBC or ECB) | +| sm4-iv | String | SM4 IV (should be specified on CBC, 16 bytes long) | +| sm4-padding | String | SM4 PADDING (should be PKCS5Padding or PKCS7Padding, NoPadding excepted) | + +### Sharding Feature Plug-in + +#### Distributed Key Generator + +* Nano ID + +Type:NANOID + +Configurable Property:none + +* CosId + +Type: COSID + +Attributes： + +| *Name* | *DataType* | *Description* | *Default Value* | +|-----------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| +| id-name | String | ID generator name | `__share__` | +| as-string | bool | Whether to generate a string type ID: Convert `long` type ID to Base-62 `String` type (`Long.MAX_VALUE` maximum string length is 11 digits), and ensure the ordering of string IDs | `false` | + +* CosId-Snowflake + +Type: COSID_SNOWFLAKE + +Attributes： + +| *Name* | *DataType* | *Description* | *Default Value* | +|-----------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| +| epoch | String | EPOCH of Snowflake ID Algorithm | `1477929600000` | +| as-string | bool | Whether to generate a string type ID: Convert `long` type ID to Base-62 `String` type (`Long.MAX_VALUE` maximum string length is 11 digits), and ensure the ordering of string IDs | `false` | + +#### Sharding Algorithm + +* Fixed interval sharding algorithm provided by CosId + +A fixed time range sharding algorithm implemented by the tool class based on `me.ahoo.cosid:cosid-core`. +When the sharding key is a JSR-310 containing class or a time-related class, it will be converted to `java.time.LocalDateTime` before the next sharding. +See the discussion at https://github.com/apache/shardingsphere/issues/14047. + +Type：COSID_INTERVAL + +Attributes： + +| *Name* | *DataType* | *Description* | *Default Value* | +|--------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| +| zone-id | String | Time zone, which must follow the contained value of `java.time.ZoneId`. For example: Asia/Shanghai | | +| logic-name-prefix | String | Prefix pattern of sharding data sources or tables | | +| datetime-lower | String | Datetime sharding lower boundary, pattern is consistent with the timestamp format of `yyyy-MM-dd HH:mm:ss` | | +| datetime-upper | String | Datetime sharding upper boundary, pattern is consistent with the timestamp format of `yyyy-MM-dd HH:mm:ss` | | +| sharding-suffix-pattern | String | Suffix pattern of sharding data sources or tables, must can be transformed to Java LocalDateTime, must be consistent with `datetime-interval-unit`. For example: yyyyMM | | +| datetime-interval-unit | String | Unit of sharding value interval, must can be transformed to Java ChronoUnit's Enum value. For example: MONTHS | | +| datetime-interval-amount | int | Interval of sharding value, after which the next shard will be entered | + +* Snowflake key-based fixed interval sharding algorithm provided by CosId + +Snowflake ID sharding algorithm with fixed time range implemented by tool class based on `me.ahoo.cosid:cosid-core`. +When the sharding key is a JSR-310 containing class or a time-related class, it will be converted to `java.time.LocalDateTime` before the next sharding. +See the discussion at https://github.com/apache/shardingsphere/issues/14047. + +Type：COSID_INTERVAL_SNOWFLAKE + +Attributes： + +| *Name* | *DataType* | *Description* | *Default Value* | +|--------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| +| zone-id | String | Time zone, which must follow the contained value of `java.time.ZoneId`. For example: Asia/Shanghai | | +| logic-name-prefix | String | Prefix pattern of sharding data sources or tables | | +| datetime-lower | String | Datetime sharding lower boundary, pattern is consistent with the timestamp format of `yyyy-MM-dd HH:mm:ss` | | +| datetime-upper | String | Datetime sharding upper boundary, pattern is consistent with the timestamp format of `yyyy-MM-dd HH:mm:ss` | | +| sharding-suffix-pattern | String | Suffix pattern of sharding data sources or tables, must can be transformed to Java LocalDateTime, must be consistent with `datetime-interval-unit`. For example: yyyyMM | | +| datetime-interval-unit | String | Unit of sharding value interval, must can be transformed to Java ChronoUnit's Enum value. For example: MONTHS | | +| datetime-interval-amount | int | Interval of sharding value, after which the next shard will be entered | + +* Modulo sharding algorithm provided by CosId + +Modulo sharding algorithm implemented by the tool class based on `me.ahoo.cosid:cosid-core`. +See the discussion at https://github.com/apache/shardingsphere/issues/14047 . + +Type: COSID_MOD + +Attributes: + +| *Name* | *DataType* | *Description* | +|-------------------|------------|---------------------------------------------------| +| mod | int | Sharding count | +| logic-name-prefix | String | Prefix pattern of sharding data sources or tables | + +## Infra Plug-in + +### Connection Pool Plug-in + +ShardingSphere-Proxy supports common data source connection pools: HikariCP, C3P0, DBCP. + +The connection pool can be specified through the parameter `dataSourceClassName`. When not specified, the default data source connection pool is HikariCP. + +* C3P0 Connection Pool + +Sample: + +```yaml +dataSources: + ds_0: + dataSourceClassName: com.mchange.v2.c3p0.ComboPooledDataSource + url: jdbc:mysql://localhost:3306/ds_2 + username: root + password: +``` + +* DBCP Connection Pool + +Sample: + +```yaml +dataSources: + ds_0: + dataSourceClassName: org.apache.commons.dbcp2.BasicDataSource + url: jdbc:mysql://localhost:3306/ds_3 + username: root + password: +``` + +## JDBC Adaptor Plug-in + +### JDBC Driver Config Plug-in + +ShardingSphere-JDBC provides a JDBC Driver, which can be used only through configuration changes without rewriting the code. + +* Apollo Driver Config + +Load JDBC URL of the yaml configuration file in the specified namespace of apollo: +``` +jdbc:shardingsphere:apollo:TEST.test_namespace +``` + +## Mode Plug-in + +### Mode Cluster Repository Plug-in + +* Nacos Repository + +Type: Nacos + +Mode: Cluster + +Attributes: + +| *Name* | *Type* | *Description* | *Default Value* | +|---------------------------|--------|---------------------------------------------------|-----------------| +| clusterIp | String | Unique identifier in cluster | Host IP | +| retryIntervalMilliseconds | long | Milliseconds of retry interval | 500 | +| maxRetries | int | Max retries for client to check data availability | 3 | +| timeToLiveSeconds | int | Seconds of ephemeral instance live | 30 | diff --git a/README_ZH.md b/README_ZH.md new file mode 100644 index 0000000..528b257 --- /dev/null +++ b/README_ZH.md @@ -0,0 +1,217 @@ +# 概述 + +ShardingSphere Plugin 旨在为 ShardingSphere 可插拔架构提供插件实现，可以参考 [ShardingSphere 开发者手册](https://shardingsphere.apache.org/document/current/cn/dev-manual/) 对 SPI 进行扩展。 +欢迎广大开发者们积极贡献插件实现，一起打造 ShardingSphere 分布式的数据库生态系统。 + +[](https://github.com/apache/shardingsphere-plugin/blob/main/README.md) +[](https://github.com/apache/shardingsphere-plugin/blob/main/README_ZH.md) + +# 插件实现 + +## 功能插件 + +### 加密功能插件 + +#### 模糊加密算法插件 + +* 单字符摘要模糊加密算法 + +类型：CHAR_DIGEST_LIKE + +可配置属性： + +| *名称* | *数据类型* | *说明* | +|-------|--------|--------------------| +| delta | int | 字符Unicode码偏移量（十进制） | +| mask | int | 字符加密掩码（十进制） | +| start | int | 密文Unicode初始码（十进制） | +| dict | String | 常见字 | + +#### 标准加密算法插件 + +* RC4 加密算法 + +类型：RC4 + +可配置属性： + +| *名称* | *数据类型* | *说明* | +|---------------|--------|-------------| +| rc4-key-value | String | RC4 使用的 KEY | + +* SM3 加密算法 + +类型：SM3 + +可配置属性： + +| 名称 | 数据类型 | 说明 | +| ------------- | --------- | ------------- | +| sm3-salt | String | SM3 使用的 SALT（空 或 8 Bytes） | + +* SM4 加密算法 + +类型：SM4 + +可配置属性： + +| 名称 | 数据类型 | 说明 | +| ------------- | --------- | ------------- | +| sm4-key | String | SM4 使用的 KEY （16 Bytes） | +| sm4-mode | String | SM4 使用的 MODE （CBC 或 ECB） | +| sm4-iv | String | SM4 使用的 IV （MODE为CBC时需指定，16 Bytes）| +| sm4-padding | String | SM4 使用的 PADDING （PKCS5Padding 或 PKCS7Padding，暂不支持NoPadding）| + +### 分片功能插件 + +#### 分布式主键生成插件 + +* NanoID + +类型：NANOID + +可配置属性： 无 + +* CosId + +类型: COSID + +可配置属性： + +| *属性名称* | *数据类型* | *说明* | *默认值* | +|-----------|--------|----------------------------------------------------------------------------------------------|-------------| +| id-name | String | ID 生成器名称 | `__share__` | +| as-string | bool | 是否生成字符串类型ID: 将 `long` 类型 ID 转换成 62 进制 `String` 类型（`Long.MAX_VALUE` 最大字符串长度11位），并保证字符串 ID 有序性 | `false` | + +* CosId-Snowflake + +类型: COSID_SNOWFLAKE + +可配置属性： + +| *属性名称* | *数据类型* | *说明* | *默认值* | +|-----------|--------|----------------------------------------------------------------------------------------------|-----------------| +| epoch | String | 雪花 ID 算法的 EPOCH | `1477929600000` | +| as-string | bool | 是否生成字符串类型ID: 将 `long` 类型 ID 转换成 62 进制 `String` 类型（`Long.MAX_VALUE` 最大字符串长度11位），并保证字符串 ID 有序性 | `false` | + +#### 分片算法插件 + +* 基于 CosId 的固定时间范围的分片算法 + +基于 `me.ahoo.cosid:cosid-core` 的工具类实现的固定时间范围的分片算法。 +当分片键为 JSR-310 的所含类或与时间相关的类，将转换为`java.time.LocalDateTime`后再做下一步分片。 +参考 https://github.com/apache/shardingsphere/issues/14047 的讨论。 + +类型：COSID_INTERVAL + +可配置属性： + +| *属性名称* | *数据类型* | *说明* | *默认值* | +|--------------------------|--------|--------------------------------------------------------------------------------------------|-------| +| zone-id | String | 时区，必须遵循 `java.time.ZoneId` 的所含值。 例如：Asia/Shanghai | | +| logic-name-prefix | String | 分片数据源或真实表的前缀格式 | | +| datetime-lower | String | 时间分片下界值，格式与 `yyyy-MM-dd HH:mm:ss` 的时间戳格式一致 | | +| datetime-upper | String | 时间分片上界值，格式与 `yyyy-MM-dd HH:mm:ss` 的时间戳格式一致 | | +| sharding-suffix-pattern | String | 分片数据源或真实表的后缀格式，必须遵循 Java DateTimeFormatter 的格式，必须和 `datetime-interval-unit` 保持一致。例如：yyyyMM | | +| datetime-interval-unit | String | 分片键时间间隔单位，必须遵循 Java ChronoUnit 的枚举值。例如：MONTHS | | +| datetime-interval-amount | int | 分片键时间间隔，超过该时间间隔将进入下一分片 | | + +* 基于 CosId 的雪花ID固定时间范围的分片算法 + +基于 `me.ahoo.cosid:cosid-core` 的工具类实现的雪花ID固定时间范围的分片算法。 +当分片键为 JSR-310 的所含类或与时间相关的类，将转换为`java.time.LocalDateTime`后再做下一步分片。 +参考 https://github.com/apache/shardingsphere/issues/14047 的讨论。 + +类型：COSID_INTERVAL_SNOWFLAKE + +可配置属性： + +| *属性名称* | *数据类型* | *说明* | *默认值* | +|--------------------------|--------|--------------------------------------------------------------------------------------------|-------| +| zone-id | String | 时区，必须遵循 `java.time.ZoneId` 的所含值。 例如：Asia/Shanghai | | +| logic-name-prefix | String | 分片数据源或真实表的前缀格式 | | +| datetime-lower | String | 时间分片下界值，格式与 `yyyy-MM-dd HH:mm:ss` 的时间戳格式一致 | | +| datetime-upper | String | 时间分片上界值，格式与 `yyyy-MM-dd HH:mm:ss` 的时间戳格式一致 | | +| sharding-suffix-pattern | String | 分片数据源或真实表的后缀格式，必须遵循 Java DateTimeFormatter 的格式，必须和 `datetime-interval-unit` 保持一致。例如：yyyyMM | | +| datetime-interval-unit | String | 分片键时间间隔单位，必须遵循 Java ChronoUnit 的枚举值。例如：MONTHS | | +| datetime-interval-amount | int | 分片键时间间隔，超过该时间间隔将进入下一分片 | | + +* 基于 CosId 的取模分片算法 + +基于 `me.ahoo.cosid:cosid-core` 的工具类实现的取模分片算法。 +参考 https://github.com/apache/shardingsphere/issues/14047 的讨论。 + +类型：COSID_MOD + +可配置属性： + +| *属性名称* | *数据类型* | *说明* | +|-------------------|--------|----------------| +| mod | int | 分片数量 | +| logic-name-prefix | String | 分片数据源或真实表的前缀格式 | + +## 基础设施插件 + +### 连接池插件 + +ShardingSphere-Proxy 支持常见的数据库连接池: HikariCP、C3P0、DBCP。 + +可以通过参数 `dataSourceClassName` 指定连接池，当不指定时，默认的的数据库连接池为 HikariCP。 + +* C3P0 连接池 + +配置示例： + +```yaml +dataSources: + ds_0: + dataSourceClassName: com.mchange.v2.c3p0.ComboPooledDataSource + url: jdbc:mysql://localhost:3306/ds_2 + username: root + password: +``` + +* DBCP 连接池 + +配置示例： + +```yaml +dataSources: + ds_0: + dataSourceClassName: org.apache.commons.dbcp2.BasicDataSource + url: jdbc:mysql://localhost:3306/ds_3 + username: root + password: +``` + +## JDBC 接入端插件 + +### JDBC Driver 配置插件 + +ShardingSphere-JDBC 提供了 JDBC 驱动，可以仅通过配置变更即可使用，无需改写代码。 + +* Apollo Driver 配置 + +加载 apollo 指定 namespace 中的 yaml 配置文件的 JDBC URL： +``` +jdbc:shardingsphere:apollo:TEST.test_namespace +``` + +## 治理中心插件 + +### 治理中心集群模式持久化插件 + +* Nacos 持久化 + +类型：Nacos + +适用模式：Cluster + +可配置属性： + +| *名称* | *数据类型* | *说明* | *默认值* | +|---------------------------|--------|-------------------|--------| +| clusterIp | String | 集群中的唯一标识 | 真实主机IP | +| retryIntervalMilliseconds | long | 重试间隔毫秒数 | 500 | +| maxRetries | int | 客户端检查数据可用性的最大重试次数 | 3 | +| timeToLiveSeconds | int | 临时实例失效的秒数 | 30 | \ No newline at end of file diff --git a/features/encrypt/like/pom.xml b/features/encrypt/like/pom.xml index f461332..8ef772e 100644 --- a/features/encrypt/like/pom.xml +++ b/features/encrypt/like/pom.xml @@ -20,10 +20,10 @@ <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.apache.shardingsphere</groupId> - <artifactId>shardingsphere-plugin-feature-encrypt</artifactId> + <artifactId>shardingsphere-plugin-features-encrypt</artifactId> <version>5.4.1-SNAPSHOT</version> </parent> - <artifactId>shardingsphere-plugin-feature-encrypt-like</artifactId> + <artifactId>shardingsphere-plugin-features-encrypt-like</artifactId> <name>${project.artifactId}</name> <dependencies> diff --git a/features/encrypt/pom.xml b/features/encrypt/pom.xml index b8be577..beafcb4 100644 --- a/features/encrypt/pom.xml +++ b/features/encrypt/pom.xml @@ -23,11 +23,13 @@ <artifactId>shardingsphere-plugin-features</artifactId> <version>5.4.1-SNAPSHOT</version> </parent> - <artifactId>shardingsphere-plugin-feature-encrypt</artifactId> + <artifactId>shardingsphere-plugin-features-encrypt</artifactId> <packaging>pom</packaging> <name>${project.artifactId}</name> <modules> + <module>like</module> + <module>rc4</module> <module>sm</module> </modules> </project> diff --git a/features/encrypt/rc4/pom.xml b/features/encrypt/rc4/pom.xml index 60846cb..57d0c8f 100644 --- a/features/encrypt/rc4/pom.xml +++ b/features/encrypt/rc4/pom.xml @@ -20,10 +20,10 @@ <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.apache.shardingsphere</groupId> - <artifactId>shardingsphere-plugin-feature-encrypt</artifactId> + <artifactId>shardingsphere-plugin-features-encrypt</artifactId> <version>5.4.1-SNAPSHOT</version> </parent> - <artifactId>shardingsphere-plugin-feature-encrypt-rc4</artifactId> + <artifactId>shardingsphere-plugin-features-encrypt-rc4</artifactId> <name>${project.artifactId}</name> <dependencies> diff --git a/features/encrypt/sm/pom.xml b/features/encrypt/sm/pom.xml index 236ca37..77f55bd 100644 --- a/features/encrypt/sm/pom.xml +++ b/features/encrypt/sm/pom.xml @@ -20,10 +20,10 @@ <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.apache.shardingsphere</groupId> - <artifactId>shardingsphere-plugin-feature-encrypt</artifactId> + <artifactId>shardingsphere-plugin-features-encrypt</artifactId> <version>5.4.1-SNAPSHOT</version> </parent> - <artifactId>shardingsphere-plugin-feature-encrypt-sm</artifactId> + <artifactId>shardingsphere-plugin-features-encrypt-sm</artifactId> <name>${project.artifactId}</name> <dependencies> diff --git a/features/pom.xml b/features/pom.xml index 4129810..dcd9f9a 100644 --- a/features/pom.xml +++ b/features/pom.xml @@ -28,7 +28,7 @@ <name>${project.artifactId}</name> <modules> - <module>sharding</module> <module>encrypt</module> + <module>sharding</module> </modules> </project> diff --git a/features/sharding/cosid/pom.xml b/features/sharding/cosid/pom.xml index ebba32d..9128663 100644 --- a/features/sharding/cosid/pom.xml +++ b/features/sharding/cosid/pom.xml @@ -20,10 +20,10 @@ <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.apache.shardingsphere</groupId> - <artifactId>shardingsphere-plugin-feature-sharding</artifactId> + <artifactId>shardingsphere-plugin-features-sharding</artifactId> <version>5.4.1-SNAPSHOT</version> </parent> - <artifactId>shardingsphere-plugin-feature-sharding-cosid</artifactId> + <artifactId>shardingsphere-plugin-features-sharding-cosid</artifactId> <name>${project.artifactId}</name> <properties> @@ -42,10 +42,6 @@ <artifactId>cosid-core</artifactId> <version>${cosid.version}</version> </dependency> - <dependency> - <groupId>org.projectlombok</groupId> - <artifactId>lombok</artifactId> - </dependency> </dependencies> <build> diff --git a/features/sharding/nanoid/pom.xml b/features/sharding/nanoid/pom.xml index d3e3eec..3d8e36a 100644 --- a/features/sharding/nanoid/pom.xml +++ b/features/sharding/nanoid/pom.xml @@ -20,10 +20,10 @@ <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.apache.shardingsphere</groupId> - <artifactId>shardingsphere-plugin-feature-sharding</artifactId> + <artifactId>shardingsphere-plugin-features-sharding</artifactId> <version>5.4.1-SNAPSHOT</version> </parent> - <artifactId>shardingsphere-plugin-feature-sharding-nanoid</artifactId> + <artifactId>shardingsphere-plugin-features-sharding-nanoid</artifactId> <name>${project.artifactId}</name> <properties> diff --git a/features/sharding/pom.xml b/features/sharding/pom.xml index c59a67f..83de02b 100644 --- a/features/sharding/pom.xml +++ b/features/sharding/pom.xml @@ -23,7 +23,7 @@ <artifactId>shardingsphere-plugin-features</artifactId> <version>5.4.1-SNAPSHOT</version> </parent> - <artifactId>shardingsphere-plugin-feature-sharding</artifactId> + <artifactId>shardingsphere-plugin-features-sharding</artifactId> <packaging>pom</packaging> <name>${project.artifactId}</name> diff --git a/pom.xml b/pom.xml index 354320f..56f582f 100644 --- a/pom.xml +++ b/pom.xml @@ -33,9 +33,8 @@ <modules> <module>features</module> <module>infra</module> - <module>features/encrypt/like</module> - <module>mode</module> <module>jdbc</module> + <module>mode</module> </modules> <properties>
