简介：这是一份围绕 Spring Boot、Spring Cloud、Nacos、Gateway 与 MyBatis 五大组件搭建完整微服务架构的实战资源，定位为 Java 开发者学习分布式系统的入门到进阶参考资料。资源以可运行示例工程演示服务注册发现、统一网关路由、配置中心管理及数据库持久化等核心环节，项目按模块拆分，便于理解微服务之间的协作方式与分层边界。
压缩包共 71 个文件，以 java 源码、class 编译产物、xml 映射与配置、yml 配置清单为主体，附带 sql 初始化脚本、jar 依赖及 properties 配置文件，整体仅 53KB，结构轻量、便于本地直接导入复现。目录按 user-service、gateway、product-service、feign-api 等模块组织，从网关入口到业务服务再到数据访问均有对应实现，适合对照学习微服务拆分粒度与模块间调用关系。
已有 2419 人学习下载。对准备入职或正在做毕设的 Java 开发者而言，这份资源可直接作为脚手架模板，结合源码理解各组件在真实项目中的职责边界，节省从零搭建环境与排查整合问题的时间，也能为后续扩展分布式组件提供可对照的起点。
1. 微服务套件装进本地：版本矩阵才是最大的坑
一套 SpringBoot + SpringCloud + Nacos + Gateway + MyBatis 的微服务骨架，是整个 Java 后端最常见的落地方案，几乎每个公司都要搭一遍。但真正动手时你会发现，代码写得再漂亮，也扛不住 SpringBoot 和 SpringCloud 版本对不上——启动三秒就报错，报错信息还全是 Bean 找不到、依赖循环这类看不懂的黑话，翻半天文档才发现是版本矩阵选错了。
这不是个例，我接手过好几个项目翻车都是同一个原因：要么 SpringBoot 升到了 2.7 却配了 Hoxton 的 Cloud，要么 Nacos 用了 2.x 但没开 9848 端口，要么 Gateway 模块里手滑引了 web 包导致端口冲突。这套环境的复杂度不在业务代码里，而在版本对应关系和注册中心的启动配置上。这篇文章把版本选型、Nacos 安装、父工程搭建、Gateway 路由配置、MyBatis 接入和验证链路从头走一遍，适合正在搭第一批微服务模块的开发者，也适合被版本问题卡住想换一套稳妥组合的人。
2. 先把底座备齐：JDK、Maven 与 Nacos 的环境选型和启动
2.1 JDK 与 Maven 版本选型：先定坐标再写代码
搭建微服务环境的第一步不是打开 IDE 写代码，而是先把 JDK、Maven 和 Nacos 的版本定死。微服务的基础环境一旦版本不匹配，后续所有服务都会受影响，尤其是 SpringBoot 与 SpringCloud 的版本依赖关系，必须先确定组合再动工。
推荐一套经过验证的稳定组合：JDK 1.8、Maven 3.6.3、SpringBoot 2.3.12.RELEASE、SpringCloud Hoxton.SR12、SpringCloud Alibaba 2.2.5.RELEASE、Nacos 2.2.3。JDK 1.8 依旧是微服务项目的主流选择，虽然更高版本的 JDK 也能跑，但很多公司的存量依赖和 MyBatis 插件对 JDK 8 的支持最稳定，不必在基础环境上冒险。
Maven 安装完成后需要检查镜像源配置，国内网络环境下建议在settings.xml中配置阿里云镜像，否则下载 SpringCloud Alibaba 依赖时会非常慢，甚至超时失败。
<mirror> <id>aliyunmaven</id> <mirrorOf>*</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> </mirror>这段配置写在 Maven 安装目录conf/settings.xml的<mirrors>节点内。mirrorOf设为*表示所有仓库请求都走阿里云镜像，url指向阿里云公共仓库，它聚合了 Maven Central 和 JCenter 的制品。配置完成后用mvn -v验证 Maven 版本号是否正常输出，再用一个空项目执行mvn dependency:resolve测试依赖下载是否顺畅。
2.2 下载并启动 Nacos：单机模式下的两个启动参数
Nacos 在这里同时承担注册中心和配置中心两个角色，是整套微服务体系最先启动的组件。去 Nacos 官方 GitHub Releases 页面下载nacos-server-2.2.3.tar.gz，解压后进入bin目录，Linux 环境直接执行启动脚本：
# Linux / macOS 单机模式启动（注意是 startup 不是 start） sh startup.sh -m standalone # Windows 环境用 startup.cmd -m standalone-m standalone参数指定单机模式启动。Nacos 默认以集群模式读取配置，不加这个参数会一直尝试寻找集群节点并反复报错。启动完成后观察日志，出现Nacos started successfully就代表启动成功。
Nacos 2.x 版本启动后默认监听 8848 端口提供控制台和 HTTP API，但同时还会监听 9848 端口用于 gRPC 通信，这是 2.x 与 1.x 的核心差异之一。如果服务器有防火墙或运行在云主机上，只放行 8848 会导致客户端连接超时，需要同时放行 8848 和 9848。
启动后访问http://localhost:8848/nacos，默认账号密码都是nacos，登录后能看到服务列表、配置列表等管理界面。这个控制台在后面排查服务注册问题时非常有用，服务是否上线、配置是否加载成功都一目了然。
2.3 验证 Nacos 控制台：确认注册中心与配置中心就绪
Nacos 启动后不要急着开始写工程代码，先做两个快速验证，确认底座是好的。
第一个验证是打开控制台页面，确认登录成功且左侧菜单完整；第二个验证是确认 9848 端口在监听，执行netstat -an | grep 9848，如果只看到 8848 而看不到 9848，说明 Nacos 2.x 的 gRPC 端口未正常监听，需要检查是否为端口冲突。这两个验证都通过后，注册中心和配置中心才算真正就绪，后续任何服务注册不上、配置拉不到的问题都可以优先怀疑依赖配置而不是 Nacos 本身。
3. 搭建父工程与公共模块：用一套坐标锁死所有版本
3.1 父工程 pom：dependencyManagement 统一锁定关键坐标
微服务项目通常采用多模块结构，父工程只做依赖版本管理，不写业务代码。在父 pom 中通过dependencyManagement锁定 SpringBoot、SpringCloud、SpringCloud Alibaba 三大组件的版本，子模块引入依赖时就不必再写版本号，这能从根本上避免多个服务版本不一致的问题。
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.3.12.RELEASE</version> <relativePath/> </parent> <properties> <spring-cloud.version>Hoxton.SR12</spring-cloud.version> <spring-cloud-alibaba.version>2.2.5.RELEASE</spring-cloud-alibaba.version> <mybatis-starter.version>2.1.4</mybatis-starter.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-dependencies</artifactId> <version>${spring-cloud.version}</version> <type>pom</type> <scope>import</scope> </dependency> <dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-alibaba-dependencies</artifactId> <version>${spring-cloud-alibaba.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>这段配置的核心是import方式的依赖管理。SpringCloud 和 SpringCloud Alibaba 都发布了统一的 BOM（Bill of Materials）包，通过<scope>import</scope>引入后，相当于把这两个体系管理的所有组件版本都纳入了当前工程的版本约束范围。注意 SpringCloud Alibaba 2.2.5.RELEASE 对应的是 Nacos 1.4.x 客户端，但服务端用 2.2.3 依然兼容良好，这是社区验证过最广泛使用的组合。
父 pom 的packaging要设置为pom，否则构建时会报类型错误。子模块的parent指向这个父工程后，只需声明groupId和artifactId，版本号自动沿用父工程的定义。
3.2 公共 API 模块：把实体类和 Feign 接口单独抽一层
公共模块common-api的职责是存放各服务共享的实体类、统一返回体和 Feign 调用接口。这个模块不启动任何服务，只提供依赖引用。抽取公共模块有几个实际好处：实体类统一管理避免多个服务重复定义、Feign 接口与实现分离让服务间调用解耦、序列化字段不一致导致的数据错乱从源头消除。
<artifactId>common-api</artifactId> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <optional>true</optional> </dependency> </dependencies><optional>true</optional>表示这个 web 依赖不会被传递到引用方，因为 common-api 被业务服务引用时，业务服务自身已经带了 web 或 webflux 依赖，避免重复引入造成冲突。在 common-api 中定义统一返回体Result<T>，包含code、message、data三个字段，提供success()和error()静态工厂方法，所有微服务接口都返回这个结构，前端解析逻辑统一，排查问题也方便。
3.3 在 Nacos 里预建配置文件：dataId 规则与数据库配置
把配置放在 Nacos 而不是本地application.yml中，是微服务配置中心的核心价值。Nacos 的配置管理遵循dataId规则，格式为${spring.application.name}-${profile}.${file-extension}，例如user-service-dev.yaml。服务启动时会根据应用名和激活的 profile 自动拉取对应配置。
在 Nacos 控制台的配置列表页面新增一条配置，dataId填user-service-dev.yaml，group保持DEFAULT_GROUP，配置内容为：
spring: datasource: url: jdbc:mysql://localhost:3306/micro_user?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.demo.common.entityserverTimezone=Asia/Shanghai是连接 MySQL 8 的必备参数，不设置会报时区错误。mapper-locations指定 XML 文件位置，type-aliases-package让 MyBatis 能直接使用实体类短类名作为参数和返回值类型，避免在 XML 中写全限定类名。这里把数据库和 MyBatis 配置放在 Nacos 中管理，环境切换时只需在 Nacos 上调整配置而无需重新打包。
4. 避坑手册：微服务启动阶段最容易翻车的几个点
4.1 SpringBoot 与 SpringCloud 版本错配导致 Bean 找不到
现象：项目启动时抛出IllegalStateException或BeanCreationException，日志提示找不到某个自动配置类，比如GatewayAutoConfiguration或NacosDiscoveryAutoConfiguration，控制台没有具体原因，业务代码一行没写也会启动失败。
原因：SpringBoot 和 SpringCloud 版本没有按官方对应关系搭配。SpringBoot 2.3.x 对应 SpringCloud Hoxton，SpringBoot 2.4 开始对应 2020.0.x 新版本号体系。如果 SpringBoot 用了 2.7 而 Cloud 还停留在 Hoxton，由于内部 API 变更，大量自动配置类无法装配。
解决：最稳妥的做法是强制固定版本组合。SpringBoot 2.3.x 配 Hoxton.SR12，SpringBoot 2.4.x 到 2.7.x 配 2021.0.x。我在搭建环境时会把版本组合写进父 pom 的properties中并加注释说明，防止后续维护者升级时把组合改乱。
4.2 Nacos 2.x 客户端连接超时：除了 8848 还有 9848
现象：服务启动日志显示 Nacos 注册中心连接成功，但实际服务列表始终为空，或者注册请求反复重试，报Client not connected, current status: STARTING的错误。控制台能打开但客户端连不上。
原因：Nacos 2.x 引入了 gRPC 通信，客户端注册、心跳、配置推送都走 9848 端口，只有 HTTP API 走 8848。很多环境只放行了 8848，服务端日志没有报错，但客户端连接一直卡在握手阶段，表现就是“注册好像成功了但列表里根本没有”。
解决：服务器安全组或防火墙同时放开 8848 和 9848，并确认 9848 端口未被占用。本地开发环境如果是修改过 Nacos 默认端口的，还要在客户端配置里同步修改spring.cloud.nacos.discovery.port对应的 gRPC 偏移量。
4.3 Gateway 模块误引 spring-boot-starter-web 导致启动冲突
现象：Gateway 服务启动时出现Spring MVC found on classpath, which is incompatible with Spring Cloud Gateway的报错，或者网关启动成功后所有路由都不生效，访问 API 直接 404。
原因：Gateway 基于 Spring WebFlux 实现，而spring-boot-starter-web引入的是 Spring MVC。两者同时存在于 classpath 时，容器初始化会冲突，Gateway 的自动配置被跳过或覆盖。
解决：Gateway 模块不要引入spring-boot-starter-web或spring-boot-starter-webmvc，只用spring-cloud-starter-gateway。如果网关模块需要调用其他服务接口，用 WebClient 而不是 RestTemplate。
4.4 MyBatis 扫不到 Mapper 接口：@MapperScan 位置放错
现象：Mapper 接口和 XML 文件都写好了，运行时报Invalid bound statement (not found)，代码编译正常但 MyBatis 找不到对应的 SQL。
原因：@MapperScan注解扫描的包路径不对，或者没有加这个注解。MyBatis 的 XML 文件路径与接口全限定名不对应时，也会出现同样的异常。
解决：启动类上使用@MapperScan("com.demo.user.mapper")明确指定 Mapper 接口所在的包。同时保证 XML 文件在resources/mapper/目录下，且 XML 的namespace必须与接口全限定名保持一致。如果用了 Nacos 管理 MyBatis 配置，还要确认mybatis.mapper-locations配置确实被加载了。
4.5 Feign 调用报 LoadBalancer 找不到：Ribbon 已被移除
现象：服务引入 OpenFeign 后编译通过，但运行时报java.lang.IllegalStateException: No Feign Client for loadBalancing defined或LoadBalancerClient not found。
原因：SpringCloud 2020 版本起 Ribbon 被移除，OpenFeign 需要显式引入spring-cloud-starter-loadbalancer才能获得负载均衡能力。旧教程大多只加 OpenFeign 依赖，导致新版本无法初始化。
解决：在调用方服务的 pom 中同时引入 OpenFeign 和 LoadBalancer 两个依赖。Hoxton 版本则不需要额外引入。这个坑在版本升级时极为常见，凡是 OpenFeign 调用失败先检查依赖导入是否完整。
5. 业务服务与网关落地：从注册到路由再到数据库查询
5.1 搭建 user-service：注册中心、配置中心和 MyBatis 三合一接入
user-service是第一个业务服务，承担用户信息的增删改查，最能体现微服务模块的完整配置。它的 pom 需要集成 Nacos 注册、Nacos 配置、MyBatis、MySQL 驱动、common-api、OpenFeign 和负载均衡组件。
<dependencies> <dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId> </dependency> <dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId> </dependency> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>${mybatis-starter.version}</version> </dependency> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-openfeign</artifactId> </dependency> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-loadbalancer</artifactId> </dependency> </dependencies>nacos-discovery负责服务注册与发现，nacos-config负责拉取远程配置，两个依赖必须同时存在才构成完整的配置中心能力。mysql-connector-java只在运行时需要，所以scope设为runtime。OpenFeign 和 LoadBalancer 之所以成对出现，是因为服务间调用需要知道目标服务地址，由 Nacos 提供实例列表后，再由 LoadBalancer 做负载均衡选择。
user-service 的application.yml是整个配置的核心：
spring: application: name: user-service profiles: active: dev cloud: nacos: discovery: server-addr: 127.0.0.1:8848 config: server-addr: 127.0.0.1:8848 file-extension: yaml namespace: publicspring.application.name必须与 Nacos 配置中心的dataId前缀保持一致，这是服务注册后显示在控制台的服务名。profiles.active指定当前环境为 dev，配合 Nacos 上配置的user-service-dev.yaml完成拼接。file-extension设置为yaml表示配置格式。namespace默认是public，如果一开始不做多环境隔离，用它即可，不需要额外创建命名空间。
启动类上需要同时加@EnableDiscoveryClient和@MapperScan：
@SpringBootApplication @EnableDiscoveryClient @MapperScan("com.demo.user.mapper") public class UserServiceApplication { public static void main(String[] args) { SpringApplication.run(UserServiceApplication.class, args); } }@EnableDiscoveryClient在 SpringCloud Edgware 之后版本其实可以省略，但保留它能更直观地表达“这是一个注册到 Nacos 的服务”。@MapperScan是 MyBatis 的 Mapper 扫描注解，扫描到接口后自动生成代理实现类。启动日志出现Registering service with nacos表示注册成功。
5.2 UserMapper 与 XML：MyBatis 从配置到可用的完整闭环
Mapper 接口定义标准的 CRUD 方法，XML 文件编写具体 SQL，这是 MyBatis 最经典的配置方式：
public interface UserMapper { User findById(@Param("id") Long id); }<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd"> <mapper namespace="com.demo.user.mapper.UserMapper"> <select id="findById" resultType="com.demo.common.entity.User"> SELECT * FROM t_user WHERE id = #{id} </select> </mapper>需要注意的是XML文件必须放在src/main/resources/mapper/目录下，并在 Nacos 配置上配好mybatis.mapper-locations: classpath:mapper/*.xml，这个配置会被nacos-config拉取并应用到 MyBatis 的 SqlSessionFactory 构建过程。如果改来改去还是报Invalid bound statement，先看 target 目录里有没有把 XML 打包进去，很多所谓“改了一百遍还是不行”的问题其实是构建目录下还是旧文件。
5.3 Gateway 网关模块：路由转发是核心诉求
Gateway 是外部请求进入微服务集群的大门，配置一个可用的网关模块只需要做两件事：注册到 Nacos 以便发现下游服务地址，配置路由规则把请求转发给对应的服务。在网关的application.yml中：
spring: application: name: gateway-server cloud: nacos: discovery: server-addr: 127.0.0.1:8848 gateway: routes: - id: user-route uri: lb://user-service predicates: - Path=/api/user/** filters: - StripPrefix=1 - id: order-route uri: lb://order-service predicates: - Path=/api/order/** filters: - StripPrefix=1 server: port: 8080路由配置的uri使用lb://前缀，表示通过 Nacos 发现服务实例并做负载均衡转发，这是网关与硬编码地址方式的本质区别。Predicates定义路由匹配条件，Path=/api/user/**表示匹配所有/api/user/开头的请求。StripPrefix=1是个容易被忽视的过滤器，它把路径中的第一个前缀去掉，即真实的/api/user/1到达 user-service 时会被转为/1，因为请求路径中的api和user都是网关层的前缀，服务内部不需要。
启动网关后访问http://localhost:8080/api/user/1，请求链路是：网关收到请求，匹配 user-route，通过 LoadBalancer 从 Nacos 拉取 user-service 的实例列表，选择一个实例发起转发，最终调用 UserController 的查询接口。服务直接互通时也可以在业务代码中用 OpenFeign 调用，而网关负责的是外部请求的统一入口和鉴权过滤。
6. 装完怎么验证跑通：一条链路把注册、路由、调用全串起来
环境全部搭好之后，用一条请求把整条链路串起来做验证。验证之前确保 Nacos 先启动，然后依次启动 user-service 和 gateway-server，用jps命令能看到两个 Java 进程在运行。
第一步验证注册中心。打开 Nacos 控制台，在服务管理页面看到user-service和gateway-server都在线，实例数为 1，健康状态为绿色。这一步能确认服务注册和心跳正常。
第二步验证配置中心。启动 user-service 时观察日志，看到类似Loading nacos data, dataId: user-service-dev.yaml的输出，说明 Nacos 配置已经被拉取。如果日志里出现dataId is empty或config not found，优先检查spring.application.name和profiles.active是否拼接成了正确的 dataId。
第三步验证网关路由转发，执行一次真实请求：
curl http://localhost:8080/api/user/1如果一切正常，返回 JSON 结构的数据，说明网关路由匹配成功，StripPrefix 过滤器生效，请求被转发到了 user-service。如果返回 404，查看网关日志确认是路由没匹配上还是目标服务根本没注册。
第四步验证数据库链路。在 user-service 日志中观察 MyBatis 是否输出了 SQL 日志，确认查询真正执行到了 MySQL。如果接口返回异常，检查数据库连接配置和 t_user 表是否存在。
最后用 Nacos 控制台的服务详情页做一次体检：点击 user-service 的实例详情，确认 IP 是否正确、端口是否对应、元数据信息是否完整。这套链路验证完成后，整套环境的健康状态就已经被充分确认了。从那以后我每次新起微服务项目，都强制先把 Nacos 注册、网关转发、数据库查询这条链路跑一遍，不跑通不写业务代码——因为环境的问题越早暴露，排查成本越低，定位越精准，后续写业务才不会把环境问题和代码问题混在一起。这套方案对你正在搭的骨架应该能直接用上，希望帮到你。
本文还有配套的精品资源，点击获取
