ShardingSphere-JDBC——配置手册序章-京东云开发者社区

配置是 ShardingSphere-JDBC 中唯一与应用开发者交互的模块，通过它可以快速清晰的理解 ShardingSphere-JDBC 所提供的功能。

本章节是 ShardingSphere-JDBC 的配置参考手册，需要时可当做字典查阅。

ShardingSphere-JDBC 提供了 4 种配置方式，用于不同的使用场景。 通过配置，应用开发者可以灵活的使用数据分片、读写分离、数据加密、影子库等功能，并且能够叠加使用。
# Java API
## 简介

Java API 是 ShardingSphere-JDBC 中所有配置方式的基础，其他配置最终都将转化成为 Java API 的配置方式。

Java API 是最复杂也是最灵活的配置方式，适合需要通过编程进行动态配置的场景下使用。

## 使用方式

### 创建简单数据源

通过 ShardingSphereDataSourceFactory 工厂创建的 ShardingSphereDataSource 实现自 JDBC 的标准接口 DataSource。

```java
// 构建数据源
Map<String, DataSource> dataSourceMap = // ...

// 构建配置规则
Collection<RuleConfiguration> configurations = // ...

// 构建属性配置
Properties props = // ...

DataSource dataSource = ShardingSphereDataSourceFactory.createDataSource(dataSourceMap, configurations, props);
```

### 创建携带治理功能的数据源

通过 GovernanceShardingSphereDataSourceFactory 工厂创建的 GovernanceShardingSphereDataSource 实现自 JDBC 的标准接口 DataSource。

```java
// 构建数据源
Map<String, DataSource> dataSourceMap = // ...

// 构建配置规则
Collection<RuleConfiguration> configurations = // ...

// 构建属性配置
Properties props = // ...

// 构建注册中心配置对象
GovernanceConfiguration governanceConfig = // ...

DataSource dataSource = GovernanceShardingSphereDataSourceFactory.createDataSource(dataSourceMap, configurations, props, governanceConfig);
```

### 使用数据源

可通过 DataSource 选择使用原生 JDBC，或JPA， MyBatis 等 ORM 框架。

以原生 JDBC 使用方式为例：

```java
DataSource dataSource = // 通过Apache ShardingSphere 工厂创建的数据源
String sql = "SELECT i.* FROM t_order o JOIN t_order_item i ON o.order_id=i.order_id WHERE o.user_id=? AND o.order_id=?";
try (
        Connection conn = dataSource.getConnection();
        PreparedStatement ps = conn.prepareStatement(sql)) {
    ps.setInt(1, 10);
    ps.setInt(2, 1000);
    try (ResultSet rs = preparedStatement.executeQuery()) {
        while(rs.next()) {
            // ...
        }
    }
}
```
# YAML 配置

## 简介

YAML 提供通过配置文件的方式与 ShardingSphere-JDBC 交互。配合治理模块一同使用时，持久化在配置中心的配置均为 YAML 格式。

YAML 配置是最常见的配置方式，可以省略编程的复杂度，简化用户配置。

## 使用方式

### 创建简单数据源

通过 YamlShardingSphereDataSourceFactory 工厂创建的 ShardingSphereDataSource 实现自 JDBC 的标准接口 DataSource。

```java
// 指定 YAML 文件路径
File yamlFile = // ...

DataSource dataSource = YamlShardingSphereDataSourceFactory.createDataSource(yamlFile);
```

### 创建携带治理功能的数据源

通过 YamlGovernanceShardingSphereDataSourceFactory 工厂创建的 GovernanceShardingSphereDataSource 实现自 JDBC 的标准接口 DataSource。

```java
// 指定 YAML 文件路径
File yamlFile = // ...

DataSource dataSource = YamlGovernanceShardingSphereDataSourceFactory.createDataSource(yamlFile);
```

### 使用数据源

可通过 DataSource 选择使用原生 JDBC，或JPA， MyBatis 等 ORM 框架。

以原生 JDBC 使用方式为例：

## YAML 配置项

### 数据源配置

分为单数据源配置和多数据源配置。
单数据源配置用于数据加密规则；多数据源配置用于分片、读写分离等规则。
如果加密和分片等功能混合使用，则应该使用多数据源配置。

#### 单数据源配置

##### 配置示例

```yaml
dataSource: !!org.apache.commons.dbcp2.BasicDataSource
  driverClassName: com.mysql.jdbc.Driver
  url: jdbc:mysql://127.0.0.1:3306/ds_name
  username: root
  password: root
```

##### 配置项说明

```yaml
dataSource: # <!!数据库连接池实现类> `!!`表示实例化该类
  driverClassName: # 数据库驱动类名
  url: # 数据库 URL 连接
  username: # 数据库用户名
  password: # 数据库密码
  # ... 数据库连接池的其它属性
```

#### 多数据源配置

##### 配置示例

```yaml
dataSources:
  ds_0: !!org.apache.commons.dbcp2.BasicDataSource
    driverClassName: org.h2.Driver
    url: jdbc:h2:mem:ds_0;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MYSQL
    username: sa
    password:
  ds_1: !!org.apache.commons.dbcp2.BasicDataSource
    driverClassName: org.h2.Driver
    url: jdbc:h2:mem:ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MYSQL
    username: sa
    password:
```

