微服务系统中如何开发

1.1 为什么需要远程配置？#

在单体项目里，配置文件一般就直接放在项目里，比如 application.yml，改了配置就重启服务就行。

但在微服务架构下，通常有这些问题：

• 公共配置分散，改一处要动 N 个项目：微服务下有十几个甚至几十个服务，很多配置是多个服务共用的（比如 Redis 地址、数据库连接、第三方接口密钥）。虽然 Spring Boot 自带的 Profile 机制（application-dev.yml、application-prod.yml）也能做多环境切换，但当服务数量多了之后，每个服务都维护自己的一套配置文件，公共配置一旦变更就要逐个修改 N 个项目，很容易漏改或改错。配置中心可以把公共配置集中管理，改一次所有服务都生效
• 敏感配置不适合放在代码仓库中：数据库密码、第三方接口密钥等敏感信息，如果直接写在项目的配置文件里，会被提交到 Git 仓库，存在泄露风险。配置中心可以集中管理这些敏感配置，代码仓库里只保留非敏感的基本配置
• 配置修改需要重启才能生效：有些配置改了之后，服务必须重启才能生效，这在生产环境是很不方便的

所以，微服务架构下，通常会引入配置中心来统一管理配置。

简单理解：配置中心就是把你之前放在 application.yml 里的配置，搬到远程服务器上统一管理。你可以随时改，改完之后服务可以做到动态生效，不需要重启。

1.2 常见的配置中心#

其中，Nacos 是国内企业用得最多的，很多公司的微服务架构都是基于 Spring Cloud Alibaba + Nacos 搭建的。

1.3 远程配置一般怎么用？#

以 Nacos 为例，一般的用法是这样的：

1）在 Nacos 控制台上创建配置

你登录 Nacos 控制台，在里面创建一个配置，比如：

• Data ID：order-service-dev.yml
• Group：DEFAULT_GROUP
• 配置内容：就是你的 yml 配置，比如数据库连接、Redis 地址等

2）在项目的 bootstrap.yml 中配置 Nacos 地址

1
spring:
2
  application:
3
    name: order-service
4
  cloud:
5
    nacos:
6
      config:
7
        server-addr: 127.0.0.1:8848
8
        file-extension: yml
9
        group: DEFAULT_GROUP   #分组不设置，默认就是DEFAULT_GROUP
10
        namespace: 7c5c0c0d-c0c5-4c0c-b0c5-0c5c0c5c0c5c   #命名空间不设置，默认是public
11
        username: nacos
12
        password: nacos
13
        shared-configs:           # 引入公共配置
14
          - data-id: application-dev.yml   # 公共配置的 Data ID
15
            refresh: true         # 是否支持动态刷新

注意：Nacos 配置相关的内容一般放在 bootstrap.yml（或 bootstrap.properties）里，而不是 application.yml。因为 bootstrap.yml 的加载优先级比 application.yml 更高，这样可以保证在应用启动时先连上 Nacos 拉取配置，再进行后续初始化。

除了在 bootstrap.yml 里写死 Nacos 地址，也可以在 IDEA 的启动配置里通过 JVM 参数指定，本地开发时用这种方式更灵活，不用改代码：

在 IDEA 的 Run Configuration 里，找到 VM options，添加：

1
-Dspring.cloud.nacos.config.server-addr=http://127.0.0.1:8848
2
-Dspring.cloud.nacos.config.file-extension=yml
3
-Dspring.cloud.nacos.config.namespace=0662a2cc-f7fd-42e0-b33b-aa07603950bd
4
-Dspring.cloud.nacos.config.shared-configs[0].data-id=application-dev.yml
5
-Dspring.cloud.nacos.config.shared-configs.refresh=true
6
-Dspring.profiles.active=dev
7
-Dspring.cloud.nacos.config.group=DEFAULT_GROUP
8
-Dspring.cloud.nacos.discovery.server-addr=http://127.0.0.1:8848
9
-Dspring.cloud.nacos.discovery.group=zy
10
-Dspring.cloud.nacos.discovery.namespace=0662a2cc-f7fd-42e0-b33b-aa07603950bd

这样本地开发连自己电脑的 Nacos，测试环境连测试环境的 Nacos，只需要改 VM 参数就行，不用动配置文件。

3）启动服务时自动拉取远程配置

服务启动后，会自动去 Nacos 拉取对应的配置，和本地配置合并后生效。

启动过程中，各个配置被读入的先后顺序是这样的：

1
1、bootstrap.yml（本地）
2
        ↓
3
2、拉取公共配置（shared-configs）
4
        ↓
5
3、拉取当前服务自己的配置（Data ID = 服务名.yml）
6
        ↓
7
4、application.yml（本地）
8
        ↓
9
最终合并生效

特别注意：这里讲的”加载顺序”和下面讲的”优先级”不是一回事，别搞混了。 上面说的是各个配置在启动过程中”什么时候被读到”，而真正决定同名属性最终用哪个值的，是优先级。Nacos 拉取到的远程配置会被插入到比本地配置更高的优先级位置上，所以它虽然比 application.yml 先被加载，最终却能覆盖 application.yml。

如果同一个属性在多处都配了，最终生效遵循以下优先级（高优先级覆盖低优先级）：

1
Nacos 服务专属配置（Data ID = 服务名.yml）    ← 最高
2
        ↓ 覆盖
3
Nacos 公共配置（shared-configs）
4
        ↓ 覆盖
5
application.yml（本地）
6
        ↓ 覆盖
7
bootstrap.yml（本地）                          ← 最低

简单记三条就够：

• 远程 > 本地：Nacos 上的配置会覆盖本地配置
• 专属 > 共享：服务自己的配置会覆盖公共配置
• application > bootstrap：本地文件中，application.yml 覆盖 bootstrap.yml

优先级能改吗？ 能，但一般不需要。Spring Cloud Nacos 提供了一些配置项（如 spring.cloud.config.override-none=true 可以让远程配置不覆盖本地），但实际项目中几乎不会去改默认优先级，了解有这么回事就行。

