分片算法
cosid-sharding 保留了 4.x 的分片算法(D7),并随每个主版本发布。它们决定一个分片值落到哪张物理表或哪个数据库, 以及一次范围查询需要访问哪些表或库。该模块只依赖 cosid-core。
implementation("me.ahoo.cosid:cosid-sharding")public interface Sharding<T extends Comparable<? super T>> extends PreciseSharding<T>, RangeSharding<T> {
String sharding(T shardingValue); // 一个值 → 一个节点
Collection<String> sharding(ShardingRange<T> range); // 一个范围 → 它涉及的节点
Collection<String> getEffectiveNodes();
}ModCycle:取模分片
ModCycle<T extends Number> 将 value mod divisor 映射为 {prefix}{index}。范围只访问它覆盖的节点, 一旦跨越 divisor 个值,就访问全部节点。负数与其他值一样路由,因此没有下界的范围(atMost、lessThan)访问全部节点。 BigInteger 与 BigDecimal 范围不会被截断为 long:范围访问其中每个值所在的节点(BigDecimal 按整数部分路由,可能多一个)。

ModCycle<Long> orders = new ModCycle<>(4, "t_order_");
orders.sharding(10L); // t_order_2
orders.sharding(ShardingRange.closed(1L, 2L)); // [t_order_1, t_order_2]
orders.sharding(ShardingRange.atLeast(0L)); // 全部四个IntervalTimeline:时间区间分片
IntervalTimeline 将有效时间范围按 IntervalStep(一个 ChronoUnit 加一个数量)切分为若干区间。 每个区间是一个名为 {prefix}{suffix} 的节点,后缀由 DateTimeFormatter 格式化。查找节点靠算术计算,而非搜索。

IntervalTimeline logs = new IntervalTimeline("t_log_",
ShardingRange.closed(LocalDateTime.of(2026, 1, 1, 0, 0), LocalDateTime.of(2026, 12, 31, 23, 59)),
IntervalStep.of(ChronoUnit.MONTHS), DateTimeFormatter.ofPattern("yyyyMM"));
logs.sharding(LocalDateTime.of(2026, 10, 27, 12, 0)); // t_log_202610有效范围之外的值会被拒绝(IllegalArgumentException);有效范围之外的范围不对应任何节点。开放上界恰好落在某个区间的起点时 (按月的 closedOpen(2026-01-01, 2026-02-01)),该区间不含任何有效时间,因而不是有效节点。
转换器
区间算法对 LocalDateTime 分片。转换器将列值转换为 LocalDateTime:
| 转换器 | 接受 |
|---|---|
StandardLocalDateTimeConvertor(zone, isSecondTs, formatter) | LocalDateTime、ZonedDateTime、OffsetDateTime、Instant、LocalDate、Date(JDBC java.sql.Date 取其日期的零点,Timestamp 取其时刻)、YearMonth、Year、epoch Long(毫秒,isSecondTs 时为秒)、符合 formatter 格式的 String |
SnowflakeLocalDateTimeConvertor(layout, zone[, codec]) | Snowflake ID,Long 或文本(默认 62 进制、11 位、左侧补齐):经 Layout.unpack 得到其发号时间 |
因此按月分片的表可以只用 Snowflake ID 作为键:
var issued = new SnowflakeLocalDateTimeConvertor(Layout.SNOWFLAKE_MS, ZoneId.of("Asia/Shanghai"));
logs.sharding(issued.toLocalDateTime(orderId));CachedSharding
new CachedSharding<>(sharding) 缓存另一个算法的范围查询结果。缓存有上界:默认最多保存 10 000 个范围,满后自行清空, 因此查找不加锁。
算法返回的节点集合是只读的(add、remove、clear 抛出 UnsupportedOperationException):它们常常就是算法的有效节点或 缓存的范围结果,由所有调用方共享。需要修改时请先复制。
与 4.x 的差异
ShardingRange取代 Guava 的Range。它保留了 Guava 的工厂方法名(closed、open、closedOpen、openClosed、atLeast、atMost、greaterThan、lessThan、all、singleton)与语义,因此迁移只需改名。BoundType为me.ahoo.cosid.sharding.BoundType。SnowflakeLocalDateTimeConvertor接受Layout与时区,而不是SnowflakeIdStateParser。cosid-sharding不再依赖 Guava 或 Lombok。- ShardingSphere 自带基于 CosId 的算法;它们在 ShardingSphere 中维护,不在本项目。
