1. 从零跑通微服务商品-订单-库存小项目为什么值得动手如果你刚开始接触 Spring Cloud大概率会被一堆名词砸晕注册中心、配置中心、服务调用、网关路由、负载均衡。每个概念单独看都能理解但真到动手时服务之间怎么找到对方、配置改了怎么不重启生效、外部请求怎么统一入口这些问题会一起冒出来。这篇教程用一个商品-订单-库存的小项目把 Spring Cloud Nacos 的核心组件串成一条完整链路让你从零跑通微服务的基本骨架。项目模拟电商系统里最常见的三个服务商品服务提供商品信息查询库存服务提供库存查询和扣减订单服务在下单时调用商品服务查价格、调用库存服务扣库存最后再加一个网关服务作为外部统一入口。所有服务都用内存数据不依赖 MySQL 和 Redis降低环境门槛。跑通之后你可以把内存数据换成真实数据库也可以在此基础上扩展鉴权、限流、链路追踪。适合谁看有 Java 和 Spring Boot 基础想系统入门 Spring Cloud 微服务的开发者正在准备微服务相关面试需要动手项目支撑理解的同学已经用过 Nacos 但没把 OpenFeign 和 Gateway 串起来的同学。整篇教程的节奏是先启动 Nacos再逐个启动服务并验证注册然后配置中心动态刷新接着用 OpenFeign 完成服务间调用最后用 Gateway 统一入口每一步都有可复制的命令和配置。2. TaoToken 前置统一 Key 与 API 通道的配置骨架在微服务项目里除了业务服务之间的调用开发过程中还经常需要调用大模型能力比如让订单服务在创建订单时生成一段摘要或者让商品服务自动补全商品描述。如果每个服务各自维护一套 API Key 和请求地址配置会散落在各个模块里改起来很麻烦。TaoToken 提供统一的 API 通道把模型调用集中管理微服务只需要读取同一份配置即可。TaoToken 的官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的作用是让你用一个统一的 Key 访问多种模型能力不用在每个服务里重复配置不同的厂商地址和密钥。对于微服务项目来说这意味着你可以在 Nacos 配置中心里放一份共享配置所有服务通过 Nacos 读取而不是把 Key 硬编码在代码里。先在你的开发环境里准备好 TaoToken 的 API Key。登录控制台后在 API Keys 页面创建一个新的 Key复制保存。这个 Key 后面会写进 Nacos 的共享配置里供各个服务读取。注意不要把 Key 直接提交到 Git 仓库生产环境建议用环境变量或配置中心加密功能。TaoToken 的接入文档在 https://taotoken.net/doc 里面列出了不同模型对应的请求路径和参数格式。如果你只是想在本地验证连通性可以直接用模型对话页面测试地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。对于长期编码和 Agent 场景可以了解 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。3. 可复制配置Nacos、OpenFeign、Gateway 与 TaoToken 的 settings.json3.1 环境准备与版本锁定先确认本地环境JDK 17Maven 3.8Nacos Server 2.x。检查命令如下java -version mvn -vNacos 解压后进入 bin 目录用单机模式启动startup.cmd -m standalone启动成功后访问 http://127.0.0.1:8848/nacos 默认账号密码都是 nacos。Nacos 2.x 会占用 8848、9848、9849 三个端口如果报 Address already in use先关闭占用这些端口的程序。项目结构如下spring-cloud-nacos-shop-demo/ ├── pom.xml ├── shop-common/ ├── product-service/ ├── order-service/ ├── stock-service/ └── gateway-service/父 pom 里锁定 Spring Boot、Spring Cloud、Spring Cloud Alibaba 的版本不要随意改动。版本错配是微服务启动失败最常见的原因。3.2 Nacos 配置中心库存服务动态刷新在 Nacos 控制台新建配置Data ID 填 stock-service.propertiesGroup 填 DEFAULT_GROUP配置格式选 Properties内容如下stock.max-deduct5点击发布。库存服务的 application.yml 里需要配置spring: application: name: stock-service cloud: nacos: config: server-addr: 127.0.0.1:8848 file-extension: propertiesNacos 会按${spring.application.name}.${file-extension}拼接 Data ID所以 Data ID 必须是 stock-service.properties写成 stock-service.yml 会对不上。读取配置的 Bean 上加两个注解RefreshScope Component public class StockConfig { Value(${stock.max-deduct:10}) private int maxDeduct; }Value 读取配置没有则用默认值 10RefreshScope 让 Nacos 配置变更后重新创建 Bean从而刷新 Value 的值。改完配置不重启服务再次请求配置接口就能看到新值。3.3 OpenFeign 接口骨架订单服务调用商品服务Feign 客户端接口如下FeignClient(name product-service) public interface ProductFeignClient { GetMapping(/product/{id}) ResultProduct getProduct(PathVariable(id) Long id); }调用库存服务的扣减接口FeignClient(name stock-service) public interface StockFeignClient { PostMapping(/stock/deduct) ResultBoolean deduct(RequestBody DeductRequest request); }FeignClient 的 name 必须和目标服务的 spring.application.name 完全一致包括大小写。启动类上加 EnableFeignClients 扫描 Feign 接口加 EnableDiscoveryClient 开启 Nacos 注册。3.4 Gateway 路由规则网关服务的 application.ymlspring: cloud: gateway: routes: - id: product-service-route uri: lb://product-service predicates: - Path/product/** - id: order-service-route uri: lb://order-service predicates: - Path/order/** - id: stock-service-route uri: lb://stock-service predicates: - Path/stock/**uri 里的 lb:// 表示使用负载均衡从 Nacos 拉取对应服务的实例列表。predicates 按路径前缀匹配。Gateway 基于 WebFlux不要引入 spring-boot-starter-web否则会冲突导致启动失败。3.5 TaoToken settings.json 配置骨架在 Nacos 里新建一个共享配置Data ID 填 taotoken-shared.propertiesGroup 填 DEFAULT_GROUP内容如下taotoken.api.base-urlhttps://taotoken.net/api taotoken.api.key你的APIKey taotoken.api.model你的模型名称各个服务在 application.yml 里引入共享配置spring: cloud: nacos: config: shared-configs: ->RefreshScope Component public class TaoTokenConfig { Value(${taotoken.api.base-url}) private String baseUrl; Value(${taotoken.api.key}) private String apiKey; Value(${taotoken.api.model}) private String model; }这样所有服务共用一份 TaoToken 配置改 Key 或换模型只需要在 Nacos 里改一次不用逐个服务重启。4. 验证请求从服务注册到完整链路4.1 编译并启动商品服务在项目根目录执行mvn clean install -DskipTests看到 BUILD SUCCESS 后运行 ProductServiceApplication。application.yml 配置server: port: 8081 spring: application: name: product-service cloud: nacos: discovery: server-addr: 127.0.0.1:8848 group: DEFAULT_GROUP启动后进入 Nacos 控制台 → 服务管理 → 服务列表应该能看到 product-service。测试商品接口Invoke-WebRequest -Uri http://127.0.0.1:8081/product/1 -Method GET预期返回{ code: 200, message: success, data: { id: 1, name: iPhone 16, price: 6999.00 } }4.2 启动库存服务并验证配置刷新运行 StockServiceApplication端口 8083。查询库存Invoke-WebRequest -Uri http://127.0.0.1:8083/stock/1 -Method GET查询当前配置值Invoke-WebRequest -Uri http://127.0.0.1:8083/stock/config/max-deduct -Method GET返回 5。然后在 Nacos 控制台把 stock.max-deduct 改成 20发布后不重启服务再次请求返回值变成 20说明动态刷新生效。把值改回 5尝试扣减 10 件Invoke-WebRequest -Uri http://127.0.0.1:8083/stock/deduct -Method POST -ContentType application/json -Body {productId:1,quantity:10}返回“单次扣减数量超过上限 5”的错误说明配置中心控制业务规则生效。4.3 启动订单服务并测试 OpenFeign 调用运行 OrderServiceApplication端口 8082。下单接口Invoke-WebRequest -Uri http://127.0.0.1:8082/order/create -Method POST -ContentType application/json -Body {productId:1,quantity:2}预期返回订单创建成功totalAmount 是商品单价乘以数量。查看 order-service 控制台日志能看到调用 product-service 查询商品、调用 stock-service 扣减库存的记录。4.4 启动网关服务并验证完整链路运行 GatewayServiceApplication端口 8080。通过网关访问三个服务Invoke-WebRequest -Uri http://127.0.0.1:8080/product/1 -Method GET Invoke-WebRequest -Uri http://127.0.0.1:8080/stock/1 -Method GET Invoke-WebRequest -Uri http://127.0.0.1:8080/order/create -Method POST -ContentType application/json -Body {productId:1,quantity:2}三个接口都正常返回说明网关路由、服务注册、OpenFeign 调用全部打通。完整链路是外部请求到 Gateway 8080Gateway 按路径转发到对应服务订单服务再通过 OpenFeign 调用商品服务和库存服务。4.5 验证 TaoToken 连通性在任意一个服务里加一个测试接口读取 TaoToken 配置并发起一次请求RestController public class TaoTokenTestController { Value(${taotoken.api.base-url}) private String baseUrl; Value(${taotoken.api.key}) private String apiKey; GetMapping(/taotoken/ping) public String ping() { return baseUrl baseUrl , keyPrefix apiKey.substring(0, 6); } }启动服务后访问该接口确认能读到 Nacos 里的共享配置。如果返回的 baseUrl 是 https://taotoken.net/api 说明配置读取成功。更完整的连通性验证可以用模型对话页面直接测试地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。5. 本篇常见错排查5.1 服务启动后 Nacos 列表里看不到先确认 Nacos 已启动访问 http://127.0.0.1:8848/nacos 能打开。检查 spring.cloud.nacos.discovery.server-addr 是否正确检查是否引入了 spring-cloud-starter-alibaba-nacos-discovery 依赖。查看服务启动日志搜索 nacos 关键字通常会有连接失败的具体原因。5.2 OpenFeign 报 No instances available for xxx这个错误说明目标服务没有注册到 Nacos或者 FeignClient 的 name 与目标服务名不一致。先去 Nacos 服务列表确认目标服务是否存在再检查 name 的大小写。还有一种情况是目标服务注册到了不同的 Group调用方和提供方的 Group 必须一致。5.3 OpenFeign 报 404Feign 接口路径写错或者 PathVariable 没写参数名或者目标服务的 Controller 路径不一致。检查 Feign 接口上的 GetMapping 路径和目标服务 Controller 的 RequestMapping 路径是否拼接后一致。5.4 Gateway 报 503目标服务没启动或没注册到 Nacos或者网关路由的 uri 服务名写错。检查 lb:// 后面的服务名是否和 Nacos 里的服务名一致。另外确认 Gateway 没有引入 spring-boot-starter-web否则 WebFlux 和 WebMVC 冲突会导致路由不生效。5.5 Nacos 配置不生效Data ID 或 Group 与项目配置不一致file-extension 与 Nacos 配置格式不一致读取配置的 Bean 没加 RefreshScope或者配置没点“发布”。逐项检查这四点基本能覆盖大部分配置不生效的问题。5.6 TaoToken 配置读取不到检查 Nacos 共享配置的 Data ID 和 Group 是否与 application.yml 里的 shared-configs 一致。检查 refresh 是否设为 true。如果 Key 里有特殊字符确认在 properties 文件里是否需要转义。生产环境不要把 Key 明文放在配置里建议用环境变量覆盖。6. 继续深入从跑通到用起来项目跑通之后你可以做几件事让它更接近真实场景。把内存数据换成 MySQL用 MyBatis-Plus 或 JPA 操作数据库给 Gateway 加上全局过滤器实现简单的鉴权用 Nacos 的命名空间隔离不同环境把 TaoToken 的模型调用封装成一个公共模块供多个服务复用。如果你在接入 TaoToken 时遇到 Key 配置或请求路径的问题可以先去 API Keys 页面确认 Key 状态地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 再对照接入文档检查请求格式文档地址是 https://taotoken.net/doc 。需要长期在编码和 Agent 场景里使用可以了解 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。控制台入口是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。微服务入门最怕的是只看不练把这篇教程里的命令和配置复制到本地跑一遍遇到报错就对照第 5 节的排查手册基本能把核心组件串起来。跑通之后再回头看 Nacos、OpenFeign、Gateway 的官方文档理解会深很多。
