1. 为什么我要从零搭一套SpringCloud微服务第一次接触SpringCloud是在一个企业级项目进度跟踪系统的开发任务里。当时整个系统还是单体架构所有功能模块——用户管理、工时统计、进度看板、消息通知——全部塞在一个Spring Boot工程里。本地启动一次要等将近两分钟改一行代码重新部署测试同学就得干等。最要命的是某次上线一个新功能结果把工时统计模块的接口搞挂了整个系统跟着一起崩。那次事故之后我开始认真研究微服务架构也就有了这套从入门到精通的完整实践记录。这篇文章要讲的东西很实在SpringCloud微服务架构到底怎么落地。我会从架构设计的思路讲起把服务注册发现、配置中心、服务网关、负载均衡、熔断降级这些核心组件一个个拆开配上可以直接复现的代码和配置。不管你是刚接触微服务的新手还是已经用过Spring Boot但没碰过分布式系统的开发者都能跟着走一遍。整套内容基于Spring Boot 2.7.x和Spring Cloud 2021.x版本这是目前企业里用得最稳的组合之一。我踩过的坑不少版本兼容问题、注册中心选型纠结、网关路由配置死活不生效、Feign调用超时排查了半天……这些都会在文章里一一交代。目标只有一个——让你少走弯路把微服务这套东西真正用起来。2. 微服务架构整体设计与技术选型思路2.1 从单体到微服务拆分的核心逻辑单体架构的问题不是它不好而是它不适合所有场景。项目初期单体架构开发快、部署简单、调试方便一个jar包扔服务器上就能跑。但当团队规模扩大到十几个人代码量膨胀到几十万行单体架构的弊端就暴露了编译慢、部署慢、扩展难、技术栈锁死、故障隔离差。微服务拆分的核心逻辑是按业务能力垂直切分。拿企业项目进度跟踪系统举例我会这样拆用户服务负责登录认证、权限管理、用户信息维护项目服务管理项目基本信息、里程碑、任务分配工时服务记录和统计工时、生成报表通知服务站内信、邮件、消息推送网关服务统一入口、路由转发、鉴权过滤每个服务独立开发、独立部署、独立扩展。工时服务压力大就多开几个实例通知服务访问量小就少开几个。某个服务挂了其他服务照常运行不会出现“一损俱损”的局面。但拆分不是越细越好。我见过有人把用户服务拆成“用户查询服务”“用户写入服务”“用户权限服务”结果一个简单的用户信息查询要跨三个服务调用链路长得离谱。拆分的粒度应该以“业务边界”为准而不是以“技术分层”为准。一个服务应该是一个完整的业务能力单元能独立完成一件事。2.2 技术选型为什么是这套组合SpringCloud不是单一框架而是一整套微服务解决方案的集合。选型的时候我对比过几套方案组件可选方案我的选择选择理由注册中心Eureka / Nacos / Consul / ZookeeperNacos同时支持注册发现和配置管理社区活跃中文文档全配置中心Spring Cloud Config / Nacos Config / ApolloNacos Config与注册中心统一减少运维成本服务网关Zuul / GatewayGateway基于WebFlux响应式性能更好Spring官方主推负载均衡Ribbon / LoadBalancerLoadBalancerRibbon已停止维护LoadBalancer是替代方案服务调用Feign / RestTemplate / DubboOpenFeign声明式调用代码简洁与Spring生态无缝集成熔断降级Hystrix / Sentinel / Resilience4jSentinel阿里出品功能强大控制台可视化链路追踪SleuthZipkin / SkyWalkingSkyWalking无侵入功能全面支持多种语言这套组合是我在实际项目中反复验证过的稳定性和开发效率都能兼顾。特别是Nacos一个组件搞定注册和配置两件事省了不少事。2.3 版本兼容最容易翻车的地方SpringCloud的版本管理是个大坑。Spring Boot、Spring Cloud、Spring Cloud Alibaba三者之间有严格的版本对应关系选错了直接启动报错。我用的版本组合properties spring-boot.version2.7.18/spring-boot.version spring-cloud.version2021.0.8/spring-cloud.version spring-cloud-alibaba.version2021.0.5.0/spring-cloud-alibaba.version /properties注意Spring Cloud 2021.x对应Spring Boot 2.6.x和2.7.x不要混用Spring Boot 3.x的版本否则Nacos客户端会报各种奇怪的错。版本对应关系建议直接查Spring Cloud Alibaba的官方文档不要凭感觉猜。我见过有人用Spring Boot 3.0配Spring Cloud 2021.0.x结果Nacos注册不上排查了一整天。3. 核心组件拆解与实操配置3.1 Nacos注册中心服务如何找到彼此Nacos的核心作用是服务注册与发现。每个微服务启动时把自己的IP和端口注册到Nacos调用方通过服务名从Nacos获取实例列表再发起调用。先启动Nacos Server。我用的是单机模式适合开发和测试环境# 下载Nacos Server wget https://github.com/alibaba/nacos/releases/download/2.2.3/nacos-server-2.2.3.tar.gz tar -xzf nacos-server-2.2.3.tar.gz cd nacos/bin # 单机模式启动Linux/Mac sh startup.sh -m standalone # Windows startup.cmd -m standalone启动后访问http://localhost:8848/nacos默认账号密码都是nacos。接下来在Spring Boot项目中引入Nacos依赖dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId /dependency配置文件里加上Nacos地址spring: application: name: user-service cloud: nacos: discovery: server-addr: localhost:8848 namespace: dev group: DEFAULT_GROUP启动类上加EnableDiscoveryClient注解。启动服务后在Nacos控制台的服务列表里就能看到user-service了。实操心得namespace用来隔离不同环境dev/test/prodgroup用来隔离不同项目。生产环境一定要用namespace隔离否则测试环境的服务可能被生产环境调用到。3.2 OpenFeign声明式调用像调本地方法一样调远程服务服务注册到Nacos之后怎么调用最早我用RestTemplate手动拼接URL代码又臭又长。后来换成OpenFeign一个接口搞定。引入依赖dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-openfeign/artifactId /dependency启动类加EnableFeignClients然后定义Feign客户端FeignClient(name user-service, fallback UserClientFallback.class) public interface UserClient { GetMapping(/user/{id}) ResultUserDTO getUserById(PathVariable(id) Long id); PostMapping(/user/batch) ResultListUserDTO getUsersByIds(RequestBody ListLong ids); }调用的时候直接注入UserClient像调本地方法一样Service public class WorkHourService { Autowired private UserClient userClient; public WorkHourVO getWorkHourDetail(Long userId) { ResultUserDTO result userClient.getUserById(userId); UserDTO user result.getData(); // 继续业务逻辑 } }Feign默认的超时时间很短生产环境一定要调整feign: client: config: default: connectTimeout: 5000 readTimeout: 10000 loggerLevel: basic踩坑记录Feign的PathVariable必须指定value否则启动报错。这个坑我踩过两次每次都要愣一下才想起来。3.3 Gateway服务网关统一入口与路由转发网关是微服务的门面所有外部请求先到网关再由网关转发到具体服务。这样做的好处是统一鉴权、统一限流、统一日志、隐藏内部服务结构。引入Gateway依赖注意不要引入spring-boot-starter-web否则冲突dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-gateway/artifactId /dependency路由配置有两种方式我习惯用YAMLspring: cloud: gateway: routes: - id: user-service-route uri: lb://user-service predicates: - Path/api/user/** filters: - StripPrefix1 - id: workhour-service-route uri: lb://workhour-service predicates: - Path/api/workhour/** filters: - StripPrefix1lb://user-service表示从注册中心获取实例并负载均衡。StripPrefix1表示去掉路径的第一段/api这样转发到user-service的请求就是/user/xxx。全局过滤器用来做鉴权Component public class AuthGlobalFilter implements GlobalFilter, Ordered { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { String token exchange.getRequest().getHeaders().getFirst(Authorization); if (token null || !token.startsWith(Bearer )) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } // 校验token逻辑 return chain.filter(exchange); } Override public int getOrder() { return -100; } }注意Gateway基于WebFlux不能用Spring MVC的那套东西。在Gateway里写Servlet相关的代码会直接报错。3.4 Sentinel熔断降级防止雪崩效应微服务调用链路上如果某个服务响应慢或者挂了调用方线程会被阻塞最终导致整个链路崩溃。这就是雪崩效应。Sentinel的作用就是在这种情况下快速失败返回兜底数据。引入依赖dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-sentinel/artifactId /dependency配置Sentinel控制台地址spring: cloud: sentinel: transport: dashboard: localhost:8080 port: 8719启动Sentinel控制台java -Dserver.port8080 -Dcsp.sentinel.dashboard.serverlocalhost:8080 \ -jar sentinel-dashboard-1.8.6.jar在Feign客户端上配置降级feign: sentinel: enabled: true定义降级处理类Component public class UserClientFallback implements UserClient { Override public ResultUserDTO getUserById(Long id) { return Result.fail(用户服务暂时不可用请稍后重试); } Override public ResultListUserDTO getUsersByIds(ListLong ids) { return Result.fail(批量查询用户失败); } }在Sentinel控制台可以配置流控规则、降级规则、热点规则。我一般会给核心接口配置QPS限流给非核心接口配置熔断降级。实操心得Sentinel的规则默认存在内存里重启就没了。生产环境要配置持久化把规则存到Nacos或者数据库。4. 完整项目搭建流程与关键环节4.1 工程结构规划一个标准的SpringCloud微服务项目我通常这样组织project-parent/ ├── pom.xml # 父工程管理版本 ├── common/ # 公共模块 │ ├── common-core/ # 工具类、常量、异常 │ ├── common-redis/ # Redis封装 │ └── common-swagger/ # 接口文档配置 ├── gateway/ # 网关服务 ├── user-service/ # 用户服务 ├── workhour-service/ # 工时服务 ├── project-service/ # 项目服务 └── notify-service/ # 通知服务父工程的pom只做依赖管理不写具体依赖dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-dependencies/artifactId version${spring-boot.version}/version typepom/type scopeimport/scope /dependency dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-dependencies/artifactId version${spring-cloud.version}/version typepom/type scopeimport/scope /dependency dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-alibaba-dependencies/artifactId version${spring-cloud-alibaba.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement4.2 服务提供者开发要点以用户服务为例一个标准的服务提供者包含这几层Controller层对外暴露REST接口Service层业务逻辑Mapper层数据库操作Entity/DTO/VO数据对象Controller的写法RestController RequestMapping(/user) RequiredArgsConstructor public class UserController { private final UserService userService; GetMapping(/{id}) public ResultUserVO getUserById(PathVariable Long id) { UserVO user userService.getUserById(id); return Result.success(user); } PostMapping public ResultLong createUser(RequestBody Valid UserCreateDTO dto) { Long userId userService.createUser(dto); return Result.success(userId); } }统一的返回结果封装Data public class ResultT { private Integer code; private String message; private T data; public static T ResultT success(T data) { ResultT result new Result(); result.setCode(200); result.setMessage(success); result.setData(data); return result; } public static T ResultT fail(String message) { ResultT result new Result(); result.setCode(500); result.setMessage(message); return result; } }注意服务之间的DTO要单独定义不要直接暴露Entity。Entity是数据库映射DTO是服务间传输对象两者职责不同。4.3 服务消费者开发要点消费者通过Feign调用提供者。关键点是降级处理和超时配置。FeignClient(name user-service, fallbackFactory UserClientFallbackFactory.class, configuration FeignConfig.class) public interface UserClient { // 接口定义 }用fallbackFactory而不是fallback可以拿到异常信息Component public class UserClientFallbackFactory implements FallbackFactoryUserClient { Override public UserClient create(Throwable cause) { return new UserClient() { Override public ResultUserDTO getUserById(Long id) { log.error(调用用户服务失败, cause); return Result.fail(用户服务降级 cause.getMessage()); } }; } }Feign的配置类Configuration public class FeignConfig { Bean public Logger.Level feignLoggerLevel() { return Logger.Level.FULL; } Bean public Retryer feignRetryer() { return new Retryer.Default(100, 1000, 3); } }4.4 配置中心集成Nacos作为配置中心可以把各服务的配置集中管理。在Nacos控制台新建配置Data ID:user-service-dev.yamlGroup:DEFAULT_GROUP内容: 数据库连接、Redis配置等服务端引入依赖dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-config/artifactId /dependencybootstrap.yml配置spring: application: name: user-service profiles: active: dev cloud: nacos: config: server-addr: localhost:8848 file-extension: yaml namespace: dev注意Spring Boot 2.4之后bootstrap.yml默认不生效需要引入spring-cloud-starter-bootstrap依赖或者改用spring.config.import方式。配置动态刷新在Controller上加RefreshScopeNacos配置修改后会自动生效不用重启服务。5. 常见问题排查与避坑指南5.1 服务注册不上Nacos这是最常见的问题。排查思路现象可能原因解决方法服务列表为空Nacos地址配错检查server-addr注意不要加http://服务注册了但调不通网络不通检查防火墙、安全组注册后立即掉线心跳超时检查Nacos服务端负载调整心跳间隔namespace不匹配命名空间ID写错用namespace的ID而不是名称我遇到过一次服务死活注册不上最后发现是spring.cloud.nacos.discovery.namespace填的是namespace的名称而不是ID。Nacos控制台创建namespace后会生成一个UUID配置里要填那个UUID。5.2 Feign调用超时Feign默认超时是1秒很多业务场景下不够用。调整方式feign: client: config: default: connectTimeout: 5000 readTimeout: 10000如果某个服务特别慢可以单独配置feign: client: config: user-service: readTimeout: 30000踩坑记录Feign的超时和Ribbon的超时是两回事。如果用了Ribbon还要配ribbon.ReadTimeout和ribbon.ConnectTimeout。不过现在用LoadBalancer的话只需要配Feign的就行。5.3 Gateway路由不生效Gateway路由配置看起来简单但坑不少路径匹配问题Path/api/user/**和Path/api/user/*不一样前者匹配多级路径后者只匹配一级StripPrefix问题去掉几段路径要数清楚去多了或去少了都404服务名问题lb://user-service里的服务名必须和Nacos里注册的一致依赖冲突引入了spring-boot-starter-web会导致Gateway启动失败我排查Gateway问题的一般步骤先看Gateway日志有没有路由匹配记录再用actuator/gateway/routes端点查看实际生效的路由。5.4 分布式事务问题微服务拆分后一个业务操作可能跨多个服务。比如创建项目时要同时写项目表和工时初始化表两个操作在不同服务里怎么保证一致性我的建议是能不用分布式事务就不用。大部分场景可以用最终一致性方案本地消息表业务操作和消息记录在同一个本地事务里定时补偿定时扫描未完成的消息重试对账机制定期对账发现不一致人工介入如果非要用强一致性方案Seata是个选择但运维成本高性能损耗大。小项目慎用。5.5 日志排查技巧微服务环境下一个请求跨多个服务日志分散在各处。排查问题时要能串起来。方案一用SkyWalking做链路追踪每个请求有唯一的traceId在SkyWalking UI上能看到完整调用链。方案二在网关生成traceId通过Header传递到下游服务各服务日志里打印traceId。用MDC实现// 网关过滤器里生成traceId String traceId UUID.randomUUID().toString().replace(-, ); exchange.getRequest().mutate() .header(X-Trace-Id, traceId) .build(); // 下游服务用拦截器获取 Component public class TraceInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { String traceId request.getHeader(X-Trace-Id); MDC.put(traceId, traceId); return true; } }日志格式里加上%X{traceId}这样每条日志都带traceIdgrep一下就能串起来。6. 从能跑到好用生产环境加固建议6.1 健康检查与优雅停机Spring Boot Actuator提供健康检查端点management: endpoints: web: exposure: include: health,info,metrics endpoint: health: show-details: alwaysK8s环境下用readinessProbe和livenessProbe做健康检查。优雅停机配置server: shutdown: graceful spring: lifecycle: timeout-per-shutdown-phase: 30s这样服务停止时会先拒绝新请求等正在处理的请求完成后再退出避免请求丢失。6.2 接口文档聚合每个服务用Swagger生成接口文档网关统一聚合。用springdoc-openapidependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-ui/artifactId version1.7.0/version /dependency网关配置Swagger聚合springdoc: swagger-ui: urls: - name: user-service url: /user-service/v3/api-docs - name: workhour-service url: /workhour-service/v3/api-docs这样在网关的Swagger UI上就能看到所有服务的接口文档不用一个个服务去访问。6.3 配置加密数据库密码、Redis密码这些敏感信息不能明文放在Nacos里。可以用Jasypt加密dependency groupIdcom.github.ulisesbocchio/groupId artifactIdjasypt-spring-boot-starter/artifactId version3.0.5/version /dependency加密后配置spring: datasource: password: ENC(加密后的字符串)启动时传入密钥java -jar user-service.jar --jasypt.encryptor.passwordyour-secret-key注意密钥不要写在配置文件里通过环境变量或启动参数传入。6.4 限流与熔断的粒度控制Sentinel的规则配置要分优先级核心接口QPS限流阈值根据压测结果设定非核心接口熔断降级慢调用比例超过阈值就熔断依赖外部服务的接口超时时间设短一点快速失败我一般会做一轮压测用JMeter模拟高并发观察各接口的响应时间和错误率再根据结果配置限流阈值。压测脚本要覆盖正常流量、峰值流量、异常流量三种场景。6.5 灰度发布思路微服务架构下灰度发布可以做得更精细。基于Nacos的元数据可以实现按版本路由spring: cloud: nacos: discovery: metadata: version: v1网关根据Header里的版本号路由到不同实例。这样新版本先给内部用户用没问题再全量。这套东西搭下来一个完整的SpringCloud微服务项目就能跑起来了。从注册中心到网关从服务调用到熔断降级每个组件都有它存在的理由。刚开始接触会觉得组件太多、配置太杂但用熟了之后你会发现这套架构的扩展性和容错能力是单体架构没法比的。我在实际项目中最大的体会是不要为了微服务而微服务。团队规模小、业务简单的项目单体架构反而更合适。微服务的价值在于解耦和独立扩展如果你的项目没有这些痛点强行上微服务只会增加复杂度。但如果你确实需要那这套SpringCloud的方案是经过验证的、可靠的。
SpringCloud微服务从零搭建实战：Nacos、Gateway、Sentinel核心组件详解
1. 为什么我要从零搭一套SpringCloud微服务第一次接触SpringCloud是在一个企业级项目进度跟踪系统的开发任务里。当时整个系统还是单体架构所有功能模块——用户管理、工时统计、进度看板、消息通知——全部塞在一个Spring Boot工程里。本地启动一次要等将近两分钟改一行代码重新部署测试同学就得干等。最要命的是某次上线一个新功能结果把工时统计模块的接口搞挂了整个系统跟着一起崩。那次事故之后我开始认真研究微服务架构也就有了这套从入门到精通的完整实践记录。这篇文章要讲的东西很实在SpringCloud微服务架构到底怎么落地。我会从架构设计的思路讲起把服务注册发现、配置中心、服务网关、负载均衡、熔断降级这些核心组件一个个拆开配上可以直接复现的代码和配置。不管你是刚接触微服务的新手还是已经用过Spring Boot但没碰过分布式系统的开发者都能跟着走一遍。整套内容基于Spring Boot 2.7.x和Spring Cloud 2021.x版本这是目前企业里用得最稳的组合之一。我踩过的坑不少版本兼容问题、注册中心选型纠结、网关路由配置死活不生效、Feign调用超时排查了半天……这些都会在文章里一一交代。目标只有一个——让你少走弯路把微服务这套东西真正用起来。2. 微服务架构整体设计与技术选型思路2.1 从单体到微服务拆分的核心逻辑单体架构的问题不是它不好而是它不适合所有场景。项目初期单体架构开发快、部署简单、调试方便一个jar包扔服务器上就能跑。但当团队规模扩大到十几个人代码量膨胀到几十万行单体架构的弊端就暴露了编译慢、部署慢、扩展难、技术栈锁死、故障隔离差。微服务拆分的核心逻辑是按业务能力垂直切分。拿企业项目进度跟踪系统举例我会这样拆用户服务负责登录认证、权限管理、用户信息维护项目服务管理项目基本信息、里程碑、任务分配工时服务记录和统计工时、生成报表通知服务站内信、邮件、消息推送网关服务统一入口、路由转发、鉴权过滤每个服务独立开发、独立部署、独立扩展。工时服务压力大就多开几个实例通知服务访问量小就少开几个。某个服务挂了其他服务照常运行不会出现“一损俱损”的局面。但拆分不是越细越好。我见过有人把用户服务拆成“用户查询服务”“用户写入服务”“用户权限服务”结果一个简单的用户信息查询要跨三个服务调用链路长得离谱。拆分的粒度应该以“业务边界”为准而不是以“技术分层”为准。一个服务应该是一个完整的业务能力单元能独立完成一件事。2.2 技术选型为什么是这套组合SpringCloud不是单一框架而是一整套微服务解决方案的集合。选型的时候我对比过几套方案组件可选方案我的选择选择理由注册中心Eureka / Nacos / Consul / ZookeeperNacos同时支持注册发现和配置管理社区活跃中文文档全配置中心Spring Cloud Config / Nacos Config / ApolloNacos Config与注册中心统一减少运维成本服务网关Zuul / GatewayGateway基于WebFlux响应式性能更好Spring官方主推负载均衡Ribbon / LoadBalancerLoadBalancerRibbon已停止维护LoadBalancer是替代方案服务调用Feign / RestTemplate / DubboOpenFeign声明式调用代码简洁与Spring生态无缝集成熔断降级Hystrix / Sentinel / Resilience4jSentinel阿里出品功能强大控制台可视化链路追踪SleuthZipkin / SkyWalkingSkyWalking无侵入功能全面支持多种语言这套组合是我在实际项目中反复验证过的稳定性和开发效率都能兼顾。特别是Nacos一个组件搞定注册和配置两件事省了不少事。2.3 版本兼容最容易翻车的地方SpringCloud的版本管理是个大坑。Spring Boot、Spring Cloud、Spring Cloud Alibaba三者之间有严格的版本对应关系选错了直接启动报错。我用的版本组合properties spring-boot.version2.7.18/spring-boot.version spring-cloud.version2021.0.8/spring-cloud.version spring-cloud-alibaba.version2021.0.5.0/spring-cloud-alibaba.version /properties注意Spring Cloud 2021.x对应Spring Boot 2.6.x和2.7.x不要混用Spring Boot 3.x的版本否则Nacos客户端会报各种奇怪的错。版本对应关系建议直接查Spring Cloud Alibaba的官方文档不要凭感觉猜。我见过有人用Spring Boot 3.0配Spring Cloud 2021.0.x结果Nacos注册不上排查了一整天。3. 核心组件拆解与实操配置3.1 Nacos注册中心服务如何找到彼此Nacos的核心作用是服务注册与发现。每个微服务启动时把自己的IP和端口注册到Nacos调用方通过服务名从Nacos获取实例列表再发起调用。先启动Nacos Server。我用的是单机模式适合开发和测试环境# 下载Nacos Server wget https://github.com/alibaba/nacos/releases/download/2.2.3/nacos-server-2.2.3.tar.gz tar -xzf nacos-server-2.2.3.tar.gz cd nacos/bin # 单机模式启动Linux/Mac sh startup.sh -m standalone # Windows startup.cmd -m standalone启动后访问http://localhost:8848/nacos默认账号密码都是nacos。接下来在Spring Boot项目中引入Nacos依赖dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId /dependency配置文件里加上Nacos地址spring: application: name: user-service cloud: nacos: discovery: server-addr: localhost:8848 namespace: dev group: DEFAULT_GROUP启动类上加EnableDiscoveryClient注解。启动服务后在Nacos控制台的服务列表里就能看到user-service了。实操心得namespace用来隔离不同环境dev/test/prodgroup用来隔离不同项目。生产环境一定要用namespace隔离否则测试环境的服务可能被生产环境调用到。3.2 OpenFeign声明式调用像调本地方法一样调远程服务服务注册到Nacos之后怎么调用最早我用RestTemplate手动拼接URL代码又臭又长。后来换成OpenFeign一个接口搞定。引入依赖dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-openfeign/artifactId /dependency启动类加EnableFeignClients然后定义Feign客户端FeignClient(name user-service, fallback UserClientFallback.class) public interface UserClient { GetMapping(/user/{id}) ResultUserDTO getUserById(PathVariable(id) Long id); PostMapping(/user/batch) ResultListUserDTO getUsersByIds(RequestBody ListLong ids); }调用的时候直接注入UserClient像调本地方法一样Service public class WorkHourService { Autowired private UserClient userClient; public WorkHourVO getWorkHourDetail(Long userId) { ResultUserDTO result userClient.getUserById(userId); UserDTO user result.getData(); // 继续业务逻辑 } }Feign默认的超时时间很短生产环境一定要调整feign: client: config: default: connectTimeout: 5000 readTimeout: 10000 loggerLevel: basic踩坑记录Feign的PathVariable必须指定value否则启动报错。这个坑我踩过两次每次都要愣一下才想起来。3.3 Gateway服务网关统一入口与路由转发网关是微服务的门面所有外部请求先到网关再由网关转发到具体服务。这样做的好处是统一鉴权、统一限流、统一日志、隐藏内部服务结构。引入Gateway依赖注意不要引入spring-boot-starter-web否则冲突dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-gateway/artifactId /dependency路由配置有两种方式我习惯用YAMLspring: cloud: gateway: routes: - id: user-service-route uri: lb://user-service predicates: - Path/api/user/** filters: - StripPrefix1 - id: workhour-service-route uri: lb://workhour-service predicates: - Path/api/workhour/** filters: - StripPrefix1lb://user-service表示从注册中心获取实例并负载均衡。StripPrefix1表示去掉路径的第一段/api这样转发到user-service的请求就是/user/xxx。全局过滤器用来做鉴权Component public class AuthGlobalFilter implements GlobalFilter, Ordered { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { String token exchange.getRequest().getHeaders().getFirst(Authorization); if (token null || !token.startsWith(Bearer )) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } // 校验token逻辑 return chain.filter(exchange); } Override public int getOrder() { return -100; } }注意Gateway基于WebFlux不能用Spring MVC的那套东西。在Gateway里写Servlet相关的代码会直接报错。3.4 Sentinel熔断降级防止雪崩效应微服务调用链路上如果某个服务响应慢或者挂了调用方线程会被阻塞最终导致整个链路崩溃。这就是雪崩效应。Sentinel的作用就是在这种情况下快速失败返回兜底数据。引入依赖dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-sentinel/artifactId /dependency配置Sentinel控制台地址spring: cloud: sentinel: transport: dashboard: localhost:8080 port: 8719启动Sentinel控制台java -Dserver.port8080 -Dcsp.sentinel.dashboard.serverlocalhost:8080 \ -jar sentinel-dashboard-1.8.6.jar在Feign客户端上配置降级feign: sentinel: enabled: true定义降级处理类Component public class UserClientFallback implements UserClient { Override public ResultUserDTO getUserById(Long id) { return Result.fail(用户服务暂时不可用请稍后重试); } Override public ResultListUserDTO getUsersByIds(ListLong ids) { return Result.fail(批量查询用户失败); } }在Sentinel控制台可以配置流控规则、降级规则、热点规则。我一般会给核心接口配置QPS限流给非核心接口配置熔断降级。实操心得Sentinel的规则默认存在内存里重启就没了。生产环境要配置持久化把规则存到Nacos或者数据库。4. 完整项目搭建流程与关键环节4.1 工程结构规划一个标准的SpringCloud微服务项目我通常这样组织project-parent/ ├── pom.xml # 父工程管理版本 ├── common/ # 公共模块 │ ├── common-core/ # 工具类、常量、异常 │ ├── common-redis/ # Redis封装 │ └── common-swagger/ # 接口文档配置 ├── gateway/ # 网关服务 ├── user-service/ # 用户服务 ├── workhour-service/ # 工时服务 ├── project-service/ # 项目服务 └── notify-service/ # 通知服务父工程的pom只做依赖管理不写具体依赖dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-dependencies/artifactId version${spring-boot.version}/version typepom/type scopeimport/scope /dependency dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-dependencies/artifactId version${spring-cloud.version}/version typepom/type scopeimport/scope /dependency dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-alibaba-dependencies/artifactId version${spring-cloud-alibaba.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement4.2 服务提供者开发要点以用户服务为例一个标准的服务提供者包含这几层Controller层对外暴露REST接口Service层业务逻辑Mapper层数据库操作Entity/DTO/VO数据对象Controller的写法RestController RequestMapping(/user) RequiredArgsConstructor public class UserController { private final UserService userService; GetMapping(/{id}) public ResultUserVO getUserById(PathVariable Long id) { UserVO user userService.getUserById(id); return Result.success(user); } PostMapping public ResultLong createUser(RequestBody Valid UserCreateDTO dto) { Long userId userService.createUser(dto); return Result.success(userId); } }统一的返回结果封装Data public class ResultT { private Integer code; private String message; private T data; public static T ResultT success(T data) { ResultT result new Result(); result.setCode(200); result.setMessage(success); result.setData(data); return result; } public static T ResultT fail(String message) { ResultT result new Result(); result.setCode(500); result.setMessage(message); return result; } }注意服务之间的DTO要单独定义不要直接暴露Entity。Entity是数据库映射DTO是服务间传输对象两者职责不同。4.3 服务消费者开发要点消费者通过Feign调用提供者。关键点是降级处理和超时配置。FeignClient(name user-service, fallbackFactory UserClientFallbackFactory.class, configuration FeignConfig.class) public interface UserClient { // 接口定义 }用fallbackFactory而不是fallback可以拿到异常信息Component public class UserClientFallbackFactory implements FallbackFactoryUserClient { Override public UserClient create(Throwable cause) { return new UserClient() { Override public ResultUserDTO getUserById(Long id) { log.error(调用用户服务失败, cause); return Result.fail(用户服务降级 cause.getMessage()); } }; } }Feign的配置类Configuration public class FeignConfig { Bean public Logger.Level feignLoggerLevel() { return Logger.Level.FULL; } Bean public Retryer feignRetryer() { return new Retryer.Default(100, 1000, 3); } }4.4 配置中心集成Nacos作为配置中心可以把各服务的配置集中管理。在Nacos控制台新建配置Data ID:user-service-dev.yamlGroup:DEFAULT_GROUP内容: 数据库连接、Redis配置等服务端引入依赖dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-config/artifactId /dependencybootstrap.yml配置spring: application: name: user-service profiles: active: dev cloud: nacos: config: server-addr: localhost:8848 file-extension: yaml namespace: dev注意Spring Boot 2.4之后bootstrap.yml默认不生效需要引入spring-cloud-starter-bootstrap依赖或者改用spring.config.import方式。配置动态刷新在Controller上加RefreshScopeNacos配置修改后会自动生效不用重启服务。5. 常见问题排查与避坑指南5.1 服务注册不上Nacos这是最常见的问题。排查思路现象可能原因解决方法服务列表为空Nacos地址配错检查server-addr注意不要加http://服务注册了但调不通网络不通检查防火墙、安全组注册后立即掉线心跳超时检查Nacos服务端负载调整心跳间隔namespace不匹配命名空间ID写错用namespace的ID而不是名称我遇到过一次服务死活注册不上最后发现是spring.cloud.nacos.discovery.namespace填的是namespace的名称而不是ID。Nacos控制台创建namespace后会生成一个UUID配置里要填那个UUID。5.2 Feign调用超时Feign默认超时是1秒很多业务场景下不够用。调整方式feign: client: config: default: connectTimeout: 5000 readTimeout: 10000如果某个服务特别慢可以单独配置feign: client: config: user-service: readTimeout: 30000踩坑记录Feign的超时和Ribbon的超时是两回事。如果用了Ribbon还要配ribbon.ReadTimeout和ribbon.ConnectTimeout。不过现在用LoadBalancer的话只需要配Feign的就行。5.3 Gateway路由不生效Gateway路由配置看起来简单但坑不少路径匹配问题Path/api/user/**和Path/api/user/*不一样前者匹配多级路径后者只匹配一级StripPrefix问题去掉几段路径要数清楚去多了或去少了都404服务名问题lb://user-service里的服务名必须和Nacos里注册的一致依赖冲突引入了spring-boot-starter-web会导致Gateway启动失败我排查Gateway问题的一般步骤先看Gateway日志有没有路由匹配记录再用actuator/gateway/routes端点查看实际生效的路由。5.4 分布式事务问题微服务拆分后一个业务操作可能跨多个服务。比如创建项目时要同时写项目表和工时初始化表两个操作在不同服务里怎么保证一致性我的建议是能不用分布式事务就不用。大部分场景可以用最终一致性方案本地消息表业务操作和消息记录在同一个本地事务里定时补偿定时扫描未完成的消息重试对账机制定期对账发现不一致人工介入如果非要用强一致性方案Seata是个选择但运维成本高性能损耗大。小项目慎用。5.5 日志排查技巧微服务环境下一个请求跨多个服务日志分散在各处。排查问题时要能串起来。方案一用SkyWalking做链路追踪每个请求有唯一的traceId在SkyWalking UI上能看到完整调用链。方案二在网关生成traceId通过Header传递到下游服务各服务日志里打印traceId。用MDC实现// 网关过滤器里生成traceId String traceId UUID.randomUUID().toString().replace(-, ); exchange.getRequest().mutate() .header(X-Trace-Id, traceId) .build(); // 下游服务用拦截器获取 Component public class TraceInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { String traceId request.getHeader(X-Trace-Id); MDC.put(traceId, traceId); return true; } }日志格式里加上%X{traceId}这样每条日志都带traceIdgrep一下就能串起来。6. 从能跑到好用生产环境加固建议6.1 健康检查与优雅停机Spring Boot Actuator提供健康检查端点management: endpoints: web: exposure: include: health,info,metrics endpoint: health: show-details: alwaysK8s环境下用readinessProbe和livenessProbe做健康检查。优雅停机配置server: shutdown: graceful spring: lifecycle: timeout-per-shutdown-phase: 30s这样服务停止时会先拒绝新请求等正在处理的请求完成后再退出避免请求丢失。6.2 接口文档聚合每个服务用Swagger生成接口文档网关统一聚合。用springdoc-openapidependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-ui/artifactId version1.7.0/version /dependency网关配置Swagger聚合springdoc: swagger-ui: urls: - name: user-service url: /user-service/v3/api-docs - name: workhour-service url: /workhour-service/v3/api-docs这样在网关的Swagger UI上就能看到所有服务的接口文档不用一个个服务去访问。6.3 配置加密数据库密码、Redis密码这些敏感信息不能明文放在Nacos里。可以用Jasypt加密dependency groupIdcom.github.ulisesbocchio/groupId artifactIdjasypt-spring-boot-starter/artifactId version3.0.5/version /dependency加密后配置spring: datasource: password: ENC(加密后的字符串)启动时传入密钥java -jar user-service.jar --jasypt.encryptor.passwordyour-secret-key注意密钥不要写在配置文件里通过环境变量或启动参数传入。6.4 限流与熔断的粒度控制Sentinel的规则配置要分优先级核心接口QPS限流阈值根据压测结果设定非核心接口熔断降级慢调用比例超过阈值就熔断依赖外部服务的接口超时时间设短一点快速失败我一般会做一轮压测用JMeter模拟高并发观察各接口的响应时间和错误率再根据结果配置限流阈值。压测脚本要覆盖正常流量、峰值流量、异常流量三种场景。6.5 灰度发布思路微服务架构下灰度发布可以做得更精细。基于Nacos的元数据可以实现按版本路由spring: cloud: nacos: discovery: metadata: version: v1网关根据Header里的版本号路由到不同实例。这样新版本先给内部用户用没问题再全量。这套东西搭下来一个完整的SpringCloud微服务项目就能跑起来了。从注册中心到网关从服务调用到熔断降级每个组件都有它存在的理由。刚开始接触会觉得组件太多、配置太杂但用熟了之后你会发现这套架构的扩展性和容错能力是单体架构没法比的。我在实际项目中最大的体会是不要为了微服务而微服务。团队规模小、业务简单的项目单体架构反而更合适。微服务的价值在于解耦和独立扩展如果你的项目没有这些痛点强行上微服务只会增加复杂度。但如果你确实需要那这套SpringCloud的方案是经过验证的、可靠的。