这也是为什么很多项目本地只保留最基本的配置（服务名、Nacos 地址、端口号等），其他配置全部放到 Nacos 上管理——避免本地和远程配置打架。

当然，如果某个属性只在某一处配了，其他地方没配，那自然就是那一处的值生效。

其中，公共配置是多个服务共用的配置，比如数据库连接、Redis 地址、通用日志配置等。这些配置不需要每个服务都重复配一遍，只需要在 Nacos 上创建一份公共配置文件（如 common.yml），然后在每个服务的 bootstrap.yml 中引入即可。修改公共配置时，所有引用它的服务都会生效，不用一个一个改。

1.4 哪些配置适合放远程，哪些不适合？#

原则：多环境有差异的、需要经常修改的、敏感信息类的配置，优先放配置中心。

1.5 配置修改后，服务怎么感知？#

有两种常见方式：

方式一：自动刷新

通过 @RefreshScope 注解，配合 Nacos 的配置监听机制，配置修改后，对应的 Bean 会自动重新创建，不需要重启服务。

实际开发中，最常见的场景是业务开关——比如某个功能上线后发现问题，需要紧急关闭，如果配置写在代码里就只能重新发版；但放在 Nacos 上，改个配置就能即时生效，不用重启服务。

1）在 Nacos 上添加开关配置

1
# 比如配置在 order-service-dev.yml 中
2
order:
3
  flash-sale-enabled: false    # 秒杀功能开关，false 表示关闭
4
  max-order-count: 5           # 单用户最大下单数

2）在代码中通过 @Value 读取，配合 @RefreshScope 实现动态刷新

1
@RestController
2
@RefreshScope
3
public class OrderController {
4

5
    @Value("${order.flash-sale-enabled:false}")
6
    private Boolean flashSaleEnabled;
7

8
    @Value("${order.max-order-count:10}")
9
    private Integer maxOrderCount;
10

11
    @GetMapping("/flashSale")
12
    public String flashSale() {
13
        if (!flashSaleEnabled) {
14
            return "秒杀活动暂未开放";
15
        }
16
        return "秒杀活动进行中，每人限购" + maxOrderCount + "件";
17
    }
18
}

启动服务后，浏览器访问 /flashSale 会返回”秒杀活动暂未开放”。然后在 Nacos 上把 order.flash-sale-enabled 改成 true，不用重启服务，再刷新页面就能看到返回”秒杀活动进行中，每人限购5件”。

方式二：手动重启

有些配置改了之后，确实需要重启服务才能生效（比如数据库连接池的配置）。这种情况就直接改配置、重启服务。

1.6 远程配置相关的常见问题#

问题一：本地配置不生效

这是新人特别容易遇到的问题。排查思路：

• 检查 bootstrap.yml 或 Idea 启动脚本里配置的 Nacos 地址是否正确
• 检查 Data ID、Group 是否和 Nacos 上的一致
• 检查环境（dev / test / prod）是否正确
• 检查远程配置是否覆盖了本地配置（优先级问题）

问题二：配置改了但没生效

• 确认你改的是不是正确的环境配置（可能改的是测试环境的，但本地连的是开发环境）
• 确认是否需要 @RefreshScope 才能动态刷新
• 确认修改后是否需要重启服务

问题三：远程配置里数据库、Redis 这些中间件的 IP，应该写哪个？

很多新人会困惑：Nacos 是配置中心，那配置里的数据库 IP，到底是要写 Nacos 能访问的，还是服务自己能访问的？

答案：写”服务自己能访问的”IP。

原因很简单：Nacos 只是配置的”仓库”，它负责存储和分发配置，本身根本不去连接数据库、Redis 这些中间件。真正拿着这些连接信息去建立连接、发 SQL 的，是消费配置的业务服务（order-service、user-service 等）。所以 IP 必须是业务服务所在的网络环境里能访问到的地址。

举个例子：

• Nacos、MySQL、Redis 都部署在 A 服务器
• 你的业务服务部署在 B 服务器

那么远程配置里数据库、Redis 的 IP 不能写 127.0.0.1 或 localhost，因为 127.0.0.1 在 B 服务器的视角下指的是 B 自己，B 上根本没有装 MySQL/Redis，肯定连不上。应该写 A 服务器对外的 IP（也就是从 B 服务器上能 ping 通的那个 IP）。

2.1 为什么需要注册中心？#

在单体项目里，所有代码都在一起，调用另一个模块的方法直接调就行了，不需要关心对方在哪台机器上。

但在微服务架构下，每个服务都是独立部署的，可能分布在不同机器上，而且服务的实例数量还可能随时变化（比如某个服务扩容了，从 2 个实例变成 5 个；某个实例挂了，只剩 4 个了）。

1
订单服务想调用用户服务，问题是：
2
    - 用户服务部署在哪台机器上？
3
    - IP 地址是多少？端口是多少？
4
    - 用户服务有几个实例？调哪个？
5
    - 如果某个实例挂了怎么办？

如果这些信息全靠人工维护，比如在配置文件里写死每个服务的 IP 和端口，那根本管不过来：

• 某个服务换了机器，所有调用方都要改配置
• 某个服务扩容了，调用方不知道新的实例在哪
• 某个服务挂了，调用方还在傻傻地请求已经不存在的地址

注册中心就是用来自动解决这些问题的。

2.2 注册中心是做什么的？#

用一句话概括：

注册中心就是一个”服务通讯录”，每个服务启动时把自己的地址登记上去，需要调用别人时从通讯录里查。

2.3 注册中心的工作流程#

2.4 常见的注册中心#

其中，Nacos 是目前国内企业使用最多的注册中心，特别是基于 Spring Cloud Alibaba 的微服务项目，基本上都是用 Nacos。前面说过，Nacos 同时支持配置中心和注册中心，所以很多公司只需要部署一个 Nacos 就够了。

2.5 服务注册与发现在代码中是怎么体现的？#

