This is an automated email from the ASF dual-hosted git repository.
duanzhengqiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new ee318dd47a7 refactor kernel and encrypt dev manual doc (#19100)
ee318dd47a7 is described below
commit ee318dd47a705790289d2fd3e1ba21543cc23528
Author: Chuxin Chen <[email protected]>
AuthorDate: Wed Jul 13 17:49:43 2022 +0800
refactor kernel and encrypt dev manual doc (#19100)
* refactor encrypt algorithm
* refactor kernel dev manual
* refactor parser dev manual
---
docs/document/content/dev-manual/kernel.cn.md | 67 +++++++-----
docs/document/content/dev-manual/kernel.en.md | 113 ++++++++++++---------
docs/document/content/dev-manual/sql-parser.cn.md | 25 +++--
docs/document/content/dev-manual/sql-parser.en.md | 60 ++++++-----
.../builtin-algorithm/encrypt.cn.md | 41 +++++++-
.../builtin-algorithm/encrypt.en.md | 42 ++++++--
6 files changed, 221 insertions(+), 127 deletions(-)
diff --git a/docs/document/content/dev-manual/kernel.cn.md
b/docs/document/content/dev-manual/kernel.cn.md
index 943b57877c5..ec46afad656 100644
--- a/docs/document/content/dev-manual/kernel.cn.md
+++ b/docs/document/content/dev-manual/kernel.cn.md
@@ -5,12 +5,47 @@ weight = 3
chapter = true
+++
+## SPI 接口
## SQLRouter
| *SPI 名称* | *详细说明* |
| ----------------------------------- | --------------------- |
| SQLRouter | 用于处理路由结果 |
+### SQLRewriteContextDecorator
+
+| *SPI 名称* | *详细说明* |
+| ---------------------------------- | ------------------ |
+| SQLRewriteContextDecorator | 用于处理 SQL 改写结果 |
+
+### SQLExecutionHook
+
+| *SPI 名称* | *详细说明* |
+| ----------------------------- | --------------- |
+| SQLExecutionHook | SQL 执行过程监听器 |
+
+### ResultProcessEngine
+
+| *SPI 名称* | *详细说明* |
+| ---------------------------- | ------------------- |
+| ResultProcessEngine | 用于处理结果集 |
+
+### StoragePrivilegeHandler
+
+| *SPI 名称* | *详细说明* |
+| -------------------------- | ------------------------------ |
+| StoragePrivilegeHandler | 使用数据库方言处理权限信息 |
+
+### DynamicDataSourceStrategy
+
+| *SPI 名称* | *详细说明* |
+| ------------------------------------------ | ------------------------------ |
+| DynamicDataSourceStrategy | 动态数据源获取策略 |
+
+## 示例
+
+### SQLRouter
+
| *已知实现类* | *详细说明* |
| ----------------------------------- | --------------------- |
| ReadwriteSplittingSQLRouter | 用于处理读写分离路由结果 |
@@ -19,43 +54,25 @@ chapter = true
| ShardingSQLRouter | 用于处理分片路由结果 |
| ShadowSQLRouter | 用于处理影子库路由结果 |
-## SQLRewriteContextDecorator
-
-| *SPI 名称* | *详细说明* |
-| ---------------------------------- | ------------------ |
-| SQLRewriteContextDecorator | 用于处理 SQL 改写结果 |
-
+### SQLRewriteContextDecorator
| *已知实现类* | *详细说明* |
| ---------------------------------- | --------------------- |
| ShardingSQLRewriteContextDecorator | 用于处理分片 SQL 改写结果 |
| EncryptSQLRewriteContextDecorator | 用于处理加密 SQL 改写结果 |
-## SQLExecutionHook
-
-| *SPI 名称* | *详细说明* |
-| ----------------------------- | --------------- |
-| SQLExecutionHook | SQL 执行过程监听器 |
-
+### SQLExecutionHook
| *已知实现类* | *详细说明* |
| ----------------------------- | ------------------------- |
| TransactionalSQLExecutionHook | 基于事务的 SQL 执行过程监听器 |
-## ResultProcessEngine
-
-| *SPI 名称* | *详细说明* |
-| ---------------------------- | ------------------- |
-| ResultProcessEngine | 用于处理结果集 |
+### ResultProcessEngine
| *已知实现类* | *详细说明* |
| ---------------------------- | ------------------- |
| ShardingResultMergerEngine | 用于处理分片结果集归并 |
| EncryptResultDecoratorEngine | 用于处理加密结果集改写 |
-## StoragePrivilegeHandler
-
-| *SPI 名称* | *详细说明* |
-| -------------------------- | ------------------------------ |
-| StoragePrivilegeHandler | 使用数据库方言处理权限信息 |
+### StoragePrivilegeHandler
| *已知实现类* | *详细说明* |
| -------------------------- | ------------------------------ |
@@ -64,11 +81,7 @@ chapter = true
| OraclePrivilegeHandler | 使用 Oracle 方言处理权限信息 |
| MySQLPrivilegeHandler | 使用 MySQL 方言处理权限信息 |
-## DynamicDataSourceStrategy
-
-| *SPI 名称* | *详细说明* |
-| ------------------------------------------ | ------------------------------ |
-| DynamicDataSourceStrategy | 动态数据源获取策略 |
+### DynamicDataSourceStrategy
| *已知实现类* | *详细说明* |
| ------------------------------------------ | -------------------------------
|
diff --git a/docs/document/content/dev-manual/kernel.en.md
b/docs/document/content/dev-manual/kernel.en.md
index a40a649230c..8edcd8116d7 100644
--- a/docs/document/content/dev-manual/kernel.en.md
+++ b/docs/document/content/dev-manual/kernel.en.md
@@ -5,71 +5,84 @@ weight = 3
chapter = true
+++
-## SQLRouter
+## SPI Interface
+### SQLRouter
-| *SPI Name* | *Description*
|
-| ----------------------------------- |
----------------------------------------------------- |
-| SQLRouter | Used to process routing results
|
+| *SPI Name* | *Description* |
+| ----------------------------------- | --------------------- |
+| SQLRouter | Used to process routing results
|
-| *Implementation Class* | *Description*
|
-| ----------------------------------- |
----------------------------------------------------- |
-| ReadwriteSplittingSQLRouter | Used to process read-write separation
routing results |
-| DatabaseDiscoverySQLRouter | Used to process database discovery
routing results |
-| SingleTableSQLRouter | Used to process single-table routing
results |
-| ShardingSQLRouter | Used to process sharding routing
results |
-| ShadowSQLRouter | Used to process shadow database
routing results |
+### SQLRewriteContextDecorator
-## SQLRewriteContextDecorator
+| *SPI Name* | *Description* |
+| ---------------------------------- | ------------------ |
+| SQLRewriteContextDecorator | Used to handle SQL rewrite results |
-| *SPI Name* | *Description*
|
-| ---------------------------------- |
---------------------------------------------- |
-| SQLRewriteContextDecorator | Used to process SQL rewrite results
|
+### SQLExecutionHook
-| *SPI Name* | *Description*
|
-| ---------------------------------- |
---------------------------------------------- |
-| ShardingSQLRewriteContextDecorator | Used to process sharding SQL rewrite
results |
-| EncryptSQLRewriteContextDecorator | Used to process encryption SQL rewrite
results |
+| *SPI Name* | *Description* |
+| ----------------------------- | --------------- |
+| SQLExecutionHook | SQL execution process listener |
-## SQLExecutionHook
+### ResultProcessEngine
-| *SPI Name* | *Description* |
-| ----------------------------- | --------------------------------- |
-| SQLExecutionHook | Hook of SQL execution |
+| *SPI Name* | *Description* |
+| ---------------------------- | ------------------- |
+| ResultProcessEngine | Used to process result sets |
-| *Implementation Class* | *Description* |
-| ----------------------------- | --------------------------------- |
-| TransactionalSQLExecutionHook | Transaction hook of SQL execution |
+### StoragePrivilegeHandler
+
+| *SPI Name* | *Description* |
+| -------------------------- | ------------------------------ |
+| StoragePrivilegeHandler | Use SQL dialect to process privilege metadata
|
+
+### DynamicDataSourceStrategy
+
+| *SPI Name* | *Description*
|
+| ------------------------------------------ | ------------------------------ |
+| DynamicDataSourceStrategy | Dynamic data source fetch
strategy |
-## ResultProcessEngine
+## Sample
-| *SPI Name* | *Description*
|
-| ---------------------------- |
----------------------------------------------------- |
-| ResultProcessEngine | Used by merge engine to process result set
|
+### SQLRouter
-| *Implementation Class* | *Description*
|
-| ---------------------------- |
----------------------------------------------------- |
-| ShardingResultMergerEngine | Used by merge engine to process sharding
result set |
-| EncryptResultDecoratorEngine | Used by merge engine to process encryption
result set |
+| *Implementation Class* | *Description* |
+| ----------------------------------- | --------------------- |
+| ReadwriteSplittingSQLRouter | Used to process read-write splitting
routing results |
+| DatabaseDiscoverySQLRouter | Used to process database discovery
routing results |
+| SingleTableSQLRouter | Used to process single-table routing
results |
+| ShardingSQLRouter | Used to process sharding routing
results |
+| ShadowSQLRouter | Used to process shadow database
routing results |
+
+### SQLRewriteContextDecorator
+| *Implementation Class* | *Description* |
+| ---------------------------------- | --------------------- |
+| ShardingSQLRewriteContextDecorator | Used to process sharding SQL rewrite
results |
+| EncryptSQLRewriteContextDecorator | Used to process encryption SQL rewrite
results |
+
+### SQLExecutionHook
+| *Implementation Class* | *Description* |
+| ----------------------------- | ------------------------- |
+| TransactionalSQLExecutionHook | Transaction hook of SQL execution |
-## StoragePrivilegeHandler
+### ResultProcessEngine
-| *SPI Name* | *Description*
|
-| -------------------------- |
---------------------------------------------------- |
-| StoragePrivilegeHandler | Use SQL dialect to process privilege metadata
|
+| *Implementation Class* | *Description* |
+| ---------------------------- | ------------------- |
+| ShardingResultMergerEngine | Used to handle sharding result set merge |
+| EncryptResultDecoratorEngine | Used to handle encrypted result set overrides
|
-| *Implementation Class* | *Description*
|
-| -------------------------- |
---------------------------------------------------- |
-| PostgreSQLPrivilegeHandler | Use PostgreSQL dialect to process privilege
metadata |
-| SQLServerPrivilegeHandler | Use SQLServer dialect to process privilege
metadata |
-| OraclePrivilegeHandler | Use Oracle dialect to process privilege
metadata |
-| MySQLPrivilegeHandler | Use MySQL dialect to process privilege metadata
|
+### StoragePrivilegeHandler
-## DynamicDataSourceStrategy
+| *Implementation Class* | *Description* |
+| -------------------------- | ------------------------------ |
+| PostgreSQLPrivilegeHandler | Use PostgreSQL dialect to process privilege
metadata |
+| SQLServerPrivilegeHandler | Use SQLServer dialect to process privilege
metadata |
+| OraclePrivilegeHandler | Use Oracle dialect to process privilege
metadata |
+| MySQLPrivilegeHandler | Use MySQL dialect to process privilege metadata
|
-| *SPI Name* | *Description*
|
-| ------------------------------------------ |
--------------------------------------------------- |
-| DynamicDataSourceStrategy | Dynamic data source fetch
strategy |
+### DynamicDataSourceStrategy
-| *Implementation Class* | *Description*
|
-| ------------------------------------------ |
--------------------------------------------------- |
+| *Implementation Class* | *Description*
|
+| ------------------------------------------ | -------------------------------
|
| DatabaseDiscoveryDynamicDataSourceStrategy | Use database discovery to
dynamic fetch data source |
diff --git a/docs/document/content/dev-manual/sql-parser.cn.md
b/docs/document/content/dev-manual/sql-parser.cn.md
index cee43715efb..4c076d50024 100644
--- a/docs/document/content/dev-manual/sql-parser.cn.md
+++ b/docs/document/content/dev-manual/sql-parser.cn.md
@@ -5,12 +5,24 @@ weight = 5
chapter = true
+++
-## DatabaseTypedSQLParserFacade
+## SPI 接口
+
+### DatabaseTypedSQLParserFacade
| *SPI 名称* | *详细说明* |
| ---------------------------- | ----------------------------------- |
| DatabaseTypedSQLParserFacade | 配置用于 SQL 解析的词法分析器和语法分析器入口 |
+### SQLVisitorFacade
+
+| *SPI 名称* | *详细说明*
|
+| ----------------------------------- |
------------------------------------------ |
+| SQLVisitorFacade | SQL 语法树访问器入口 |
+
+## 示例
+
+### DatabaseTypedSQLParserFacade
+
| *Implementation Class* | *Description* |
| ---------------------- |--------------------------|
| MySQLParserFacade | 基于 MySQL 的 SQL 解析器入口 |
@@ -20,17 +32,8 @@ chapter = true
| SQL92ParserFacade | 基于 SQL92 的 SQL 解析器入口 |
| OpenGaussParserFacade | 基于 openGauss 的 SQL 解析器入口 |
-## SQLVisitorFacade
+### SQLVisitorFacade
| *SPI 名称* | *详细说明*
|
| ----------------------------------- |
------------------------------------------ |
| SQLVisitorFacade | SQL 语法树访问器入口 |
-
-| *Implementation Class* | *Description*
|
-| ----------------------------------- |
----------------------------------------- |
-| MySQLStatementSQLVisitorFacade | 基于 MySQL 的提取 SQL 语句的语法树访问器 |
-| PostgreSQLStatementSQLVisitorFacade | 基于 PostgreSQL 的提取 SQL 语句的语法树访问器 |
-| SQLServerStatementSQLVisitorFacade | 基于 SQLServer 的提取 SQL 语句的语法树访问器 |
-| OracleStatementSQLVisitorFacade | 基于 Oracle 的提取 SQL 语句的语法树访问器 |
-| SQL92StatementSQLVisitorFacade | 基于 SQL92 的提取 SQL 语句的语法树访问器 |
-| OpenGaussStatementSQLVisitorFacade | 基于 openGauss 的提取 SQL 语句的语法树访问器 |
diff --git a/docs/document/content/dev-manual/sql-parser.en.md
b/docs/document/content/dev-manual/sql-parser.en.md
index ba1bb12e0c3..42a15fd5efc 100644
--- a/docs/document/content/dev-manual/sql-parser.en.md
+++ b/docs/document/content/dev-manual/sql-parser.en.md
@@ -5,31 +5,35 @@ weight = 5
chapter = true
+++
-## DatabaseTypedSQLParserFacade
-
-| *SPI Name* | *Description* |
-| ---------------------------- | -------------------------------------- |
-| DatabaseTypedSQLParserFacade | SQL parser facade for lexer and parser |
-
-| *Implementation Class* | *Description* |
-| ---------------------- |------------------------------------|
-| MySQLParserFacade | SQL parser facade for MySQL |
-| PostgreSQLParserFacade | SQL parser facade for PostgreSQL |
-| SQLServerParserFacade | SQL parser facade for SQLServer |
-| OracleParserFacade | SQL parser facade for Oracle |
-| SQL92ParserFacade | SQL parser facade for SQL92 |
-| OpenGaussParserFacade | SQL parser facade for openGauss |
-
-## SQLVisitorFacade
-
-| *SPI Name* | *Description*
|
-| ----------------------------------- |
-------------------------------------------------------- |
-| SQLVisitorFacade | SQL AST visitor facade
|
-
-| *Implementation Class* | *Description*
|
-| ----------------------------------- |
-------------------------------------------------------- |
-| MySQLStatementSQLVisitorFacade | SQL visitor of statement extracted
facade for MySQL |
-| PostgreSQLStatementSQLVisitorFacade | SQL visitor of statement extracted
facade for PostgreSQL |
-| SQLServerStatementSQLVisitorFacade | SQL visitor of statement extracted
facade for SQLServer |
-| OracleStatementSQLVisitorFacade | SQL visitor of statement extracted
facade for Oracle |
-| SQL92StatementSQLVisitorFacade | SQL visitor of statement extracted
facade for SQL92 |
+## SPI Interface
+
+### DatabaseTypedSQLParserFacade
+
+| *SPI Name* | *Description* |
+| ---------------------------- | ----------------------------------- |
+| DatabaseTypedSQLParserFacade | Configure the lexical and syntactic parser
entry for SQL parsing |
+
+### SQLVisitorFacade
+
+| *SPI Name* | *Description*
|
+| ----------------------------------- |
------------------------------------------ |
+| SQLVisitorFacade | SQL syntax tree access portal
|
+
+## Sample
+
+### DatabaseTypedSQLParserFacade
+
+| *Implementation Class* | *Description* |
+| ---------------------- |--------------------------|
+| MySQLParserFacade | SQL parser entry based on MySQL |
+| PostgreSQLParserFacade | SQL parser entry based on PostgreSQL|
+| SQLServerParserFacade | SQL parser entry based on SQLServer |
+| OracleParserFacade | SQL parser entry based on Oracle|
+| SQL92ParserFacade | SQL parser entry based on SQL92 |
+| OpenGaussParserFacade | SQL parser entry based on openGauss |
+
+### SQLVisitorFacade
+
+| *SPI Name* | *Description*
|
+| ----------------------------------- |
------------------------------------------ |
+| SQLVisitorFacade | SQL syntax tree access portal
|
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/encrypt.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/encrypt.cn.md
index 18c4f2267b9..45f2d9fa7f8 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/encrypt.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/encrypt.cn.md
@@ -3,13 +3,18 @@ title = "加密算法"
weight = 5
+++
-## MD5 加密算法
+## 背景信息
+加密算法是 Apache ShardingSphere 的加密功能使用的算法，ShardingSphere 内置了多种算法，可以让用户方便使用。
+
+## 参数解释
+
+### MD5 加密算法
类型：MD5
可配置属性：无
-## AES 加密算法
+### AES 加密算法
类型：AES
@@ -19,7 +24,7 @@ weight = 5
| ------------- | --------- | ------------- |
| aes-key-value | String | AES 使用的 KEY |
-## RC4 加密算法
+### RC4 加密算法
类型：RC4
@@ -29,7 +34,7 @@ weight = 5
| ------------- | --------- | ------------- |
| rc4-key-value | String | RC4 使用的 KEY |
-## SM3 加密算法
+### SM3 加密算法
类型：SM3
@@ -39,7 +44,7 @@ weight = 5
| ------------- | --------- | ------------- |
| sm3-salt | String | SM3 使用的 SALT（空或 8 Bytes） |
-## SM4 加密算法
+### SM4 加密算法
类型：SM4
@@ -51,3 +56,29 @@ weight = 5
| sm4-mode | String | SM4 使用的 MODE （CBC 或 ECB） |
| sm4-iv | String | SM4 使用的 IV （MODE 为 CBC 时需指定，16 Bytes）|
| sm4-padding | String | SM4 使用的 PADDING （PKCS5Padding 或
PKCS7Padding，暂不支持 NoPadding）|
+
+## 操作步骤
+1. 在加密规则中配置加密器
+2. 为加密器指定加密算法类型
+
+## 配置示例
+```yaml
+rules:
+- !ENCRYPT
+ tables:
+ t_user:
+ columns:
+ username:
+ plainColumn: username_plain
+ cipherColumn: username
+ encryptorName: name-encryptor
+ encryptors:
+ name-encryptor:
+ type: AES
+ props:
+ aes-key-value: 123456abc
+```
+
+## 相关参考
+- [核心特性：数据加密](/cn/features/encrypt/)
+- [开发者指南：数据加密](/cn/dev-manual/encrypt/)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/encrypt.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/encrypt.en.md
index ad8ec904d9b..ade900c93fc 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/encrypt.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/encrypt.en.md
@@ -3,13 +3,17 @@ title = "Encryption Algorithm"
weight = 5
+++
-## MD5 Encrypt Algorithm
+## Background
+Encryption algorithms are the algorithms used by the encryption features of
Apache ShardingSphere. A variety of algorithms are built-in to make it easy for
users to fully leverage the feature.
+
+## Parameters
+### MD5 Encrypt Algorithm
Type: MD5
Attributes: None
-## AES Encrypt Algorithm
+### AES Encrypt Algorithm
Type: AES
@@ -19,7 +23,7 @@ Attributes:
| ------------- | ---------- | ------------- |
| aes-key-value | String | AES KEY |
-## RC4 Encrypt Algorithm
+### RC4 Encrypt Algorithm
Type: RC4
@@ -29,7 +33,7 @@ Attributes:
| ------------- | ---------- | ------------- |
| rc4-key-value | String | RC4 KEY |
-## SM3 Encrypt Algorithm
+### SM3 Encrypt Algorithm
Type: SM3
@@ -39,7 +43,7 @@ Attributes:
| ------------- | ---------- | ------------- |
| sm3-salt | String | SM3 SALT (should be blank or 8 bytes long)
|
-## SM4 Encrypt Algorithm
+### SM4 Encrypt Algorithm
Type: SM4
@@ -50,4 +54,30 @@ Attributes:
| 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)|
\ No newline at end of file
+| sm4-padding | String | SM4 PADDING (should be PKCS5Padding or
PKCS7Padding, NoPadding excepted)|
+
+## Operating Procedures
+1. Configure encryptors in an encryption rule.
+2. Use relevant algorithm types in encryptors.
+
+## Configuration Examples
+```yaml
+rules:
+- !ENCRYPT
+ tables:
+ t_user:
+ columns:
+ username:
+ plainColumn: username_plain
+ cipherColumn: username
+ encryptorName: name-encryptor
+ encryptors:
+ name-encryptor:
+ type: AES
+ props:
+ aes-key-value: 123456abc
+```
+
+## Related References
+- [Core Feature: Data Encrypt](/en/features/encrypt/)
+- [Developer Guide: Data Encrypt](/en/dev-manual/encrypt/)
