shardingsphere-example 項目包含多個(gè)模塊，將為用戶(hù)帶來(lái)水平拆分、讀寫(xiě)分離、分布式治理、分布式事務(wù)、數據加密、強制路由、影子庫等功能的使用及配置樣例，覆蓋 Java API、YAML、Spring Boot、Spring Namespace 等多種業(yè)務(wù)常用的接入形態(tài)。除了 ShardingSphere-JDBC，shardingsphere-example 中還增加了 ShardingSphere-Proxy 和 ShardingSphere-Parser 的使用案例。

所有涉及到 Apache ShardingSphere 的功能特性、接入場(chǎng)景以及各種靈活的配置方式，都可以在官方的 repo 里找到樣例，方便用戶(hù)查詢(xún)和參考。下表展示了 shardingsphere-example 的模塊分布情況：

shardingsphere-example

  ├── example-core

  │   ├── config-utility

  │   ├── example-api

  │   ├── example-raw-jdbc

  │   ├── example-spring-jpa

  │   └── example-spring-mybatis

  ├── shardingsphere-jdbc-example

  │   ├── sharding-example

  │   │   ├── sharding-raw-jdbc-example

  │   │   ├── shardi
ng-spring-boot-jpa-example

  │   │   ├── sharding-spring-boot-mybatis-example

  │   │   ├── sharding-spring-namespace-jpa-example

  │   │   └── sharding-spring-namespace-mybatis-example

  │   ├── governance-example

  │   │   ├── governance-raw-jdbc-example

  │   │   ├── governance-spring-boot-mybatis-example

  │   │   └── governance-spr
ing-namespace-mybatis-example

  │   ├── transaction-example

  │   │   ├── transaction-2pc-xa-atomikos-raw-jdbc-example

  │   │   ├── transaction-2pc-xa-bitronix-raw-jdbc-example

  │   │   ├── transaction-2pc-xa-narayana-raw-jdbc-example

  │   │   ├── transaction-2pc-xa-spring-boot-example

  │   │   ├── transaction-2pc-xa-spring-namespace-example

  │   │   ├── transaction-base-seata-raw-jdbc-example       

  │   │   └── transaction-base-seata-spring-boot-example

  │   ├── other-feature-example

  │   │   ├── encrypt-example

  │   │   │   ├── encrypt-raw-jdbc-example

  │   │   │   ├── encrypt-spring-boot-mybatis-example

  │   │   │  
 └── encrypt-spring-namespace-mybatis-example

  │   │   ├── hint-example

  │   │   │   └── hint-raw-jdbc-example

  │   │   └── shadow-example

  │   │   │   ├── shadow-raw-jdbc-example

  │   │   │   ├── shadow-spring-boot-mybatis-example

  │   │   │   └── shadow-spring-namespace-mybatis-example

  │   ├── extension-example

  │   │   └── custom-sharding-algortihm-example

  ├── shardingsphere-parser-example

  ├── shardingsphere-proxy-example

  │   ├── shardingsphere-proxy-boot-mybatis-example

  │   └── shardingsphere-proxy-hint-example

  └── src/resources

        └── manual_schema.sql

1. example-core

example 核心模塊，包含實(shí)體、接口定義和其他公用代碼。

2. shardingsphere-jdbc-example

ShardingSphere-JDBC 示例模塊，展示 ShardingSphere-JDBC 的功能特性和各種使用方式。

展示如何使用  ShardingSphere-JDBC 進(jìn)行數據分片，包含分庫、分表、分庫+分表、讀寫(xiě)分離、讀寫(xiě)分離+分庫分表的應用場(chǎng)景。在 ORM 集成方面，本模塊也貼心的為用戶(hù)提供了 MyBatis 和 JPA 的集成樣例。

展示 ShardingSphere-JDBC 在分布式治理方面的應用，包含了分庫分表、讀寫(xiě)分離、數據加密、影子庫等特性與分布式治理相結合的應用場(chǎng)景。

注意： 分布式治理 example 依賴(lài) Apache ZooKeeper，請自行部署。

（3）transaction-example

展示 ShardingSphere-JDBC 支持的多種分布式事務(wù)管理方式，用戶(hù)可以根據應用場(chǎng)景選擇適合的分布式事務(wù)管理器進(jìn)行使用。鑒于分布式事務(wù)的特殊性，本模塊的示例都是基于分庫、分表或分庫+分表的場(chǎng)景設計的。

注意： Seata 事務(wù)管理器需要自行部署。

（4）other-feature-example

ShardingSphere-JDBC 其他功能特性的示例，目前包含了 encrypt（數據加密）、hint（強制路由）、shadow（影子庫）幾種類(lèi)型。

① encrypt-example

數據加密功能示例，同樣包含了 Java API、YAML、Spring Boot、Spring Namespace 等幾種接入方式的樣例。

② hint-example

強制路由功能示例，目前只提供了 YAML 配置方式的案例，更多場(chǎng)景歡迎補充。

③ shadow-example