很多新人会觉得：“注册中心这么重要，我是不是要写很多注册相关的代码？”

实际上，注册中心的使用基本上是自动的，你不需要手动写注册和发现的代码。

以 Spring Cloud Alibaba + Nacos 为例，我们的项目只需要：

1）添加依赖

1
<dependency>
2
    <groupId>com.alibaba.cloud</groupId>
3
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
4
</dependency>

2）在配置文件中指定 Nacos 地址

1
spring:
2
  application:
3
    name: order-service    # 服务名，注册到 Nacos 上的名称
4
  cloud:
5
    nacos:
6
      discovery:
7
        server-addr: 127.0.0.1:8848   # Nacos 地址
8
        group: DEFAULT_GROUP   #分组不设置，默认就是DEFAULT_GROUP
9
        namespace: 7c5c0c0d-c0c5-4c0c-b0c5-0c5c0c5c0c5c   #命名空间不设置，默认是public
10
        username: nacos
11
        password: nacos

也是可以在IDEA 的启动配置里通过 JVM 参数指定。

3）启动服务

服务启动后，Spring Cloud 会自动帮你完成以下操作：

• 把当前服务（order-service）注册到 Nacos
• 定时向 Nacos 发送心跳，告诉它”我还活着”
• 当你用 Feign 或 Dubbo 调用其他服务时，自动从 Nacos 查询目标服务的地址

你在 Nacos 控制台的”服务列表”页面，就能看到所有已注册的服务及其实例信息。

2.6 关于服务注册与发现的几个关键概念#

1）服务注册

服务启动时，将自己的信息（服务名、IP、端口等）注册到注册中心。

2）服务发现

服务消费方从注册中心获取目标服务的实例列表，选择其中一个进行调用。

3）心跳检测

注册中心会定时检查每个服务是否还活着。如果某个服务长时间没有发送心跳，注册中心会认为它已经挂了，把它从服务列表中剔除。

4）负载均衡

当一个服务有多个实例时，调用方需要决定请求哪个实例。常见的负载均衡策略有：

在 Spring Cloud 中，负载均衡默认使用的是 Spring Cloud LoadBalancer（早期版本用的是 Ribbon，从 Spring Cloud 2020.0 开始 Ribbon 已被移除，统一换成 LoadBalancer）。一般不需要你手动配置。

2.7 注册中心相关的常见问题#

问题一：服务启动了，但注册中心上看不到

排查思路：

• 检查 Nacos 地址是否配置正确
• 检查服务名是否正确
• 检查网络是否能连上 Nacos（telnet 一下 Nacos 的端口）
• 检查依赖是否引入了 spring-cloud-starter-alibaba-nacos-discovery
• 看启动日志里有没有注册失败的报错

问题二：远程调用报错”找不到服务”

这种情况通常是调用方在注册中心上找不到目标服务。排查思路：

• 确认目标服务是否已启动并注册成功
• 确认调用方配置的目标服务名和注册中心上的服务名是否一致（大小写、横杠、下划线等）
• 确认调用方和目标服务连的是同一个 Nacos、同一个命名空间（namespace）、同一个分组

3.1 Feign 接口抽取到独立 API 模块（最常见的做法）#

上面演示的是在消费方（order-service）里自己写 Feign 接口。但工作中更常见的做法是：服务提供方把 Feign 接口和 DTO 放到一个独立的模块里，打成 jar 包，消费方直接引用这个 jar 包就行。

1
openfeign-test/                       ← 父工程
2
├── user-api                          ← 独立模块，只放接口和 DTO
3
│   └── com.example.user.api
4
│       ├── UserClient.java           ← Feign 接口
5
│       └── UserDTO.java              ← 数据传输对象
6
├── user-service                      ← 服务提供方（用户服务）
7
│   └── com.example.user
8
│       ├── UserServiceApplication.java
9
│       └── controller/
10
│           └── UserController.java   ← Controller 实现 UserClient 接口
11
└── order-service                     ← 服务消费方（订单服务）
12
    └── com.example.order
13
        └── OrderServiceApplication.java

服务提供方的 Controller 直接实现这个 Feign 接口：

1
// user-api 模块中的 Feign 接口
2
@FeignClient(name = "user-service")
3
public interface UserClient {
4

5
    @GetMapping("/user/{id}")
6
    UserDTO getUserById(@PathVariable("id") Long id);
7

8
    @PostMapping("/user")
9
    void createUser(@RequestBody UserDTO user);
10
}
11

12
// user-service-impl 模块中的 Controller 实现该接口
13
@RestController
14
public class UserController implements UserClient {
15

16
    @Autowired
17
    private UserService userService;
18

19
    @Override
20
    public UserDTO getUserById(Long id) {
21
        return userService.getUserById(id);
22
    }
23

24
    @Override
25
    public void createUser(UserDTO user) {
26
        userService.createUser(user);
27
    }
28
}

消费方只需要在 pom.xml 里引用 user-api 的依赖，就能直接注入使用：

1
<!-- order-service 的 pom.xml -->
2
<dependency>
3
    <groupId>com.example</groupId>
4
    <artifactId>user-api</artifactId>
5
    <version>1.0.0</version>
6
</dependency>

1
// order-service 中直接注入，不用自己写 Feign 接口
2
@Autowired
3
private UserClient userClient;

这样做的好处：

• 消费方不用自己写 Feign 接口，直接引用提供方的 jar 包，减少重复代码
• 接口和实现天然一致，因为 Controller 实现了 Feign 接口，路径、参数、返回值都是一样的，不会出现”调用方写的接口和提供方不一致”的问题
• DTO 共享，请求和响应的对象也放在 api 模块里，双方用的是同一个类

简单理解：就像你调用别人的 SDK，人家把接口定义好打成 jar 包给你用，你不用关心人家怎么实现的，直接调就行。

入职后看到项目结构里有 xxx-api 模块，多半就是这种模式。