##### 配置项说明

```yaml
dataSources: # 数据源配置，可配置多个 <data-source-name>
  <data-source-name>: # <!!数据库连接池实现类>，`!!` 表示实例化该类
    driverClassName: # 数据库驱动类名
    url: # 数据库 URL 连接
    username: # 数据库用户名
    password: # 数据库密码
    # ... 数据库连接池的其它属性
```

### 规则配置

以规则别名开启配置，可配置多个规则。

#### 配置示例

```yaml
rules:
-! XXX_RULE_0
  xxx
-! XXX_RULE_1
  xxx
```

#### 配置项说明

```yaml
rules:
-! XXX_RULE # 规则别名，`-` 表示可配置多个规则
  # ... 具体的规则配置
```

更多详细配置请参见具体的规则配置部分。

### 属性配置

#### 配置示例

```yaml
props:
  xxx: xxx
```

#### 配置项说明

```yaml
props:
  xxx: xxx # 属性名称以及对应的值
```

更多详细配置请参见具体的规则配置部分。

### 语法说明

`!!` 表示实例化该类

`!` 表示自定义别名

`-` 表示可以包含一个或多个

`[]` 表示数组，可以与减号相互替换使用
# SPRING BOOT STARTER 配置

## 简介

ShardingSphere-JDBC 提供官方的 Spring Boot Starter，使开发者可以非常便捷的整合 ShardingSphere-JDBC 和 Spring Boot。

## 数据源配置

```properties
spring.shardingsphere.datasource.names= # 数据源名称，多数据源以逗号分隔

spring.shardingsphere.datasource.<datasource-name>.url= # 数据库 URL 连接
spring.shardingsphere.datasource.<datasource-name>.type=  # 数据库连接池类名称
spring.shardingsphere.datasource.<datasource-name>.driver-class-name= # 数据库驱动类名
spring.shardingsphere.datasource.<datasource-name>.username= # 数据库用户名
spring.shardingsphere.datasource.<datasource-name>.password= # 数据库密码
spring.shardingsphere.datasource.<datasource-name>.xxx=  # 数据库连接池的其它属性
```

## 规则配置

```properties
spring.shardingsphere.rules.<rule-type>.xxx= # 规则配置
  # ... 具体的规则配置
```

更多详细配置请参见具体的规则配置部分。

## 属性配置

```properties
spring.shardingsphere.props.xxx.xxx= # 具体的属性配置
```

详情请参见[属性配置](/cn/user-manual/shardingsphere-jdbc/configuration/props)。
# SPRING 命名空间配置

## 简介

ShardingSphere-JDBC 提供官方的 Spring 命名空间配置，使开发者可以非常便捷的整合 ShardingSphere-JDBC 和 Spring 框架。

## Spring 命名空间配置项

### 配置示例

```xml
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:shardingsphere="http://shardingsphere.apache.org/schema/shardingsphere/datasource"
       xsi:schemaLocation="http://www.springframework.org/schema/beans 
                           http://www.springframework.org/schema/beans/spring-beans.xsd 
                           http://shardingsphere.apache.org/schema/shardingsphere/datasource
                           http://shardingsphere.apache.org/schema/shardingsphere/datasource/datasource.xsd
                           ">
    <bean id="ds0" class="org.apache.commons.dbcp2.BasicDataSource" destroy-method="close">
        <property name="driverClassName" value="com.mysql.jdbc.Driver" />
        <property name="url" value="jdbc:mysql://localhost:3306/ds0" />
        <property name="username" value="root" />
        <property name="password" value="" />
    </bean>
    
    <bean id="ds1" class="org.apache.commons.dbcp2.BasicDataSource" destroy-method="close">
        <property name="driverClassName" value="com.mysql.jdbc.Driver" />
        <property name="url" value="jdbc:mysql://localhost:3306/ds1" />
        <property name="username" value="root" />
        <property name="password" value="" />
    </bean>
    
    
    
    
    <shardingsphere:data-source id="shardingDataSource" data-source-names="ds0,ds1" rule-refs="..." >
        <props>
            <prop key="xxx.xxx">${xxx.xxx}</prop>
        </props>
    </shardingsphere:data-source>
</beans>
```

### 配置项说明

命名空间：[http://shardingsphere.apache.org/schema/shardingsphere/datasource/datasource-5.0.0.xsd](http://shardingsphere.apache.org/schema/shardingsphere/datasource/datasource-5.0.0.xsd)

\<shardingsphere:data-source />

| *名称*            | *类型* | *说明*                       |
| ----------------- | ----- | --------------------------- |
| id                | 属性  | Spring Bean Id               |
| data-source-names | 标签  | 数据源名称，多个数据源以逗号分隔 |
| rule-refs         | 标签  | 规则名称，多个规则以逗号分隔     |
| props (?)         | 标签  | 属性配置，详情请参见[属性配置](/cn/user-manual/shardingsphere-jdbc/configuration/props) |