Apache ShardingSphere JDBC YAML 配置全解指南

Apache ShardingSphere JDBC YAML 配置全解指南

📌 核心配置结构概览

# 数据源配置 (必填)
dataSources: 
  <data_source_name>: 
    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
    url: jdbc:mysql://localhost:3306/db0
    username: root
    password: root
    # 其他连接池参数...

# 规则配置 (必填)
rules:
- !SHARDING # 分片规则
  # 分片规则配置...
- !READWRITE_SPLITTING # 读写分离规则
  # 读写分离配置...
- !ENCRYPT # 加密规则
  # 加密配置...

# 全局属性配置 (可选)
props:
  sql-show: true
  sql-simple: false
  executor-size: 20
  max-connections-size-per-query: 50

🔍 数据源配置详解

1. 基础数据源配置

dataSources:
  ds_0:
    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
    url: jdbc:mysql://127.0.0.1:3306/demo_ds_0?serverTimezone=UTC&useSSL=false
    username: root
    password: root
    connectionTimeout: 30000
    idleTimeout: 600000
    maxLifetime: 1800000
    maximumPoolSize: 50
    
  ds_1:
    dataSourceClassName: org.apache.commons.dbcp2.BasicDataSource
    url: jdbc:mysql://127.0.0.1:3306/demo_ds_1
    username: root
    password: root
    maxTotal: 50
    maxIdle: 10
    minIdle: 5

2. 数据源参数优化建议

参数	默认值	生产建议	说明
connectionTimeout	30s	5-10s	连接超时时间
idleTimeout	10m	5-10m	空闲连接超时
maxLifetime	30m	20-30m	连接最大生命周期
maximumPoolSize	50	CPU核数*2	最大连接数
minIdle	0	5-10	最小空闲连接数

⚙️ 分片规则配置精要

1. 标准分片配置

rules:
- !SHARDING
  # 分片表配置
  tables:
    t_order: 
      actualDataNodes: ds_${0..1}.t_order_${0..15} # 物理表分布
      databaseStrategy: # 分库策略
        standard:
          shardingColumn: user_id
          shardingAlgorithmName: database_inline
      tableStrategy: # 分表策略
        standard:
          shardingColumn: order_id
          shardingAlgorithmName: table_inline
      keyGenerateStrategy: # 主键生成
        column: order_id
        keyGeneratorName: snowflake
        
  # 分片算法配置
  shardingAlgorithms:
    database_inline:
      type: INLINE
      props:
        algorithm-expression: ds_${user_id % 2}
    table_inline:
      type: INLINE
      props:
        algorithm-expression: t_order_${order_id % 16}
        
  # 分布式序列算法
  keyGenerators:
    snowflake:
      type: SNOWFLAKE
      props:
        worker-id: 123

2. 高级分片算法类型

算法类型	适用场景	配置示例
INLINE	简单分片表达式	ds_${order_id % 64}
INTERVAL	按时间范围分片	datetime-interval: 30
HASH_MOD	哈希取模分片	sharding-count: 16
CLASS_BASED	自定义分片逻辑	strategy: com.example.CustomShard
COSID_MOD	高性能分布式序列分片	mod: 32

🔄 读写分离配置模板

1. 基础读写分离

rules:
- !READWRITE_SPLITTING
  dataSources:
    pr_ds: # 读写分离数据源名称
      type: Static # 静态数据源
      props:
        write-data-source-name: ds_primary # 写数据源
        read-data-source-names: ds_replica0, ds_replica1 # 读数据源
      loadBalancerName: round_robin # 负载均衡算法
      
  loadBalancers:
    round_robin:
      type: ROUND_ROBIN
    random:
      type: RANDOM
    weight:
      type: WEIGHT
      props:
        ds_replica0: 2
        ds_replica1: 1

2. 动态数据源发现

rules:
- !READWRITE_SPLITTING
  dataSources:
    dynamic_ds:
      type: Dynamic
      props:
        auto-aware-data-source-name: governance_ds # 注册中心数据源
        write-data-source-query-enabled: true

🔐 数据加密配置

1. 字段级加密配置