3.2 contextId 解决同服务名多个 FeignClient（了解）#

有些项目会把一个大服务的接口拆成多个 FeignClient（比如用户查询一组、用户管理一组），这时会出现两个 @FeignClient 的 name 相同的情况，启动会报错。加上 contextId 就能解决：

1
// 两个接口都指向 user-service，用 contextId 区分
2
@FeignClient(name = "user-service", contextId = "userQueryClient")
3
public interface UserQueryClient {
4

5
    @GetMapping("/user/{id}")
6
    UserDTO getUserById(@PathVariable("id") Long id);
7
}
8

9
@FeignClient(name = "user-service", contextId = "userManageClient")
10
public interface UserManageClient {
11

12
    @PostMapping("/user")
13
    void createUser(@RequestBody UserDTO user);
14

15
    @PutMapping("/user")
16
    void updateUser(@RequestBody UserDTO user);
17
}

简单理解：Spring 容器里不能有两个同名的 Bean。name 相同的 FeignClient 会冲突，contextId 就是给它们起不同的 Bean 名字。

4.1 Dubbo 和 OpenFeign 的区别#

简单理解：OpenFeign 就像你用浏览器访问网页，走的是通用的 HTTP 协议；Dubbo 就像两个人打专线电话，用专门的协议直接通话，速度更快但需要两边都用同一套协议。

4.2 Dubbo 的基本用法#

Dubbo 的使用方式有两种主流写法：一种是老版本的 XML / 注解方式，另一种是新版本推荐的 Spring Boot 方式。现在新项目基本都用 Spring Boot 方式，这里也以此为例。

1）添加依赖

服务提供方和服务消费方都需要引入 Dubbo 的 starter：

1
<dependency>
2
    <groupId>org.apache.dubbo</groupId>
3
    <artifactId>dubbo-spring-boot-starter</artifactId>
4
    <version>3.2.0</version>
5
</dependency>
6
<!-- 注册中心以 Nacos 为例 -->
7
<dependency>
8
    <groupId>org.apache.dubbo</groupId>
9
    <artifactId>dubbo-registry-nacos</artifactId>
10
    <version>3.2.0</version>
11
</dependency>

2）配置 Dubbo

1
dubbo:
2
  application:
3
    name: user-service
4
  registry:
5
    address: nacos://127.0.0.1:8848?namespace=7c5c0c0d-c0c5-4c0c-b0c5-0c5c0c5c0c5c&group=zy
6
    username: nacos
7
    password: nacos
8
  protocol:
9
    name: dubbo
10
    port: 20880

3）定义服务接口

Dubbo 的做法是：把接口定义抽成一个独立的模块（API 模块），服务提供方和消费方都依赖这个模块。

1
// user-api 模块（公共接口）
2
public interface UserService {
3
    UserDTO getUserById(Long id);
4
}

4）服务提供方实现接口

在用户服务中实现这个接口，并暴露为 Dubbo 服务：

1
// user-service 模块（服务提供方）
2
@DubboService
3
public class UserServiceImpl implements UserService {
4

5
    @Autowired
6
    private UserMapper userMapper;
7

8
    @Override
9
    public UserDTO getUserById(Long id) {
10
        User user = userMapper.selectById(id);
11
        UserDTO dto = new UserDTO();
12
        dto.setId(user.getId());
13
        dto.setName(user.getName());
14
        return dto;
15
    }
16
}

@DubboService 注解表示：这个类是一个 Dubbo 服务，会自动注册到注册中心，其他服务可以通过远程调用来使用它。

5）服务消费方调用远程服务

在订单服务中，通过 @DubboReference 注入远程服务：

1
// order-service 模块（服务消费方）
2
@Service
3
public class OrderServiceImpl implements OrderService {
4

5
    @DubboReference
6
    private UserService userService;
7

8
    public OrderDTO getOrderDetail(Long orderId) {
9
        Order order = orderMapper.selectById(orderId);
10
        // 远程调用用户服务
11
        UserDTO user = userService.getUserById(order.getUserId());
12
        OrderDTO dto = new OrderDTO();
13
        dto.setOrder(order);
14
        dto.setUser(user);
15
        return dto;
16
    }
17
    }

可以看到，使用方式和 OpenFeign 类似，注入后直接调用方法就行，底层 Dubbo 会自动完成远程调用。

6）启动类上加注解

1
@EnableDubbo
2
@SpringBootApplication
3
public class OrderApplication {
4
    public static void main(String[] args) {
5
        SpringApplication.run(OrderApplication.class, args);
6
    }
7
}

说明：Dubbo 3.x 配合 dubbo-spring-boot-starter 时已经支持自动装配，理论上可以不写 @EnableDubbo。但项目里如果用到了包路径扫描（比如服务接口分散在多个包下），写上 @EnableDubbo 并配合 @DubboService/@DubboReference 会更稳妥，所以很多老项目和教程里都保留了这个注解。新人照着现有代码来就行。

4.3 Dubbo 使用时的注意事项#

1）接口模块要独立

Dubbo 的服务接口（如 UserService）通常放在一个独立的 api 模块中，服务提供方和消费方都依赖这个模块。这样消费方不需要依赖服务提供方的整个项目，只需要知道接口定义就行。

2）序列化问题

Dubbo 远程调用时，传输的对象需要能被序列化。所以 DTO 类一定要实现 Serializable 接口：

1
public class UserDTO implements Serializable {
2
    private static final long serialVersionUID = 1L;
3
    private Long id;
4
    private String name;
5
    // ...
6
}

3）版本号

Dubbo 支持给同一个接口配置不同的版本号，在做接口升级时非常有用：

1
// 服务提供方
2
@DubboService(version = "2.0")
3
public class UserServiceImplV2 implements UserService { ... }
4

5
// 服务消费方
6
@DubboReference(version = "2.0")
7
private UserService userService;

4）超时和重试配置

Dubbo 的超时和重试配置在后面”远程调用失败怎么办”章节会详细讲，这里先知道有这个概念就行。