影子庫功能示例，包含了影子庫特性與數據加密、分庫分表、讀寫(xiě)分離等特性結合的應用樣例。

（5）extension-example

本模塊展示 ShardingSphere-JDBC 的自定義擴展能力，用戶(hù)可以通過(guò) SPI 或 ShardingSphere 提供的其他方式進(jìn)行功能擴展。

① custom-sharding-algortihm-example

展示了如何通過(guò) 'CLASS_BASED' 方式進(jìn)行自定義分片算法的擴展。

3. shardingsphere-parser-example

SQLParserEngine  是 Apache ShardingSphere 定制的 SQL 解析引擎，也是 ShardingSphere-JDBC 和 ShardingSphere-Proxy 的能力基礎。用戶(hù)輸入的 SQL 文本 通過(guò)  SQLParserEngine   解析成可以識別的語(yǔ)法對象，之后才能進(jìn)行路由、改寫(xiě)等增強操作。

從 5.0.0-alpha 版本開(kāi)始，Apache ShardingSphere 將 SQL 解析這一核心能力開(kāi)放給用戶(hù)，用戶(hù)可以通過(guò) API 調用  SQLParserEngine，在自己的應用系統中進(jìn)行高效的 SQL 解析，滿(mǎn)足更多個(gè)性化的業(yè)務(wù)需要。

本模塊展示了  SQLParserEngine API 的使用方式，覆蓋了 MySQL、PostgreSQL、Oracle、SQLServer 以及 SQL92 等各種語(yǔ)法形式。

4. shardingsphere-proxy-example

ShardingSphere-Proxy 示例模塊，包含了分庫分表、讀寫(xiě)分離和強制路由等常用場(chǎng)景的配置樣例。由于 ShardingSphere-Proxy 與 ShardingSphere-JDBC 在功能特性的支持度上大體相同，未列舉的示例也可以對照  shardingsphere-jdbc-example  進(jìn)行參考。

（1）shardingsphere-proxy-boot-mybatis-example

展示了通過(guò) Proxy 配置數據分片，并使用 SpringBoot + MyBatis 的方式進(jìn)行數據訪(fǎng)問(wèn)的場(chǎng)景示例。

（2）shardingsphere-proxy-hint-example

展示了通過(guò) Proxy 配置強制路由，并使用 Java 客戶(hù)端進(jìn)行數據訪(fǎng)問(wèn)的場(chǎng)景示例。

在 Apache ShardingSphere 5.0.0-beta 版本發(fā)布之際，社區貢獻者對 shardingsphere-example 也進(jìn)行了升級和優(yōu)化，主要包括：

• JDK 版本升級

• 組件版本升級

• 類(lèi)命名優(yōu)化

• 配置文件優(yōu)化

• SQL 腳本優(yōu)化

以下是升級相關(guān)的詳細內容：

在以 Java 作為主要語(yǔ)言的專(zhuān)業(yè)開(kāi)發(fā)者中，Java 8 LTS（長(cháng)期支持版本）仍然是最受歡迎的版本。

來(lái)源《JetBrains 公司 2020 關(guān)于 Java 的報告》：https://blog.jetbrains.com/zh-hans/idea/2020/10/java-2020/

shardingsphere-example 升級以后要求 Java 8 作為最低版本。如果您當前使用的是 Java 7 或更早版本，則需要先升級 JDK。

shardingsphere-example 對 Spring 相關(guān)組件進(jìn)行升級。

• spring-boot version 由 1.5.17 升級到 2.0.9.RELEASE

• springframework version 由 4.3.20.RELEASE 升級到 5.0.13.RELEASE

• mybatis-spring-boot-start version 由 1.3.0 升級到 2.0.1

• mybatis-spring version 由 1.3.0 升級到 2.0.1

shardingsphere-example 對持久層框架 MyBatis 和 Hibernate 進(jìn)行了升級。

• mybatis version 由 3.4.2 升級到 3.5.1

• hibernate version 由 4.3.11.Final 升級到 5.2.18.Final

shardingsphere-example 對數據庫連接池 HikariCP 進(jìn)行了升級。

• HikariCP artifactId 由 HikariCP-java7 升級到 HikariCP

• HikariCP version 由 2.4.11 升級到 3.4.2

shardingsphere-example 對 MySQL 和 PostgreSQL 連接驅動(dòng)進(jìn)行了升級。

• mysql-connector-java version 由 5.1.42 升級到 5.1.47

• postgresql version 由 42.2.5.jre7 升級到 42.2.5

從這里開(kāi)始，我們將通過(guò)幾個(gè)典型場(chǎng)景來(lái)說(shuō)明如何配置和運行 example。

由于 shardingsphere-example 項目模塊眾多，本次挑選幾個(gè)關(guān)注度較高的 ShardingSphere-JDBC 應用場(chǎng)景來(lái)舉例說(shuō)明。

1. shardingsphere-example 使用 Maven 作為構建工具，請提前準備 Maven 環(huán)境；

