ShardingSphere 分片附录详解

ShardingSphere 分片附录详解

本附录提供分片功能的核心参考指南，包含算法表达式、配置项说明及最佳实践参数。以下为系统化总结：

---

一、分片算法表达式语法手册

1. 行表达式语法（Inline Sharding）

// 基础占位符
${begin..end}      // 范围区间
${[enum1, enum2]}  // 枚举值
${expression}      // Groovy表达式

// 分库分表组合
ds_${user_id % 4}.t_order_${order_date.getYear()}_${order_id % 16}

2. 时间函数扩展

// 支持Java日期API
tbl_${new java.text.SimpleDateFormat("yyyyMM").format(create_time)}

// 时间偏移计算
tbl_${create_time.getTime() + 30 * 24 * 3600 * 1000}

3. 复合表达式

// 条件分支
${order_id > 10000 ? 'hist' : 'curr'}_${user_id % 8}

// 安全处理
${(user_id ?: 0) % 16} // 防NPE

---

二、分片配置项全集

1. 分片规则配置项

sharding:
  tables:
    t_order:
      actualDataNodes: ds_${0..3}.t_order_${0..15}  # 物理节点
      databaseStrategy: # 分库策略
        standard:
          shardingColumn: user_id
          shardingAlgorithmName: db_mod
        complex: # 复合策略
          shardingColumns: region,user_type
          shardingAlgorithmName: composite_algo
        hint: # Hint策略
          shardingAlgorithmName: hint_algo
      tableStrategy: ... # 同databaseStrategy结构
      keyGenerateStrategy: # 主键生成
        column: order_id
        keyGeneratorName: snowflake

2. 分片算法参数表

算法类型	配置项	必填	说明
MOD	sharding-count	✅	分片数量
HASH_MOD	sharding-count	✅	分片数量
VOLUME_RANGE	range-lower	✅	范围下界
	range-upper	✅	范围上界
	sharding-volume	✅	分片容量
INTERVAL	datetime-pattern	✅	时间格式(yyyy-MM)
	datetime-lower	✅	最小时间
	datetime-upper	⚠️	最大时间(可选)
	sharding-suffix-pattern	✅	分片后缀格式(yyyyMM)
	datetime-interval-unit	✅	时间单位(DAY/MONTH)

3. 分布式序列参数

类型	配置项	默认值	说明
SNOWFLAKE	worker-id	0	工作机器ID (0~1023)
	max-vibration-offset	1	最大时间回退容忍毫秒数
	max-tolerate-time-difference	0	最大时钟偏差容忍毫秒数
UUID	-	-	无参数

---

三、Hint强制路由指令集

1. SQL Hint语法

/* ShardingSphere hint: sharding-database-value=123 */
SELECT * FROM t_order;

/* 多值指定 */
/* ShardingSphere hint: sharding-table-value=5, sharding-database-value=2 */

2. 编程API（Java）

// 设置分片值
try (HintManager hintManager = HintManager.getInstance()) {
    hintManager.setDatabaseShardingValue(123L); 
    hintManager.addTableShardingValue("t_order", 5);
    jdbcTemplate.query("SELECT * FROM t_order", ...);
}

// 清除分片上下文
HintManager.clear();

---

四、弹性伸缩操作命令

1. DistSQL 扩容语法

-- 添加新数据源
ADD RESOURCE ds_4 (
  URL="jdbc:mysql://127.0.0.1:3306/ds_4",
  USER=root,
  PASSWORD=root,
  PROPERTIES("maxPoolSize"=50)
);

-- 修改分片规则
ALTER SHARDING TABLE RULE t_order (
  RESOURCES(ds_0,ds_1,ds_2,ds_3,ds_4),
  SHARDING_COLUMN=user_id,
  TYPE(NAME=mod, PROPERTIES("sharding-count"=5))
);

-- 启动数据迁移
START MIGRATION JOB BY TYPE (name=sharding_scaling, props=...);

2. 迁移状态监控

SHOW SCALING LIST;                     -- 查看任务列表
SHOW SCALING STATUS {jobId};           -- 检查进度
STOP SCALING {jobId};                  -- 停止任务

---

五、性能调优参数表

props:
  # 连接池配置
  max-connections-size-per-query: 1    # 每查询最大连接数
  kernel-executor-size: 16             # 执行线程数
  
  # 查询优化
  proxy-frontend-executor-size: 8      # Proxy前端线程数
  proxy-backend-query-fetch-size: 1000 # 结果集分批大小
  
  # 事务控制
  xa-transaction-manager-type: Atomikos # XA实现选择
  xa-recovery-interval-seconds: 60     # 恢复间隔
  
  # 日志配置
  sql-show: true                       # 显示逻辑SQL
  sql-simple: false                    # 简化日志输出

---

六、分片元数据查询SQL

1. 规则查询

-- 查看分片表规则
SHOW SHARDING TABLE RULES [FROM schemaName];

-- 检查分片算法
SHOW SHARDING ALGORITHMS;

-- 查询绑定表
SELECT * FROM information_schema.SHARDING_BINDING_TABLES;

2. 运行时状态

-- 当前数据源状态
SHOW INSTANCE LIST; 

-- 分片节点流量
SELECT * FROM information_schema.SHARDING_TABLE_STATISTICS;

---

七、错误代码速查表

错误码	类别	原因	解决方案
10000	配置错误	分片算法未定义	检查shardingAlgorithms配置
11000	SQL解析错误	不支持WITH子句	重写SQL语句
12000	执行异常	跨分片DML未启用分布式事务	添加@GlobalTransactional注解
13010	分布式主键冲突	worker-id重复	检查集群worker-id分配
14020	弹性伸缩失败	源数据源连接超时	验证网络连通性

---

八、版本兼容性矩阵

功能	5.0	5.1	5.2	5.3
自定义分片算法	✅	✅	✅	✅
DistSQL动态配置	❌	✅	✅	✅
异构存储支持	❌	⚠️	✅	✅
Kubernetes Operator	❌	❌	✅	✅

升级注意：

• 4.x → 5.x 需重写分片配置（YAML结构调整）
• 分布式序列SNOWFLAKE实现不兼容（需数据迁移）

本附录为分片功能的权威参考，建议结合官方配置手册进行实践验证。