5）Dubbo 和 OpenFeign 在 Nacos 服务列表中的区别

使用 OpenFeign 的项目，所有服务都会注册到 Nacos 服务列表中，不管是调用方还是被调用方。

但 Dubbo 不一样：只有服务提供者会注册到 Nacos 服务列表，消费者默认不会注册。 消费者只是订阅它需要调用的服务，不会把自己作为”服务”注册上去。

所以如果你用的是 Dubbo，在 Nacos 服务列表里只看到提供者、看不到消费者，这是正常的，不是配置问题。想确认消费者是否正常工作，可以在 Nacos 控制台点进某个服务，查看它的”订阅者列表”（注意：Dubbo 3.x 中订阅者的应用名可能显示为 “unknown”，这也是正常现象，不影响实际调用）。

4.4 怎么快速判断项目用的是哪种？#

入职后，快速判断项目远程调用方式的方法：

注意：有些项目可能同时用了 OpenFeign 和 Dubbo。比如内部服务间调用用 Dubbo（性能更好），调用外部系统用 OpenFeign（走 HTTP 更通用）。碰到这种情况不要奇怪。

5.1 超时配置#

不管是 OpenFeign 还是 Dubbo，都需要合理配置超时时间。

OpenFeign 超时配置：

1
feign:
2
  client:
3
    config:
4
      default:
5
        connectTimeout: 5000   # 连接超时 5 秒
6
        readTimeout: 10000     # 读取超时 10 秒

Dubbo 超时配置：

1
dubbo:
2
  consumer:
3
    timeout: 5000    # 全局超时 5 秒

也可以在注解上针对单个服务设置超时：

1
@DubboReference(timeout = 10000)
2
private UserService userService;

注意：正常情况下不需要单独设置超时时间，公司一般通过 Nacos 远程配置统一管理，或者直接使用框架默认值。除非你新写的接口调用比较耗时，而且已经优化到极限、业务方也可以接受，这时候再去修改超时配置。

5.2 重试#

有些临时性的网络抖动，重试一次可能就好了。但重试要谨慎，因为很多时候，请求超时并不代表业务一定失败。比如下游服务可能已经成功执行了，只是响应返回过程中超时了，如果此时直接重试，可能会导致重复下单、重复扣款等问题。

正因为如此，大部分项目不会在远程调用层面对所有接口统一开启自动重试。通常只会对查询类、幂等接口做有限重试，而新增、扣减、支付类接口一般会禁用自动重试。

处理方式有两种思路：

• 直接禁用重试：简单粗暴，非幂等接口设置 retries = 0，大部分项目用这种
• 把接口做成幂等：比如下单接口用唯一订单号做去重，扣款接口用唯一交易流水号做去重，同样的请求只处理一次。这样即使重试也不会重复操作，但需要额外开发去重逻辑

说明：OpenFeign 默认不重试，调用失败直接抛异常，所以一般不需要额外配置。Dubbo 默认会重试 2 次（总共调用 3 次），非幂等接口一定要手动设置 retries = 0，否则可能会重复操作。

如果确实需要 OpenFeign 开启重试（比如查询类接口），配置一个 Retryer Bean 即可：

1
@Configuration
2
public class FeignConfig {
3

4
    @Bean
5
    public Retryer retryer() {
6
        // 参数：初始间隔(ms)、最大间隔(ms)、最大尝试次数（含首次调用）
7
        return new Retryer.Default(100, 1000, 3);
8
    }
9
}

注意：这是全局配置，对所有 FeignClient 生效。如果项目中既有查询接口（可重试）又有写入接口（不可重试），就不要全局开启，可以在 @FeignClient 的 configuration 属性上针对单个客户端指定配置。

如果用的是 Dubbo，可以通过配置或注解设置重试次数：

1
dubbo:
2
  consumer:
3
    retries: 2       # 全局重试 2 次（总共调用 3 次）

也可以在注解上针对单个服务设置：

1
@DubboReference(retries = 0)  // 不重试（非幂等接口建议关闭）
2
private OrderService orderService;
3

4
@DubboReference(retries = 2)  // 重试 2 次（查询类接口可以开）
5
private UserService userService;

5.3 降级（Fallback）#

降级就是调用失败时，不直接报错，而是返回一个兜底结果：

1
@FeignClient(name = "user-service", fallback = UserClientFallback.class)
2
public interface UserClient {
3

4
    @GetMapping("/user/{id}")
5
    UserDTO getUserById(@PathVariable("id") Long id);
6
}
7

8
// 降级类
9
@Component
10
public class UserClientFallback implements UserClient {
11

12
    @Override
13
    public UserDTO getUserById(Long id) {
14
        UserDTO fallback = new UserDTO();
15
        fallback.setId(id);
16
        fallback.setName("未知用户");
17
        return fallback;
18
    }
19
}

踩坑提醒：Spring Cloud 2020+ 移除了 Hystrix，如果项目中没有引入替代的断路器依赖（如 spring-cloud-starter-circuitbreaker-resilience4j），或者没有在配置文件中开启 spring.cloud.openfeign.circuitbreaker.enabled=true，fallback 属性会静默失效，不报错也不降级。另外，降级类一定要加 @Component 注解，否则 Spring 不认识它，fallback 同样不会生效。

Dubbo 没有像 OpenFeign 那样内置的 fallback 参数，但可以通过 mock 属性声明降级逻辑：

1
@DubboReference(version = "1.0.0", mock = "return null")
2
private UserService userService;

mock 的几种写法：

说明：mock 方式虽然简单，但大部分项目中用得不多，很多项目直接不配降级，远程调用失败就抛异常，由全局异常处理器统一处理。入职后先看项目里有没有现成的写法，照着来就行。

不过，降级不是所有项目都会用。有些公司要求每个远程调用都配置降级；也有很多项目不配降级，远程调用失败就直接抛异常，由全局异常处理器统一处理。两种方式都可以，取决于公司的技术规范。入职后先看项目里有没有降级相关的代码，照着现有写法来就行。