2. 準備 Apache ShardingSphere，如果你的設備中尚未安裝 Apache ShardingSphere，可以按照如下方式進(jìn)行下載和編譯：

## 克隆 Apache ShardingSphere 項目

git 
clone 


## 編譯源代碼


cd shardingsphere

mvn clean install -Prelease

3. 將 shardingsphere-example 項目導入自己的 IDE 中；

4. 準備一個(gè)可管理的數據庫環(huán)境，例如本地的 MySQL 實(shí)例；

5. 如需運行讀寫(xiě)分離測試，請確保數據庫的主從同步機制工作正常；

6. 執行數據庫初始化腳本：examples/src/resources/manual_schema.sql

1. 模塊路徑

examples/shardingsphere-jdbc-example/sharding-example/sharding-spring-boot-mybatis-example

2. 場(chǎng)景目標

本示例展示 ShardingSphere-JDBC 結合 SpringBoot 和 MyBatis 進(jìn)行分庫分表的應用場(chǎng)景。此次分片的目標是 2 庫 4 表，即將一張邏輯表拆分為 4 個(gè)分片，均勻保存在 2 個(gè)不同的數據庫中。

3. 運行準備

• 配置 application.properties

• 將 spring.profiles.active 設置為  sharding-databases-tables

• 配置 application-sharding-databases-tables.properties

• 將  jdbc-url   修改為自己的數據庫地址，并配置正確的用戶(hù)名密碼等信息

• 將  spring.shardingsphere.props.sql-show  屬性設置為  true

詳細配置說(shuō)明請閱讀配置手冊：

https://shardingsphere.apache.org/document/current/cn/user-manual/shardingsphere-jdbc/configuration/spring-boot-starter/sharding/

4. 啟動(dòng)運行

運行啟動(dòng)類(lèi)：   ShardingSpringBootMybatisExample.java

此時(shí)即可通過(guò)日志中的「Logic SQL」和「Actual SQL」觀(guān)察每一條 SQL 語(yǔ)句的路由情況，理解分庫分表的運行機制。

1. 模塊路徑

examples/shardingsphere-jdbc-example/sharding-example/sharding-raw-jdbc-example

2. 場(chǎng)景目標

本示例展示如何使用 YAML 配置 ShardingSphere-JDBC 的讀寫(xiě)分離功能。此次演示的場(chǎng)景是一個(gè)寫(xiě)庫 + 兩個(gè)讀庫的分離配置。

3. 運行準備

• 配置 META-INF/readwrite-splitting.yaml

• 將  jdbc-url  修改為自己的數據庫地址，并配置正確的用戶(hù)名密碼等信息

• 將  props.sql-show  屬性設置為   true

詳細配置說(shuō)明請閱讀配置手冊：

4. 啟動(dòng)運行

打開(kāi)啟動(dòng)類(lèi)： ShardingRawYamlConfigurationExample.java ，將  shardingType  設置為  ShardingType.READWRITE_SPLITTING ，并啟動(dòng)運行。

此時(shí)即可通過(guò)日志中的「Logic SQL」和「Actual SQL」觀(guān)察每一條 SQL 語(yǔ)句的路由情況，理解讀寫(xiě)分離的運行機制。

注意： 如果主從數據庫無(wú)法正常同步，將會(huì )發(fā)生查詢(xún)異常。

1. 模塊路徑：

examples/shardingsphere-jdbc-example/extension-example/custom-sharding-algortihm-example/class-based-sharding-algorithm-example

2. 場(chǎng)景目標

本示例展示如何使用  CLASS_BASED  方式進(jìn)行自定義算法擴展，讓 ShardingSphere-JDBC 在進(jìn)行分片路由時(shí)，使用用戶(hù)提供的算法來(lái)計算分片結果。此次演示的場(chǎng)景是使用自定義分片算法進(jìn)行分庫。

3. 運行準備

詳細配置說(shuō)明請閱讀配置手冊：

https://shardingsphere.apache.org/document/current/cn/user-manual/shardingsphere-jdbc/configuration/built-in-algorithm/sharding/

4. 啟動(dòng)運行

運行啟動(dòng)類(lèi)：

YamlClassBasedShardingAlgorithmExample.java

此時(shí)即可通過(guò)日志觀(guān)察分庫運行情況，并可以通過(guò) DEBUG 等方式檢查自定義算法的輸入輸出是否符合預期。

以上就是本次知識庫分享的全部?jì)热?。有關(guān) ShardingSphere-JDBC、ShardingSphere-Proxy 和 ShardingSphere-Parser 的示例將在未來(lái)繼續為大家分享。如果讀者有感興趣的場(chǎng)景需求，或是發(fā)現了新的問(wèn)題、新的提升點(diǎn)，歡迎在 GitHub issue 列表提出建議，也可提交 Pull Request 參與到開(kāi)源社區，為世界級的項目貢獻力量。

往期精彩請點(diǎn)擊原文鏈接。

歡迎掃碼關(guān)注我們