企业官网建设流程全解析

本文基于ShardingSphere5.3.2 稳定版，手把手讲解 SpringBoot 完整整合流程，包含环境适配、依赖引入、数据库搭建、全量配置、代码实战、核心功能讲解及生产踩坑方案，所有代码可直接复制上线使用。

一、技术栈版本适配（避坑核心）

ShardingSphere5 对框架版本有严格适配要求，版本混用会直接导致启动报错、分片失效，新手务必严格对照以下适配组合：

• SpringBoot2.x 适配组合：SpringBoot2.7.x + ShardingSphere5.3.2 + MySQL8.0 + MyBatis-Plus3.5.x

• SpringBoot3.x 适配组合：SpringBoot3.2.x + ShardingSphere5.5.x + JDK17 + MySQL8.0

• 核心说明：ShardingSphere5 彻底废弃4.x旧依赖包名，统一使用shardingsphere-jdbc-core-spring-boot-starter，新旧依赖不可混用

二、项目依赖引入（Maven）

新建或打开已有 SpringBoot 项目，在 pom.xml 中引入核心依赖，本文提供生产通用稳定配置，包含分片核心、数据库驱动、持久层框架全套依赖。

2.1 SpringBoot2.x 完整依赖

<!-- SpringBoot Web基础 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- ShardingSphere5 分片核心依赖 --> <dependency> <groupId>org.apache.shardingsphere</groupId> <artifactId>shardingsphere-jdbc-core-spring-boot-starter</artifactId> <version>5.3.2</version> </dependency> <!-- MySQL8驱动 --> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency> <!-- MyBatis-Plus 持久层框架 --> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>3.5.3.1</version> </dependency> <!-- Lombok 简化代码 --> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency>

2.2 SpringBoot3.x 适配调整

SpringBoot3 项目只需修改 ShardingSphere 版本，其余依赖通用，适配最新特性：

<version>5.5.0</version>

三、数据库环境准备（2库4表实战场景）

本次实战采用企业最常用的水平分库分表方案，模拟订单大数据量场景：搭建2个数据库，每个数据库包含2张结构一致的订单表，实现数据均匀分片存储。

3.1 创建分片数据库

新建两个独立数据库，统一编码为 utf8mb4，适配全字符集：

CREATE DATABASE IF NOT EXISTS order_db0 DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE DATABASE IF NOT EXISTS order_db1 DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

3.2 批量创建分片数据表

order_db0、order_db1 两个库中，分别创建 t_order_0、t_order_1 两张分片表，四张物理表结构完全一致：