注意：配置了 fallback 的话，降级类里返回的值要合理。比如查询用户信息失败，返回”未知用户”是合理的；但如果下单接口失败返回”下单成功”，那就会出大问题。

5.4 熔断(了解)#

熔断和降级通常会配合使用。当某个服务调用失败率过高、响应时间过长，或者异常次数达到阈值后，熔断器会暂时阻止继续调用下游服务，避免故障扩散。此时系统通常会进入降级逻辑，返回默认值、缓存数据或友好提示。就像家里的保险丝，电流过大时自动断开，保护整个电路不烧毁。

常见的熔断框架有 Sentinel 和 Resilience4j，国内企业用 Sentinel 比较多。早期的 Hystrix 目前已经停止维护，新项目基本不再使用。

如果项目用了 Sentinel，通常会通过 @SentinelResource 注解标记需要保护的远程调用方法，然后在 Sentinel 控制台上配置熔断规则。

不过，熔断在很多公司的项目中并没有使用。因为熔断、限流等治理功能会增加系统复杂度，需要额外维护规则、监控和告警。对于访问量不大、服务链路不复杂的项目，很多公司不会专门引入完整的熔断体系，只用 Nacos + OpenFeign/Dubbo + Gateway 就够了。所以入职后发现项目里没有熔断相关的代码，不要觉得奇怪。先了解公司有没有用，如果有就学一下 Sentinel 的用法，如果没有就不用管。

3.1 放开接口时，网关层和服务层都要放#

这是一个新人特别容易踩的坑。

很多项目中，网关层会做统一鉴权（Token 校验、权限检查等），不在白名单里的请求会被网关直接拦截，根本到不了后端服务。所以当你需要放开某个接口（比如登录、注册、公共查询等无需登录就能访问的接口）时，不能只在服务层放开，网关层也要同步放开。

举个例子：你写了一个 /system/register 注册接口，不需要登录就能访问。你在系统服务里把 Security 配置放开了，但前端调用时还是返回 401。原因是：请求先到了网关，网关的鉴权过滤器发现没有 Token，直接返回 401 了，请求根本没到你的系统服务。

1
前端请求 /system/register（没带 Token）
2
        ↓
3
网关鉴权过滤器 → 没有 Token → 直接返回 401 ❌
4
        ↓ （请求根本没到系统服务）
5
系统服务（你配的放开规则没机会生效）

正确做法：在网关的鉴权过滤器白名单中，也把这个接口加上。 比如前面示例中的 AuthGlobalFilter：

1
// 白名单路径（不需要鉴权的接口）
2
if (path.startsWith("/auth/login")
3
        || path.startsWith("/system/register")    // ← 加上需要放开的接口
4
        || path.startsWith("/file/public")) {
5
    return chain.filter(exchange);
6
}

简单记：微服务架构下，一个请求要经过网关 → 服务两道关。放开接口时两道关都要放，少放一个就会被拦住。排查 401、403 问题时，先确认是网关拦的还是服务拦的，不要只盯着服务层看。

3.2 通过接口路径定位到哪个服务处理的#

入职后经常会遇到这种情况：前端跟你说某个接口报错了，你拿到接口路径（比如 /system/user/list），但不知道这个请求最终是由哪个后端服务处理的。这时候就可以通过网关的路由规则来定位。

定位步骤：

1）找到网关的路由配置

路由配置一般在网关模块的 application.yml（或 bootstrap.yml）里，也可能在 Nacos 的网关配置中。

2）用请求路径匹配路由规则