rules:
- !ENCRYPT
  tables:
    t_user:
      columns:
        phone:
          cipherColumn: phone_cipher
          assistedQueryColumn: phone_assisted # 辅助查询列
          encryptorName: aes_encryptor
        id_card:
          cipherColumn: id_card_cipher
          encryptorName: sm4_encryptor
          
  encryptors:
    aes_encryptor:
      type: AES
      props:
        aes-key-value: 123456abc
    sm4_encryptor:
      type: SM4
      props:
        sm4-key-value: 123456abcdef1234

2. 查询列类型选择

算法类型	特点	适用场景
CHAR_DIGEST_LIKE	MD5/SHA1哈希	模糊查询
MD5	标准MD5哈希	等值查询
SM3	国密SM3哈希	国内合规场景
CUSTOM	自定义算法	特殊业务需求

⚡ 全局属性配置

1. 核心性能参数

props:
  sql-show: true # 显示SQL日志
  sql-simple: false # 显示完整SQL
  executor-size: 20 # 执行线程池大小
  max-connections-size-per-query: 50 # 每查询最大连接数
  check-table-metadata-enabled: false # 启动时检查表元数据
  query-with-cipher-column: true # 使用密文列查询
  proxy-frontend-flush-threshold: 128 # 代理刷新阈值

2. 生产环境推荐配置

props:
  sql-show: false # 生产关闭SQL日志
  executor-size: $ {CPU核数} * 2
  max-connections-size-per-query: 100
  kernel-executor-size: 100 # 内核线程池大小
  proxy-backend-query-fetch-size: -1 # 流式获取
  proxy-frontend-executor-size: 128 # 前端线程数
  proxy-opentracing-enabled: true # 启用追踪

🧩 多规则组合配置

分片+读写分离+加密

rules:
- !SHARDING
  # 分片配置...
  
- !READWRITE_SPLITTING
  # 读写分离配置...
  
- !ENCRYPT
  # 加密配置...
  
- !MASK # 数据脱敏
  # 脱敏配置...
  
- !SHADOW # 影子库
  # 影子库配置...

🚨 配置最佳实践

1. 环境变量注入

dataSources:
  ds_0:
    url: ${DATASOURCE_URL:jdbc:mysql://localhost:3306/default}
    username: ${DATASOURCE_USER:root}
    password: ${DATASOURCE_PASSWORD:root}

2. 配置分模块管理

config/
├── datasources.yaml # 数据源配置
├── sharding.yaml    # 分片规则
├── rw-splitting.yaml # 读写分离
└── encrypt.yaml     # 加密规则

启动时合并配置：

bin/start.sh --config config/datasources.yaml \
             --config config/sharding.yaml \
             --config config/rw-splitting.yaml

3. 配置版本控制

# 版本标记
version: v2.3

# 变更记录
changelog:
  - version: v2.2
    date: 2023-06-01
    comment: 增加新分片表

🔧 调试与验证技巧

1. 配置校验命令

# 校验YAML语法
bin/validate-config.sh config.yaml

# 模拟执行计划
EXPLAIN SELECT * FROM t_order WHERE user_id=123;

2. 运行时配置查询

-- 查看分片规则
SHOW SHARDING TABLE RULES;

-- 查看读写分离规则
SHOW READWRITE_SPLITTING RULES;

-- 查看加密规则
SHOW ENCRYPT RULES;

3. 动态配置变更

-- 动态添加数据源
REGISTER STORAGE UNIT ds_2 (
  URL="jdbc:mysql://127.0.0.1:3306/ds_2",
  USER="root",
  PASSWORD="root"
);

-- 刷新元数据
REFRESH METADATA;

💎 总结：YAML配置核心要点

1. 模块化配置：数据源、规则、属性分离
2. 算法复用：命名算法多处引用
3. 环境适配：通过变量区分环境
4. 规则组合：灵活叠加多种数据治理能力
5. 动态治理：结合DistSQL实现配置热更新

最佳实践路径：
开发环境 → 使用完整SQL日志调试配置
测试环境 → 验证分片路由和算法正确性
生产环境 → 关闭敏感日志，优化连接参数