-- 切换数据库 order_db0 USE order_db0; CREATE TABLE IF NOT EXISTS t_order_0 ( id BIGINT COMMENT '分布式唯一主键', user_id BIGINT NOT NULL COMMENT '分片键-用户ID', order_no VARCHAR(32) NOT NULL COMMENT '订单编号', amount DECIMAL(10,2) COMMENT '订单金额', create_time DATETIME DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_user_id(user_id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; CREATE TABLE IF NOT EXISTS t_order_1 LIKE t_order_0; -- 切换数据库 order_db1 执行相同建表语句 USE order_db1; CREATE TABLE IF NOT EXISTS t_order_0 LIKE t_order_0; CREATE TABLE IF NOT EXISTS t_order_1 LIKE t_order_0;

四、ShardingSphere5 核心配置（application.yml）

ShardingSphere5 所有规则统一配置在spring.shardingsphere节点下，摒弃了4.x混乱的配置方式，支持行表达式简化多库多表配置。本次配置实现user_id 取模分库+取模分表，搭配雪花算法分布式ID，全程零代码侵入。

4.1 完整可运行配置文件

spring: # ShardingSphere5 分片核心配置 shardingsphere: # 多数据源配置 datasource: names: ds0,ds1 # 第一个分片库 order_db0 ds0: type: com.zaxxer.hikari.HikariDataSource driver-class-name: com.mysql.cj.jdbc.Driver jdbc-url: jdbc:mysql://127.0.0.1:3306/order_db0?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true username: root password: 你的数据库密码 # 第二个分片库 order_db1 ds1: type: com.zaxxer.hikari.HikariDataSource driver-class-name: com.mysql.cj.jdbc.Driver jdbc-url: jdbc:mysql://127.0.0.1:3306/order_db1?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true username: root password: 你的数据库密码 # 分片规则配置 rules: sharding: # 逻辑表分片规则 tables: # 业务操作逻辑表名（无需真实存在） t_order: # 匹配所有物理数据节点 actual-data-nodes: ds$->{0..1}.t_order_$->{0..1} # 分库策略 database-strategy: standard: sharding-column: user_id sharding-algorithm-name: order-mod-inline # 分表策略 table-strategy: standard: sharding-column: user_id sharding-algorithm-name: order-mod-inline # 分布式主键策略 key-generate-strategy: column: id key-generator-name: snowflake # 分片算法定义 sharding-algorithms: order-mod-inline: type: INLINE props: # 取模分片算法：user_id % 2 algorithm-expression: $->{user_id % 2} # 分布式ID生成器 key-generators: snowflake: type: SNOWFLAKE props: worker-id: 1 # 单机固定1，集群需保证节点唯一 # 全局参数配置 props: sql-show: true # 开启SQL日志打印，查看分片路由详情 # MyBatis-Plus基础配置 mybatis-plus: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.sharding.entity configuration: map-underscore-to-camel-case: true

4.2 核心配置逐行解析

• datasource.names：声明所有分片数据源别名，多个用逗号分隔

• actual-data-nodes：行表达式批量匹配所有物理库表，无需逐个手动配置，简洁高效

• standard标准分片策略：适用于单分片键场景，支持等值查询、IN查询精准路由

• INLINE行表达式算法：新手首选，基于取模、范围规则分片，维护成本最低

• snowflake分布式ID：全局唯一主键，彻底解决多库自增ID重复问题

• sql-show=true：控制台打印真实路由SQL，是调试分片规则的核心利器

五、业务代码实战（零侵入CRUD）

Sharding-JDBC 最大优势就是业务代码零侵入，整合完成后，原有 MyBatis、MyBatis-Plus 写法完全不变，只需操作逻辑表，中间件自动完成SQL解析、路由、数据聚合。

5.1 订单实体类

实体类只需标注逻辑表名，主键设置为雪花算法自动生成：

package com.sharding.entity; import com.baomidou.mybatisplus.annotation.IdType; import com.baomidou.mybatisplus.annotation.TableId; import com.baomidou.mybatisplus.annotation.TableName; import lombok.Data; import java.math.BigDecimal; import java.time.LocalDateTime; @Data @TableName("t_order") // 对应配置中的逻辑表 public class TOrder { // 雪花算法自动生成分布式ID @TableId(type = IdType.ASSIGN_ID) private Long id; // 分片键 private Long userId; // 订单编号 private String orderNo; // 订单金额 private BigDecimal amount; // 创建时间 private LocalDateTime createTime; }

5.2 Mapper接口

package com.sharding.mapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.sharding.entity.TOrder; import org.apache.ibatis.annotations.Mapper; @Mapper public interface OrderMapper extends BaseMapper<TOrder> { }

5.3 测试接口（验证分片路由）

编写测试接口，插入不同 userId 的订单数据，验证自动分片路由：

package com.sharding.controller; import com.sharding.entity.TOrder; import com.sharding.mapper.OrderMapper; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import javax.annotation.Resource; import java.math.BigDecimal; @RestController @RequestMapping("/order") public class OrderController { @Resource private OrderMapper orderMapper; @GetMapping("/add") public String addOrder() { // userId=1 1%2=1 路由至 ds1.t_order_1 TOrder order1 = new TOrder(); order1.setUserId(1L); order1.setOrderNo("ORD20260712001"); order1.setAmount(new BigDecimal("89.90")); orderMapper.insert(order1); // userId=2 2%2=0 路由至 ds0.t_order_0 TOrder order2 = new TOrder(); order2.setUserId(2L); order2.setOrderNo("ORD20260712002"); order2.setAmount(new BigDecimal("129.90")); orderMapper.insert(order2); return "分片数据插入成功！查看控制台路由日志"; } }

六、项目启动与结果验证

6.1 启动项目

启动 SpringBoot 项目，无报错即代表 ShardingSphere 整合成功，数据源、分片规则加载完成。

6.2 接口测试

访问接口http://localhost:8080/order/add，查看控制台SQL日志，可清晰看到：

1. userId=1 的数据插入ds1.t_order_1

2. userId=2 的数据插入ds0.t_order_0

业务层无需感知多库多表，完全由 ShardingSphere 自动完成分片路由，整合生效。

七、常用扩展功能配置

7.1 单库分表配置（轻量化方案）

若仅需解决单表数据量大问题，无需分库，可简化为单库多表配置，仅保留一个数据源即可，适配中小数据量场景。

7.2 广播表配置（解决跨库关联）

字典表、配置表等小表，可配置为广播表，自动同步到所有分片库，解决跨库JOIN查询问题，只需在sharding规则中新增广播表配置即可。

八、生产环境高频踩坑总结

8.1 启动报错：依赖版本不兼容

问题原因：SpringBoot3 搭配低版本 ShardingSphere5.3.x，存在自动配置冲突

解决方案：SpringBoot3 统一使用 5.5.0 及以上版本，SpringBoot2 稳定使用5.3.2

8.2 查询无数据、路由异常

问题原因：查询SQL未携带分片键，触发全库全表广播查询，性能极差且数据错乱

解决方案：业务查询强制携带分片键，禁止无分片键全量查询

8.3 主键重复、插入失败

问题原因：未关闭数据库自增，未配置雪花算法ID

解决方案：实体类主键使用 ASSIGN_ID，yml 开启雪花算法生成策略

8.4 控制台无SQL日志

解决方案：确认sql-show: true配置生效，排查日志级别配置