比如接口路径是 /system/user/list，对照路由规则：匹配 Path=/system/**，对应的 uri 是 lb://ruoyi-system，所以这个接口是 ruoyi-system 处理的。

3）确认转发后的实际路径

由于配了 StripPrefix=1，转发前会去掉第一段 /system，所以 ruoyi-system 收到的请求路径是 /user/list，对应 Controller 里的 @GetMapping("/user/list")。

举几个例子：

注意：如果请求路径没有匹配到任何路由规则，网关会直接返回 404。如果匹配到了但目标服务不可用，网关会返回 502。

常见问题排查：

• 接口返回 404：先确认路由规则是否匹配你的接口路径，再确认 StripPrefix 配置是否正确（比如接口实际路径是 /user/list，但 StripPrefix 多去了一段，转发后变成 /list，服务里根本匹配不到）
• 接口返回 502：通常表示网关调用下游服务失败，不一定是服务宕机，也可能是服务未注册、连接超时、网络异常等原因。先确认服务是否注册成功，再确认服务本身是否正常（直接调服务 IP 看看能不能通）
• 本地调试时可以先绕过网关：如果网关出了问题不好排查，先直接请求你自己服务的本地端口，确认接口本身没问题。服务没问题之后，再去看网关层面的问题
• 在浏览器控制台（F12 → Network）看到接口请求，对照路由规则就能快速定位到对应的服务

3.3 跨域处理（了解）#

前端页面直接请求多个不同地址的服务会碰到跨域问题。在微服务架构下，跨域最理想的做法是在网关层统一处理，比如在网关模块里写一个跨域过滤器（实现 WebFilter），统一设置跨域响应头，这样所有经过网关的请求都不用再单独处理。

但真实项目中，不一定都在网关层做。也有可能通过以下方式处理：

• 在业务服务的公共模块里统一配置：所有服务都依赖一个公共模块（如 framework、common），在公共模块里通过 CorsFilter 统一处理
• 在 Nginx 层处理：有些项目在 Nginx 反向代理时直接加跨域头，请求还没到网关就解决了
• 按需单独处理：只在需要的接口上单独配，比如通过 WebMvcConfigurer.addCorsMappings() 或在 Controller 上加 @CrossOrigin

所以入职后，遇到跨域问题先看项目里是怎么处理的，不要自己加配置，可能和已有的配置冲突。

Redisson 加锁 API 速览#

Redisson 加锁常用的方法就下面几个，先有个整体印象，看后面的代码才不懵：

简单记：lock 是”抢不到就一直等”，tryLock 是”等一会儿就算了”。至于”不写过期时间会不会出问题”，下面会专门讲。

5.1 Redisson 原生写法#

下面是一个电商项目中库存锁定的真实代码，使用 Redisson 的 lock() 方法：

1
@Autowired
2
private RedissonClient redissonClient;
3

4
@Transactional(rollbackFor = Exception.class)
5
public void lockStock(List<StockLockParam> stockLockParams) {
6
    List<RLock> locks = new ArrayList<>();
7
    try {
8
        for (StockLockParam param : stockLockParams) {
9
            // 1. 按商品 SKU ID 获取锁（每个商品一把锁，粒度细）
10
            RLock lock = redissonClient.getLock("lock:stock:" + param.getSkuId());
11
            // 2. 加锁（阻塞等待，直到获取成功）
12
            lock.lock();
13
            locks.add(lock);
14

15
            // 3. 执行业务逻辑：校验库存 → 扣减库存
16
            int stock = stockService.getStock(param.getSkuId());
17
            if (stock < param.getCount()) {
18
                throw new BusinessException("库存不足");
19
            }
20
            stockService.deductStock(param.getSkuId(), param.getCount());
21
        }
22

23
        // 4. 保存库存锁定记录
24
        stockLockMapper.saveBatch(stockLockParams);
25

26
        // 5. 发送延时消息，1小时后自动解锁库存（订单超时未支付场景）
27
        mqTemplate.syncSend("stock-unlock-topic", orderIds);
28

29
    } finally {
30
        // 6. 释放所有锁（只释放当前线程持有的，避免释放别人的锁）
31
        for (RLock lock : locks) {
32
            if (lock.isHeldByCurrentThread()) {
33
                lock.unlock();
34
            }
35
        }
36
    }
37
}

说明：这里用 lock.lock() 阻塞等待，保证一定拿到锁才继续执行。获取锁后，通过 isHeldByCurrentThread() 判断再释放，防止释放别人的锁。锁的粒度是 SKU 级别（lock:stock:{skuId}），不是整个订单，并发性能更好。

疑问：上面 lock.lock() 没有写过期时间，会不会出问题？

不会。这正是 Redisson 和手写 SETNX 锁（第 4 节那种）最大的区别——无参的 lock.lock() 会自动带过期时间，并启动”看门狗”机制自动续期：

• 拿到锁时，Redisson 在底层设了一个默认过期时间（默认 30 秒）
• 同时启动一个后台线程（看门狗），每隔 10 秒检查一次：“这个锁还被当前线程持有吗？是的话，把过期时间重新刷回 30 秒”

这样就化解了一个矛盾：业务没跑完时一直续期，不会出现”锁提前过期、别人插队”的超卖问题；而服务一旦宕机，看门狗也跟着死了，锁最多 30 秒后自动释放，不会永远卡死。

⚠️ 反直觉的坑：一旦你显式指定过期时间（比如 lock.lock(10, SECONDS) 或 tryLock(5, 30, SECONDS)），看门狗就不会启动了，锁到点强制释放，哪怕业务还没跑完。所以要么用无参 lock.lock()（靠看门狗），要么自己估算一个足够长的过期时间，别设太短。

下面是一个 tryLock 的例子，抢锁失败时还能给用户一个友好提示：

1
RLock lock = redissonClient.getLock("lock:product:" + productId);
2
try {
3
    if (lock.tryLock(5, 30, TimeUnit.SECONDS)) {   // 最多等 5 秒；拿到后锁 30 秒强制释放
4
        try {
5
            doDeductStock(productId);
6
        } finally {
7
            lock.unlock();
8
        }
9
    } else {
10
        throw new BusinessException("系统繁忙，请稍后重试");  // 抢锁失败，给用户友好提示
11
    }
12
} catch (InterruptedException e) {
13
    Thread.currentThread().interrupt();
14
}

5.2 实际项目中的封装方式#

在实际开发中，公司一般会把 Redisson 封装成自定义注解，你不会直接写上面的代码。最常见的封装方式是「自定义注解 + AOP」：通过注解声明锁，AOP 切面自动处理加锁和解锁，业务代码完全不感知锁的存在。以下是某项目的真实封装：

1
// 注解定义
2
@Target({ElementType.METHOD})
3
@Retention(RetentionPolicy.RUNTIME)
4
public @interface RedissonLock {
5
    /** 锁的 key，支持 SpEL 表达式，例如：keys = {"#orderId"} */
6
    String[] keys();
7
    /** key 前缀，默认用「类名:方法名」 */
8
    String prefix() default "";
9
    /** 锁超时时间（毫秒），默认 30000ms */
10
    long lockTimeout() default 0;
11
    /** 等待加锁超时时间（毫秒），0 表示不等待 */
12
    long waitTimeout() default 0;
13
}

1
// AOP 切面实现（核心逻辑）
2
@Aspect
3
@Component
4
public class RedissonLockAspect {
5

6
    private final RedissonClient redissonClient;
7

8
    @Around("@annotation(RedissonLock)")
9
    public Object around(ProceedingJoinPoint joinPoint) {
10
        Method targetMethod = ((MethodSignature) joinPoint.getSignature()).getMethod();
11
        RedissonLock annotation = targetMethod.getAnnotation(RedissonLock.class);
12

13
        // 1. 通过 SpEL 解析锁的 key（例如从参数中取 orderId）
14
        String lockKey = getLockKey(annotation.keys(), targetMethod, joinPoint.getArgs());
15
        String keyPrefix = targetMethod.getDeclaringClass().getName()
16
                         + ":" + targetMethod.getName();
17

18
        // 2. 获取锁
19
        RLock lock = redissonClient.getLock("lock:" + keyPrefix + ":" + lockKey);
20
        boolean lockFlag = false;
21
        Object proceed = null;
22
        try {
23
            // 3. 尝试加锁（带超时）
24
            lockFlag = lock.tryLock(annotation.waitTimeout(),
25
                                    annotation.lockTimeout(), TimeUnit.MILLISECONDS);
26
            if (lockFlag) {
27
                // 4. 获取成功，执行业务方法
28
                proceed = joinPoint.proceed();
29
            }
30
        } finally {
31
            if (lockFlag && lock.isHeldByCurrentThread()) {
32
                lock.unlock();
33
            }
34
        }
35
        // 5. 获取失败，抛异常（防重复提交）
36
        if (proceed == null) {
37
            throw new BusinessException("操作过于频繁，请稍后重试");
38
        }
39
        return proceed;
40
    }
41
}

使用时只需加一个注解：

1
@RedissonLock(keys = {"#orderId"}, waitTimeout = 5000, lockTimeout = 30000)
2
public void processOrder(String orderId) {
3
    // 业务逻辑，自动被分布式锁保护
4
}

4.1 本地事务 + 普通消息（最常用，但有隐患）#

这是企业里用得最多的一种方式。注意这里用的是 MQ 的「普通消息」，不是「事务消息」，所以会有一个先天的隐患，下面会专门讲。

实现思路：

代码示例（以 RocketMQ 为例）：

1）订单服务（生产者）——创建订单后发送扣库存消息

1
@Service
2
public class OrderServiceImpl implements OrderService {
3

4
    @Autowired
5
    private OrderMapper orderMapper;
6
    @Autowired
7
    private RocketMQTemplate rocketMQTemplate;
8

9
    @Transactional
10
    public void createOrder(Order order) {
11
        // 1. 写订单表（本地事务）
12
        orderMapper.insert(order);
13

14
        // 2. 发送消息到 MQ，通知商品服务扣库存
15
        StockMessage msg = new StockMessage();
16
        msg.setOrderId(order.getId());         // 带上订单 ID，消费端用于幂等校验和取消订单
17
        msg.setProductId(order.getProductId());
18
        msg.setQuantity(order.getQuantity());
19
        rocketMQTemplate.convertAndSend("topic-stock-deduct", msg);
20

21

22
        //其他业务逻辑
23
    }
24
}

2）商品服务（消费者）——收到消息后扣库存

1
@Component
2
@RocketMQMessageListener(
3
    topic = "topic-stock-deduct",           // 监听哪个 topic（和生产者发送时的 topic 一致）
4
    consumerGroup = "product-service-group" // 消费者组名：同一组内只有一台机器消费这条消息，避免重复消费
5
)
6
public class StockConsumer implements RocketMQListener<StockMessage> {
7

8
    @Autowired
9
    private ProductMapper productMapper;
10
    @Autowired
11
    private OrderClient orderClient;       // 回调订单服务，用于取消订单
12
    @Autowired
13
    private StringRedisTemplate redisTemplate;
14

15
    @Override
16
    public void onMessage(StockMessage msg) {
17
        // 【幂等校验】防止 MQ 重复投递导致库存被多扣
18
        // MQ 保证「至少一次」投递，不保证「恰好一次」，所以消费端必须自己做幂等
19
        String lockKey = "mq:stock:deducted:" + msg.getOrderId();
20
        Boolean alreadyDeducted = redisTemplate.opsForValue().setIfAbsent(lockKey, "1", 24, TimeUnit.HOURS);
21
        if (!Boolean.TRUE.equals(alreadyDeducted)) {
22
            log.info("订单{}已扣过库存，跳过重复消息", msg.getOrderId());
23
            return;  // 已处理过，直接返回
24
        }
25

26
        try {
27
            // 扣库存（SQL 里带 stock > 0 条件，原子操作防超卖）
28
            int rows = productMapper.deductStock(msg.getProductId(), msg.getQuantity());
29
            if (rows == 0) {
30
                // 库存不足是「业务异常」，不能靠 MQ 重试解决（重试再多库存还是不够）
31
                // 正确做法：走业务补偿 —— 通知订单服务取消这张订单
32
                redisTemplate.delete(lockKey);  // 清除标记，允许后续如果用户重新下单时能正常处理
33
                orderClient.cancelOrder(msg.getOrderId(), "库存不足");
34
                return;   // 正常返回，消息消费成功，不再重试
35
            }
36
        } catch (Exception e) {
37
            // 扣库存过程中发生异常（如数据库超时），清除幂等标记
38
            // 让 MQ 重试时能重新进入，否则 key 会把重试全部挡住
39
            redisTemplate.delete(lockKey);
40
            throw e;  // 抛出异常，触发 MQ 重试
41
        }
42
    }
43
}

3）消息体定义

1
@Data
2
@AllArgsConstructor
3
@NoArgsConstructor
4
public class StockMessage implements Serializable {
5
    private Long orderId;      // 订单 ID（用于幂等校验 + 取消订单）
6
    private Long productId;
7
    private Integer quantity;
8
}

⚠️ 必须知道的隐患：上面这段代码有一个经典坑——@Transactional 方法里直接调用 rocketMQTemplate.convertAndSend() 发消息。如果消息发出之后，本地事务因为后续代码抛异常而回滚了，会出现：本地数据没写入，但 MQ 消息已经发出去并被下游消费了，导致数据不一致。

关于消费端的幂等：MQ 默认会重试，所以消费端要做幂等处理（比如通过消息 ID 或业务 ID 去重），防止重复消费导致库存多扣。多次重试仍失败的消息会进入死信队列，需要人工介入。

优点：实现简单，服务间解耦 缺点：有上述”事务回滚但消息已发”的隐患；属于最终一致性，有少量延迟

4.2 本地消息表 + MQ（推荐）#

上面的方案有一个隐患：本地事务和消息发送不在同一个原子操作中。本地消息表就是用来解决这个问题的。

思路：不直接发 MQ 消息，而是先在本地数据库里写一条消息记录，和业务数据在同一个事务中，然后由定时任务扫描并发送。

流程：

1）消息表结构（参考）