Seata分布式事务原理及优势解析

在微服务架构中,各服务往往独立部署、独立数据库,涉及到一个业务场景时,可能需要多个服务/多个数据库的写操作,这就引出了“分布式事务”的概念。Seata(Simple Extensible Autonomous Transaction Architecture)是阿里巴巴开源的一套易于集成、高性能、可插拔的分布式事务解决方案。本文将深入剖析 Seata 的分布式事务原理、核心架构、典型流程,并配以代码示例和图解,帮助读者快速掌握 Seata 的使用及其技术优势。


目录

  1. 为什么需要分布式事务
  2. Seata简介与核心组件
  3. Seata架构与典型流程
    3.1. Seata 核心组件图解
    3.2. 事务发起与分支注册流程
    3.3. 分支执行与提交/回滚流程
  4. Seata 事务模式:AT 模式原理详解
    4.1. AT 模式的 Undo Log 机制
    4.2. 一阶段提交 (1PC) 与二阶段提交 (2PC)
    4.3. AT 模式的完整流程图解
  5. Seata 与 Spring Boot 集成示例
    5.1. 环境准备与依赖
    5.2. Seata 配置文件示例
    5.3. 代码示例:@GlobalTransactional 与业务代码
    5.4. RM(Resource Manager)配置与 Undo Log 表
  6. Seata的优势与使用注意事项
    6.1. 相比传统 2PC 的性能优势
    6.2. 轻量级易集成、支持多种事务模型
    6.3. 异常自动恢复与可观测性
    6.4. 注意谨慎场景与性能调优建议
  7. 总结

1. 为什么需要分布式事务

在单体应用中,数据库事务(ACID)可以保证在同一数据库的一系列操作要么全部成功、要么全部回滚。然而在微服务架构下,一个完整业务往往涉及多个服务,各自管理不同的数据源:

  • 场景举例:

    1. 用户下单服务(OrderService)需要写 orders 表;
    2. 库存服务(StockService)需要扣减 stock 表;
    3. 支付服务(PaymentService)需要写 payments 表;
    4. 可能还需要写日志、写配送信息等。

如果我们仅靠单库事务,无法跨服务保证一致性。比如在扣减库存之后,支付失败了,库存和订单就会出现不一致。这种场景就需要分布式事务来保证以下特性:

  • 原子性:多个服务/多个数据库的写操作要么都完成,要么都不生效。
  • 一致性:业务最终状态一致。
  • 隔离性:同一全局事务的并发执行对彼此保持隔离。
  • 持久性:事务提交后的数据在持久化层不会丢失。

Seata 正是为解决这类跨服务、跨数据库的事务一致性问题而设计的。


2. Seata简介与核心组件

Seata 是一个分布式事务解决方案,致力于提供高性能、易用、强一致性保障。其核心组件包括:

  1. TC(Transaction Coordinator)事务协调器

    • 负责维护全局事务(Global Transaction)状态(Begin → Commit/Rollback)
    • 为每个全局事务生成全局唯一 ID(XID)
    • 协同各分支事务(Branch)完成提交或回滚
    • 典型实现为独立进程,通过 gRPC/HTTP 与业务侧 TM 通信
  2. TM(Transaction Manager)事务管理器

    • 集成在业务应用(如 Spring Boot 服务)中
    • 通过 @GlobalTransactional 标注的方法开启全局事务(发送 Begin 请求给 TC)
    • 在执行本地业务方法时,为所依赖的数据库操作注册分支事务,发送 BranchRegister 给 TC
  3. RM(Resource Manager)资源管理器

    • 代理并拦截实际数据库连接(使用 DataSourceProxy 或 MyBatis 拦截器)
    • 在每个分支事务中,本地 SQL 执行前后插入 Undo Log,用于回滚时恢复
    • 当 TC 通知全局提交/回滚时,向数据库提交或回滚相应的分支

以下是 Seata 核心组件的简化架构图解:

┌───────────────────────────────────────────────────────────────────┐
│                           业务微服务 (Spring Boot)               │
│  ┌──────────────┐    ┌───────────────┐    ┌───────────────┐       │
│  │   TM 客户端   │    │   TM 客户端    │    │   TM 客户端    │       │
│  │  (事务管理)   │    │  (事务管理)    │    │  (事务管理)    │       │
│  └──────┬───────┘    └──────┬────────┘    └──────┬────────┘       │
│         │                    │                   │                │
│         │ GlobalBegin         │ GlobalBegin       │                │
│         ▼                    ▼                   ▼                │
│  ┌───────────────────────────────────────────────────────────┐     │
│  │                       Transaction Coordinator (TC)      │     │
│  └───────────────────────────────────────────┬───────────────┘     │
│              BranchCommit/BranchRollback    │                     │
│      ◄────────────────────────────────────────┘                     │
│                                                                      │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐            │
│  │    RM 实现     │    │    RM 实现     │    │    RM 实现     │            │
│  │ (DataSourceProxy)│  │ (MyBatis 拦截器) │  │  (RocketMQ 模块) │            │
│  └──────┬───────┘    └──────┬────────┘    └──────┬────────┘            │
│         │                   │                  │                     │
│         │ 本地数据库操作     │ 本地队列写入      │                     │
│         ▼                   ▼                  ▼                     │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐          │
│  │    DB (MySQL)  │  │   DB (Postgre) │  │  MQ (RocketMQ) │          │
│  │    Undo Log    │  │   Undo Log     │  │  本地事务     │          │
│  └────────────────┘  └────────────────┘  └────────────────┘          │
└───────────────────────────────────────────────────────────────────┘
  • TM:负责全局事务的开启/提交/回滚,向 TC 发起全局事务请求。
  • TC:充当协调者,维护全局事务状态,等待分支事务上报执行结果后,再统一 Commit/Rollback。
  • RM:在业务侧为每个分支事务生成并保存 Undo Log,当 TC 通知回滚时,根据 Undo Log 执行反向操作。

3. Seata架构与典型流程

3.1. Seata 核心组件图解

       ┌───────────────────────────────────────────────────────────────────┐
       │                            Global Transaction                    │
       │  ┌──────────────┐ 1. Begin  ┌──────────────┐ 2. BranchRegister      │
       │  │   TM 客户端   ├─────────▶│      TC      ├──────────────────────┐ │
       │  │(业务应用 A)   │          └───┬──────────┘                      │ │
       │  └──────────────┘   ◀──────────┴──────────┐                      │ │
       │       │                                   │                      │ │
       │       │ 3. BranchCommit/BranchRollback    │                      │ │
       │       ▼                                   │                      │ │
       │  ┌──────────────┐                         │                      │ │
       │  │    RM 模块    │                         │                      │ │
       │  │ (DB Proxy)   │                         │                      │ │
       │  └──────┬───────┘                         │                      │ │
       │         │ 4. 本地事务执行 & Undo Log 记录  │                      │ │
       │         ▼                                   │                      │ │
       │     ┌───────────┐                           │                      │ │
       │     │   DB (MySQL)│                           │                      │ │
       │     └───────────┘                           │                      │ │
       │                                             │                      │ │
       │  ┌──────────────┐   1. Begin   ┌──────────────┐  2. BranchRegister  │ │
       │  │   TM 客户端   ├─────────▶│      TC      ├──────────────────────┘ │
       │  │(业务应用 B)   │          └───┬──────────┘                        │ │
       │  └──────────────┘   ◀──────────┴──────────┐                        │ │
       │       │                                   │                        │ │
       │       │ 3. BranchCommit/BranchRollback    │                        │ │
       │       ▼                                   │                        │ │
       │  ┌──────────────┐                         │                        │ │
       │  │    RM 模块    │                         │                        │ │
       │  │ (DB Proxy)   │                         │                        │ │
       │  └──────┬───────┘                         │                        │ │
       │         │ 4. 本地事务执行 & Undo Log 记录  │                        │ │
       │         ▼                                   │                        │ │
       │     ┌───────────┐                           │                        │ │
       │     │   DB (MySQL)│                           │                        │ │
       │     └───────────┘                           │                        │ │
       └───────────────────────────────────────────────────────────────────┘
  1. 全局事务开始(GlobalBegin)

    • TM 客户端(业务方法被 @GlobalTransactional 标注)向 TC 发送 GlobalBegin 请求,TC 返回一个全局事务 ID(XID)。
  2. 分支注册(BranchRegister)

    • 客户端在执行业务操作时(如第一家服务写入订单表),RM 模块拦截 SQL,并向 TC 发送 BranchRegister 注册分支事务,TC 记录该分支事务 ID(Branch ID)。
  3. 分支执行(Local Transaction)

    • RM 拦截器执行本地数据库事务,并写入 Undo Log。完成后向 TC 汇报 BranchCommit(若成功)或 BranchRollback(若失败)。
  4. 全局事务提交/回滚(GlobalCommit/GlobalRollback)

    • 当业务方法执行完成,TM 客户端向 TC 发送 GlobalCommitGlobalRollback
    • GlobalCommit:TC 收集所有分支事务状态,只要所有分支都返回成功,TC 向各分支 RM 发送 BranchCommit,各 RM 执行本地提交(二阶段提交协议的第二阶段);
    • GlobalRollback:TC 向各分支 RM 发送 BranchRollback,RM 根据之前保存的 Undo Log 执行回滚。

3.2. 事务发起与分支注册流程

下面详细说明一次简单的两阶段提交流程(AT 模式)。

3.2.1 全局事务发起

业务A 的 Service 方法(被 @GlobalTransactional 注解)
  │
  │ GlobalBegin(XID) ───────────────────────────────────────────▶  TC
  │                                                            (生成 XID)
  │ ◀───────────────────────────────────────────────────────────
  │  继续执行业务逻辑
  • TM 客户端调用 GlobalBegin,TC 生成唯一 XID(如:127.0.0.1:8091:24358583)并返回。

3.2.2 分支事务注册

业务A 的 Service 调用 DAO 操作数据库
  │
  │ RM 拦截到 SQL(如 INSERT INTO orders ...)
  │
  │ BranchRegister(XID, ResourceID, LockKeys) ────────────────▶  TC
  │       (注册 "创建订单" 分支) 执行 SQL 并插入 Undo Log
  │ ◀───────────────────────────────────────────────────────────
  │  本地事务提交,向 TM 返回成功
  • RM 根据 DataSourceProxy 拦截到 SQL,先向 TC 发送分支注册请求,TC 返回一个 Branch ID。
  • RM 在本地数据库执行 SQL,并保存 Undo Log(插入或更新前的旧值)。
  • 完成本地提交后,RM 向 TC 报告分支提交 (BranchCommit),TC 对该分支标记“已就绪提交”。

3.3. 分支执行与提交/回滚流程

当全局事务中所有分支注册并就绪后,最终提交或回滚流程如下:

                           ↑       ▲
                           │       │ BranchCommit/BranchRollback
     ┌─────────────────┐   │       │
     │  TM 客户端调用   │   │       │
     │  GlobalCommit   │───┼───────┘
     └───────┬─────────┘   │
             │            │
             │ GlobalCommit
             ▼            │
           ┌─────────────────────────┐
           │        TC 判断所有分支已就绪,  │
           │    广播 Commit 请求给每个分支 RM  │
           └────────────┬────────────┘
                        │
              ┌─────────▼─────────┐
              │      RM1 (Resource)  │
              │  收到 BranchCommit   │
              │  执行本地事务提交    │
              └─────────┬─────────┘
                        │
              ┌─────────▼─────────┐
              │      RM2 (Resource)  │
              │  收到 BranchCommit   │
              │  执行本地事务提交    │
              └─────────┬─────────┘
                        │
               … 其他分支  … 
  • 全局提交阶段:TC 依次向每个分支 RM 发送 BranchCommit
  • RM 提交:各 RM 根据之前的 Undo Log,在本地完成真正的提交;
  • 回滚流程(若有分支失败或业务抛异常):TC 向所有分支发送 BranchRollback,各 RM 根据 Undo Log 回滚本地操作。

4. Seata 事务模式:AT 模式原理详解

Seata 支持多种事务模型(AT、TCC、SAGA、XA 等),其中最常用也是最简单易用的是 AT(Automatic Transaction)模式。它无需业务端显式编写 Try/Confirm/Cancel 方法,而是通过拦截 ORM 框架的 SQL,将原子操作记录到 Undo Log,从而实现对分支事务的回滚。

4.1. AT 模式的 Undo Log 机制

  • Undo Log 作用:在每个分支事务执行之前,RM 会根据 SQL 拦截到 Before-Image(旧值),并在本地数据库的 undo_log 表中插入一行 Undo Log,记录更新/删除前的旧数据库状态。
  • Undo Log 格式示例(MySQL 表):

    idbranch\_idrollback\_infolog\_statuslog\_createdlog\_modified
    124358583-1{"table":"orders","pk":"order\_id=1", "before":{"status":"0",...}}02021-01-012021-01-01
  • Undo Log 内容说明

    • branch_id:分支事务 ID,对应一次分支注册。
    • rollback_info:序列化后的 JSON/YAML 格式,包含要回滚的表名、主键条件以及 Before-Image 数据。
    • log_status:标识该 Undo Log 的状态(0:未回滚,1:已回滚)。
  • 写入时机:当 RM 拦截到 UPDATE orders SET status=‘1’ WHERE order_id=1 时,先执行类似:

    INSERT INTO undo_log(branch_id, rollback_info, log_status, log_created, log_modified)
    VALUES(24358583-1, '{"table":"orders","pk":"order_id=1","before":{"status":"0"}}', 0, NOW(), NOW())

    然后再执行:

    UPDATE orders SET status='1' WHERE order_id=1;
  • 回滚时机:如果全局事务需要回滚,TC 会向 RM 发送回滚请求,RM 按 undo_log 中的 rollback_info 逐条执行以下回滚 SQL:

    UPDATE orders SET status='0' WHERE order_id=1;
    UPDATE undo_log SET log_status=1 WHERE id=1;

4.2. 一阶段提交 (1PC) 与二阶段提交 (2PC)

  • 二阶段提交流程(Two-Phase Commit):

    1. 阶段1(Prepare 阶段):各分支事务执行本地事务,并告知 TC “准备就绪”(仅写 Undo Log,不提交);
    2. 阶段2(Commit/Rollback 阶段):TC 收到所有分支就绪后,广播 Commit/Rollback。若 Commit,各分支提交本地事务;若回滚,各分支读 Undo Log 进行回滚。
  • Seata AT 模式实际上是一种改良版的 2PC

    • 阶段1:在分支执行前,先写 Undo Log(相当于 Prepare),然后执行本地 UPDATE/DELETE/INSERT,最后提交该分支本地事务;
    • 阶段2:当 TC 通知 Commit 时,分支无需任何操作(因为本地已提交);当 TC 通知 Rollback 时,各分支读取 Undo Log 执行回滚。
    • 由于本地事务已经提交,AT 模式减少了一次本地事务的提交等待,性能优于传统 2PC。

4.3. AT 模式的完整流程图解

┌────────────────────────────────────────────────────────────────┐
│                         全局事务 TM 客户端                      │
│   @GlobalTransactional                                     │
│   public void placeOrder() {                                 │
│       orderService.createOrder();   // 分支1                    │
│       stockService.deductStock();   // 分支2                    │
│       paymentService.payOrder();    // 分支3                    │
│   }                                                        │
└────────────────────────────────────────────────────────────────┘
              │                 │                 │
1. Begin(XID)  │                 │                 │
──────────────▶│                 │                 │
              │                 │                 │
2. CreateOrder │                 │                 │
   BranchRegister(XID)           │                 │
              └────────────────▶│                 │
               Undo Log & Local SQL                │
              ◀─────────────────┘                 │
                                                  │
                              2. DeductStock       │
                              BranchRegister(XID)  │
                              └──────────────────▶│
                               Undo Log & Local SQL│
                              ◀────────────────────┘
                                                  │
                                          2. PayOrder 
                                          BranchRegister(XID)
                                          └───────────────▶
                                           Undo Log & Local SQL
                                          ◀───────────────┘
                                                  │
3. TM send GlobalCommit(XID)                     │
──────────────▶                                 │
              │                                  │
4. TC 广播 Commit 通知                            │
   BranchCommit(XID, branchId) ──▶ RM1           │
                                         (Undo Log 不生效)│
                                         分支已本地提交   │
                                                  │
                                      BranchCommit(XID, branchId) ──▶ RM2
                                         (Undo Log 不生效)  
                                         分支已本地提交
                                                  │
                                      BranchCommit(XID, branchId) ──▶ RM3
                                         (Undo Log 不生效)
                                         分支已本地提交
                                                  │
          │                                           │
          │ 全局事务结束                                                           
  • 分支执行阶段:每个分支执行时已完成本地数据库提交,仅在本地保留 Undo Log;
  • 全局提交阶段:TC 通知分支 Commit,各分支无需再做本地提交;
  • 回滚流程:若有一个分支执行失败或 TM 主动回滚,TC 通知所有分支 Rollback,各 RM 读取 Undo Log 反向执行恢复。

5. Seata 与 Spring Boot 集成示例

下面演示如何在 Spring Boot 项目中快速集成 Seata,并使用 AT 模式 完成分布式事务。

5.1. 环境准备与依赖

  1. 准备环境

    • JDK 1.8+
    • Maven
    • MySQL(用于存储业务表与 Seata 的 Undo Log 表)
    • 已部署好的 Seata Server(TC),可以直接下载 Seata 二进制包并启动
  2. Maven 依赖(在 Spring Boot pom.xml 中添加):

    <dependencies>
      <!-- Spring Boot Starter -->
      <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
      </dependency>
    
      <!-- Seata Spring Boot Starter -->
      <dependency>
        <groupId>io.seata</groupId>
        <artifactId>seata-spring-boot-starter</artifactId>
        <version>1.5.2</version> <!-- 根据最新版本替换 -->
      </dependency>
    
      <!-- MyBatis Spring Boot Starter(或 JPA、JdbcTemplate 根据实际) -->
      <dependency>
        <groupId>org.mybatis.spring.boot</groupId>
        <artifactId>mybatis-spring-boot-starter</artifactId>
        <version>2.2.0</version>
      </dependency>
    
      <!-- MySQL 驱动 -->
      <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>8.0.25</version>
      </dependency>
    </dependencies>
  3. Seata Server(TC)配置

    • 修改 Seata 解压目录下 conf/registry.conf 中:

      registry {
        type = "file"
        file {
          name = "registry.conf"
        }
      }
    • 修改 conf/registry.conf,指定注册中心类型(若使用 Nacos、etcd、ZooKeeper 可相应调整)。
    • 修改 conf/file.confservice.vgroup-mapping,配置业务应用对应的事务分组名称(dataSource 属性):

      vgroup_mapping.my_test_tx_group = "default"
    • 启动 Seata Server:

      sh bin/seata-server.sh

5.2. Seata 配置文件示例

在 Spring Boot application.yml 中添加 Seata 相关配置:

spring:
  application:
    name: order-service

  datasource:
    # 使用 Seata 提供的 DataSourceProxy
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/order_db?useUnicode=true&characterEncoding=utf-8&serverTimezone=UTC
    username: root
    password: 123456
    # Seata 需要的属性
    seata:
      tx-service-group: my_test_tx_group  # 与 file.conf 中 vgroup_mapping 的 key 一致

mybatis:
  mapper-locations: classpath*:/mappers/**/*.xml
  type-aliases-package: com.example.demo.model

# Seata 客户端配置
seata:
  enabled: true
  application-id: order-service
  tx-service-group: my_test_tx_group
  service:
    vgroup-mapping:
      my_test_tx_group: "default"
  client:
    rm:
      retry-count: 5
      rm-async-commit-buffer-limit: 10000
  registry:
    type: file
    file:
      name: registry.conf
  config:
    type: file
    file:
      name: file.conf
  • tx-service-group:全局事务分组名称,需要与 Seata Server 的配置文件中的 vgroup_mapping 对应。
  • application-id:业务应用的唯一标识。
  • registryconfig:指定注册中心与配置中心类型及所在的文件路径。

5.3. 代码示例:@GlobalTransactional 与业务代码

  1. 主配置类

    @SpringBootApplication
    @EnableTransactionManagement
    public class OrderServiceApplication {
        public static void main(String[] args) {
            SpringApplication.run(OrderServiceApplication.class, args);
        }
    }
  2. 数据源代理

    在 Spring Boot DataSource 配置中使用 Seata 的 DataSourceProxy

    @Configuration
    public class DataSourceProxyConfig {
    
        @Bean
        @ConfigurationProperties(prefix = "spring.datasource")
        public DataSource druidDataSource() {
            return new com.alibaba.druid.pool.DruidDataSource();
        }
    
        @Bean("dataSource")
        public DataSource dataSourceProxy(DataSource druidDataSource) {
            // 包装为 Seata 的 DataSourceProxy
            return new io.seata.rm.datasource.DataSourceProxy(druidDataSource);
        }
    
        // MyBatis 配置 DataSource 为 DataSourceProxy
        @Bean
        public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception {
            SqlSessionFactoryBean factoryBean = new SqlSessionFactoryBean();
            factoryBean.setDataSource(dataSource);
            // 其他配置略...
            return factoryBean.getObject();
        }
    }
  3. Undo Log 表

    在业务数据库中,需要有 Seata 默认的 Undo Log 表:

    CREATE TABLE `undo_log` (
      `id` BIGINT(20) NOT NULL AUTO_INCREMENT,
      `branch_id` BIGINT(20) NOT NULL,
      `xid` VARCHAR(100) NOT NULL,
      `context` VARCHAR(128) NULL,
      `rollback_info` LONG BLOB NOT NULL,
      `log_status` INT(11) NOT NULL,
      `log_created` DATETIME NOT NULL,
      `log_modified` DATETIME NOT NULL,
      PRIMARY KEY (`id`),
      UNIQUE KEY `ux_undo_branch_xid` (`xid`,`branch_id`)
    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
  4. 业务 Service 示例

    @Service
    public class OrderService {
    
        @Autowired
        private OrderMapper orderMapper;
    
        @Autowired
        private StockFeignClient stockFeignClient;
    
        @Autowired
        private PaymentFeignClient paymentFeignClient;
    
        /**
         * 使用 @GlobalTransactional 标注开启全局分布式事务
         */
        @GlobalTransactional(name = "order-create-tx", rollbackFor = Exception.class)
        public void createOrder(Order order) {
            // 1. 保存订单表
            orderMapper.insert(order);
    
            // 2. 扣减库存(远程调用库存服务)
            stockFeignClient.deduct(order.getProductId(), order.getQuantity());
    
            // 3. 扣减余额(远程调用支付服务)
            paymentFeignClient.pay(order.getUserId(), order.getAmount());
        }
    }
    • createOrder 方法开始时,Seata TM 会向 TC 发送 GlobalBegin,获取 XID;
    • 在保存订单时,RM(DataSourceProxy)会拦截并向 TC 注册分支事务,写 Undo Log;
    • 当调用库存和支付服务时,分别在远程服务中重复同样的流程(各自将本地数据库代理给 Seata ),注册分支并写 Undo Log;
    • 方法最后若无异常,TM 向 TC 发送 GlobalCommit,TC 广播 BranchCommit 给各分支 RM;
    • 若中途抛异常,TM 会自动向 TC 发送 GlobalRollback,TC 广播 BranchRollback,各 RM 根据 Undo Log 回滚本地数据。

6. Seata的优势与使用注意事项

6.1. 相比传统 2PC 的性能优势

  • 传统 2PC:每个分支在 Prepare 阶段要预写数据并锁表/锁行,等待全局确认后再执行真实提交或回滚,会产生两次本地事务提交,性能较差。
  • Seata AT 模式:只在分支中执行一次本地提交,并在本地保存 Undo Log,属于“改良版 2PC”,只有在全局回滚时才执行回滚操作,提交路径减少了一次阻塞点。
  • 性能提升:由于减少一次本地事务提交,且将回滚逻辑延后,Seata AT 相较传统 2PC 性能有明显提升。

6.2. 轻量级易集成、支持多种事务模型

  • Spring Boot 一行配置:通过添加 seata-spring-boot-starter、注解 @GlobalTransactional,即可快速开启分布式事务。
  • 支持多种事务模型:除 AT 模式外,还支持 TCC(Try-Confirm-Cancel)、SAGA、XA 等,满足不同业务粒度的一致性需求。

6.3. 异常自动恢复与可观测性

  • 自动恢复:如果某个分支节点宕机,TC 会周期性扫描未完成的分支事务,触发重试或重新回滚。
  • 可观测性:Seata 提供配置项可开启日志收集、监控指标,对事务的提交/回滚过程进行全链路追踪,便于排查问题。

6.4. 注意谨慎场景与性能调优建议

  • 长事务慎用:AT 模式会长时间锁定行,若事务长时间挂起,可能导致热点行锁等待。
  • Undo Log 表膨胀:高并发写入时,Undo Log 会快速增长,应及时清理或触发 GC。
  • 数据库压力监控:由于 Seata 会多写 Undo Log 表,业务表写入压力会增加,需要做好数据库垂直或水平扩展规划。
  • 网络延迟:TC 与 TM、RM 之间依赖网络通信,需保证网络可靠低延迟。

7. 总结

本文从分布式事务的需求出发,系统介绍了 Seata 的核心架构、AT 模式原理、Undo Log 机制、典型的两阶段提交流程,并通过 Spring Boot 集成示例演示了 Seata 的落地方案。Seata 通过在分支事务中“先提交本地、后统一提交或回滚” 的方式,相比传统 2PC,在性能和可用性上具有显著优势。同时,Seata 支持多种事务模型,并提供异步恢复、可观测性等特性,非常适合微服务架构下的跨服务、跨数据库一致性场景。

  • Seata 优势

    1. 性能更优:AT 模式减少一次本地提交,降低事务开销;
    2. 易集成:Spring Boot 一键式接入;
    3. 支持多模型:AT、TCC、SAGA、XA;
    4. 自动恢复:TC 定期扫描分支状态并自动重试/补偿;
    5. 可观测性:事务日志、监控指标、调用链追踪。

在实际生产环境中,请结合业务场景(事务长度、并发压力、数据库类型等)合理选择 Seata 模式,做好数据库性能监控与合理分库分表,才能充分发挥 Seata 的优势,保障系统的高可用与数据一致性。

MyBatis Plus自动映射失败深度解析:解决数据库表与实体类不匹配问题

在使用 MyBatis Plus 进行数据访问时,往往可以借助其“自动映射”功能,省去大量手动编写 ResultMap@Result 的工作。但在实际开发中,我们常常会遇到“实体类与数据库表字段不完全匹配,导致自动映射失败”的尴尬场景。本文将从原理出发,结合代码示例和图解,详细讲解导致映射失败的常见原因,并给出相应的解决方案。通过阅读,你将系统地理解 MyBatis Plus 的映射规则,学会快速定位与修复实体类与表结构不匹配的问题。


目录

  1. MyBatis Plus 自动映射原理概述
  2. 常见导致自动映射失败的原因
    2.1. 命名策略不一致(下划线 vs 驼峰)
    2.2. 实体字段与表字段类型不匹配
    2.3. 字段缺失或多余
    2.4. 未配置或配置错误的注解
    2.5. 全局配置干扰
  3. 案例一:下划线字段与驼峰属性映射失败分析
    3.1. 问题再现:表结构 & 实体代码
    3.2. MyBatis Plus 默认命名策略
    3.3. 失败原因图解与日志分析
    3.4. 解决方案:开启驼峰映射或手动指定字段映射
  4. 案例二:字段类型不兼容导致映射失败
    4.1. 问题再现:表中 tinyint(1) 对应 Boolean
    4.2. MyBatis Plus TypeHandler 原理
    4.3. 解决方案:自定义或使用内置 TypeHandler
  5. 案例三:注解配置不当导致主键识别失败
    5.1. 问题再现:@TableId 配置错误或遗漏
    5.2. MyBatis Plus 主键策略识别流程
    5.3. 解决方案:正确使用 @TableId@TableName@TableField
  6. 全局配置与自动映射的配合优化
    6.1. 全局启用驼峰映射
    6.2. 全局字段前缀/后缀过滤
    6.3. Mapper XML 与注解映射的配合
  7. 工具与调试技巧
    7.1. 查看 SQL 日志与返回列
    7.2. 使用 @TableField(exist = false) 忽略非表字段
    7.3. 利用 IDE 快速生成映射代码
  8. 总结与最佳实践

1. MyBatis Plus 自动映射原理概述

MyBatis Plus 在执行查询时,会根据返回结果的列名(ResultSetMetaData 中的列名)与实体类的属性名进行匹配。例如,数据库表有列 user_name,实体类有属性 userName,如果开启了驼峰映射(map-underscore-to-camel-case = true),则 MyBatis Plus 会将 user_name 转换为 userName 并注入到实体中。其基本流程如下:

┌───────────────────────────────┐
│       执行 SQL 查询            │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ JDBC 返回 ResultSet (列名:C)  │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ MyBatis Plus 读取列名 (C)      │
│  1. 若驼峰映射开启:            │
│     将 “下划线” 转换为驼峰       │
│  2. 找到与实体属性 (P) 对应的映射 │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ 调用 Setter 方法,将值注入到 P│
└───────────────────────────────┘

若 C 与 P 无法匹配,MyBatis Plus 就不会调用对应的 Setter,导致该属性值为 null 或默认值。本文将围绕这个匹配过程,深入分析常见问题及解决思路。


2. 常见导致自动映射失败的原因

下面列举常见的几类问题及简要描述:

2.1 命名策略不一致(下划线 vs 驼峰)

  • 表字段 使用 user_name,而实体属性usernameuserName
  • 未开启 map-underscore-to-camel-case 驼峰映射,导致 user_name 无法匹配 userName
  • 开启驼峰映射 却在注解上自定义了不同的列名,导致规则冲突。

2.2 实体字段与表字段类型不匹配

  • SQL 类型:如表中字段是 tinyint(1),实体属性是 Boolean;MyBatis 默认可能将其映射为 ByteInteger
  • 大数类型bigint 对应到 Java 中可能为了精度使用 LongBigInteger,却在实体中写成了 Integer
  • 枚举类型:数据库存储字符串 “MALE / FEMALE”,实体枚举类型不匹配,导致赋值失败。

2.3 字段缺失或多余

  • 表删除或在新增字段后,忘记在实体类中添加对应属性,导致查询时列未能映射到实体。
  • 实体存在非表字段:需要用 @TableField(exist = false) 忽略,否则映射引擎会报错找不到列。

2.4 未配置或配置错误的注解

  • @TableName:如果实体类与表名不一致,未使用 @TableName("real_table") 指定真实表名。
  • @TableField(value = "xxx"):当字段名与实体属性不一致时,需要手动指定,否则自动策略无法匹配。
  • @TableId:主键映射或 ID 策略配置不正确,导致插入或更新异常。

2.5 全局配置干扰

  • 全局驼峰映射关闭application.yml 中未开启 mybatis-plus.configuration.map-underscore-to-camel-case=true
  • 字段前缀/后缀过滤:全局配置了 tableFieldUnderlinecolumnLabelUpper 等参数,影响映射规则。

3. 案例一:下划线字段与驼峰属性映射失败分析

3.1 问题再现:表结构 & 实体代码

假设数据库中有如下表 user_info

CREATE TABLE user_info (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_name VARCHAR(50),
  user_age INT,
  create_time DATETIME
);

而对应的实体类 UserInfo 写为:

package com.example.demo.entity;

import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import java.time.LocalDateTime;

@TableName("user_info")
public class UserInfo {
    @TableId
    private Long id;

    private String userName;
    private Integer userAge;

    // 忘记添加 createTime 字段
    // private LocalDateTime createTime;

    // getters & setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }

    public String getUserName() { return userName; }
    public void setUserName(String userName) { this.userName = userName; }

    public Integer getUserAge() { return userAge; }
    public void setUserAge(Integer userAge) { this.userAge = userAge; }
}

此时我们执行查询:

import com.example.demo.entity.UserInfo;
import com.example.demo.mapper.UserInfoMapper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.List;

@Service
public class UserService {
    @Autowired
    private UserInfoMapper userInfoMapper;

    public List<UserInfo> listAll() {
        return userInfoMapper.selectList(null);
    }
}
  • 预期userName 对应 user_nameuserAge 对应 user_age,并将 create_time 映射到一个属性。
  • 实际结果userNameuserAge 的值正常,但 createTime 未定义在实体中,MyBatis Plus 将忽略该列;如果驼峰映射未开启,甚至 userNameuserAge 都会是 null

3.2 MyBatis Plus 默认命名策略

MyBatis Plus 默认使用的命名策略(NamingStrategy.underline_to_camel)会对列名进行下划线转驼峰。但前提条件是在全局配置中或注解中启用该转换:

# application.yml
mybatis-plus:
  configuration:
    # 开启下划线转驼峰映射(驼峰命名)
    map-underscore-to-camel-case: true

如果未配置上面的项,MyBatis Plus 不会对列名做任何转换,从而无法将 user_name 映射到 userName

3.3 失败原因图解与日志分析

┌───────────────────────────────┐
│       查询结果列列表           │
│  [id, user_name, user_age,    │
│   create_time]                │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ MyBatis Plus自动映射引擎      │
│  1. 读取列名 user_name         │
│  2. 未开启驼峰映射,保持原样   │
│  3. 在实体 UserInfo 中查找属性  │
│     getUser_name() 或 user_name │
│  4. 找不到,跳过该列           │
│  5. 下一个列 user_age 类似处理   │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ 映射结果:                     │
│  id=1, userName=null,         │
│  userAge=null,                │
│  (create_time 忽略)           │
└───────────────────────────────┘

日志示例(Spring Boot 启用 SQL 日志级别为 DEBUG):

DEBUG com.baomidou.mybatisplus.core.MybatisConfiguration - MappedStatement(id=... selectList, ...) does not have property: user_name
DEBUG com.baomidou.mybatisplus.core.MybatisConfiguration - MappedStatement(id=... selectList, ...) does not have property: user_age
DEBUG com.baomidou.mybatisplus.core.MybatisConfiguration - MappedStatement(id=... selectList, ...) does not have property: create_time

3.4 解决方案:开启驼峰映射或手动指定字段映射

3.4.1 方案1:全局开启驼峰映射

application.yml 中加入:

mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true

此时,MyBatis Plus 会执行下划线 → 驼峰转换,user_nameuserName。同时,需要在实体中增加 createTime 字段:

private LocalDateTime createTime;

public LocalDateTime getCreateTime() { return createTime; }
public void setCreateTime(LocalDateTime createTime) { this.createTime = createTime; }

3.4.2 方案2:手动指定字段映射

如果不想全局启用驼峰映射,也可在实体类中针对每个字段使用 @TableField 显式指定列名:

@TableName("user_info")
public class UserInfo {
    @TableId
    private Long id;

    @TableField("user_name")
    private String userName;

    @TableField("user_age")
    private Integer userAge;

    @TableField("create_time")
    private LocalDateTime createTime;

    // getters & setters...
}

此时就不依赖全局命名策略,而是用注解进行精确匹配。


4. 案例二:字段类型不兼容导致映射失败

4.1 问题再现:表中 tinyint(1) 对应 Boolean

在 MySQL 数量中,常常使用 tinyint(1) 存储布尔值,例如:

CREATE TABLE product (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  name VARCHAR(100),
  is_active TINYINT(1)  -- 0/1 存布尔
);

如果在实体类中直接写成 private Boolean isActive;,MyBatis Plus 默认会尝试将 tinyint(1) 映射成 IntegerByte,而无法自动转换为 Boolean,导致字段值为 null 或抛出类型转换异常。

4.2 MyBatis Plus TypeHandler 原理

MyBatis Plus 使用 MyBatis 底层的 TypeHandler 机制来完成 JDBC 类型与 Java 类型之间的转换。常见的内置 Handler 包括:

  • IntegerTypeHandler:将整数列映射到 Integer
  • LongTypeHandler:将 BIGINT 映射到 Long
  • BooleanTypeHandler:将 JDBC BIT / BOOLEAN 映射到 Java Boolean
  • ByteTypeHandlerShortTypeHandler 等。

MyBatis Plus 默认注册了部分常用 TypeHandler,但对 tinyint(1)Boolean 并不默认支持(MySQL 驱动会将 tinyint(1) 视为 Boolean,但在不同版本或不同配置下可能不生效)。所以需要显式指定或自定义 Handler。

4.3 解决方案:自定义或使用内置 TypeHandler

4.3.1 方案1:手动指定 @TableFieldtypeHandler

import org.apache.ibatis.type.JdbcType;
import org.apache.ibatis.type.BooleanTypeHandler;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;

@TableName("product")
public class Product {
    @TableId
    private Long id;

    private String name;

    @TableField(value = "is_active", jdbcType = JdbcType.TINYINT, typeHandler = BooleanTypeHandler.class)
    private Boolean isActive;

    // getters & setters...
}
  • jdbcType = JdbcType.TINYINT:告知 MyBatis 列类型为 TINYINT
  • typeHandler = BooleanTypeHandler.class:使用 MyBatis 内置的 BooleanTypeHandler,将 0/1 转换为 false/true

4.3.2 方案2:全局注册自定义 TypeHandler

如果项目中有大量 tinyint(1)Boolean 的转换需求,可以在全局配置中加入自定义 Handler。例如,创建一个 TinyintToBooleanTypeHandler

import org.apache.ibatis.type.BaseTypeHandler;
import org.apache.ibatis.type.JdbcType;
import java.sql.*;

public class TinyintToBooleanTypeHandler extends BaseTypeHandler<Boolean> {
    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, Boolean parameter, JdbcType jdbcType) throws SQLException {
        ps.setInt(i, parameter ? 1 : 0);
    }

    @Override
    public Boolean getNullableResult(ResultSet rs, String columnName) throws SQLException {
        int value = rs.getInt(columnName);
        return value != 0;
    }

    @Override
    public Boolean getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
        int value = rs.getInt(columnIndex);
        return value != 0;
    }

    @Override
    public Boolean getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
        int value = cs.getInt(columnIndex);
        return value != 0;
    }
}

然后在 MyBatis 配置中全局注册:

mybatis-plus:
  configuration:
    type-handlers-package: com.example.demo.typehandler

这样,当 MyBatis Plus 扫描到该包下的 TinyintToBooleanTypeHandler,并结合对应的 jdbcType,会自动触发映射。


5. 案例三:注解配置不当导致主键识别失败

5.1 问题再现:@TableId 配置错误或遗漏

假如有如下表 order_info,主键为 order_id,且采用自增策略:

CREATE TABLE order_info (
  order_id BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id BIGINT,
  total_price DECIMAL(10,2)
);

而实体类定义为:

@TableName("order_info")
public class OrderInfo {
    // 少写了 @TableId
    private Long orderId;

    private Long userId;
    private BigDecimal totalPrice;

    // getters & setters...
}
  • 问题:MyBatis Plus 无法识别主键,默认会根据 id 字段查找或使用全表查询,然后更新/插入策略混乱。
  • 后果:插入时无法拿到自增主键,执行 updateById 会出现 WHERE id = ? 却找不到对应列,导致 SQL 异常或无效。

5.2 MyBatis Plus 主键策略识别流程

MyBatis Plus 在执行插入操作时,如果实体类中没有明确指定 @TableId,会:

  1. 尝试查找:判断实体类中是否有属性名为 id 的字段,并将其视作主键。
  2. 若无,就无法正确拿到自增主键,会导致 INSERT 后无主键返回,或使用雪花 ID 策略(如果全局配置了)。

在更新时,如果 @TableId 未配置,会尝试从实体的 id 属性获取主键值,导致找不到列名 id 报错。

5.3 解决方案:正确使用 @TableId@TableName@TableField

正确的实体应该写成:

package com.example.demo.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import java.math.BigDecimal;

@TableName("order_info")
public class OrderInfo {

    @TableId(value = "order_id", type = IdType.AUTO)
    private Long orderId;

    private Long userId;
    private BigDecimal totalPrice;

    // getters & setters...
}
  • @TableId(value = "order_id", type = IdType.AUTO)

    • value = "order_id":指定实际的表主键列名;
    • type = IdType.AUTO:使用数据库自增策略。

如果实体属性名与列名不一致,需使用 @TableField 指定:

@TableField("total_price")
private BigDecimal totalPrice;

6. 全局配置与自动映射的配合优化

在实际项目中,各种小错误可能会互相干扰。下面介绍一些常用的全局配置与优化方案。

6.1 全局启用驼峰映射

application.yml 中添加:

mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true

效果: 所有查询结果列名如 create_timeuser_name 都会自动映射到实体属性 createTimeuserName

6.2 全局字段前缀/后缀过滤

如果表中有公共字段前缀(如 tb_user_name)而实体属性不加前缀,可以在注解或全局策略中进行过滤。例如:

mybatis-plus:
  global-config:
    db-config:
      table-prefix: tb_   # 全局去除表名前缀
      field-strategy: not_empty

6.3 Mapper XML 与注解映射的配合

有时自动映射无法满足复杂场景,可结合 XML 手动编写 ResultMap

<resultMap id="UserInfoMap" type="com.example.demo.entity.UserInfo">
    <id property="id" column="id" />
    <result property="userName" column="user_name" />
    <result property="userAge" column="user_age" />
    <result property="createTime" column="create_time" />
</resultMap>

<select id="selectAll" resultMap="UserInfoMap">
    SELECT id, user_name, user_age, create_time FROM user_info
</select>

在 Mapper 接口中调用 selectAll() 即可准确映射:

List<UserInfo> selectAll();

7. 工具与调试技巧

以下技巧可帮助你快速定位映射失败的问题:

7.1 查看 SQL 日志与返回列

application.yml 中开启 MyBatis Plus SQL 日志:

logging:
  level:
    com.baomidou.mybatisplus: debug
    org.apache.ibatis: debug

启动后,在控制台可以看到:

  • 最终执行的 SQL:帮助确认查询语句。
  • 返回列名:MyBatis 会打印 “不匹配的列” 信息,如 does not have property: user_name,可据此定位实体与列不一致处。

7.2 使用 @TableField(exist = false) 忽略非表字段

如果实体类中包含业务特有字段,不对应数据库列,可在属性上加上:

@TableField(exist = false)
private String transientField;

这样 MyBatis Plus 在映射时会忽略该属性,不会报错找不到对应列。

7.3 利用 IDE 快速生成映射代码

工具如 IntelliJ IDEA 的 MyBatis Plus 插件或 MyBatis Generator 可以根据数据库表结构自动生成实体、Mapper 接口和 XML 文件,减少手写注解或 ResultMap 的工作量。


8. 总结与最佳实践

通过本文的分析与多个案例演示,我们可以总结如下最佳实践,以避免或快速定位 MyBatis Plus 自动映射失败的问题:

  1. 统一命名规范

    • 数据库表字段使用下划线分隔,Java 实体属性使用驼峰命名,并开启全局驼峰映射 map-underscore-to-camel-case=true
    • 若命名风格特殊,务必在实体上使用 @TableField(value = "...") 指定对应列名。
  2. 主键与表名注解

    • 对于实体与表名不一致的情况,必须显式加上 @TableName("real_table_name")
    • 对于主键字段,务必使用 @TableId(value="col", type=IdType.XXX) 正确指定列名与主键策略。
  3. TypeHandler 匹配

    • 注意数据库字段类型与实体属性类型的匹配,特别是布尔字段、时间类型、JSON 类型等。
    • 如有需要,自定义或指定合适的 TypeHandler 进行转换。
  4. 忽略无关字段

    • 实体中非数据库列字段必须加 @TableField(exist = false),避免映射引擎抛出“找不到对应列”的错误。
  5. 日志调试

    • 开启 MyBatis Plus 与 MyBatis 的 DEBUG 日志,查看不匹配列和映射过程,有助于快速定位问题。
  6. 组合使用 XML 与注解

    • 对于过于复杂的查询或特殊映射,可借助 XML 自定义 ResultMap,手动指定列到属性的映射关系。
  7. 保持表结构与实体同步

    • 开发过程中尽量采用代码生成工具或严格的同步流程,避免表字段变更后忘记更新实体,造成映射失败。

通过遵循上述原则,并灵活运用 MyBatis Plus 提供的注解与配置,你可以快速解决大多数“自动映射失败”的问题,最大程度上发挥 MyBatis Plus 自动化特性,提升开发效率。

Redis实战篇:深入探索分布式锁的应用

在微服务与分布式系统中,多个进程或节点需要协调访问共享资源。如何保证在并发环境下,只有一个客户端能够对某个资源进行操作,是架构设计的一项重要挑战。分布式锁正是为了解决这一类问题而存在。作为一个高性能的内存数据库,Redis 以其原子命令和丰富的数据结构,天然适合用于实现分布式锁。本文将通过代码示例、图解与详细说明,帮助你从零开始掌握 Redis 分布式锁的原理与最佳实践。


目录

  1. 分布式锁概述
  2. 基于 SETNX 的简易分布式锁

    • 2.1 SETNX 原理与语义
    • 2.2 Java 代码示例(Jedis)
    • 2.3 存在的问题:死锁与误删
  3. 使用 Lua 脚本保证原子性与安全释放

    • 3.1 Lua 脚本原理解析
    • 3.2 Java 调用 Lua 脚本示例(Spring Data Redis)
    • 3.3 流程图解:加锁与解锁的时序
  4. Redisson:生产级分布式锁方案

    • 4.1 Redisson 简介
    • 4.2 Java 示例:使用 Redisson 实现公平锁与可重入锁
  5. 分布式锁常见应用场景

    • 5.1 限流与排队
    • 5.2 分布式任务调度
    • 5.3 资源抢购与秒杀系统
  6. 分布式锁的性能与注意事项

    • 6.1 锁粒度与加锁时长控制
    • 6.2 避免单点故障:哨兵与集群模式
    • 6.3 看门狗(Watchdog)机制与续期
  7. 完整实战示例:秒杀场景下的库存扣减

    • 7.1 需求描述与设计思路
    • 7.2 Lua 脚本实现原子库存扣减
    • 7.3 Java 端集成与高并发测试
  8. 总结与最佳实践

分布式锁概述

在单机程序中,我们常常使用操作系统提供的互斥锁(如 Java 中的 synchronizedReentrantLock)来保证同一 JVM 内线程对共享资源的互斥访问。但是在微服务架构下,往往多个服务实例部署在不同的机器或容器上,进程间无法直接使用 JVM 锁机制。此时,需要借助外部组件来协调——这就是分布式锁的用途。

分布式锁的核心目标

  1. 互斥(Mutual Exclusion)
    任意时刻,只有一个客户端持有锁,其他客户端无法同时获得锁。
  2. 可重入(Reentrancy,可选)
    如果同一客户端在持有锁的情况下再次请求锁,应当允许(可重入锁);否则可能陷入死锁。
  3. 阻塞与非阻塞

    • 阻塞式:若获取锁失败,客户端会阻塞、等待;
    • 非阻塞式:若获取锁失败,直接返回失败,让客户端决定重试或退出。
  4. 防止死锁
    若客户端在持有锁后崩溃或网络抖动导致无法释放锁,必须有过期机制自动释放,以避免其他客户端永远无法获取。
  5. 高可用与性能
    分布式锁的实现需要具备高可用性,不能成为系统瓶颈;在并发量非常高的场景下,需要保证性能足够好。

Redis 为分布式锁提供了天然支持:

  • 原子性命令(如 SETNXDEL 等)可用作加锁与解锁;
  • 内置过期时间(TTL),可避免死锁;
  • Lua 脚本可以将多步操作封装为原子执行;
  • 有成熟的客户端库(如 Redisson)封装了可靠的分布式锁机制。

接下来,我们将一步步深入,从最简单的 SETNX 实现,到 Lua 脚本优化,再到生产级 Redisson 应用,全面掌握 Redis 分布式锁的实践方法。


基于 SETNX 的简易分布式锁

最基础的分布式锁思路是:客户端使用 Redis 命令 SETNX key value(SET if Not eXists)尝试创建一个锁标识。当 SETNX 返回 1 时,表示锁成功获取;当返回 0 时,表示锁已被其他客户端持有,需要重试或直接失败。

2.1 SETNX 原理与语义

  • 语法

    SETNX lock_key client_id
    • lock_key:锁对应的 Redis 键;
    • client_id:唯一标识当前客户端或线程(通常使用 UUID 或 IP+线程ID)。
  • 返回值

    • 如果 lock_key 不存在,Redis 会将其设置为 client_id,并返回 1
    • 如果 lock_key 已存在,什么都不做,返回 0
  • 加锁示例

    > SETNX my_lock "client_123"
    1   # 表示加锁成功
    > SETNX my_lock "client_456"
    0   # 表示加锁失败,my_lock 已被 "client_123" 持有

由于 SETNX 具有原子性,多客户端并发执行时只有一个会成功,满足最基本的互斥需求。

但是,光用 SETNX 还不足够。假设客户端 A 成功设置了锁,但在执行业务逻辑前崩溃或网络中断,锁永远不会被删除,导致后续客户端一直阻塞或失败,出现“死锁”问题。为了解决这一点,需要为锁设置过期时间(TTL),在客户端未正常释放时,由 Redis 自动删除锁键。

Redis 2.6.12 之后推荐使用 SET 命令带上参数 NX(只在键不存在时设置)和 PX(设置过期时间,毫秒级),以原子方式完成“加锁+设置过期”两步操作:

SET lock_key client_id NX PX 5000
  • NX:当且仅当 lock_key 不存在时,才执行设置;
  • PX 5000:将 lock_key 的过期时间设为 5000 毫秒(即 5 秒)。

这种写法避免了先 SETNXEXPIRE 可能出现的竞态问题(在 SETNXEXPIRE 之间 Redis 异常导致锁没有过期时间)。

2.2 Java 代码示例(Jedis)

下面用 Jedis 客户端演示基于 SET NX PX 的简易分布式锁:

import redis.clients.jedis.Jedis;
import redis.clients.jedis.params.SetParams;

import java.util.UUID;

public class SimpleRedisLock {

    private Jedis jedis;
    private String lockKey;
    private String clientId;         // 唯一标识,确保解锁安全
    private int expireTimeMillis;    // 锁超时时间(毫秒)

    public SimpleRedisLock(Jedis jedis, String lockKey, int expireTimeMillis) {
        this.jedis = jedis;
        this.lockKey = lockKey;
        this.clientId = UUID.randomUUID().toString();
        this.expireTimeMillis = expireTimeMillis;
    }

    /**
     * 尝试获取锁
     *
     * @return true 表示加锁成功;false 表示加锁失败
     */
    public boolean tryLock() {
        SetParams params = new SetParams();
        params.nx().px(expireTimeMillis);
        String result = jedis.set(lockKey, clientId, params);
        return "OK".equals(result);
    }

    /**
     * 释放锁(非安全方式:直接 DEL)
     */
    public void unlockUnsafe() {
        jedis.del(lockKey);
    }

    /**
     * 释放锁(安全方式:检查 value 再删除)
     *
     * @return true 表示释放成功;false 表示未释放(可能锁已过期或非自己的锁)
     */
    public boolean unlockSafe() {
        String value = jedis.get(lockKey);
        if (clientId.equals(value)) {
            jedis.del(lockKey);
            return true;
        }
        return false;
    }
}
  • 构造函数中,为当前客户端生成唯一的 clientId,用来在解锁时验证自身持有锁的合法性。
  • tryLock() 方法使用 jedis.set(lockKey, clientId, nx, px) 原子地完成“加锁 + 过期设置”。
  • unlockUnsafe() 直接 DEL,无法防止客户端误删其他客户端的锁。
  • unlockSafe()GET 判断值是否与 clientId 相同,只有相同时才 DEL,避免误删他人锁。但这段逻辑并非原子,存在并发风险:

    • A 客户端执行 GET,发现和自身 clientId 相同;
    • 在 A 调用 DEL 之前,锁意外过期,B 客户端重新获得锁并设置了新的 clientId
    • A 继续执行 DEL,将 B 加的锁错误删除,导致锁失效。

2.3 存在的问题:死锁与误删

基于上面示例,我们可以总结简易锁实现中常见的两个风险:

  1. 死锁风险

    • 如果客户端在持锁期间崩溃或网络抖动,导致无法主动释放锁,但使用了带过期时间的 SET NX PX,锁会在到期后自动释放,从而避免死锁。但如果不设过期,或者业务时间超过过期时间,又没有续期机制,会造成后续客户端加锁失败。
  2. 误删他人锁

    • 在非原子 “检查再删除” 逻辑中,客户端有可能在检查到锁属于自己但在调用 DEL 之前发生超时或运行延迟,造成误删了后来获得锁的其他客户端的锁。
    • 因此,必须用 Lua 脚本将“比对 value + 删除 key”两步操作封装为原子命令。

为保证安全释放,我们需要借助 Lua 脚本。下面详细演示如何在 Redis 端使用 Lua 脚本,确保原子执行。


使用 Lua 脚本保证原子性与安全释放

Redis 内置的 Lua 引擎允许我们将多条命令组合为单个原子操作。借助 Lua 脚本,可以在解锁时进行“判断 value 是否匹配”与“删除 key”两步的原子化,从而完全杜绝误删他人锁的问题。

3.1 Lua 脚本原理解析

3.1.1 加锁脚本

我们使用更通用的 SET 命令带参数实现“加锁 + 过期”,无需额外的 Lua 脚本。示例:

EVAL "return redis.call('SET', KEYS[1], ARGV[1], 'NX', 'PX', ARGV[2])" 1 lock_key client_id 5000
  • KEYS[1]:锁键(lock_key
  • ARGV[1]:客户端标识(client_id
  • ARGV[2]:过期时间(5000 毫秒)
  • 返回值:

    • "OK" 表示加锁成功;
    • nil 表示加锁失败。

不过,因为 SET NX PX 本身就是原子命令,没有必要用 Lua 包装。我们直接在客户端用 jedis.set(key, value, nx, px) 即可。

3.1.2 解锁脚本

下面是一段完整的 Lua 脚本 unlock.lua,用于安全释放分布式锁:

-- unlock.lua
-- KEYS[1] = lock_key
-- ARGV[1] = client_id

if redis.call("GET", KEYS[1]) == ARGV[1] then
    -- 只有当锁的持有者与传入 client_id 一致时,才删除锁
    return redis.call("DEL", KEYS[1])
else
    return 0
end
  • 逻辑解析

    1. redis.call("GET", KEYS[1]):获取锁键存储的 client_id
    2. 如果与 ARGV[1] 相同,说明当前客户端确实持有锁,于是执行 redis.call("DEL", KEYS[1]) 删除锁,返回值为 1 (表示删除成功);
    3. 否则返回 0,表示未执行删除(可能锁已过期或锁持有者不是当前客户端)。
  • 原子性保证
    整段脚本在 Redis 端一次性加载并执行,期间不会被其他客户端命令打断,保证“比对+删除”操作的原子性,从根本上避免了在“GET”与“DEL”之间的竞态条件。

3.2 Java 调用 Lua 脚本示例(Spring Data Redis)

假设你在 Spring Boot 项目中使用 Spring Data Redis,可以这样加载并执行 Lua 脚本:

3.2.1 将 unlock.lua 放到 resources/scripts/ 目录下

src
└── main
    └── resources
        └── scripts
            └── unlock.lua

3.2.2 定义 Spring Bean 加载 Lua 脚本

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;
import org.springframework.data.redis.core.script.DefaultRedisScript;

@Configuration
public class RedisScriptConfig {

    /**
     * 将 unlock.lua 脚本加载为 DefaultRedisScript
     */
    @Bean
    public DefaultRedisScript<Long> unlockScript() {
        DefaultRedisScript<Long> script = new DefaultRedisScript<>();
        // 指定脚本路径 相对于 classpath
        script.setLocation(new ClassPathResource("scripts/unlock.lua"));
        // 返回值类型
        script.setResultType(Long.class);
        return script;
    }
}

3.2.3 在分布式锁工具类中执行脚本

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.data.redis.core.script.DefaultRedisScript;
import org.springframework.stereotype.Service;

import java.util.Collections;
import java.util.UUID;
import java.util.concurrent.TimeUnit;

@Service
public class RedisDistributedLock {

    @Autowired
    private StringRedisTemplate redisTemplate;

    @Autowired
    private DefaultRedisScript<Long> unlockScript;

    private static final long DEFAULT_EXPIRE_MILLIS = 5000; // 默认锁过期 5 秒

    /**
     * 获取分布式锁
     *
     * @param lockKey 锁 Key
     * @return clientId 用于之后解锁时比对;如果返回 null 表示获取锁失败
     */
    public String tryLock(String lockKey) {
        String clientId = UUID.randomUUID().toString();
        Boolean success = redisTemplate.opsForValue()
                .setIfAbsent(lockKey, clientId, DEFAULT_EXPIRE_MILLIS, TimeUnit.MILLISECONDS);
        if (Boolean.TRUE.equals(success)) {
            return clientId;
        }
        return null;
    }

    /**
     * 释放锁:使用 Lua 脚本保证原子性
     *
     * @param lockKey  锁 Key
     * @param clientId 获取锁时返回的 clientId
     */
    public boolean unlock(String lockKey, String clientId) {
        // KEYS[1] = lockKey; ARGV[1] = clientId
        Long result = redisTemplate.execute(
                unlockScript,
                Collections.singletonList(lockKey),
                clientId
        );
        return result != null && result > 0;
    }
}
  • tryLock 方法:

    • 通过 setIfAbsent(key, value, timeout, unit) 相当于 SET key value NX PX timeout,如果返回 true,表示加锁成功并设置过期时间。
    • 返回随机 clientId,用于后续安全解锁。若返回 null,表示加锁失败(已被占用)。
  • unlock 方法:

    • 通过 redisTemplate.execute(unlockScript, keys, args)unlock.lua 脚本在 Redis 端执行,原子地完成判断与删除。

3.3 流程图解:加锁与解锁的时序

下面用一个简化的 ASCII 图,帮助理解 Redis 分布式锁在加锁与解锁时的各个步骤:

                          ┌──────────────────────────────────┐
                          │            Redis Server          │
                          └──────────────────────────────────┘
                                     ▲             ▲
                                     │             │
          1. tryLock("my_lock")      │             │ 4. unlock("my_lock", clientId)
             SET my_lock clientId NX PX expireTime │
                                     │             │
                                     ▼             │
   ┌───────────────────────┐    ┌──────────────────────────────────┐
   │   应用 A(客户端)     │    │ 1. Redis 端执行 SETNX + EXPIRE     │
   │                       │    │    原子完成后返回 OK               │
   │ clientId = uuid-A     │    └──────────────────────────────────┘
   │ 加锁成功              │              │
   │ 业务逻辑执行中...     │              ▼
   │                       │    ┌──────────────────────────────────┐
   │                       │    │  /Lock Keys                       │
   │                       │    │  my_lock -> uuid-A (TTL: expire)  │
   └───────────────────────┘    └──────────────────────────────────┘
                                     ▲
                                     │
                 2. 其他客户端 B    │    3. A 调用 unlock 前锁过期?
                    tryLock        │
                 SET my_lock uuid-B?│
                   返回 null       │
                                     │
                                     │
           ┌───────────────────────┐  │            ┌───────────────────────┐
           │ 应用 B(客户端)      │  │            │ 应用 A 调用 unlock   │
           │ 加锁失败,返回 null   │  │            │(执行 Lua 脚本)     │
           └───────────────────────┘  │            └───────────────────────┘
                                     │                   │
                                     │ 4.1 Redis 接收 Lua 脚本  │
                                     │    if GET(key)==clientId │
                                     │      then DEL(key)       │
                                     │      else return 0       │
                                     │
                                     ▼
                           ┌──────────────────────────────────┐
                           │     Lock Key 可能已过期或被 B 获得   │
                           │  - 若 my_lock 值 == uuid-A: DEL 成功  │
                           │  - 否则返回 0,不删除任何数据        │
                           └──────────────────────────────────┘
  • 步骤 1:客户端 A 通过 SET key value NX PX expire 成功加锁;
  • 步骤 2:锁过期前,客户端 B 反复尝试 SET key 均失败;
  • 步骤 3:客户端 A 业务逻辑执行完毕,调用 unlock 方法,在 Redis 端运行 unlock.lua 脚本;
  • 步骤 4:Lua 脚本比对 GET(key)clientId,如果一致则 DEL(key),否则不做任何操作,保证安全释放。

通过上述方式,我们既保证了锁在超时后自动释放,也避免了误删他人锁的风险。


Redisson 生产级分布式锁方案

虽然自己动手实现分布式锁可以帮助理解原理,但在生产环境中有以下挑战:

  • 需要处理锁续期、锁失效、锁可重入、可重试、超时控制等复杂逻辑;
  • 要考虑 Redis 单点故障,需要使用 Redis Sentinel 或 Cluster 模式保证高可用;
  • 如果自己实现的代码不够健壮,在极端并发情况下可能出现竞态或性能瓶颈。

为此,Redisson(基于 Jedis/Lettuce 封装的 Redis 客户端工具包)提供了一套成熟的分布式锁方案,功能丰富、易用且可靠。Redisson 内部会自动完成续期看门狗、超时回退等机制,支持多种锁类型(可重入锁、公平锁、读写锁、信号量等)。

4.1 Redisson 简介

  • 起源:由 Redisson 团队开发,是一个基于 Netty 的 Redis Java 客户端,封装了众多 Redis 功能。
  • 核心特性

    • 可重入锁(Reentrant Lock)
    • 公平锁(Fair Lock)
    • 读写锁(ReadWrite Lock)
    • 信号量(Semaphore)Latch
    • 分布式队列、集合、映射 等。
    • 支持单机、Sentinel、Cluster 模式。
    • 内置看门狗(Watchdog)机制,自动续期锁,防止锁误释放。
  • maven 依赖

    <dependency>
        <groupId>org.redisson</groupId>
        <artifactId>redisson-spring-boot-starter</artifactId>
        <version>3.25.0</version>
    </dependency>

    也可以只引入 redisson 核心包,根据需要自行配置。

4.2 Java 示例:使用 Redisson 实现公平锁与可重入锁

下面演示如何在 Spring Boot 中,通过 Redisson 快速实现分布式锁。

4.2.1 配置 Redisson Client

application.yml 中配置 Redis 地址(以单机模式为例):

spring:
  redis:
    host: 127.0.0.1
    port: 6379
  redisson:
    # 可以将 Redisson 配置都放在 config 文件中,也可以使用 spring-boot-starter 默认自动配置
    # 这里使用简单模式,指向单个 Redis 节点
    address: redis://127.0.0.1:6379
    lockWatchdogTimeout: 30000 # 看门狗超时时间(ms),Redisson 会自动续期直到 30 秒

如果希望使用 Sentinel 或 Cluster,只需将 addresssentinelAddressesclusterNodes 等配置项配置好即可。

4.2.2 注入 RedissonClient 并获取锁

import org.redisson.api.RLock;
import org.redisson.api.RedissonClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.concurrent.TimeUnit;

@Service
public class RedissonLockService {

    @Autowired
    private RedissonClient redissonClient;

    /**
     * 获取可重入锁并执行业务
     *
     * @param lockKey  锁名称
     * @param leaseTime 锁过期时间(秒)
     * @return 返回业务执行结果
     */
    public String doBusinessWithReentrantLock(String lockKey, long leaseTime) {
        RLock lock = redissonClient.getLock(lockKey);
        boolean acquired = false;
        try {
            // 尝试加锁:等待时间 3 秒,锁超时时间由 leaseTime 决定
            acquired = lock.tryLock(3, leaseTime, TimeUnit.SECONDS);
            if (!acquired) {
                return "无法获取锁,业务拒绝执行";
            }
            // 模拟业务逻辑
            Thread.sleep(2000);
            return "业务执行完成,锁自动续期或定时释放";
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return "业务执行被打断";
        } finally {
            if (acquired && lock.isHeldByCurrentThread()) {
                lock.unlock();
            }
        }
    }

    /**
     * 公平锁示例:保证先请求锁的线程先获得锁
     */
    public String doBusinessWithFairLock(String lockKey) {
        RLock fairLock = redissonClient.getFairLock(lockKey + ":fair");
        boolean acquired = false;
        try {
            acquired = fairLock.tryLock(5, 10, TimeUnit.SECONDS);
            if (!acquired) {
                return "无法获取公平锁,业务拒绝执行";
            }
            // 模拟业务
            Thread.sleep(1000);
            return "公平锁业务执行完成";
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return "业务执行被打断";
        } finally {
            if (acquired && fairLock.isHeldByCurrentThread()) {
                fairLock.unlock();
            }
        }
    }
}
  • getLock(lockKey) 返回一个常规的可重入锁(非公平),Redisson 会在内部创建并维护一个有序的临时节点队列,结合看门狗机制自动续期。
  • getFairLock(lockKey) 返回一个公平锁,会严格按照请求顺序分配锁,适用于对公平性要求高的场景。
  • lock.tryLock(waitTime, leaseTime, unit)

    • waitTime:尝试获取锁的最长等待时间,超过则返回 false
    • leaseTime:加锁成功后,锁的自动过期时间;如果 leaseTime 为 0,则会启用看门狗模式,Redisson 会在锁快到过期时自动续期(续期周期为过期时间的 1/3)。

4.2.3 在 Controller 中使用

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class RedissonLockController {

    @Autowired
    private RedissonLockService lockService;

    @GetMapping("/redisson/reentrant")
    public String testReentrantLock() {
        return lockService.doBusinessWithReentrantLock("myReentrantLock", 10);
    }

    @GetMapping("/redisson/fair")
    public String testFairLock() {
        return lockService.doBusinessWithFairLock("myLock");
    }
}
  • 并发访问 /redisson/reentrant/redisson/fair 即可看到锁的排队与互斥执行效果。

分布式锁常见应用场景

分布式锁广泛应用于多实例系统中对共享资源或关键业务的互斥保护,以下列举常见场景:

5.1 限流与排队

  • 流量突发保护:当某个接口或资源承受高并发请求时,可先通过获取锁(或令牌桶、信号量)来限制同时访问人数。
  • 排队处理:对一批请求,串行化顺序执行,例如限购系统中,先获取锁的用户方可继续扣库存、下单,其他用户需排队等待或返回 “系统繁忙”。

5.2 分布式任务调度

  • 定时任务去重:在多台机器上同时部署定时任务,为了避免同一个任务被多次执行,可以在执行前获取一把分布式锁,只有持有锁的实例才执行任务。
  • Leader 选举:多个调度节点中,只有 Leader(获得锁的节点)执行特定任务,其他节点处于候选或 standby 状态。

5.3 资源抢购与秒杀系统

  • 库存扣减:当大批量用户同时抢购某个商品时,需要保证库存只被扣减一次。加锁可让一个用户在扣减库存期间,其他并发请求暂时阻塞或失败。
  • 支付与退款:对于同一订单多次支付或退款操作,需要使用分布式锁保证只能有一个线程对该订单进行状态变更。

分布式锁的性能与注意事项

在生产环境使用 Redis 分布式锁,需要注意以下性能和可靠性细节:

6.1 锁粒度与加锁时长控制

  • 锁粒度:不要为了简单而把全局资源都用同一个锁。应尽可能缩小锁粒度,例如对同一个“用户 ID”加锁,而非对整个“商品库存”加锁。
  • 加锁时长:合理设置过期时间,既要足够长以完成业务,又不能过度冗余,避免长时间持有锁阻塞其他请求。对于无法预估业务耗时场景,推荐使用看门狗模式(Redisson 自动续期),或定时手动续期。
  • 超时退避:当获取锁失败时,可采用指数退避(Exponential Backoff)策略,避免大量客户端瞬间重试造成雪崩。

6.2 避免单点故障:哨兵与集群模式

  • 单机模式:若 Redis 单节点出现故障,锁服务不可用。生产环境应避免使用单机模式。
  • 哨兵模式(Sentinel):可配置多个 Redis 实例组成哨兵集群,实现主从切换与自动故障转移。Redisson 与 Jedis 都支持哨兵模式的连接。
  • 集群模式(Cluster):Redis Cluster 将数据分片到多台节点,可实现更高的可用与可扩展。Redisson 也支持 Cluster 模式下的分布式锁。需注意:在 Cluster 模式下,使用分布式锁时要保证加锁与解锁操作发送到同一主节点,否则由于网络分片机制造成一致性问题。

6.3 看门狗(Watchdog)机制与续期

  • 看门狗概念:一些客户端(如 Redisson)会在加锁时启动一个“看门狗”线程,不断向 Redis 发送 PEXPIRE 延长过期时间,防止锁在持有过程中因过期而被其他客户端误获取。
  • 实现原理:Redisson 在 lock()tryLock() 成功后,会根据锁的 leaseTime 或默认值,启动一个后台定时任务,周期性地续期。例如默认 leaseTime=30 秒时,每隔 10 秒(默认 1/3)向 Redis 发送延时续命令,直到调用 unlock() 或看门狗检测到应用宕机。
  • 注意:如果使用自己手撰的 SET NX PX 方案,需要自行实现续期逻辑,否则锁在超时时间到达后,Redis 会自动删除,可能导致持锁客户端仍在执行业务时锁被误释放。

完整实战示例:秒杀场景下的库存扣减

下面通过一个典型的“秒杀系统”案例,将前文所述技术串联起来,演示如何在高并发场景下,利用 Redis 分布式锁与 Lua 脚本实现原子库存扣减并防止超卖。

7.1 需求描述与设计思路

  • 场景:假设某电商平台对某款热门商品发起秒杀活动,初始库存为 100 件。短时间内可能有上万用户并发请求秒杀。
  • 核心挑战

    1. 防止超卖:在高度并发下,只允许库存 > 0 时才能扣减,扣减后库存减 1,并录入订单信息。
    2. 保证原子性:库存检查与扣减必须在 Redis 端原子执行,防止出现并发竞态造成库存负数(即超卖)。
    3. 分布式锁保护:在订单生成和库存扣减的代码区域,需保证同一件商品只有一个线程能操作库存。
  • 解决方案思路

    1. 使用 Redis Lua 脚本,将“检查库存 + 扣减库存 + 记录订单”三步操作打包为一次原子执行,保证不会中途被其他客户端打断。
    2. 使用分布式锁(Redisson 或原生 SET NX PX + Lua 解锁脚本)保护下单流程,避免在库存扣减与订单写库之间发生并发冲突。
    3. 结合本地缓存或消息队列做削峰,进一步减轻 Redis 压力,此处主要聚焦 Redis 分布式锁与 Lua 脚本实现,不展开队列削峰。

7.2 Lua 脚本实现原子库存扣减

7.2.1 脚本逻辑

将以下 Lua 脚本保存为 seckill.lua,放置在项目资源目录(如 resources/scripts/seckill.lua):

-- seckill.lua
-- KEYS[1] = 库存 key,例如 "seckill:stock:1001"
-- KEYS[2] = 订单 key,例如 "seckill:order:userId"
-- ARGV[1] = 当前用户 ID (用户标识)
-- ARGV[2] = 秒杀订单流水号 (唯一 ID)

-- 查询当前库存
local stock = tonumber(redis.call("GET", KEYS[1]) or "-1")
if stock <= 0 then
    -- 库存不足,直接返回 0 表示秒杀失败
    return 0
else
    -- 库存充足,扣减库存
    redis.call("DECR", KEYS[1])
    -- 生成用户订单,可以把订单流水号存入一个 Set 或者按需存储
    -- 这里示例为将订单记录到 HASH 结构中,key 为 KEYS[2], field 为 用户ID, value 为 订单流水号
    redis.call("HSET", KEYS[2], ARGV[1], ARGV[2])
    -- 返回 1 表示秒杀成功
    return 1
end
  • 参数说明

    • KEYS[1]:当前商品的库存键,初始值为 库存数量
    • KEYS[2]:用于存储所有成功秒杀订单的键(HASH 结构),键名格式可自定义,如 seckill:order:1001 表示商品 ID 为 1001 的订单集合。
    • ARGV[1]:秒杀用户 ID,用于作为 HASH 的 field。
    • ARGV[2]:秒杀订单流水号,用于作为 HASH 的 value。
  • 执行逻辑

    1. 通过 redis.call("GET", KEYS[1]) 获取当前库存数,若 <= 0 返回 0,秒杀失败;
    2. 否则,执行 DECR 扣减库存;
    3. 将该用户的订单流水号记录到 HSET KEYS[2] ARGV[1] ARGV[2],用于后续下游处理(如持久化到数据库)。
    4. 最后返回 1,表示秒杀成功。

7.2.2 优势分析

  • 由于整个脚本在 Redis 端以单次原子操作执行,不会被其他客户端命令插入,因此库存检查与扣减的逻辑绝对不会出现竞态,避免了“超卖”。
  • 通过 HSET 记录订单,仅当扣减库存成功时才执行,保证库存与订单信息一致。
  • Lua 脚本执行速度远快于客户端多次 GET/DECR/HSET 的网络往返,性能更高。

7.3 Java 端集成与高并发测试

下面以 Spring Boot + Spring Data Redis 为例,展示如何加载并执行 seckill.lua 脚本,并模拟高并发进行秒杀测试。

7.3.1 项目依赖(pom.xml

<dependencies>
    <!-- Spring Boot Starter Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring Data Redis -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-redis</artifactId>
    </dependency>

    <!-- Lettuce Client(Redis 客户端) -->
    <dependency>
        <groupId>io.lettuce</groupId>
        <artifactId>lettuce-core</artifactId>
    </dependency>

    <!-- Redisson,用于分布式锁 -->
    <dependency>
        <groupId>org.redisson</groupId>
        <artifactId>redisson-spring-boot-starter</artifactId>
        <version>3.25.0</version>
    </dependency>
</dependencies>

7.3.2 加载 Lua 脚本 Bean

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;
import org.springframework.data.redis.core.script.DefaultRedisScript;

@Configuration
public class SeckillScriptConfig {

    @Bean
    public DefaultRedisScript<Long> seckillScript() {
        DefaultRedisScript<Long> script = new DefaultRedisScript<>();
        script.setLocation(new ClassPathResource("scripts/seckill.lua"));
        script.setResultType(Long.class);
        return script;
    }
}

7.3.3 秒杀服务实现

import org.redisson.api.RLock;
import org.redisson.api.RedissonClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.data.redis.core.script.DefaultRedisScript;
import org.springframework.stereotype.Service;

import java.util.Collections;
import java.util.UUID;
import java.util.concurrent.TimeUnit;

@Service
public class SeckillService {

    @Autowired
    private RedisTemplate<String, Object> redisTemplate;

    @Autowired
    private DefaultRedisScript<Long> seckillScript;

    @Autowired
    private RedissonClient redissonClient;

    // 模拟秒杀接口
    public String seckill(String productId, String userId) {
        String stockKey = "seckill:stock:" + productId;
        String orderKey = "seckill:order:" + productId;
        String orderId = UUID.randomUUID().toString();

        // 1. 获取分布式锁,防止同一用户并发重复购买(可选)
        String userLockKey = "seckill:userLock:" + userId;
        RLock userLock = redissonClient.getLock(userLockKey);
        boolean lockAcquired = false;
        try {
            lockAcquired = userLock.tryLock(3, 5, TimeUnit.SECONDS);
            if (!lockAcquired) {
                return "请勿重复请求";
            }

            // 2. 调用 Lua 脚本执行原子库存扣减 + 记录订单
            Long result = redisTemplate.execute(
                    seckillScript,
                    Collections.singletonList(stockKey),
                    Collections.singletonList(orderKey),
                    userId,
                    orderId
            );
            if (result != null && result == 1) {
                return "秒杀成功,订单ID=" + orderId;
            } else {
                return "秒杀失败,库存不足";
            }
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return "系统异常,请重试";
        } finally {
            if (lockAcquired && userLock.isHeldByCurrentThread()) {
                userLock.unlock();
            }
        }
    }

    /**
     * 初始化库存,用于测试
     */
    public void initStock(String productId, int count) {
        String stockKey = "seckill:stock:" + productId;
        redisTemplate.opsForValue().set(stockKey, count);
    }
}
  • 步骤解析

    1. 分布式锁保护

      • userLockKey = "seckill:userLock:" + userId 为锁的 Key,只允许同一个用户在并发场景下只有一把锁,避免重复请求。
      • Redisson 的 tryLock 会自动续期(看门狗),锁过期后自动解锁,防止死锁。
    2. 调用 Lua 脚本

      • redisTemplate.execute(seckillScript, keys, args...) 会在 Redis 端原子执行 seckill.lua 脚本,实现库存检查与扣减、订单记录。
      • 脚本返回 1 表示扣减成功,返回 0 表示库存不足。
    3. 释放分布式锁

      • 无论秒杀成功或失败,都要在 finally 中释放锁,避免锁泄漏。

7.3.4 Controller 暴露秒杀接口

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/seckill")
public class SeckillController {

    @Autowired
    private SeckillService seckillService;

    /**
     * 初始化库存,非真实场景仅用于测试
     */
    @PostMapping("/init")
    public String init(@RequestParam String productId, @RequestParam int count) {
        seckillService.initStock(productId, count);
        return "初始化库存成功,商品ID=" + productId + ",库存=" + count;
    }

    /**
     * 秒杀接口
     */
    @PostMapping("/buy")
    public String buy(@RequestParam String productId, @RequestParam String userId) {
        return seckillService.seckill(productId, userId);
    }
}

7.3.5 高并发测试演示

  1. 启动 Redis(建议单机模式即可)
  2. 启动 Spring Boot 应用
  3. 初始化库存

    curl -X POST "http://localhost:8080/seckill/init?productId=1001&count=100"
  4. 并发模拟用户抢购

    • 编写一个简单的脚本或使用压测工具(如 ApacheBench、JMeter)发送并发 curl 请求:

      for i in {1..200}; do
        curl -X POST "http://localhost:8080/seckill/buy?productId=1001&userId=user_$i" &
      done
      wait
    • 观察执行结果,大约有 100 条返回 “秒杀成功”,其余“秒杀失败,库存不足”。
    • 可以从 Redis 中查看库存剩余为 0,订单记录存储成功。
  5. Redis 中验证结果

    redis-cli
    > GET seckill:stock:1001
    "0"
    
    > HGETALL seckill:order:1001
    1) "user_1"
    2) "orderId-xxx"
    3) "user_2"
    4) "orderId-yyy"
    ...
    • HGETALL seckill:order:1001 列出了所有成功抢购的用户 ID 及订单流水号,确保没有超卖。

通过上述示例,我们利用 Redis Lua 脚本完成了关键的“检查库存 + 扣减库存 + 记录订单”原子操作,并结合分布式锁(Redisson)防止同一用户重复请求,达到了秒杀场景下的高并发安全保护。


总结与最佳实践

本文从最基础的 SETNX 实现,到使用 Lua 脚本保证原子性,再到 Redisson 生产级分布式锁 的使用,系统地讲解了 Redis 分布式锁的原理与实践。以下几点是实际项目中经常需要注意的最佳实践与总结:

  1. Redis 单点要避免

    • 生产环境请部署 Redis Sentinel 或 Cluster,保证分布式锁服务的高可用。
    • Redisson 能够自动感知主从切换,并维护锁的续期与数据一致性。
  2. 加锁时长需合理

    • 业务执行时间不可预估时,推荐使用 Redisson 的 Watchdog 机制,让锁自动续期,避免锁在业务执行过程中意外过期。
    • 如果选择手动管理过期时间(PX 参数),务必确保过期时间大于业务耗时,并考虑超时续期机制。
  3. 锁粒度需细化

    • 避免使用过于粗糙的全局锁,合理拆分资源维度,按业务对象(如“商品ID+用户ID”或“订单ID”)加锁,减少锁冲突。
    • 可以结合本地缓存、消息队列等方式,减少对 Redis 分布式锁的压力。
  4. Lua 脚本封装关键逻辑

    • 将“检查值 + 修改值”这种需要原子执行的操作都封装到 Lua 脚本中,避免客户端多次网络往返和中途竞态。
    • Lua 脚本性能优异,几乎和普通 Redis 命令一样快,可放心在高并发场景下使用。
  5. 监控与日志

    • 对于分布式锁的获取与释放,需要做好监控与日志记录,尤其是失败场景的告警与追踪,保证系统可观测性。
    • 记录锁获取失败的次数和耗时,帮助调试性能瓶颈和锁等待问题。
  6. 竞态重试与退避策略

    • 并发非常高时,大量客户端同时抢锁,可能造成 Redis 压力陡增。可在客户端实现重试次数与退避机制,避免“热点”锁雪崩。
    • 例如:tryLock 失败后,先 sleep 10ms,再重试;若再次失败,则根据指数退避逐渐延长重试间隔。

通过深入理解分布式锁的原理、常见风险以及成熟的解决方案(如 Redisson),你可以在实际场景中灵活应用 Redis 分布式锁,保证系统在高并发情况下仍能正确、稳定地完成关键业务逻辑。

Spring Cloud 与 Zookeeper:打造高效分布式协调系统

在微服务架构下,如何保证各个服务实例之间的协调、配置和通信是一项核心难题。ZooKeeper 作为一个高性能的分布式协调框架,为服务注册与发现、分布式配置、分布式锁等场景提供了统一的解决方案。而 Spring Cloud Zookeeper 则将 ZooKeeper 与 Spring 生态无缝对接,让我们可以在熟悉的 Spring Boot 项目中,快速构建稳定、可扩展的分布式系统。

本文将从以下几个方面,结合代码示例与图解,详细讲解如何使用 Spring Cloud 与 ZooKeeper 打造高效的分布式协调系统:

  1. 环境准备
  2. ZooKeeper 基础与 Spring Cloud Zookeeper 概览
  3. 服务注册与发现示例

    • 3.1. 依赖与配置
    • 3.2. 服务提供者示例
    • 3.3. 服务消费者示例
    • 3.4. 注册发现流程图解
  4. 分布式配置示例

    • 4.1. ZooKeeper 上存放配置
    • 4.2. Spring Cloud Zookeeper Config 配置与代码
    • 4.3. 配置拉取与刷新流程图解
  5. 分布式锁示例

    • 5.1. Curator 基础与依赖
    • 5.2. 实现分布式锁的代码示例
    • 5.3. 分布式锁使用流程图解
  6. 监控与运维要点
  7. 总结

环境准备

在动手之前,我们需要准备以下环境:

  1. JDK 1.8+
  2. Maven 3.5+
  3. ZooKeeper 3.5.x 或 3.6.x
  4. Spring Boot 2.3.x 或更高
  5. Spring Cloud Hoxton.RELEASE / Spring Cloud 2020.x(本文示例基于 Spring Cloud Hoxton)
  6. 开发工具:IntelliJ IDEA / Eclipse 等

1. 启动 ZooKeeper

本地开发中,可以通过 Docker 方式快速启动一个单节点 ZooKeeper 实例:

# 拉取官方镜像并运行
docker run -d --name zk -p 2181:2181 zookeeper:3.6.2

# 检查是否正常启动
docker logs zk
# 看到 "binding to port 0.0.0.0/0.0.0.0:2181" 便代表 zk 已正常启动

如果不使用 Docker,也可自行从官网(https://zookeeper.apache.org/)下载并解压,编辑 conf/zoo.cfg,然后:

# 进入解压目录
bin/zkServer.sh start
# 检查状态
bin/zkServer.sh status

默认情况下,ZooKeeper 会监听 localhost:2181


ZooKeeper 基础与 Spring Cloud Zookeeper 概览

2.1 ZooKeeper 核心概念

  • ZNode
    ZooKeeper 数据模型类似于一棵树(称为znodes 树),每个节点(称为 ZNode)都可以存储少量数据,并可拥有子节点。ZNode 有两种主要类型:

    1. 持久节点(Persistent ZNode):客户端创建后,除非显式删除,否则不会过期。
    2. 临时节点(Ephemeral ZNode):由客户端会话(Session)控制,一旦与 ZooKeeper 的连接断开,该节点会自动删除。
  • Watch 机制
    客户端可在 ZNode 上注册 Watch,当节点数据变化(如创建、删除、数据更新)时,ZooKeeper 会触发 Watch 通知客户端,便于实现分布式事件通知。
  • 顺序节点(Sequential)
    ZooKeeper 支持给节点名称追加自增序号,保证在同一个父节点下,子节点具有严格的顺序编号。这在 leader 选举、队列实现等场景非常常用。

2.2 Spring Cloud Zookeeper 概览

Spring Cloud 为我们提供了两个与 ZooKeeper 紧密集成的模块:

  1. spring-cloud-starter-zookeeper-discovery

    • 用于服务注册与发现。底层会在 ZooKeeper 上创建临时顺序节点(Ephemeral Sequential ZNode),注册服务信息,并定期心跳。其他消费者可通过 ZooKeeper 的 Watch 机制,实时获取注册列表。
  2. spring-cloud-starter-zookeeper-config

    • 用于分布式配置中心。将配置信息存储在 ZooKeeper 的某个路径下,Spring Cloud 在启动时会从 ZooKeeper 拉取配置并加载到 Spring 环境中,支持动态刷新(与 Spring Cloud Bus 联动)。

了解了这两个模块的作用后,我们可以根据不同场景,灵活使用 Spring Cloud Zookeeper 来完成分布式协调相关功能。


服务注册与发现示例

分布式系统下,服务实例可能动态上下线。传统的硬编码地址方式无法满足弹性扩缩容需求。通过 ZooKeeper 作为注册中心,每个服务启动时将自身元信息注册到 ZooKeeper,消费者动态从注册中心获取可用实例列表并发起调用,极大简化了运维复杂度。

3.1 依赖与全局配置

假设我们使用 Spring Cloud Hoxton.RELEASE 版本,并在 pom.xml 中引入以下依赖:

<!-- spring-boot-starter-parent 版本 -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.3.8.RELEASE</version>
    <relativePath/> 
</parent>

<properties>
    <!-- Spring Cloud 版本 -->
    <spring-cloud.version>Hoxton.SR9</spring-cloud.version>
    <java.version>1.8</java.version>
</properties>

<dependencies>
    <!-- Web Starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring Cloud Zookeeper Discovery -->
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-zookeeper-discovery</artifactId>
    </dependency>

    <!-- 如需读取配置信息,也可同时引入 Config Starter -->
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-zookeeper-config</artifactId>
    </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <!-- 引入 Spring Cloud BOM -->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

所有微服务都需要配置与 ZooKeeper 的连接信息。在 application.yml(或 application.properties)中添加以下全局配置:

spring:
  application:
    name: ${SERVICE_NAME:demo-service}   # 服务名称,可通过环境变量覆盖
  cloud:
    zookeeper:
      connect-string: 127.0.0.1:2181     # ZooKeeper 地址
      discovery:
        enabled: true                     # 启用服务注册与发现
      # 如需配置路径前缀,可通过 base-path 设置
      # base-path: /services

说明:

  • spring.cloud.zookeeper.connect-string:指定 ZooKeeper 的 IP\:Port,可填写集群(逗号分隔)。
  • spring.cloud.zookeeper.discovery.enabled:开启 Zookeeper 作为服务注册中心。
  • spring.application.name:服务注册到 ZooKeeper 时所使用的节点名称(ZNode 名称)。

接下来,我们基于上述依赖和全局配置,实现一个简单的服务提供者和消费者示例。

3.2 服务提供者示例

1. Main 类与注解

在服务提供者项目下创建主类,添加 @EnableDiscoveryClient 注解,启用服务注册:

package com.example.provider;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

@SpringBootApplication
@EnableDiscoveryClient  // 启用服务注册功能
public class ProviderApplication {
    public static void main(String[] args) {
        SpringApplication.run(ProviderApplication.class, args);
    }
}

2. Controller 暴露简单接口

创建一个 REST 控制器,提供一个返回“Hello from provider”的示例接口,并带上服务端口以示区分:

package com.example.provider.controller;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @Value("${server.port}")
    private String port;

    @GetMapping("/hello")
    public String hello() {
        return "Hello from provider, port: " + port;
    }
}

3. application.yml 配置

src/main/resources/application.yml 中添加以下内容:

server:
  port: 8081

spring:
  application:
    name: provider-service

  cloud:
    zookeeper:
      connect-string: 127.0.0.1:2181
      discovery:
        enabled: true
        # 可选:可自己定义注册时所处路径
        # root-node: /services

启动后,当服务初始化完成并与 ZooKeeper 建立会话时,Spring Cloud Zookeeper 会在路径 /provider-service(或结合 root-node 定制的路径)下创建一个临时顺序节点(Ephemeral Sequential)。该节点中会包含该实例的元数据(如 IP、端口、权重等)。

Node 结构示意(ZooKeeper)

/provider-service
   ├─ instance_0000000001    (data: {"instanceId":"10.0.0.5:8081","port":8081,…})
   ├─ instance_0000000002    (data: {...})
   └─ ……
  • 由于是临时节点,服务实例下线或心跳中断,节点会自动删除,实现自动剔除失效实例。

3.3 服务消费者示例

1. Main 类与注解

在服务消费者项目下,同样添加 @EnableDiscoveryClient

package com.example.consumer;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

@SpringBootApplication
@EnableDiscoveryClient  // 启用服务发现
public class ConsumerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ConsumerApplication.class, args);
    }
}

2. RestTemplate Bean 注册

为了方便发起 HTTP 请求,我们使用 RestTemplate 并结合 @LoadBalanced 注解,让其支持通过服务名发起调用:

package com.example.consumer.config;

import org.springframework.cloud.client.loadbalancer.LoadBalanced;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;

@Configuration
public class RestTemplateConfig {

    @Bean
    @LoadBalanced  // 使 RestTemplate 支持 Ribbon(或 Spring Cloud Commons)的负载均衡,自动从注册中心获取实例列表
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

说明:

  • @LoadBalanced 标注的 RestTemplate 会自动拦截 http://service-name/… 形式的调用,并将 service-name 替换为可用实例列表(由 ZooKeeper 提供)。
  • 在 Spring Cloud Hoxton 及以上版本中,不再强制使用 Ribbon,调用流程由 Spring Cloud Commons 的负载均衡客户端负责。

3. 构建调用接口

新建一个控制器,通过注入 DiscoveryClient 查询所有 provider-service 的实例列表,并使用 RestTemplate 发起调用:

package com.example.consumer.controller;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.cloud.client.ServiceInstance;
import org.springframework.cloud.client.discovery.DiscoveryClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestTemplate;

import java.util.List;

/**
 * 演示服务发现与调用
 */
@RestController
public class ConsumerController {

    @Autowired
    private DiscoveryClient discoveryClient;

    @Autowired
    private RestTemplate restTemplate;

    @GetMapping("/invoke-provider")
    public String invokeProvider() {
        // 1. 从注册中心(ZooKeeper)获取 provider-service 的所有实例
        List<ServiceInstance> instances = discoveryClient.getInstances("provider-service");
        if (instances == null || instances.isEmpty()) {
            return "No available instances";
        }
        // 简单起见,这里只拿第一个实例的 URI
        String url = instances.get(0).getUri().toString() + "/hello";
        // 2. 通过 RestTemplate 发起调用
        return restTemplate.getForObject(url, String.class);
    }

    @GetMapping("/invoke-via-loadbalance")
    public String invokeViaLoadBalance() {
        // 通过 LoadBalanced RestTemplate,直接以服务名发起调用
        String url = "http://provider-service/hello";
        return restTemplate.getForObject(url, String.class);
    }
}

4. application.yml 配置

server:
  port: 8082

spring:
  application:
    name: consumer-service

  cloud:
    zookeeper:
      connect-string: 127.0.0.1:2181
      discovery:
        enabled: true

启动消费者后,可以通过访问 http://localhost:8082/invoke-providerhttp://localhost:8082/invoke-via-loadbalance 来间接调用 provider-service,并实时感知集群实例变更。

3.4 注册发现流程图解

下面用一张简化的 ASCII 图,展示从服务提供者注册,到消费者发现并调用的大致流程:

┌──────────────────────────────────────────────────────────────┐
│                          ZooKeeper                            │
│               (127.0.0.1:2181 单节点示例)                     │
│                                                                │
│  /provider-service                                              │
│     ├─ instance_0000000001  <- 临时顺序节点,data 包含服务IP:8081 │
│     └─ instance_0000000002  <- 另一台机器上的 provider 实例        │
│                                                                │
│  /consumer-service                                              │
│     └─ instance_0000000001  <- 消费者自身也会注册到 ZooKeeper    │
│                                                                │
└──────────────────────────────────────────────────────────────┘
         ▲                               ▲
         │                               │
         │ 1. ProviderApplication 启动   │  4. ConsumerApplication  启动
         │    - 创建 /provider-service/instance_0000000001 临时节点  │
         │                               │    - 创建 /consumer-service/instance_0000000001
         │                               │
┌────────────────┐                      ┌────────────────┐
│ Provider (8081) │                      │ Consumer (8082) │
│ @EnableDiscoveryClient                 │ @EnableDiscoveryClient
│                                         │
│ 2. Spring Cloud ZK Client 与 ZooKeeper 建立会话               │
│    - 注册元数据 (IP、端口、权重等)                              │
└────────────────┘                      └────────────────┘
         │                               │
         │ 3. ConsumerController 调用   │
         │    discoveryClient.getInstances("provider-service")   │
         │    ZooKeeper 返回实例列表实例                                │
         │                               │
         │    ServiceInstance 列表: [                    │
         │      {instanceId=instance_0000000001, URI=http://10.0.0.5:8081}, │
         │      {…第二个实例…} ]                    │
         │                               │
         │ 5. RestTemplate 通过实例 IP:8081 发起 HTTP 请求            │
         │                               │
         ▼                               ▼
┌────────────────────┐            ┌─────────────────────┐
│  “Hello from provider, port:8081” │            │  Consumer 返回给客户端         │
└────────────────────┘            └─────────────────────┘
  • 1. 提供者启动后,Spring Cloud Zookeeper 自动在 ZooKeeper 上创建 /provider-service/instance_xxx 的临时顺序节点。
  • 2. 该临时节点包含元数据信息,可在 ZooKeeper 客户端(如 zkCli、ZooInspector)中查看。
  • 3. 消费者启动后,从 /provider-service 下获取所有子节点列表,即可得知哪些 provider 实例正在运行。
  • 4. 消费者通过 RestTemplate 或者手动拼装 URL,发送 HTTP 请求实现跨实例调用。

这种基于 ZooKeeper 的注册与发现机制,天然支持实例下线(临时节点自动删除)、节点故障感知(Watch 通知)等分布式协调特性。


分布式配置示例

除了服务注册与发现,ZooKeeper 常被用于存储分布式配置,使多环境、多实例能够在运行时动态拉取配置信息。Spring Cloud Zookeeper Config 模块将 ZooKeeper 路径中的配置,作为 Spring Boot 的配置源注入。

4.1 ZooKeeper 上存放配置

  1. 创建 ZooKeeper 上的配置节点树
    假设我们要为 provider-service 存放配置信息,可在 ZooKeeper 根路径下建立如下结构:

    /config
       └─ provider-service
           ├─ application.yml      (全局配置)
           └─ dev
               └─ application.yml  (dev 环境特定配置)
  2. /config/provider-service/application.yml 中放入内容
    例如:

    # /config/provider-service/application.yml 中的数据(以 zkCli 或其他方式写入)
    message:
      prefix: "Hello from ZooKeeper Config"
  3. 如果有多环境需求,如 dev、prod,可创建 /config/provider-service/dev/application.yml/config/provider-service/prod/application.yml 来覆盖对应环境的属性。

写入示例(使用 zkCli)

# 进入 zkCli
./zkCli.sh -server 127.0.0.1:2181

# 创建 /config 节点(持久节点)
create /config ""

# 创建 provider-service 节点
create /config/provider-service ""

# 在 /config/provider-service 下创建 application.yml,并写入配置
create /config/provider-service/application.yml "message:\n  prefix: \"Hello from ZooKeeper Config\""

# 如需覆盖 dev 环境,可:
create /config/provider-service/dev ""
create /config/provider-service/dev/application.yml "message:\n  prefix: \"[DEV] Hello from ZooKeeper Config\""

4.2 Spring Cloud Zookeeper Config 配置与代码

要让 Spring Boot 应用从 ZooKeeper 拉取配置,需要在 bootstrap.yml(注意:必须是 bootstrap.yml 而非 application.yml,因为 Config 在应用上下文初始化时就要加载)中进行如下配置:

# src/main/resources/bootstrap.yml
spring:
  application:
    name: provider-service  # 与 ZooKeeper 中 /config/provider-service 对应
  cloud:
    zookeeper:
      connect-string: 127.0.0.1:2181
      config:
        enabled: true         # 开启 ZK Config
        root: /config         # 配置在 ZooKeeper 中的根路径
        default-context: application  # 加载 /config/provider-service/application.yml
        # profile-separator: "/" # 默认 "/" 即 /config/{service}/{profile}/{context}.yml

解释:

  • spring.cloud.zookeeper.config.root:指定 ZooKeeper 上存放配置的根路径(对应 zkCli 中创建的 /config)。
  • spring.application.name:用于定位子路径 /config/provider-service,从而加载该目录下的 application.yml
  • 如果设置了 spring.profiles.active=dev,则同时会加载 /config/provider-service/dev/application.yml 并覆盖同名属性。

1. Main 类与注解

package com.example.provider;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.context.config.annotation.RefreshScope;

@SpringBootApplication
public class ProviderApplication {
    public static void main(String[] args) {
        SpringApplication.run(ProviderApplication.class, args);
    }
}

2. 使用 ZK 配置的 Bean

借助 @RefreshScope,我们可以实现配置的动态刷新。以下示例展示了如何将 ZooKeeper 中的 message.prefix 属性注入到业务代码中:

package com.example.provider.controller;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RefreshScope  // 支持动态刷新
@RestController
public class ConfigController {

    @Value("${message.prefix}")
    private String prefix;

    @GetMapping("/zk-config-message")
    public String getZkConfigMessage() {
        return prefix + ", port: " + System.getenv("SERVER_PORT");
    }
}

此时,只要我们在 ZooKeeper 上更新 /config/provider-service/application.yml 中的 message.prefix 值,且在应用运行时触发一次刷新(如调用 /actuator/refresh,需引入 Spring Boot Actuator),即可让 @Value 注入的属性生效更新。

3. application.yml(与 bootstrap.yml 区分开)

  • bootstrap.yml 用于配置 Spring Cloud Config Client 相关属性(优先级更高)。
  • application.yml 用于常规应用级配置,比如服务器端口、日志配置等。

application.yml 中只需配置常规内容即可,例如:

# src/main/resources/application.yml
server:
  port: ${SERVER_PORT:8081}
logging:
  level:
    root: INFO

4.3 配置拉取与刷新流程图解

┌──────────────────────────────────────────────────────────────────┐
│                          ZooKeeper                              │
│                 (127.0.0.1:2181 单节点示例)                        │
│                                                                  │
│  /config                                                          │
│     └─ provider-service                                           │
│          ├─ application.yml  (message.prefix = "Hello from ZK")  │
│          └─ dev                                                    │
│              └─ application.yml (message.prefix = "[DEV] Hello")  │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
         ▲                                      ▲
         │ 1. Provider 启动时读取 bootstrap.yml 中     │
         │    的 ZK Config 配置                          │
         │                                              │
┌───────────────────────────────┐        ┌───────────────────────────────┐
│       ProviderApplication     │        │   ZooKeeper Config Path Tree   │
│   Spring Boot 初始化时:        │        │   root: /config                │
│   - 查找 /config/provider-service/application.yml  │
│   - 读取 message.prefix="Hello from ZK"           │
└───────────────────────────────┘        └───────────────────────────────┘
         │ 2. 将 ZK 中的属性注入到 Spring Environment    │
         ▼                                          
┌───────────────────────────────────────────────────────────────────┐
│                 Spring Boot 应用上下文                          │
│  - 启动完成后,ConfigController 中的 prefix="Hello from ZK"        │
│  - 可通过 /zk-config-message 接口读取到最新值                       │
└───────────────────────────────────────────────────────────────────┘
         │
         │ 3. 若在 zkCli 中执行:  
         │    set /config/provider-service/application.yml   
         │    "message.prefix: 'Updated from ZK'"  
         │
         │ 4. 在应用运行时调用 /actuator/refresh (需启用 Actuator)  
         │    Spring Cloud 会重新拉取 ZK 上的配置,并刷新 @RefreshScope Bean  
         ▼
┌───────────────────────────────────────────────────────────────────┐
│                 Spring Environment 动态刷新                        │
│  - prefix 属性更新为 "Updated from ZK"                            │
│  - 访问 /zk-config-message 即可获取最新值                            │
└───────────────────────────────────────────────────────────────────┘

分布式锁示例

在分布式场景中,往往需要多实例对共享资源进行互斥访问。例如并发限流、分布式队列消费、分布式任务调度等场景,分布式锁是基础保障。ZooKeeper 原生提供了顺序临时节点等机制,Apache Curator(Netflix 出品的 ZooKeeper 客户端封装库)则进一步简化了分布式锁的使用。Spring Cloud Zookeeper 本身不直接提供锁相关 API,但我们可以在 Spring Boot 应用中引入 Curator,再结合 ZooKeeper 实现分布式锁。

5.1 Curator 基础与依赖

1. 添加 Maven 依赖

在项目的 pom.xml 中添加以下 Curator 相关依赖:

<dependency>
    <groupId>org.apache.curator</groupId>
    <artifactId>curator-framework</artifactId>
    <version>5.2.1</version>
</dependency>

<dependency>
    <groupId>org.apache.curator</groupId>
    <artifactId>curator-recipes</artifactId>
    <version>5.2.1</version>
</dependency>
  • curator-framework:Curator 的基础 API,用于创建 ZooKeeper 客户端连接。
  • curator-recipes:Curator 提供的各种“食谱”(Recipes),如分布式锁、Barrier、Leader 选举等。这里我们重点使用分布式锁(InterProcessMutex)。

2. 配置 CuratorFramework Bean

在 Spring Boot 中创建一个配置类,用于初始化 CuratorFramework 并注入到 Spring 容器中:

package com.example.lock.config;

import org.apache.curator.framework.CuratorFramework;
import org.apache.curator.framework.CuratorFrameworkFactory;
import org.apache.curator.retry.ExponentialBackoffRetry;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ZkCuratorConfig {

    @Bean(initMethod = "start", destroyMethod = "close")
    public CuratorFramework curatorFramework() {
        // ExponentialBackoffRetry 参数:初始重试时间、最大重试次数、最大重试时间
        ExponentialBackoffRetry retryPolicy = new ExponentialBackoffRetry(1000, 3);
        return CuratorFrameworkFactory.builder()
                .connectString("127.0.0.1:2181")
                .sessionTimeoutMs(5000)
                .connectionTimeoutMs(3000)
                .retryPolicy(retryPolicy)
                .build();
    }
}
  • connectString:指定 ZooKeeper 地址,可填集群地址列表
  • sessionTimeoutMs:会话超时时间
  • retryPolicy:重试策略,这里使用指数退避重试

CuratorFramework Bean 会在容器启动时自动调用 start(),在容器关闭时调用 close(),完成与 ZooKeeper 的连接和资源释放。

5.2 实现分布式锁的代码示例

1. 分布式锁工具类

以下示例封装了一个简单的分布式锁工具,基于 Curator 的 InterProcessMutex

package com.example.lock.service;

import org.apache.curator.framework.CuratorFramework;
import org.apache.curator.framework.recipes.locks.InterProcessMutex;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.concurrent.TimeUnit;

@Service
public class DistributedLockService {

    private static final String LOCK_ROOT_PATH = "/distributed-lock";

    @Autowired
    private CuratorFramework curatorFramework;

    /**
     * 获取分布式锁
     *
     * @param lockName   锁名称,在 ZooKeeper 下会对应 /distributed-lock/{lockName} 路径
     * @param timeoutSec 获取锁超时时间(秒)
     * @return InterProcessMutex 对象,若获取失败返回 null
     */
    public InterProcessMutex acquireLock(String lockName, long timeoutSec) throws Exception {
        String lockPath = LOCK_ROOT_PATH + "/" + lockName;
        // 创建 InterProcessMutex,内部会在 lockPath 下创建临时顺序节点
        InterProcessMutex lock = new InterProcessMutex(curatorFramework, lockPath);
        // 尝试获取锁,超时后无法获取则返回 false
        boolean acquired = lock.acquire(timeoutSec, TimeUnit.SECONDS);
        if (acquired) {
            return lock;
        } else {
            return null;
        }
    }

    /**
     * 释放分布式锁
     *
     * @param lock InterProcessMutex 对象
     */
    public void releaseLock(InterProcessMutex lock) {
        if (lock != null) {
            try {
                lock.release();
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    }
}
  • 构造 InterProcessMutex(curatorFramework, lockPath) 时,Curator 会在 /distributed-lock/lockName 路径下创建临时顺序子节点,形成分布式锁队列。
  • lock.acquire(timeout, unit):尝试获取锁,阻塞直到成功或超时。
  • lock.release():释放锁时,Curator 会删除自己创建的临时节点,并通知后续等待的客户端。

2. Controller 使用示例

新建一个 REST 控制器,模拟多实例并发争抢锁的场景:

package com.example.lock.controller;

import org.apache.curator.framework.recipes.locks.InterProcessMutex;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import com.example.lock.service.DistributedLockService;

@RestController
public class LockController {

    @Autowired
    private DistributedLockService lockService;

    @GetMapping("/execute-with-lock")
    public String executeWithLock() {
        String lockName = "my-lock";
        InterProcessMutex lock = null;
        try {
            // 尝试获取锁,超时时间 5 秒
            lock = lockService.acquireLock(lockName, 5);
            if (lock == null) {
                return "无法获取分布式锁,请稍后重试";
            }
            // 模拟业务执行
            Thread.sleep(2000);
            return "执行成功,当前线程获得锁并完成业务逻辑";
        } catch (Exception e) {
            return "执行异常:" + e.getMessage();
        } finally {
            // 释放锁
            lockService.releaseLock(lock);
        }
    }
}

启动多个服务实例(端口不同),同时访问 http://localhost:{port}/execute-with-lock,只有第一个获取到锁的实例会真正执行业务,其他请求要么阻塞等待,要么在超时后返回“无法获取锁”。

5.3 分布式锁使用流程图解

┌───────────────────────────────────────────────────────────────────┐
│                          ZooKeeper                                │
│                     (127.0.0.1:2181)                               │
│                                                                    │
│  /distributed-lock                                                 │
│     ├─ my-lock/LOCK-0000000001  (临时顺序节点)                      │
│     ├─ my-lock/LOCK-0000000002                                        │
│     └─ …                                                          │
│                                                                    │
└───────────────────────────────────────────────────────────────────┘
         ▲                     ▲                   ▲
         │ 1. 实例A 调用 acquireLock("my-lock")             │
         │    → 在 /distributed-lock/my-lock 下创建          │
         │      临时顺序节点 LOCK-0000000001 (最小序号)     │
         │    → 获取到锁                                          │
┌───────────────────┐      2. 实例B 同时调用 acquireLock("my-lock")      ┌───────────────────┐
│  实例A (port:8081) │─────▶ 在 /distributed-lock/my-lock 下创建          │  实例B (port:8082) │
│  acquire() → LOCK-0000000001 (最小)   │      临时顺序节点 LOCK-0000000002 (次小)     │
│  成功获得锁       │◀─────────                                           │  等待 LOCK-0000000001 释放锁 │
└───────────────────┘              3. 实例A 释放锁 (release())         └───────────────────┘
         │                     ▲                   │
         │ 4. ZooKeeper 删除 LOCK-0000000001 → 触发 B 的 Watch │
         │                     │                   │
         ▼                     │                   ▼
┌───────────────────────────┐  │  5. 实例B 发现自己序号最小,获得锁  ┌───────────────────────────┐
│  实例A 完成业务逻辑;退出  │  │  (执行 acquire() 返回成功)         │    实例B 完成业务逻辑        │
└───────────────────────────┘  │                                    └───────────────────────────┘
                               │
                               │ 6. 依此类推,其他实例继续排队获取锁

通过 Curator 封装的 InterProcessMutex,我们不需要手动实现序号节点的创建、Watch 监听等底层逻辑,只需调用 acquire()release() 即可保障互斥访问。


监控与运维要点

  1. ZooKeeper 集群化

    • 生产环境建议至少搭建 3\~5 节点的 ZooKeeper 集群,保证分布式协调的可靠性与可用性。
    • 使用投票机制(过半数)进行 leader 选举,避免出现脑裂。
  2. ZooKeeper 数据结构管理

    • 为不同功能(服务注册、配置、锁、队列等)合理规划 ZNode 路径前缀,例如:

      /services/{service-name}/instance-00001
      /config/{application}/{profile}/…
      /distributed-lock/{lock-name}/…
      /queue/{job-name}/…
    • 定期清理历史残留节点,避免节点数量过多导致性能下降。
  3. ZooKeeper 性能优化

    • 内存与文件描述符:为 ZK Server 分配足够的内存,调整操作系统的文件描述符限制(ulimit -n)。
    • heapSize 和 GC:禁用堆外内存开销过大的 GC 参数,并监控 JMX 指标(后续可接入 Prometheus + Grafana)。
    • 一主多从或三节点集群:保证节点之间网络稳定、延迟低。
  4. Spring Cloud Zookeeper 客户端配置

    • 重试策略:在 application.yml 中可配置 retry-policy,例如 ExponentialBackoffRetry,保证短暂网络抖动时客户端自动重连。
    • 心跳与会话超时:调整 sessionTimeoutMsconnectionTimeoutMs 等参数,以匹配应用的可用性要求。
    • 动态配置刷新:若使用分布式配置,确保引入 spring-boot-starter-actuator 并开启 /actuator/refresh 端点,方便手动触发配置刷新。
  5. 故障诊断

    • 常见问题包括:ZooKeeper Session 超时导致临时节点丢失、客户端 Watch 逻辑未处理导致服务发现延迟、节点数过多导致性能下降。
    • 建议使用工具:zkCli.sh 查看 ZNode 结构,ZooInspector 可视化浏览 ZNode 树;定时监控 ZooKeeper 丢失率、平均延迟、请求数等。

总结

通过本文的示例与图解,我们展示了如何使用 Spring Cloud Zookeeper 构建一个基础的分布式协调系统,主要涵盖以下三个方面:

  1. 服务注册与发现

    • 依托 ZooKeeper 临时顺序节点与 Watch 机制,实现实例自动上下线与负载均衡。
    • 利用 Spring Cloud Zookeeper 的 @EnableDiscoveryClientRestTemplate@LoadBalanced)让调用更为简单透明。
  2. 分布式配置中心

    • 将配置信息存放在 ZooKeeper 路径之下,Spring Cloud 在启动时从 ZooKeeper 拉取并注入到环境中。
    • 通过 @RefreshScope/actuator/refresh 实现动态刷新,保证配置修改无需重启即可生效。
  3. 分布式锁

    • 基于 Apache Curator 封装的 InterProcessMutex,让我们无需关心 ZooKeeper 底层的顺序临时节点创建与 Watch 逻辑,只需调用 acquire() / release() 即可实现锁。
    • 在高并发或分布式任务场景下,通过 ZooKeeper 保证互斥访问,保证业务正确性。

除此之外,ZooKeeper 还可支持分布式队列、Leader 选举、Barrier 等更多场景,但核心思想离不开其“一致性”、“顺序节点”和“Watch 机制”。Spring Cloud Zookeeper 将这些能力以极低的使用门槛集成到 Spring Boot 应用中,让我们可以专注于业务逻辑,而不是去实现分布式协调的底层复杂度。

后续拓展方向

  • 分布式队列:基于 ZooKeeper Sequential Node 实现生产者-消费者队列。
  • Leader 选举:使用 Curator 提供的 LeaderSelector,确保集群中只有一个主节点在做特定任务。
  • Service Mesh 与 Zookeeper:与 Istio、Envoy 等技术对比,探索更灵活的服务治理方案。
  • Spring Cloud Alibaba Nacos / Consul 对比:了解 Zookeeper 相对其他注册中心(如 Nacos、Consul、Eureka)的优劣势。

通过掌握本篇内容,相信你可以在自己的项目中快速导入 Spring Cloud Zookeeper,实现服务治理、配置管理和分布式锁等功能,全面提升微服务集群的稳定性与可运维性。

SpringBoot实战:利用Redis Lua脚本实现分布式多命令原子操作与锁

在分布式系统中,多个客户端同时访问同一份共享资源时,往往需要保证操作的原子性与并发安全。Redis 天然支持高并发场景,但如果仅依赖其单命令原子性,对于多命令组合场景(比如同时修改多个键、检查并更新等)就无法保证原子性。而借助 Lua 脚本,Redis 可以将多条命令包装在同一个脚本里执行,保证**“一组命令”**在 Redis 侧原子执行,从而避免并发冲突。此外,Lua 脚本也常用于实现可靠的分布式锁逻辑。

本文将以 Spring Boot + Spring Data Redis 为基础,全面讲解如何通过 Redis Lua 脚本实现:

  1. 多命令原子操作
  2. 分布式锁(含锁超时续命令与安全释放)

内容包含环境准备、概念介绍、关键代码示例、以及图解说明,帮助你更容易上手并快速应用到项目中。


目录

  1. 环境准备
    1.1. 技术栈与依赖
    1.2. Redis 环境部署
  2. Lua 脚本简介
  3. Spring Boot 集成 Spring Data Redis
    3.1. 引入依赖
    3.2. RedisTemplate 配置
  4. Redis Lua 脚本的原子性与执行流程
    4.1. 为什么要用 Lua 脚本?
    4.2. Redis 调用 Lua 脚本执行流程(图解)
  5. 分布式多命令原子操作示例
    5.1. 场景描述:库存扣减 + 订单状态更新
    5.2. Lua 脚本编写
    5.3. Java 端调用脚本
    5.4. 代码示例详解
    5.5. 执行流程图示
  6. 分布式锁实现示例
    6.1. 分布式锁设计思路
    6.2. 简易版锁:SETNX + TTL
    6.3. 安全释放锁:Lua 脚本检测并删除
    6.4. Java 实现分布式锁类
    6.5. 使用示例与图解
  7. 完整示例项目结构一览
  8. 总结

环境准备

1.1 技术栈与依赖

  • JDK 1.8+
  • Spring Boot 2.5.x 或更高
  • Spring Data Redis 2.5.x
  • Redis 6.x 或更高版本
  • Maven 构建工具

主要依赖示例如下(摘自 pom.xml):

<dependencies>
    <!-- Spring Boot Starter Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring Data Redis -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-redis</artifactId>
    </dependency>
    
    <!-- Lettuce (Redis Client) -->
    <dependency>
        <groupId>io.lettuce</groupId>
        <artifactId>lettuce-core</artifactId>
    </dependency>

    <!-- 可选:用于 Lombok 简化代码 -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    
    <!-- 可选:用于日志 -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
    </dependency>
</dependencies>

1.2 Redis 环境部署

本地调试可通过 Docker 快速启动 Redis 实例,命令示例:

docker run -d --name spring-redis -p 6379:6379 redis:6.2.6 redis-server --appendonly yes

如果已经安装 Redis,可直接在本地启动:

redis-server /usr/local/etc/redis/redis.conf

确认 Redis 可用后,可使用 redis-cli 测试连接:

redis-cli ping
# 若返回 PONG 则表示正常

Lua 脚本简介

Lua 是一种轻量级脚本语言,语法简单且灵活。Redis 原生集成了一个 Lua 解释器(基于 Lua 5.1),允许客户端通过 EVAL 命令将“一段” Lua 脚本上传到 Redis 服务器并执行。Lua 脚本执行以下特点:

  1. 原子性
    整段脚本会以单个“调用”原子执行,中间不被其他客户端命令插入。
  2. 效率高
    避免了客户端-服务器之间多次网络往返,直接在服务器端执行多条命令。
  3. 可使用 Redis 原生命令
    在 Lua 脚本里,所有 Redis 命令都可通过 redis.call()redis.pcall() 调用。

常见指令:

  • EVAL script numkeys key1 key2 ... arg1 arg2 ...
  • EVALSHA sha1 numkeys key1 ... arg1 ...

其中:

  • script:Lua 代码
  • numkeys:脚本中要访问的 key 的数量
  • key1/key2...:传入的 key 列表
  • arg1/arg2...:传入的其他参数列表

Spring Boot 集成 Spring Data Redis

3.1 引入依赖

pom.xml 中,确保存在以下依赖:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>
<dependency>
    <groupId>io.lettuce</groupId>
    <artifactId>lettuce-core</artifactId>
</dependency>

Spring Boot 自动配置了 Lettuce 作为 Redis 客户端。如果你想使用 Jedis,只需排除 Lettuce 并引入 Jedis 依赖即可。

3.2 RedisTemplate 配置

在 Spring Boot 中,推荐使用 RedisTemplate<String, Object> 来操作 Redis。我们需要在配置类中进行基础配置:

@Configuration
public class RedisConfig {

    @Bean
    public RedisConnectionFactory redisConnectionFactory() {
        // 默认 LettuceConnectionFactory 会读取 application.properties 中的配置
        return new LettuceConnectionFactory();
    }

    @Bean
    public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) {
        RedisTemplate<String, Object> template = new RedisTemplate<>();
        template.setConnectionFactory(factory);

        // 使用 StringRedisSerializer 序列化 key
        StringRedisSerializer stringSerializer = new StringRedisSerializer();
        template.setKeySerializer(stringSerializer);
        template.setHashKeySerializer(stringSerializer);

        // 使用 Jackson2JsonRedisSerializer 序列化 value
        Jackson2JsonRedisSerializer<Object> jacksonSerializer =
                new Jackson2JsonRedisSerializer<>(Object.class);
        ObjectMapper om = new ObjectMapper();
        om.setVisibility(PropertyAccessor.ALL, JsonAutoDetect.Visibility.ANY);
        om.enableDefaultTyping(ObjectMapper.DefaultTyping.NON_FINAL);
        jacksonSerializer.setObjectMapper(om);
        template.setValueSerializer(jacksonSerializer);
        template.setHashValueSerializer(jacksonSerializer);

        template.afterPropertiesSet();
        return template;
    }
}

application.properties 中,添加 Redis 连接配置:

spring.redis.host=127.0.0.1
spring.redis.port=6379
# 如果有密码,可加上:
# spring.redis.password=yourpassword

有了上述配置后,我们就能在其它组件或 Service 中注入并使用 RedisTemplate<String, Object> 了。


Redis Lua 脚本的原子性与执行流程

4.1 为什么要用 Lua 脚本?

  • 多命令原子性
    如果你在业务逻辑里需要对多个 Key 进行操作(例如:扣库存后更新订单状态),而只是使用多条 Redis 命令,就无法保证这几步操作“同时”成功或失败,存在中途出错导致数据不一致的风险。
  • 减少网络开销
    如果客户端需要执行多条命令,通常要经历 N 次网络往返(RTT)。而使用 Lua 脚本,只需要一次调用,就能在服务器端执行多条命令,极大提高性能。
  • 实现复杂逻辑
    某些场景下,需要复杂的判断、条件分支,这时可以在 Lua 中完成,而不必在客户端反复查询、再发命令,从而减少延迟和潜在的并发问题。

4.2 Redis 调用 Lua 脚本执行流程(图解)

下面是一次典型的 Lua 脚本调用流程示意图:

┌───────────┐               ┌───────────┐               ┌───────────┐
│ Client    │               │ Redis     │               │  Data     │
│ (Java)    │   EVAL LUA     │ Server    │               │ Storage   │
│           ├──────────────▶│           │               │(Key1,Key2)│
└───────────┘    (script)   │           │               └───────────┘
                            │           │
                            │ 1. 加载/执行│
                            │    Lua 脚本│
                            │ 2. 调用 lua │◀────────────┐
                            │    redis.call(... )          │
                            │    多命令执行               │
                            │ 3. 返回结果                  │
                            └───────────┘
                                      ▲
                                      │
                           响应结果    │
                                      │
                              ┌───────────┐
                              │ Client    │
                              │ (Java)    │
                              └───────────┘
  • Step 1:Java 客户端通过 RedisTemplate.execute() 方法,将 Lua 脚本和参数一起提交给 Redis Server。
  • Step 2:Redis 在服务器端加载并执行 Lua 脚本。脚本内可以直接调用 redis.call("GET", key)redis.call("SET", key, value) 等命令。此时,Redis 会对这整个脚本加锁,保证脚本执行期间,其他客户端命令不会插入。
  • Step 3:脚本执行完后,将返回值(可以是数字、字符串、数组等)返回给客户端。

分布式多命令原子操作示例

5.1 场景描述:库存扣减 + 订单状态更新

假设我们有一个电商场景,需要在用户下单时执行两步操作:

  1. 检查并扣减库存
  2. 更新订单状态为“已创建”

如果拆成两条命令:

IF stock > 0 THEN DECR stockKey
SET orderStatusKey "CREATED"

在高并发情况下,这两条命令无法保证原子性,可能出现以下问题:

  1. 扣减库存后,更新订单状态时程序异常,导致库存减少但订单未创建。
  2. 查询库存时,已被其他线程扣减,但未及时更新,导致库存不足。

此时,借助 Lua 脚本可以将“检查库存 + 扣减库存 + 更新订单状态”三步逻辑,放在一个脚本里执行,保证原子性。

5.2 Lua 脚本编写

创建一个名为 decr_stock_and_create_order.lua 的脚本,内容如下:

-- decr_stock_and_create_order.lua

-- 获取传入的参数
-- KEYS[1] = 库存 KEY (e.g., "product:stock:1001")
-- KEYS[2] = 订单状态 KEY (e.g., "order:status:abcd1234")
-- ARGV[1] = 扣减数量 (一般为 1)
-- ARGV[2] = 订单状态 (e.g., "CREATED")

local stockKey = KEYS[1]
local orderKey = KEYS[2]
local decrCount = tonumber(ARGV[1])
local statusVal = ARGV[2]

-- 查询当前库存
local currentStock = tonumber(redis.call("GET", stockKey) or "-1")

-- 如果库存不足,则返回 -1 代表失败
if currentStock < decrCount then
    return -1
end

-- 否则,扣减库存
local newStock = redis.call("DECRBY", stockKey, decrCount)

-- 将订单状态写入 Redis
redis.call("SET", orderKey, statusVal)

-- 返回剩余库存
return newStock

脚本说明:

  1. local stockKey = KEYS[1]:第一个 Redis Key,表示商品库存
  2. local orderKey = KEYS[2]:第二个 Redis Key,表示订单状态
  3. ARGV[1]:要扣减的库存数量
  4. ARGV[2]:订单状态值
  5. 先做库存检查:若不足,直接返回 -1
  6. 再做库存扣减 + 写入订单状态,最后返回剩余库存

5.3 Java 端调用脚本

在 Spring Boot 项目中,我们可以将上述 Lua 脚本放在 resources/scripts/ 目录下,然后通过 DefaultRedisScript 加载并执行。

1)加载脚本

@Component
public class LuaScriptLoader {

    /**
     * 加载 "decr_stock_and_create_order.lua" 脚本文件
     * 脚本返回值类型是 Long
     */
    @Bean
    public DefaultRedisScript<Long> decrStockAndCreateOrderScript() {
        DefaultRedisScript<Long> redisScript = new DefaultRedisScript<>();
        // 指定脚本文件路径(classpath 下)
        redisScript.setLocation(new ClassPathResource("scripts/decr_stock_and_create_order.lua"));
        redisScript.setResultType(Long.class);
        return redisScript;
    }
}
注意ClassPathResource("scripts/decr_stock_and_create_order.lua") 要与 src/main/resources/scripts/ 目录对应。

2)Service 层执行脚本

@Service
public class OrderService {

    @Autowired
    private StringRedisTemplate stringRedisTemplate; // 也可用 RedisTemplate<String, Object>

    @Autowired
    private DefaultRedisScript<Long> decrStockAndCreateOrderScript;

    /**
     * 尝试扣减库存并创建订单
     *
     * @param productId   商品ID
     * @param orderId     订单ID
     * @param decrCount   扣减数量,一般为1
     * @return 如果返回 -1 ,表示库存不足;否则返回扣减后的剩余库存
     */
    public long decrStockAndCreateOrder(String productId, String orderId, int decrCount) {
        // 组装 Redis key
        String stockKey = "product:stock:" + productId;
        String orderKey = "order:status:" + orderId;

        // KEYS 列表
        List<String> keys = Arrays.asList(stockKey, orderKey);
        // ARGV 列表
        List<String> args = Arrays.asList(String.valueOf(decrCount), "CREATED");

        // 执行 Lua 脚本
        Long result = stringRedisTemplate.execute(
                decrStockAndCreateOrderScript,
                keys,
                args.toArray()
        );

        if (result == null) {
            throw new RuntimeException("Lua 脚本返回 null");
        }
        return result;
    }
}
  • stringRedisTemplate.execute(...):第一个参数是 DefaultRedisScript,指定脚本和返回类型;
  • 第二个参数是 keys 列表;
  • 剩余可变参数 args 对应脚本中的 ARGV

如果 result == -1,代表库存不足,需在用户侧抛出异常或返回提示;否则返回剩余库存供业务使用。

5.4 代码示例详解

  1. Lua 脚本层面

    • 首先用 redis.call("GET", stockKey) 获取当前库存,这是原子操作。
    • 判断库存是否足够:如果 currentStock < decrCount,直接返回 -1,表示库存不足,并结束脚本。
    • 否则,使用 redis.call("DECRBY", stockKey, decrCount) 进行扣减,返回新的库存数。
    • 接着用 redis.call("SET", orderKey, statusVal) 将订单状态写入 Redis。
    • 最后将 newStock 返回给 Java 客户端。
  2. Java 层面

    • 通过 DefaultRedisScript<Long> 将 Lua 脚本加载到 Spring 容器中,该 Bean 名为 decrStockAndCreateOrderScript
    • OrderService 中注入 StringRedisTemplate(简化版 RedisTemplate<String, String>),同时注入 decrStockAndCreateOrderScript
    • 调用 stringRedisTemplate.execute(...),将脚本、Key 列表与参数列表一并传递给 Redis。
    • 使用脚本返回的 Long 值决定业务逻辑分支。

这样一来,无论在多高并发的场景下,这个“扣库存 + 生成订单”操作,都能在 Redis 侧以原子方式执行,避免并发冲突和数据不一致风险。

5.5 执行流程图示

下面用 ASCII 图解总体执行流程,帮助理解:

┌─────────────────┐      1. 发送 EVAL 脚本请求       ┌─────────────────┐
│  Java 客户端    │ ─────────────────────────────▶ │    Redis Server  │
│ (OrderService)  │    KEYS=[stockKey,orderKey]   │                 │
│                 │    ARGV=[1, "CREATED"]       │                 │
└─────────────────┘                                └─────────────────┘
                                                       │
                                                       │ 2. 在 Redis 端加载脚本
                                                       │   并执行以下 Lua 代码:
                                                       │   if stock<1 then return -1
                                                       │   else decr库存; set 订单状态; return newStock
                                                       │
                                                       ▼
                                                ┌─────────────────┐
                                                │  Redis 数据层    │
                                                │ (Key:product:   │
                                                │  stock:1001)    │
                                                └─────────────────┘
                                                       │
                                                       │ 3. 返回执行结果 = newStock 或 -1
                                                       │
                                                       ▼
┌─────────────────┐                                ┌─────────────────┐
│  Java 客户端    │ ◀──────────────────────────── │    Redis Server  │
│ (OrderService)  │    返回 Long result           │                 │
│                 │    (e.g. 99 或 -1)           │                 │
└─────────────────┘                                └─────────────────┘

分布式锁实现示例

在分布式系统中,很多场景需要通过分布式锁来控制同一资源在某一时刻只能一个客户端访问。例如:秒杀场景、定时任务并发调度、数据迁移等。

下面以 Redis + Lua 脚本方式实现一个安全、可靠的分布式锁。主要思路与步骤如下:

  1. 使用 SET key value NX PX timeout 来尝试获取锁
  2. 如果获取成功,返回 OK
  3. 如果获取失败,返回 null,可重试或直接失败
  4. 释放锁时,需要先判断 value 是否和自己存储的标识一致,以防误删他人锁
注意:判断并删除的逻辑需要通过 Lua 脚本实现,否则会出现“先 GET 再 DEL”期间锁被别的客户端抢走,造成误删。

6.1 分布式锁设计思路

  • 锁 Key:比如 lock:order:1234
  • 值 Value:每个客户端生成一个唯一随机值(UUID),保证释放锁时只删除自己持有的锁
  • 获取锁SET lockKey lockValue NX PX expireTime,NX 表示只有当 key 不存在时才设置,PX 表示设置过期时间
  • 释放锁:通过 Lua 脚本,判断 redis.call("GET", lockKey) == lockValue 时,才执行 DEL lockKey

6.2 简易版锁:SETNX + TTL

在没有 Lua 脚本时,最简单的分布式锁(不推荐):

public boolean tryLockSimple(String lockKey, String lockValue, long expireTimeMillis) {
    // 使用 StringRedisTemplate
    Boolean success = stringRedisTemplate.opsForValue()
        .setIfAbsent(lockKey, lockValue, Duration.ofMillis(expireTimeMillis));
    return Boolean.TRUE.equals(success);
}

public void unlockSimple(String lockKey) {
    stringRedisTemplate.delete(lockKey);
}

缺点:

  1. 释放锁时无法判断当前锁是否属于自己,会误删别人的锁。
  2. 如果业务执行时间超过 expireTimeMillis,锁过期后被别人获取,导致解锁删除了别人的锁。

6.3 安全释放锁:Lua 脚本检测并删除

编写一个 Lua 脚本 redis_unlock.lua,内容如下:

-- redis_unlock.lua
-- KEYS[1] = lockKey
-- ARGV[1] = lockValue

-- 只有当存储的 value 和传入 value 相同时,才删除锁
if redis.call("GET", KEYS[1]) == ARGV[1] then
    return redis.call("DEL", KEYS[1])
else
    return 0
end

运行流程:

  1. client 传入 lockKeylockValue
  2. 脚本先执行 GET lockKey,若值等于 lockValue,则执行 DEL lockKey,并返回删除结果(1)
  3. 否则直接返回 0,不做任何删除

这样就保证了“只删除自己加的锁”,避免误删锁的问题。

6.4 Java 实现分布式锁类

在 Spring Boot 中,我们可以封装一个 RedisDistributedLock 工具类,封装锁的获取与释放逻辑。

1)加载解锁脚本

@Component
public class RedisScriptLoader {

    // 前面已经加载了 decrStock 脚本,下面加载解锁脚本
    @Bean
    public DefaultRedisScript<Long> unlockScript() {
        DefaultRedisScript<Long> redisScript = new DefaultRedisScript<>();
        redisScript.setLocation(new ClassPathResource("scripts/redis_unlock.lua"));
        redisScript.setResultType(Long.class);
        return redisScript;
    }
}

2)封装分布式锁工具类

@Service
public class RedisDistributedLock {

    @Autowired
    private StringRedisTemplate stringRedisTemplate;

    @Autowired
    private DefaultRedisScript<Long> unlockScript;

    /**
     * 尝试获取分布式锁
     *
     * @param lockKey        锁 Key
     * @param lockValue      锁 Value(通常为 UUID)
     * @param expireTimeMillis 过期时间(毫秒)
     * @return 是否获取成功
     */
    public boolean tryLock(String lockKey, String lockValue, long expireTimeMillis) {
        Boolean success = stringRedisTemplate.opsForValue()
                .setIfAbsent(lockKey, lockValue, Duration.ofMillis(expireTimeMillis));
        return Boolean.TRUE.equals(success);
    }

    /**
     * 释放锁:只有锁的持有者才能释放
     *
     * @param lockKey   锁 Key
     * @param lockValue 锁 Value
     * @return 是否释放成功
     */
    public boolean unlock(String lockKey, String lockValue) {
        List<String> keys = Collections.singletonList(lockKey);
        List<String> args = Collections.singletonList(lockValue);
        // 执行 lua 脚本,返回 1 代表删除了锁,返回 0 代表未删除
        Long result = stringRedisTemplate.execute(unlockScript, keys, args.toArray());
        return result != null && result > 0;
    }
}
方法解析
  • tryLock

    • 使用 stringRedisTemplate.opsForValue().setIfAbsent(key,value,timeout)SETNX + TTL,保证只有当 key 不存在时,才设置成功
    • expireTimeMillis 用于避免死锁,防止业务没有正常释放锁导致锁永远存在
  • unlock

    • 通过先 GET lockKeylockValue 做对比,等于时再 DEL lockKey,否则不删除
    • 这部分通过 redis_unlock.lua Lua 脚本实现原子“校验并删除”

6.5 使用示例与图解

1)使用示例

@RestController
@RequestMapping("/api/lock")
public class LockController {

    @Autowired
    private RedisDistributedLock redisDistributedLock;

    @GetMapping("/process")
    public ResponseEntity<String> processTask() {
        String lockKey = "lock:task:123";
        String lockValue = UUID.randomUUID().toString();
        long expireTime = 5000; // 5秒过期

        boolean acquired = redisDistributedLock.tryLock(lockKey, lockValue, expireTime);
        if (!acquired) {
            return ResponseEntity.status(HttpStatus.CONFLICT).body("获取锁失败,请稍后重试");
        }

        try {
            // 业务处理逻辑
            Thread.sleep(3000); // 模拟执行 3 秒
            return ResponseEntity.ok("任务执行成功");
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("任务执行异常");
        } finally {
            // 释放锁(安全释放)
            boolean released = redisDistributedLock.unlock(lockKey, lockValue);
            if (!released) {
                // 日志记录:释放锁失败(可能锁已过期被其他人持有)
                System.err.println("释放锁失败,lockKey=" + lockKey + ", lockValue=" + lockValue);
            }
        }
    }
}

2)解锁 Lua 脚本流程图(图解)

┌────────────────┐         1. EVAL redis_unlock.lua         ┌─────────────────┐
│ Java 客户端    │ ─────────────────────────────────────────▶ │  Redis Server    │
│ (unlock 方法) │    KEYS=[lockKey], ARGV=[lockValue]      │                  │
└────────────────┘                                         └─────────────────┘
                                                              │
                                                              │ 2. 执行 Lua:
                                                              │    if GET(key)==value 
                                                              │       then DEL(key)
                                                              │       else return 0
                                                              │
                                                              ▼
                                                    ┌──────────────────────────┐
                                                    │   Redis Key-Value 存储     │
                                                    │   lockKey -> lockValue     │
                                                    └──────────────────────────┘
                                                              │
                                                              │ 3. 返回结果 1 或 0
                                                              ▼
┌────────────────┐                                         ┌─────────────────┐
│ Java 客户端    │ ◀───────────────────────────────────────── │  Redis Server    │
│ (unlock 方法) │   返回 1(删除成功)或 0(未删除)         │                  │
└────────────────┘                                         └─────────────────┘

这样,分布式锁的获取与释放就得到了很好的保障,在高并发分布式场景中能避免竞态条件与误删锁带来的风险。


完整示例项目结构一览

以下是本文示例代码对应的典型项目目录结构:

springboot-redis-lua-demo/
├── pom.xml
├── src
│   ├── main
│   │   ├── java
│   │   │   └── com.example.redisluademo
│   │   │       ├── RedisConfig.java
│   │   │       ├── LuaScriptLoader.java
│   │   │       ├── OrderService.java
│   │   │       ├── RedisDistributedLock.java
│   │   │       └── controller
│   │   │            ├── OrderController.java
│   │   │            └── LockController.java
│   │   └── resources
│   │       ├── application.properties
│   │       └── scripts
│   │           ├── decr_stock_and_create_order.lua
│   │           └── redis_unlock.lua
│   └── test
│       └── java
│           └── com.example.redisluademo
│               └── RedisLuaDemoApplicationTests.java
└── README.md

简要说明:

  • RedisConfig.java:配置 RedisTemplate
  • LuaScriptLoader.java:加载 Lua 脚本
  • OrderService.java:演示多命令原子操作脚本调用
  • RedisDistributedLock.java:分布式锁工具类
  • OrderController.java:演示下单调用示例(可选,适当演示接口)
  • LockController.java:演示分布式锁场景
  • decr_stock_and_create_order.luaredis_unlock.lua:两个核心 Lua 脚本

总结

本文详细介绍了在 Spring Boot 项目中,如何借助 Redis Lua 脚本,实现:

  1. 分布式多命令原子操作

    • 通过 Lua 脚本将 “检查库存、扣库存、写订单状态” 三步逻辑打包在一起,保证在 Redis 端以原子方式执行,避免中途失败导致数据不一致。
    • 在 Java 侧,通过 DefaultRedisScript 加载脚本并配合 RedisTemplate.execute() 调用脚本。
  2. 分布式锁

    • 结合 SETNX + TTL 实现基本的加锁操作;
    • 利用 Lua 脚本保证“先校验 Value 再删除”这一操作的原子性,避免误删除锁的问题。
    • 在 Java 侧封装加锁与解锁逻辑,确保业务执行期间获取到合适的并发控制。

通过“代码示例 + 图解”,本文帮助你较为清晰地理解 Redis Lua 脚本在高并发场景下的威力,以及如何在 Spring Boot 中优雅地集成使用。你可以将上述示例直接复制到项目中,根据业务需求进行扩展和优化。

Tip

  • 如果业务中有更复杂的并发控制需求,也可以借助像 Redisson 这样的 Redis 客户端,直接使用它封装好的分布式锁和信号量功能。
  • 发布时间和配置请根据线上的 Redis 版本进行测试,注意 Redis 集群模式下 Lua 脚本涉及到多节点 key 存取时,需要将所有 key 定位到同一个 slot,否则脚本会报错。

Spring Boot项目中MyBatis-Plus多容器分布式部署ID重复问题深度剖析

一、引言

在微服务架构或容器化部署环境下,往往会将同一个 Spring Boot 应用镜像在多台机器或多个容器中运行,以实现高可用与负载均衡。若项目使用 MyBatis-Plus 默认的自增主键策略(AUTO_INCREMENT),多容器并发写入数据库时,就会出现 ID 冲突或重复的问题,严重影响数据一致性。本文将从问题产生的根本原因出发,结合代码示例与图解,深入剖析常见的 ID 生成方案,并演示如何在 MyBatis-Plus 中优雅地解决分布式部署下的 ID 重复问题。


二、问题背景与分析

2.1 单实例 vs 多容器部署的差异

  • 单实例部署:Spring Boot 应用只有一个实例访问数据库,使用 AUTO_INCREMENT 主键时,数据库会为每条插入操作自动分配连续且唯一的主键,几乎不存在 ID 冲突问题。
  • 多容器部署:在 Kubernetes 或 Docker Swarm 等环境下,我们可能将相同应用运行多份,容器 A 和容器 B 同时向同一张表批量插入数据。如果依赖数据库自增字段,就需要确保所有写请求串行化,否则在高并发下仍会依赖数据库锁定机制。尽管数据库会避免同一时刻分配相同自增值,但在水平扩展且读写分离、分库分表等场景中,自增 ID 仍然可能产生冲突或不连续(例如各库自增起始值相同)。

另外,如果采用了分库分表,数据库层面的自增序列在不同分表间并不能保证全局唯一。更重要的是,在多副本缓存层、分布式消息队列中回写数据时,单纯的自增 ID 也会带来重复风险。

2.2 MyBatis-Plus 默认主键策略

MyBatis-Plus 的 @TableId 注解默认使用 IdType.NONE,若数据库表主键列是自增类型(AUTO_INCREMENT),MyBatis-Plus 会从 JDBC 执行插入后获取数据库生成的自增 ID。参考代码:

// 实体类示例
public class User {
    @TableId(value = "id", type = IdType.AUTO)
    private Long id;
    private String name;
    // ... Getter/Setter ...
}

上述映射在单实例场景下工作正常,但无法在多容器分布式部署中避免 ID 重复。


三、常见分布式ID生成方案

3.1 UUID

  • 原理:通过 java.util.UUIDUUID.randomUUID() 生成一个全局唯一的 128 位标识(字符串格式),几乎不会重复。
  • 优缺点

    • 优点:不需集中式协调,简单易用;
    • 缺点:UUID 较长,存储与索引成本高;对于数字型主键需要额外转换;无法按顺序排列,影响索引性能。

示例代码:

// 在实体类中使用 UUID 作为 ID
public class Order {
    @TableId(value = "id", type = IdType.ASSIGN_UUID)
    private String id;
    private BigDecimal amount;
    // ...
}

MyBatis-Plus IdType.ASSIGN_UUID 会在插入前调用 UUID.randomUUID().toString().replace("-", ""),得到 32 位十六进制字符串。

3.2 数据库全局序列(Sequence)

  • 多数企业数据库(如 Oracle、PostgreSQL)支持全局序列。每次从序列获取下一个值,保证全局唯一。
  • 缺点:MySQL 直到 8.0 才支持 CREATE SEQUENCE,很多旧版 MySQL 仍需通过“自增表”或“自增列+段值”来模拟序列,略显麻烦。且跨分库分表场景下,需要集中式获取序列,略损性能。

MyBatis-Plus 在 MySQL 上也可通过以下方式使用自定义序列:

// 在数据库中创建一个自增表 seq_table(id BIGINT AUTO_INCREMENT)
@TableId(value = "id", type = IdType.INPUT)
private Long id;

// 插入前通过 Mapper 获取 seq_table 的下一个自增值
Long nextId = seqTableMapper.nextId();
user.setId(nextId);
userMapper.insert(user);

3.3 Redis 全局自增

  • 利用 Redis 的 INCRINCRBY 操作,保证在单个 Redis 实例或集群的状态下,自增序列全局唯一。
  • 优缺点

    • 优点:性能高(内存操作),可集群部署;
    • 缺点:Redis 宕机或分区时需要方案保证可用性与数据持久化,且 Redis 也是单点写。

示例代码(Spring Boot + Lettuce/Redisson):

@Autowired
private StringRedisTemplate redisTemplate;

public Long generateOrderId() {
    return redisTemplate.opsForValue().increment("global:order:id");
}

// 在实体插入前设置 ID
Long id = generateOrderId();
order.setId(id);
orderMapper.insert(order);

3.4 Twitter Snowflake 算法

  • 原理:Twitter 开源的 Snowflake 算法生成 64 位整型 ID,结构为:1 位符号(0),41 位时间戳(毫秒)、10 位机器标识(datacenterId + workerId,可自定义位数),12 位序列号(同一毫秒内自增)。
  • 优缺点

    • 优点:整体性能高、单机无锁,支持多节点同时生成;ID 有时间趋势,可按时间排序。
    • 缺点:需要配置机器 ID 保证不同实例的 datacenterId+workerId 唯一;时间回拨会导致冲突。

MyBatis-Plus 内置对 Snowflake 的支持,只需将 @TableId(type = IdType.ASSIGN_ID)IdType.ASSIGN_SNOWFLAKE 应用在实体类上。


四、MyBatis-Plus 中使用 Snowflake 的实战演示

下面以 Snowflake 为例,演示如何在 Spring Boot + MyBatis-Plus 多容器分布式环境中确保 ID 唯一。示例将演示:

  1. 配置 MyBatis-Plus 使用 Snowflake
  2. 生成唯一的 workerId / datacenterId
  3. 在实体中声明 @TableId(type = IdType.ASSIGN_ID)
  4. 演示两个容器同时插入数据不冲突

4.1 Spring Boot 项目依赖

pom.xml 中引入 MyBatis-Plus:

<dependencies>
    <!-- MyBatis-Plus Starter -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-boot-starter</artifactId>
        <version>3.5.3.1</version>
    </dependency>
    <!-- MySQL 驱动 -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>8.0.31</version>
    </dependency>
    <!-- Spring Boot Starter Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

4.2 创建一个雪花算法 ID 生成器 Bean

在 Spring Boot 启动类或单独的配置类中,注册 MyBatis-Plus 提供的 IdentifierGenerator 实现:

import com.baomidou.mybatisplus.core.incrementer.DefaultIdentifierGenerator;
import com.baomidou.mybatisplus.core.incrementer.IdentifierGenerator;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SnowflakeConfig {

    /**
     * MyBatis-Plus 默认的雪花算法实现 DefaultIdentifierGenerator
     * 使用前请确保在 application.properties 中配置了以下属性:
     * mybatis-plus.snowflake.worker-id=1
     * mybatis-plus.snowflake.datacenter-id=1
     */
    @Bean
    public IdentifierGenerator idGenerator() {
        return new DefaultIdentifierGenerator();
    }
}

DefaultIdentifierGenerator 会读取 Spring 环境变量 mybatis-plus.snowflake.worker-idmybatis-plus.snowflake.datacenter-id 来初始化 Snowflake 算法实例,workerIddatacenterId 需要保证在所有容器实例中不重复。

4.3 application.yml / application.properties 配置

假设使用 YAML,分别为不同实例配置不同的 worker-id

spring:
  application:
    name: mybatisplus-demo

mybatis-plus:
  snowflake:
    worker-id: ${WORKER_ID:0}
    datacenter-id: ${DATACENTER_ID:0}
  global-config:
    db-config:
      id-type: ASSIGN_ID
  • ${WORKER_ID:0} 允许通过环境变量注入,每个容器通过 Docker 或 Kubernetes 环境变量指定不同值。
  • id-type: ASSIGN_ID 表示全局主键策略为 MyBatis-Plus 内置雪花算法生成。

启动时,在容器 A 中设置 WORKER_ID=1,在容器 B 中设置 WORKER_ID=2,二者保证不同,即可避免冲突。

4.4 实体类示例

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import java.time.LocalDateTime;

@TableName("user")
public class User {

    @TableId(type = IdType.ASSIGN_ID)
    private Long id;

    private String username;
    private String email;

    // 自动填充示例(可选)
    private LocalDateTime createTime;
    private LocalDateTime updateTime;

    // Getter/Setter...
}
  • @TableId(type = IdType.ASSIGN_ID):MyBatis-Plus 在插入前会调用默认的 IdentifierGenerator(即 DefaultIdentifierGenerator),按 Snowflake 算法生成唯一 Long 值。

4.5 Mapper 接口与 Service 层示例

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import org.apache.ibatis.annotations.Mapper;

@Mapper
public interface UserMapper extends BaseMapper<User> {
    // 继承 BaseMapper 即可具有基本 CRUD 操作
}
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class UserService {
    @Autowired
    private UserMapper userMapper;

    public User createUser(String username, String email) {
        User user = new User();
        user.setUsername(username);
        user.setEmail(email);
        userMapper.insert(user);
        return user;
    }
}

不需要手动设置 id,MyBatis-Plus 会自动调用 Snowflake 生成。

4.6 演示多容器插入

启动两个容器实例:

  • 容器 A(WORKER_ID=1
  • 容器 B(WORKER_ID=2

同时发送如下 HTTP 请求(假设 REST API 已暴露):

POST /users  请求体: {"username":"alice","email":"alice@example.com"}
  • 在容器 A 中处理时,Snowflake 算法产生的 id 例如 140xxxxx0001
  • 在容器 B 中处理时,Snowflake 算法产生的 id 例如 140xxxxx1001
    两者不会重复;如“图:多容器部署中基于Snowflake的ID生成示意图”所示,分别对应不同 workerId 的实例同时向同一个共享数据库插入数据,主键不会冲突。

五、图解:多容器部署中 Snowflake ID 生成示意图

(上方已展示“图:多容器部署中基于Snowflake的ID生成示意图”)

  • Container1(workerId=1)Container2(workerId=2)
  • 各自使用 Snowflake 算法,通过高位的 workerId 区分,生成不同 ID
  • 两者同时插入到共享数据库,不会产生重复的主键

六、其他分布式ID生成方案对比与选型

6.1 UUID vs Snowflake

方案唯一性长度时间趋势索引效率配置复杂度
UUID (String)极高36/32 字符较差
Snowflake极高64 位数值
  • 如果对 ID 长度与排序性能要求高,推荐 Snowflake。
  • 若对二进制 ID 不能接受、只需简单唯一值,可使用 UUID。

6.2 Redis 全局自增 vs Snowflake

方案唯一性性能单点压力配置复杂度
Redis INCR极高Redis 单点写
Snowflake极高无单点写
  • Redis 需考虑高可用切换与持久化,对运维要求高;Snowflake 纯 Java 实现,无额外依赖,更易水平扩展。

七、总结与实践建议

  1. 避免数据库自增主键
    多容器部署时不要再依赖单一数据库自增,应选用分布式 ID 生成方案。
  2. 选择合适的方案

    • Snowflake:大多数场景下的首选,性能高、可排序;
    • UUID:对性能与索引要求不高、需要跨语言兼容时可采纳;
    • Redis:需谨慎考虑 Redis 高可用与分区容错。
  3. 环境变量注入 workerId
    在 Kubernetes 中可通过 ConfigMap 或 Deployment 环境变量注入不同的 WORKER_ID,确保各实例唯一。
  4. 注意时钟回拨问题
    如果服务器时间被回调,会导致 Snowflake 生成重复或回退 ID,请使用 NTP 保证时钟一致或引入时间回拨处理逻辑。
  5. 回源策略
    如果数据库或 ID 服务不可用,应对插入操作进行失败重试或降级,避免影响业务可用性。

综上所述,通过在 Spring Boot + MyBatis-Plus 中使用 Snowflake(IdType.ASSIGN_ID)或其他分布式 ID 生成器,可以有效避免多容器部署下的 ID 重复问题,保障系统高可用与数据一致性。

2025-05-31

目录

  1. 前言:为何要在前端加密?
  2. CryptoJS 简介与安装配置

    1. CryptoJS 主要功能概览
    2. 在 Vue 中安装并引入 CryptoJS
  3. 前端加密实战:使用 AES 对称加密

    1. AES 加密原理简述
    2. 在 Vue 组件中编写 AES 加密函数
    3. 示例代码:登录表单提交前加密
    4. 前端加密流程 ASCII 图解
  4. 后端解密实战:Java 中使用 JCE 解密

    1. Java 加密/解密基础(JCE)
    2. Java 后端引入依赖(Maven 配置)
    3. Java 解密工具类示例
    4. Spring Boot Controller 示例接收并解密
    5. 后端解密流程 ASCII 图解
  5. 完整示例:从前端到后台的端到端流程

    1. Vue 端示例组件:登录并加密提交
    2. Java 后端示例:解密并校验用户名密码
  6. 注意事项与最佳实践

    1. 密钥与 IV 的管理
    2. 数据完整性与签名
    3. 前端加密的局限性
  7. 总结

1. 前言:为何要在前端加密?

在传统的客户端-服务器交互中,用户在前端输入的敏感信息(如用户名、密码、信用卡号等)通常会以明文通过 HTTPS 提交到后台。即便在 HTTPS 保护下,仍有以下安全隐患:

  • 前端漏洞:如果用户的浏览器或网络受到中间人攻击,可能篡改或窃取表单数据。虽然 HTTPS 可以避免网络监听,但存在一些复杂场景(如企业网络代理、根证书伪造等),会让 HTTPS 保护失效。
  • 浏览器泄露:当用户在公用计算机或不安全环境下输入敏感数据,可能被浏览器插件劫持。
  • 后端日志:如果后端在日志中意外记录了明文敏感信息,可能存在泄露风险。
  • 合规需求:某些行业(如金融、医疗)要求即便在传输层使用 TLS,也要在应用层对敏感数据额外加密以符合法规。

因此,在前端对敏感数据进行一次对称加密(如 AES),并在后端对其解密,能够为安全防护增加一道“保险层”,即便数据在传输层被截获,也难以被攻击者直接获取明文。

**本指南将演示如何在 Vue 前端使用 CryptoJS 对数据(以登录密码为例)进行 AES 加密,并在 Java 后端使用 JCE(Java Cryptography Extension)对之解密验证。**整个流程清晰可见,适合初学者和中高级开发者参考。


2. CryptoJS 简介与安装配置

2.1 CryptoJS 主要功能概览

CryptoJS 是一套纯 JavaScript 实现的常用加密算法库,包含以下常见模块:

  • 哈希函数:MD5、SHA1、SHA224、SHA256、SHA3 等
  • 对称加密:AES、DES、TripleDES、RC4、Rabbit
  • 编码方式:Base64、UTF-8、Hex、Latin1 等
  • HMAC(Hash-based Message Authentication Code):HmacSHA1、HmacSHA256 等

由于 CryptoJS 纯前端可用,不依赖于 Node 内置模块,体积较小、使用方便,常用于浏览器环境的数据加密、签名和哈希操作。


2.2 在 Vue 中安装并引入 CryptoJS

  1. 安装 CryptoJS
    在你的 Vue 项目根目录下执行:

    npm install crypto-js --save

    或者使用 Yarn:

    yarn add crypto-js
  2. 在组件中引入 CryptoJS

    • 在需要进行加密操作的 Vue 组件中,引入相关模块。例如我们要使用 AES 对称加密,可写:

      import CryptoJS from 'crypto-js';
    • 如果只想单独引入 AES 相关模块以减小包体积,也可以:

      import AES from 'crypto-js/aes';
      import Utf8 from 'crypto-js/enc-utf8';
      import Base64 from 'crypto-js/enc-base64';

      这样打包后只会包含 AES、Utf8、Base64 模块,而不会附带其他算法。

  3. 配置示例(main.js 或组件中)
    若希望在全局都可以使用 CryptoJS,可在 main.js 中:

    import Vue from 'vue';
    import CryptoJS from 'crypto-js';
    Vue.prototype.$crypto = CryptoJS;

    这样在任意组件中,可以通过 this.$crypto.AES.encrypt(...) 访问 CryptoJS 功能。不过出于清晰性,我们更建议在单个组件顶层直接 import CryptoJS from 'crypto-js'


3. 前端加密实战:使用 AES 对称加密

为了最大程度地兼容性与安全性,我们采用 AES-256-CBC 模式对称加密。对称加密的特点是加密/解密使用同一个密钥(Key)与初始向量(IV),加密速度快,适合浏览器端。

3.1 AES 加密原理简述

  • AES(Advanced Encryption Standard,高级加密标准)是一种分组密码算法,支持 128、192、256 位密钥长度。
  • CBC 模式(Cipher Block Chaining):对每个分组与前一分组的密文进行异或运算,增强安全性。
  • 对称加密的基本流程:

    1. 生成密钥(Key)与初始向量(IV):Key 一般为 32 字节(256 位),IV 长度为 16 字节(128 位)。
    2. 对明文进行 Padding:AES 分组长度为 16 字节,不足则填充(CryptoJS 默认使用 PKCS#7 填充)。
    3. 加密:For each block: CipherText[i] = AES_Encrypt(PlainText[i] ⊕ CipherText[i-1]),其中 CipherText[0] = AES_Encrypt(PlainText[0] ⊕ IV)
    4. 输出密文:以 Base64 或 Hex 編码传输。

要在前端与后端一致地加解密,需约定相同的 KeyIVPadding编码方式。本例中,我们统一使用:

  • Key:以 32 字节随机字符串(由后端与前端约定),使用 UTF-8 编码
  • IV:以 16 字节随机字符串(也可以使用固定或随机 IV),使用 UTF-8 编码
  • Padding:默认 PKCS#7
  • 输出:Base64 编码

示例

Key = '12345678901234567890123456789012'  // 32 字节
IV  = 'abcdefghijklmnop'                // 16 字节

3.2 在 Vue 组件中编写 AES 加密函数

在 Vue 组件中,可将加密逻辑封装为一个方法,方便调用。以下示例演示如何使用 CryptoJS 对字符串进行 AES-256-CBC 加密并输出 Base64。

<script>
import CryptoJS from 'crypto-js';

export default {
  name: 'EncryptExample',
  data() {
    return {
      // 测试用明文
      plaintext: 'Hello, Vue + Java 加密解密!',
      // 32 字节(256 位)Key,前后端需保持一致
      aesKey: '12345678901234567890123456789012',
      // 16 字节(128 位)IV
      aesIv: 'abcdefghijklmnop',
      // 存放加密后 Base64 密文
      encryptedText: ''
    };
  },
  methods: {
    /**
     * 使用 AES-256-CBC 对 plaintext 进行加密,输出 Base64
     */
    encryptAES(plain) {
      // 将 Key 与 IV 转成 WordArray
      const key = CryptoJS.enc.Utf8.parse(this.aesKey);
      const iv  = CryptoJS.enc.Utf8.parse(this.aesIv);
      // 执行加密
      const encrypted = CryptoJS.AES.encrypt(
        CryptoJS.enc.Utf8.parse(plain),
        key,
        {
          iv: iv,
          mode: CryptoJS.mode.CBC,
          padding: CryptoJS.pad.Pkcs7
        }
      );
      // encrypted.toString() 默认返回 Base64 编码
      return encrypted.toString();
    },
    /**
     * 测试加密流程
     */
    doEncrypt() {
      this.encryptedText = this.encryptAES(this.plaintext);
      console.log('加密后的 Base64:', this.encryptedText);
    }
  },
  mounted() {
    // 示例:组件加载后自动加密一次
    this.doEncrypt();
  }
};
</script>
  • 核心步骤

    1. CryptoJS.enc.Utf8.parse(...):将 UTF-8 字符串转为 CryptoJS 能识别的 WordArray(内部格式)。
    2. CryptoJS.AES.encrypt(messageWordArray, keyWordArray, { iv, mode, padding }):执行加密。
    3. encrypted.toString():将加密结果以 Base64 字符串形式返回。

如果想输出 Hex 编码,可写 encrypted.ciphertext.toString(CryptoJS.enc.Hex);但后端也要对应以 Hex 解码。


3.3 示例代码:登录表单提交前加密

通常我们在登录时,只需对“密码”字段进行加密,其他表单字段(如用户名、验证码)可不加密。以下是一个完整的 Vue 登录示例:

<!-- src/components/Login.vue -->
<template>
  <div class="login-container">
    <h2>登录示例(前端 AES 加密)</h2>
    <el-form :model="loginForm" ref="loginFormRef" label-width="80px">
      <el-form-item label="用户名" prop="username" :rules="[{ required: true, message: '请输入用户名', trigger: 'blur' }]">
        <el-input v-model="loginForm.username" autocomplete="off"></el-input>
      </el-form-item>
      <el-form-item label="密码" prop="password" :rules="[{ required: true, message: '请输入密码', trigger: 'blur' }]">
        <el-input v-model="loginForm.password" type="password" autocomplete="off"></el-input>
      </el-form-item>
      <el-form-item>
        <el-button type="primary" @click="handleSubmit">登录</el-button>
      </el-form-item>
    </el-form>

    <div v-if="encryptedPassword">
      <h4>加密后密码(Base64):</h4>
      <p class="cipher">{{ encryptedPassword }}</p>
    </div>
  </div>
</template>

<script>
import CryptoJS from 'crypto-js';
import axios from 'axios';

export default {
  name: 'Login',
  data() {
    return {
      loginForm: {
        username: '',
        password: ''
      },
      // 与后端约定的 Key 与 IV(示例)
      aesKey: '12345678901234567890123456789012',
      aesIv: 'abcdefghijklmnop',
      encryptedPassword: ''
    };
  },
  methods: {
    /**
     * 对密码进行 AES 加密,返回 Base64
     */
    encryptPassword(password) {
      const key = CryptoJS.enc.Utf8.parse(this.aesKey);
      const iv  = CryptoJS.enc.Utf8.parse(this.aesIv);
      const encrypted = CryptoJS.AES.encrypt(
        CryptoJS.enc.Utf8.parse(password),
        key,
        {
          iv: iv,
          mode: CryptoJS.mode.CBC,
          padding: CryptoJS.pad.Pkcs7
        }
      );
      return encrypted.toString();
    },
    /**
     * 表单提交事件
     */
    handleSubmit() {
      this.$refs.loginFormRef.validate(valid => {
        if (!valid) return;
        // 1. 对密码加密
        const cipherPwd = this.encryptPassword(this.loginForm.password);
        this.encryptedPassword = cipherPwd;
        // 2. 组装参数提交给后端
        const payload = {
          username: this.loginForm.username,
          password: cipherPwd // 将密文发送给后端
        };
        // 3. 发送 POST 请求
        axios.post('/api/auth/login', payload)
          .then(res => {
            console.log('后端返回:', res.data);
            this.$message.success('登录成功!');
          })
          .catch(err => {
            console.error(err);
            this.$message.error('登录失败!');
          });
      });
    }
  }
};
</script>

<style scoped>
.login-container {
  width: 400px;
  margin: 50px auto;
}
.cipher {
  word-break: break-all;
  background: #f5f5f5;
  padding: 10px;
  border: 1px dashed #ccc;
}
</style>
  • 该示例使用了 Element-UI 的 el-formel-inputel-button 组件,仅作演示。
  • encryptPassword 方法对 loginForm.password 进行 AES 加密,并把 Base64 密文赋给 encryptedPassword(用于在页面上实时展示)。
  • 提交请求时,将 username 与加密后的 password 一并 POST 到后端 /api/auth/login 接口。后端收到密文后需要对其解密,才能比对数据库中的明文(或哈希)密码。

3.4 前端加密流程 ASCII 图解

┌────────────────────────────────────────┐
│             用户输入表单               │
│  username: alice                       │
│  password: mySecret123                 │
└──────────────┬─────────────────────────┘
               │  点击“登录”触发 handleSubmit()
               ▼
   ┌─────────────────────────────────────┐
   │ 调用 encryptPassword('mySecret123') │
   │  1. keyWordArray = Utf8.parse(aesKey) │
   │  2. ivWordArray  = Utf8.parse(aesIv)  │
   │  3. encrypted = AES.encrypt(          │
   │       Utf8.parse(password),           │
   │       keyWordArray,                   │
   │       { iv: ivWordArray, mode: CBC }  │
   │    )                                  │
   │  4. cipherText = encrypted.toString() │
   └──────────────┬───────────────────────┘
                  │  返回 Base64 密文
                  ▼
   ┌─────────────────────────────────────┐
   │ 组装 payload = {                    │
   │   username: 'alice',                │
   │   password: 'U2FsdGVkX1...=='        │
   │ }                                    │
   └──────────────┬───────────────────────┘
                  │  axios.post('/api/auth/login', payload)
                  ▼
   ┌─────────────────────────────────────┐
   │    发送 HTTPS POST 请求 (json)       │
   └─────────────────────────────────────┘

4. 后端解密实战:Java 中使用 JCE 解密

前端对数据进行了 AES-256-CBC 加密并以 Base64 格式发送到后端,Java 后端需要做以下几件事:

  1. 接收 Base64 密文字符串
  2. Base64 解码得到密文字节数组
  3. 使用与前端相同的 Key、IV 以及填充模式(PKCS5Padding,对应 PKCS7)进行 AES 解密
  4. 将解密后的字节数组转换为 UTF-8 明文

下面逐步演示在 Java(以 Spring Boot 为例)中如何解密。


4.1 Java 加密/解密基础(JCE)

Java 中的加密/解密 API 集中在 javax.crypto 包内,核心类包括:

  • Cipher:加解密的核心类,指定算法/模式/填充方式后,可调用 init()doFinal() 进行加密解密。
  • SecretKeySpec:用来将字节数组转换成对称密钥 SecretKey
  • IvParameterSpec:用来封装初始化向量(IV)。
  • Base64:Java 8 内置的 Base64 编解码类(java.util.Base64)。

对应 AES/CBC/PKCS5Padding 解密流程示例(伪代码):

// 1. 准备 Key 与 IV
byte[] keyBytes = aesKey.getBytes(StandardCharsets.UTF_8); // 32 字节
byte[] ivBytes  = aesIv.getBytes(StandardCharsets.UTF_8);  // 16 字节
SecretKeySpec keySpec = new SecretKeySpec(keyBytes, "AES");
IvParameterSpec ivSpec = new IvParameterSpec(ivBytes);

// 2. Base64 解码密文
byte[] cipherBytes = Base64.getDecoder().decode(base64CipherText);

// 3. 初始化 Cipher
Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
cipher.init(Cipher.DECRYPT_MODE, keySpec, ivSpec);

// 4. 执行解密
byte[] plainBytes = cipher.doFinal(cipherBytes);

// 5. 转为 UTF-8 字符串
String plaintext = new String(plainBytes, StandardCharsets.UTF_8);

注意:Java 默认使用 PKCS5Padding,而 CryptoJS 使用的是 PKCS7Padding。二者在实现上是兼容的,所以无需额外配置即可互通。


4.2 Java 后端引入依赖(Maven 配置)

如果你使用 Spring Boot,可在 pom.xml 中引入 Web 依赖即可,无需额外加密库,因为 JCE 已内置于 JDK。示例如下:

<!-- pom.xml -->
<project>
  <!-- ... 省略其他配置 ... -->
  <dependencies>
    <!-- Spring Boot Web Starter -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- 如果需要 JSON 处理,Spring Boot 通常自带 Jackson -->
    <!-- 直接使用 spring-boot-starter-web 即可 -->
  </dependencies>
</project>

对于更早期的 JDK(如 JDK 7),若使用 AES-256 可能需要安装 JCE Unlimited Strength Jurisdiction Policy Files。不过从 JDK 8u161 开始,Unlimited Strength 已默认启用,无需额外安装。


4.3 Java 解密工具类示例

src/main/java/com/example/util/EncryptUtils.java 创建一个工具类 EncryptUtils,封装 AES 解密方法:

package com.example.util;

import javax.crypto.Cipher;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class EncryptUtils {

    /**
     * 使用 AES/CBC/PKCS5Padding 对 Base64 编码的密文进行解密
     *
     * @param base64CipherText 前端加密后的 Base64 密文
     * @param aesKey           与前端约定的 32 字节(256 位)Key
     * @param aesIv            与前端约定的 16 字节 (128 位) IV
     * @return 解密后的明文字符串
     */
    public static String decryptAES(String base64CipherText, String aesKey, String aesIv) {
        try {
            // 1. 将 Base64 密文解码成字节数组
            byte[] cipherBytes = Base64.getDecoder().decode(base64CipherText);

            // 2. 准备 Key 和 IV
            byte[] keyBytes = aesKey.getBytes(StandardCharsets.UTF_8);
            byte[] ivBytes  = aesIv.getBytes(StandardCharsets.UTF_8);
            SecretKeySpec keySpec = new SecretKeySpec(keyBytes, "AES");
            IvParameterSpec ivSpec = new IvParameterSpec(ivBytes);

            // 3. 初始化 Cipher
            Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
            cipher.init(Cipher.DECRYPT_MODE, keySpec, ivSpec);

            // 4. 执行解密
            byte[] plainBytes = cipher.doFinal(cipherBytes);

            // 5. 转为字符串并返回
            return new String(plainBytes, StandardCharsets.UTF_8);
        } catch (Exception e) {
            e.printStackTrace();
            return null; // 解密失败返回 null,可根据实际情况抛出异常
        }
    }
}

关键点说明

  • aesKey.getBytes(StandardCharsets.UTF_8):将约定的 32 字节 Key 转为字节数组。
  • Cipher.getInstance("AES/CBC/PKCS5Padding"):指定 AES/CBC 模式,填充方式为 PKCS5Padding。
  • SecretKeySpecIvParameterSpec 分别封装 Key 与 IV。
  • cipher.doFinal(cipherBytes):执行真正的解密操作,返回明文字节数组。

4.4 Spring Boot Controller 示例接收并解密

以下示例展示如何在 Spring Boot Controller 中接收前端发送的 JSON 请求体,提取密文字段并调用 EncryptUtils.decryptAES(...) 解密,再与数据库中的明文/哈希密码进行比对。

// src/main/java/com/example/controller/AuthController.java
package com.example.controller;

import com.example.util.EncryptUtils;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@RestController
@RequestMapping("/api/auth")
public class AuthController {

    // 与前端保持一致的 Key 与 IV
    private static final String AES_KEY = "12345678901234567890123456789012"; // 32 字节
    private static final String AES_IV  = "abcdefghijklmnop";                 // 16 字节

    /**
     * 登录接口:接收前端加密后的用户名 & 密码,解密后验证
     */
    @PostMapping("/login")
    public ResponseEntity<?> login(@RequestBody Map<String, String> payload) {
        String username     = payload.get("username");
        String encryptedPwd = payload.get("password");

        // 1. 对密码进行解密
        String plainPassword = EncryptUtils.decryptAES(encryptedPwd, AES_KEY, AES_IV);
        if (plainPassword == null) {
            return ResponseEntity.badRequest().body("解密失败");
        }

        // 2. TODO:在这里根据 username 从数据库查询用户信息,并比对明文密码或哈希密码
        // 假设从数据库查出 storedPassword
        String storedPassword = "mySecret123"; // 示例:实际项目中请使用哈希比对

        if (plainPassword.equals(storedPassword)) {
            // 验证通过
            return ResponseEntity.ok("登录成功!");
        } else {
            return ResponseEntity.status(401).body("用户名或密码错误");
        }
    }
}
  • 方法参数 @RequestBody Map<String, String> payload:Spring 会自动将 JSON 转为 Map,其中 username 对应用户输入的用户名,password 对应前端加密后的 Base64 密文。
  • 成功解密后,得到明文密码 plainPassword。在实际项目中,应将 plainPassword 与数据库中存储的哈希密码(如 BCrypt 存储)比对,而不是直接明文比对。此处为了演示,假设数据库中存的是明文 mySecret123

4.5 后端解密流程 ASCII 图解

Vue 前端发送请求:
POST /api/auth/login
Content-Type: application/json

{
  "username": "alice",
  "password": "U2FsdGVkX18Yr8...=="  // Base64 AES-256-CBC 密文
}

        │
        ▼
┌───────────────────────────────────────────────────────────┐
│        AuthController.login(@RequestBody payload)        │
│  1. username = payload.get("username")                   │
│  2. encryptedPwd = payload.get("password")               │
│  3. 调用 EncryptUtils.decryptAES(encryptedPwd, AES_KEY, AES_IV) │
│     → Base64.decode → Cipher.init → doFinal() → 明文 bytes  │
│     → 转字符串 plainPassword                             │
│  4. 从数据库查出 storedPassword                           │
│  5. plainPassword.equals(storedPassword) ?                 │
│       - 是:登录成功                                       │
│       - 否:用户名或密码错误                               │
└───────────────────────────────────────────────────────────┘

5. 完整示例:从前端到后台的端到端流程

下面将前面零散的代码整合为一个“简单的登录Demo”,包括 Vue 端组件与 Java Spring Boot 后端示例,方便你实践一遍完整流程。

5.1 Vue 端示例组件:登录并加密提交

项目目录结构(前端)

vue-cryptojs-demo/
├── public/
│   └── index.html
├── src/
│   ├── App.vue
│   ├── main.js
│   └── components/
│       └── Login.vue
├── package.json
└── vue.config.js

src/components/Login.vue

<template>
  <div class="login-container">
    <h2>Vue + CryptoJS 登录示例</h2>
    <el-form :model="loginForm" ref="loginFormRef" label-width="80px">
      <el-form-item label="用户名" prop="username" :rules="[{ required: true, message: '请输入用户名', trigger: 'blur' }]">
        <el-input v-model="loginForm.username" autocomplete="off"></el-input>
      </el-form-item>
      <el-form-item label="密码" prop="password" :rules="[{ required: true, message: '请输入密码', trigger: 'blur' }]">
        <el-input v-model="loginForm.password" type="password" autocomplete="off"></el-input>
      </el-form-item>
      <el-form-item>
        <el-button type="primary" @click="handleSubmit">登录</el-button>
      </el-form-item>
    </el-form>

    <div v-if="encryptedPassword" style="margin-top: 20px;">
      <h4>加密后密码(Base64):</h4>
      <p class="cipher">{{ encryptedPassword }}</p>
    </div>
  </div>
</template>

<script>
import CryptoJS from 'crypto-js';
import axios from 'axios';

export default {
  name: 'Login',
  data() {
    return {
      loginForm: {
        username: '',
        password: ''
      },
      // 与后端保持一致的 Key 与 IV
      aesKey: '12345678901234567890123456789012', // 32 字节
      aesIv: 'abcdefghijklmnop',                // 16 字节
      encryptedPassword: ''
    };
  },
  methods: {
    /**
     * 对密码进行 AES/CBC/PKCS7 加密
     */
    encryptPassword(password) {
      const key = CryptoJS.enc.Utf8.parse(this.aesKey);
      const iv = CryptoJS.enc.Utf8.parse(this.aesIv);
      const encrypted = CryptoJS.AES.encrypt(
        CryptoJS.enc.Utf8.parse(password),
        key,
        {
          iv: iv,
          mode: CryptoJS.mode.CBC,
          padding: CryptoJS.pad.Pkcs7
        }
      );
      return encrypted.toString(); // Base64
    },
    /**
     * 表单提交
     */
    handleSubmit() {
      this.$refs.loginFormRef.validate(valid => {
        if (!valid) return;
        // 1. 对密码加密
        const cipherPwd = this.encryptPassword(this.loginForm.password);
        this.encryptedPassword = cipherPwd;
        // 2. 组装参数
        const payload = {
          username: this.loginForm.username,
          password: cipherPwd
        };
        // 3. 发送请求到后端(假设后端地址为 http://localhost:8080)
        axios.post('http://localhost:8080/api/auth/login', payload)
          .then(res => {
            this.$message.success(res.data);
          })
          .catch(err => {
            console.error(err);
            if (err.response && err.response.status === 401) {
              this.$message.error('用户名或密码错误');
            } else {
              this.$message.error('登录失败,请稍后重试');
            }
          });
      });
    }
  }
};
</script>

<style scoped>
.login-container {
  width: 400px;
  margin: 50px auto;
}
.cipher {
  word-break: break-all;
  background: #f5f5f5;
  padding: 10px;
  border: 1px dashed #ccc;
}
</style>

src/App.vue

<template>
  <div id="app">
    <Login />
  </div>
</template>

<script>
import Login from './components/Login.vue';

export default {
  name: 'App',
  components: { Login }
};
</script>

<style>
body {
  font-family: 'Arial', sans-serif;
}
</style>

src/main.js

import Vue from 'vue';
import App from './App.vue';
// 引入 Element-UI(可选)
import ElementUI from 'element-ui';
import 'element-ui/lib/theme-chalk/index.css';

Vue.use(ElementUI);

Vue.config.productionTip = false;

new Vue({
  render: h => h(App)
}).$mount('#app');
至此,前端示例部分完成。用户输入用户名和密码,点击“登录”后触发 handleSubmit(),先加密密码并显示加密结果,再将加密后的密码与用户名一起以 JSON POST 到 Spring Boot 后端。

5.2 Java 后端示例:解密并校验用户名密码

项目目录结构(后端)

java-cryptojs-demo/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   ├── com/example/DemoApplication.java
│   │   │   ├── controller/AuthController.java
│   │   │   └── util/EncryptUtils.java
│   │   └── resources/
│   │       └── application.properties
└── pom.xml

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
             http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>java-cryptojs-demo</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>
  <name>Java CryptoJS Demo</name>
  <description>Spring Boot Demo for CryptoJS Decryption</description>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.5.5</version>
  </parent>

  <dependencies>
    <!-- Spring Boot Web -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Lombok(可选,用于简化日志) -->
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <optional>true</optional>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <!-- Spring Boot Maven Plugin -->
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

src/main/java/com/example/DemoApplication.java

package com.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

src/main/java/com/example/util/EncryptUtils.java

package com.example.util;

import javax.crypto.Cipher;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class EncryptUtils {

    /**
     * 解密 Base64 AES 密文(AES/CBC/PKCS5Padding)
     *
     * @param base64CipherText 前端加密后的 Base64 编码密文
     * @param aesKey           32 字节 Key
     * @param aesIv            16 字节 IV
     * @return 明文字符串 或 null(解密失败)
     */
    public static String decryptAES(String base64CipherText, String aesKey, String aesIv) {
        try {
            // Base64 解码
            byte[] cipherBytes = Base64.getDecoder().decode(base64CipherText);

            // Key 与 IV
            byte[] keyBytes = aesKey.getBytes(StandardCharsets.UTF_8);
            byte[] ivBytes = aesIv.getBytes(StandardCharsets.UTF_8);
            SecretKeySpec keySpec = new SecretKeySpec(keyBytes, "AES");
            IvParameterSpec ivSpec = new IvParameterSpec(ivBytes);

            // 初始化 Cipher
            Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
            cipher.init(Cipher.DECRYPT_MODE, keySpec, ivSpec);

            // 执行解密
            byte[] plainBytes = cipher.doFinal(cipherBytes);
            return new String(plainBytes, StandardCharsets.UTF_8);
        } catch (Exception e) {
            e.printStackTrace();
            return null;
        }
    }
}

src/main/java/com/example/controller/AuthController.java

package com.example.controller;

import com.example.util.EncryptUtils;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@RestController
@RequestMapping("/api/auth")
public class AuthController {

    // 与前端保持一致的 Key 与 IV
    private static final String AES_KEY = "12345678901234567890123456789012";
    private static final String AES_IV  = "abcdefghijklmnop";

    @PostMapping("/login")
    public ResponseEntity<?> login(@RequestBody Map<String, String> payload) {
        String username     = payload.get("username");
        String encryptedPwd = payload.get("password");

        // 解密
        String plainPassword = EncryptUtils.decryptAES(encryptedPwd, AES_KEY, AES_IV);
        if (plainPassword == null) {
            return ResponseEntity.badRequest().body("解密失败");
        }

        // TODO:在此处根据 username 查询数据库并校验密码
        // 演示:假设用户名 alice,密码 mySecret123
        if ("alice".equals(username) && "mySecret123".equals(plainPassword)) {
            return ResponseEntity.ok("登录成功!");
        } else {
            return ResponseEntity.status(401).body("用户名或密码错误");
        }
    }
}

src/main/resources/application.properties

server.port=8080

启动后端

mvn clean package
java -jar target/java-cryptojs-demo-1.0.0.jar

后端将监听在 http://localhost:8080,与前端的 Axios 请求保持一致。


6. 注意事项与最佳实践

6.1 密钥与 IV 的管理

  1. 切勿将 Key 明文硬编码在生产代码中

    • 生产环境应通过更安全的方式管理密钥,例如从环境变量、Vault 服务或后端配置中心动态下发。
    • 前端存储 Key 本身并不能完全保证安全,只是增加一次防护。如果前端 Key 泄露,攻击者依然可以伪造密文。
  2. IV 的选择

    • CBC 模式下 IV 应尽量随机生成,保证同一明文多次加密输出不同密文,从而增强安全性。
    • 在示例中,我们使用了固定 IV 便于演示与调试。在生产中,建议每次随机生成 IV,并将 IV 与密文一起发送给后端(例如将 IV 放在密文前面,Base64 编码后分割)。

    示例

    // 前端随机生成 16 字节 IV
    const ivRandom = CryptoJS.lib.WordArray.random(16);
    const encrypted = CryptoJS.AES.encrypt(
      CryptoJS.enc.Utf8.parse(plainPassword),
      key,
      { iv: ivRandom, mode: CryptoJS.mode.CBC, padding: CryptoJS.pad.Pkcs7 }
    );
    // 将 IV 与密文一起拼接:iv + encrypted.toString()
    const result = ivRandom.toString(CryptoJS.enc.Base64) + ':' + encrypted.toString();

    后端解密时,需先从 result 中解析出 Base64 IV 和 Base64 Ciphertext,分别解码后调用 AES 解密。

  3. Key 的长度与格式

    • AES-256 要求 Key 长度为 32 字节,AES-128 则要求 Key 长度为 16 字节。可根据需求选择。
    • 请使用 UTF-8 编码来生成字节数组。若 Key 包含非 ASCII 字符,务必保持前后端编码一致。

6.2 数据完整性与签名

对称加密只能保证机密性(confidentiality),即对手无法从密文恢复明文,但并不能保证数据在传输过程中未被篡改。为此,可在密文外层再加一层签名(HMAC)或摘要校验(SHA256):

  1. 计算 HMAC-SHA256

    • 在发送密文 cipherText 之外,前端对 cipherText 使用 HMAC-SHA256 计算签名 signature = HMAC_SHA256(secretSignKey, cipherText)
    • { cipherText, signature } 一并发送给后台。
    • 后端收到后,先用相同的 secretSignKeycipherText 计算 HMAC 并比对 signature,确保密文未被中间篡改,再做 AES 解密。
  2. 代码示例(前端)

    import CryptoJS from 'crypto-js';
    
    // 1. 计算签名
    const signature = CryptoJS.HmacSHA256(cipherText, signKey).toString();
    
    // 2. 最终 payload
    const payload = {
      username: 'alice',
      password: cipherText,
      sign: signature
    };
  3. 代码示例(后端)

    // 1. 接收 cipherText 与 sign
    String cipherText = payload.get("password");
    String sign       = payload.get("sign");
    
    // 2. 使用相同的 signKey 计算 HMAC-SHA256
    Mac hmac = Mac.getInstance("HmacSHA256");
    hmac.init(new SecretKeySpec(signKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] computed = hmac.doFinal(cipherText.getBytes(StandardCharsets.UTF_8));
    String computedSign = Base64.getEncoder().encodeToString(computed);
    
    if (!computedSign.equals(sign)) {
        return ResponseEntity.status(400).body("签名校验失败");
    }
    // 3. 通过签名校验后再解密
    String plainPassword = EncryptUtils.decryptAES(cipherText, AES_KEY, AES_IV);

这样,前端加密完的数据在传输过程中不仅是机密的,还保证了完整性防篡改


6.3 前端加密的局限性

  1. Key 暴露风险

    • 前端的 Key 无法完全保密,只要用户手里有源码或在浏览器控制台调试,就能看到 Key。真正的机密管理应在后端完成。
    • 前端加密更多是一种“次级防护”,用于防止简单的明文泄露,而非替代后端安全机制。
  2. 仅防止明文泄露,并不防止重放攻击

    • 如果攻击者截获了合法密文,仍可直接“重放”该密文来进行登录尝试。解决方法:

      • 在加密前插入时间戳随机数(nonce)等参数,并在后端验证这些参数是否过期或是否已使用。
      • 结合 HMAC 签名,确保每次请求的签名必须与时间戳/随机数一致。
  3. 兼容性与浏览器支持

    • CryptoJS 纯 JavaScript 实现,对大多数现代浏览器兼容良好,但在极老旧浏览器可能性能较差。
    • 如果对性能要求更高,可考虑使用 Web Crypto API(仅限现代浏览器),但兼容性不如 CryptoJS 广泛。

7. 总结

本文全面介绍了如何在 Vue 前端使用 CryptoJS 进行 AES 对称加密,并在 Java 后端使用 JCE 进行解密的端到端流程。涵盖内容包括:

  1. 前端加密动机:为何要在传输层之外再额外加密敏感数据。
  2. CryptoJS 介绍与安装:如何在 Vue 项目中引入并使用 CryptoJS 进行 AES 加密。
  3. 前端加密示例:详细讲解 AES/CBC/PKCS7 加密流程及代码示例,演示登录时对密码加密提交。
  4. 后端解密详解:基于 JCE 的 AES/CBC/PKCS5Padding 解密实现,并在 Spring Boot Controller 中演示如何接收并验证。
  5. 完整示例:提供 Vue 端组件与 Java 后端示例,展示实际运行效果。
  6. 注意事项与最佳实践:包括密钥和 IV 管理、数据完整性签名、防重放攻击,以及前端加密局限性等。

通过本文,你可以快速上手在 Vue 与 Java 环境下实现安全的对称加密与解密,提升敏感数据传输的安全性。当然,在实际生产环境中,还应结合更完善的认证授权、HTTPS/TLS、Token 签名等方案,共同构筑更高强度的安全防线。

2025-05-26

SpringAI轻松构建MCP Client-Server架构


一、背景与概念

Spring AI 是 Spring Boot 生态下的一个扩展框架,用于简化在 Java 应用中集成大型语言模型(LLM)及外部工具的流程。通过它,我们可以快速创建符合模型上下文协议(MCP,Model Context Protocol)标准的 Client 与 Server,使得大模型能够主动或被动地调用各种资源与工具,从而大幅提升 AI 应用的能力(DeepSeek, 腾讯云)。MCP 将 AI 模型、客户端和服务器抽象成三层架构:

  • 客户端(Client):运行在应用方,承担与 LLM 的交互,将用户输入转换为 MCP 请求;
  • 服务器(Server):作为中间层,接收 MCP 请求并调用后端资源或功能;
  • 资源(Resource):包括数据库、外部 API、业务逻辑等实际可被调用的能力(博客园, 博客园)。

下面我们以 Spring AI MCP 为基础,从环境准备、项目依赖、代码示例和流程图解,详细讲解如何构建一个简单的 MCP Client-Server 架构,并为你提供可复制的代码示例,助你快速上手。


二、环境准备与依赖

1. 系统要求

  • Java 17+,Maven 3.6+;
  • 操作系统:Linux、macOS 或 Windows(需安装 JDK);
  • IDE:IntelliJ IDEA、Eclipse 等。

2. 添加 Maven 依赖

在 Client 与 Server 项目中,我们分别引入 Spring Boot 与 Spring AI MCP Starter。以下是两个项目的 pom.xml 关键片段:

2.1 MCP Server pom.xml

<properties>
    <java.version>17</java.version>
    <spring-boot.version>3.4.3</spring-boot.version>
    <spring-ai.version>1.0.0-M6</spring-ai.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Spring Boot 核心依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- MCP Server Starter(基于 WebMVC) -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-mcp-server-webmvc-spring-boot-starter</artifactId>
    </dependency>
    <!-- Lombok 简化 Getter/Setter(可选) -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    <!-- 测试依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <!-- 辅助库(如 Hutool,可根据需要添加) -->
    <dependency>
        <groupId>cn.hutool</groupId>
        <artifactId>hutool-all</artifactId>
        <version>5.8.36</version>
    </dependency>
</dependencies>
  • spring-ai-mcp-server-webmvc-spring-boot-starter 提供了服务器端自动配置与 MCP 协议接口(博客园, DeepSeek);
  • spring-ai-bom 负责统一管理 Spring AI 相关依赖的版本。

2.2 MCP Client pom.xml

<properties>
    <java.version>17</java.version>
    <spring-boot.version>3.4.3</spring-boot.version>
    <spring-ai.version>1.0.0-M6</spring-ai.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Spring Boot 核心依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- MCP Client Starter -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
    </dependency>
    <!-- 如果需要使用 WebFlux,可引入 reactive 依赖 -->
    <!-- <dependency> -->
    <!--     <groupId>org.springframework.boot</groupId> -->
    <!--     <artifactId>spring-boot-starter-webflux</artifactId> -->
    <!-- </dependency> -->
    <!-- Lombok、测试类等按需添加 -->
</dependencies>
  • spring-ai-mcp-client-spring-boot-starter 提供了客户端自动配置、MCP 请求发送与封装框架(Home, 腾讯云);
  • 两个项目都可以选择引入 WebFlux Starter 来实现异步通信,但本文以 WebMVC 为主。

三、MCP 架构与流程图解

在实际开发中,MCP 架构可以抽象为如下三层关系图:

+------------------+       +--------------------+       +-------------------+
|                  |       |                    |       |                   |
|   AI 大模型      | <---> |  MCP Client (前端) | <---> | MCP Server (后端) |
| (DeepSeek/ChatGPT)|       |                    |       |                   |
+------------------+       +--------------------+       +-------------------+
                                     |                        |
                                     v                        v
                           +------------------+       +-------------------+
                           | 数据库/文件/API   |       | 外部服务/其他工具  |
                           +------------------+       +-------------------+
  1. AI 大模型:通常部署在第三方平台(如 OpenAI、DeepSeek、ChatGPT 等),负责自然语言理解与生成。
  2. MCP Client:作为模型的前置代理,接收来自前端/用户的指令,转换为 MCP 标准请求(JSON-RPC 2.0),并与 MCP Server 通信。
  3. MCP Server:接收 MCP Client 发送的请求,根据请求的“能力”( Capability )调用本地资源(如数据库、文件、API 等),并将执行结果返回给 Client。
  4. Resource(资源层):包含存储、业务系统、工具函数等实际可被调用的内容。

整体流程如下:

  1. 用户发起问题(如“查询订单状态”)→
  2. AI 模型生成一段指令(如 {"capability": "order.query", "params": {...}})→
  3. MCP Client 将该指令封装为 JSON-RPC 请求,通过 STDIO、HTTP 等协议发送给 MCP Server→
  4. MCP Server 根据 capability 调用对应的业务逻辑(如从数据库中查询订单),获取结果→
  5. MCP Server 将结果以 JSON-RPC 响应形式返回给 Client→
  6. MCP Client 将调用结果拼接回大模型的上下文,让 AI 模型基于最新信息生成最终回答(博客园, 维基百科)。

四、实现 MCP Server

下面以一个简单的“订单查询”服务为例,演示如何使用 Spring AI MCP Server 构建后端能力提供方。

1. 项目结构概览

mcp-server/
├─ src/
│  ├─ main/
│  │  ├─ java/
│  │  │   └─ com.example.mcpserver/
│  │  │        ├─ McpServerApplication.java      // Spring Boot 启动类
│  │  │        ├─ controller/
│  │  │        │   └─ OrderCapabilityController.java  // MCP 能力控制器
│  │  │        ├─ service/
│  │  │        │   └─ OrderService.java          // 订单业务逻辑
│  │  │        └─ model/
│  │  │            └─ Order.java                 // 订单领域模型
│  │  └─ resources/
│  │      ├─ application.yml                    // 配置文件
│  │      └─ data/
│  │          └─ orders.json                    // 模拟数据库:订单数据
└─ pom.xml

2. 配置文件(application.yml

spring:
  application:
    name: mcp-server
  ai:
    mcp:
      server:
        enabled: true              # 启用 MCP Server 自动配置
        transports:
          - name: default
            protocol: http        # 使用 HTTP 协议
            options:
              port: 8081          # Server 监听端口
  • spring.ai.mcp.server.enabled: true:开启 MCP Server 自动化配置(博客园, DeepSeek);
  • transports 可配置多种传输协议,此处使用 HTTP,监听 8081 端口。

3. 启动类(McpServerApplication.java

package com.example.mcpserver;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class McpServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }
}
  • 标准 Spring Boot 启动类,无需额外配置,Spring AI MCP Server Starter 会根据 application.yml 自动注册 MCP Server 对应的 JSON-RPC Endpoint。

4. 领域模型(Order.java

package com.example.mcpserver.model;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor
@NoArgsConstructor
public class Order {
    private String orderId;
    private String productName;
    private Double amount;
    private String status;
}
  • 简单的订单实体,包含订单号、商品名、金额与状态字段。

5. 业务逻辑(OrderService.java

package com.example.mcpserver.service;

import com.example.mcpserver.model.Order;
import org.springframework.stereotype.Service;

import javax.annotation.PostConstruct;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;

@Service
public class OrderService {

    private Map<String, Order> orderMap;

    @PostConstruct
    public void init() throws IOException {
        // 从 resources/data/orders.json 读取模拟订单数据
        String json = new String(Files.readAllBytes(Paths.get(
            getClass().getClassLoader().getResource("data/orders.json").toURI())));
        List<Order> orders = new ObjectMapper().readValue(json, new TypeReference<List<Order>>() {});
        orderMap = orders.stream().collect(Collectors.toMap(Order::getOrderId, o -> o));
    }

    public Order queryById(String orderId) {
        return orderMap.get(orderId);
    }
}
  • @PostConstruct 注解表示在 Bean 初始化完成后,读取本地 JSON 模拟数据,构建 orderMap
  • queryById 方法根据订单号查询订单。

6. MCP 能力控制器(OrderCapabilityController.java

package com.example.mcpserver.controller;

import com.example.mcpserver.model.Order;
import com.example.mcpserver.service.OrderService;
import org.springframework.ai.mcp.server.annotation.McpCapability;
import org.springframework.ai.mcp.server.annotation.McpController;
import org.springframework.ai.mcp.server.model.McpRequest;
import org.springframework.ai.mcp.server.model.McpResponse;
import org.springframework.beans.factory.annotation.Autowired;

import java.util.HashMap;
import java.util.Map;

@McpController
public class OrderCapabilityController {

    @Autowired
    private OrderService orderService;

    /**
     * 接收能力请求:capability = "order.query"
     * 请求 params 示例:{"orderId":"12345"}
     */
    @McpCapability(name = "order.query")
    public McpResponse queryOrder(McpRequest request) {
        // 从请求中解析参数
        String orderId = request.getParams().get("orderId").toString();
        Order order = orderService.queryById(orderId);

        Map<String, Object> result = new HashMap<>();
        if (order != null) {
            result.put("orderId", order.getOrderId());
            result.put("productName", order.getProductName());
            result.put("amount", order.getAmount());
            result.put("status", order.getStatus());
        } else {
            result.put("error", "Order not found");
        }

        // 返回 MCP 响应
        return McpResponse.success(result);
    }
}
  • @McpController 标注该类为 MCP Server 控制器;
  • @McpCapability(name = "order.query") 表示此方法映射到能力名称 order.query
  • 方法入参 McpRequest 自动封装 JSON-RPC 中的 params
  • 返回值 McpResponse.success(...) 会被序列化为符合 MCP 约定的 JSON-RPC 响应体(博客园, 知乎专栏)。

7. 模拟订单数据(orders.json

将以下内容放入 src/main/resources/data/orders.json

[
  {
    "orderId": "10001",
    "productName": "无线鼠标",
    "amount": 29.99,
    "status": "已发货"
  },
  {
    "orderId": "10002",
    "productName": "机械键盘",
    "amount": 89.50,
    "status": "待发货"
  }
]
  • 该 JSON 列表模拟两个订单,实际项目可替换为数据库或外部 API。

五、实现 MCP Client

MCP Client 负责向 MCP Server 发送请求,并将服务器返回的结果拼接回 AI 模型上下文。下面以向上文 Server 查询订单为例,演示 Client 端如何配置与调用。

1. 项目结构概览

mcp-client/
├─ src/
│  ├─ main/
│  │  ├─ java/
│  │  │   └─ com.example.mcpclient/
│  │  │        ├─ McpClientApplication.java         // Spring Boot 启动类
│  │  │        ├─ service/
│  │  │        │   └─ OrderQueryService.java         // 订单查询服务
│  │  │        └─ controller/
│  │  │            └─ ClientController.java          // 简易 Rest 接口
│  │  └─ resources/
│  │      └─ application.yml                        // 配置文件
└─ pom.xml

2. 配置文件(application.yml

spring:
  application:
    name: mcp-client
  ai:
    mcp:
      client:
        enabled: true
        transports:
          - name: default
            protocol: http      # 使用 HTTP 协议
            options:
              url: http://localhost:8081/mcp       # 指向 MCP Server 地址
  • spring.ai.mcp.client.enabled: true:开启 MCP Client 自动化配置;
  • transports[0].protocol: httpurl 指定服务端的 MCP Endpoint(注意:默认路径为 /mcp),所以完整地址为 http://localhost:8081/mcp(Home, 腾讯云)。

3. 启动类(McpClientApplication.java

package com.example.mcpclient;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class McpClientApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpClientApplication.class, args);
    }
}

4. 订单查询服务(OrderQueryService.java

package com.example.mcpclient.service;

import org.springframework.ai.mcp.client.McpClient;
import org.springframework.ai.mcp.client.model.McpClientRequest;
import org.springframework.ai.mcp.client.model.McpClientResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.HashMap;
import java.util.Map;

@Service
public class OrderQueryService {

    @Autowired
    private McpClient mcpClient;

    /**
     * 调用 MCP Server 的 "order.query" 能力
     * @param orderId 订单号
     * @return 查询结果 Map
     */
    public Map<String, Object> queryOrder(String orderId) {
        // 构建 MCP 客户端请求
        McpClientRequest request = McpClientRequest.builder()
                .capability("order.query")
                .params(Map.of("orderId", orderId))
                .build();

        // 同步调用 MCP Server
        McpClientResponse response = mcpClient.call(request);
        if (response.isSuccess()) {
            return response.getResult();
        } else {
            return Map.of("error", response.getError().getMessage());
        }
    }
}
  • @Autowired private McpClient mcpClient;:由 Spring AI 自动注入,封装了发送 JSON-RPC 调用的细节;
  • 使用 McpClientRequest.builder(),指定 capabilityparams,等价于 JSON-RPC 请求中 methodparams 字段;
  • mcpClient.call(request) 会将请求通过 HTTP POST 发送到服务器,等待同步返回;
  • McpClientResponse 进行 isSuccess() 判断后,获取结果或错误消息(Home, 腾讯云)。

5. 简易 Rest 接口(ClientController.java

package com.example.mcpclient.controller;

import com.example.mcpclient.service.OrderQueryService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@RestController
@RequestMapping("/api")
public class ClientController {

    @Autowired
    private OrderQueryService orderQueryService;

    /**
     * HTTP GET 接口:/api/order/{id}
     * 示例请求:GET http://localhost:8080/api/order/10001
     */
    @GetMapping("/order/{id}")
    public Map<String, Object> getOrder(@PathVariable("id") String orderId) {
        return orderQueryService.queryOrder(orderId);
    }
}
  • 通过 /api/order/{id} 暴露一个简单的 HTTP 接口,供前端或调用方进行测试;
  • 当收到请求后,Service 会再调用 MCP Client,将请求转发至 MCP Server,并将最终结果以 JSON 返回给前端。

六、端到端调用流程

下面我们通过一个简化的流程图来说明从 Client 到 Server 的调用步骤:

+-------------+         HTTP POST Index        +-------------+
|  REST 前端   |  GET /api/order/10001         | MCP Client  |
| (浏览器/Postman)| ------------------------> | (Spring Boot)|
+-------------+                              +-------------+
        |                                           |
        |   内部调用:                                |
        |   mcpClient.call({                         |
        |     "method": "order.query",              |
        |     "params": { "orderId": "10001" }       |
        |   })                                       |
        v                                           v
+-------------+      HTTP POST JSON-RPC          +-------------+
|             | <-------------------------------- | MCP Server  |
|             |    {"jsonrpc":"2.0",              | (Spring Boot)|
|             |     "method":"order.query",       +-------------+
|             |     "params":{"orderId":"10001"},     |
|   网页/API   |     "id":1}                     |
+-------------+                                   |
                                                   | 调用 OrderService.queryById("10001")
                                                   v
                                                +-------------+
                                                |  订单数据层   |
                                                +-------------+
                                                   |
                                                   v
                                     返回结果: {orderId, productName, amount, status}
                                                   |
                      JSON-RPC 响应: {"jsonrpc":"2.0","result":{...},"id":1}
                                                   |
                                                   v
+-------------+    HTTP 响应: {...}               +-------------+
| 前端客户端  | <--------------------------------  | MCP Client  |
+-------------+                                  +-------------+
  1. 前端(或 Postman、cURL)向 Client 暴露的 /api/order/{id} 发起 GET 请求。
  2. ClientController 调用 OrderQueryService.queryOrder(orderId),该服务通过 McpClient 以 JSON-RPC 方式向服务器发起 HTTP POST 请求(method="order.query"params={"orderId":"10001"})。
  3. MCP Server 将请求路由到 OrderCapabilityController.queryOrder(...),进一步调用 OrderService.queryById(...) 查询数据,并将结果封装到 McpResponse.success(result)
  4. MCP Server 返回 JSON-RPC 响应体,Client 将结果解析并返回给前端。

七、图示说明

为进一步帮助理解架构,以下是关键流程的简要示意图(采用 ASCII 形式):

┌─────────────────────────────────────────────────────────────────┐
│                           前端浏览器                             │
│  GET http://localhost:8080/api/order/10001                       │
└─────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                       MCP Client(Spring Boot)                  │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │  @RestController                                          │  │
│  │  public Map<String,Object> getOrder(id) {                  │  │
│  │      return orderQueryService.queryOrder(id);              │  │
│  │  }                                                         │  │
│  │                                                             │  │
│  │  // 通过 McpClient 调用服务器                                   │  │
│  │  McpClientRequest req = McpClientRequest.builder()         │  │
│  │      .capability("order.query")                             │  │
│  │      .params(Map.of("orderId", id))                         │  │
│  │      .build();                                              │  │
│  │  McpClientResponse resp = mcpClient.call(req);              │  │
│  │  return resp.getResult();                                   │  │
│  │                                                             │  │
│  │  Spring.ai.mcp.client 自动配置                               │  │
│  │  URL = http://localhost:8081/mcp                             │  │
│  └─────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                                  │ HTTP POST JSON-RPC
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                       MCP Server(Spring Boot)                  │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │  @McpController                                            │  │
│  │  public McpResponse queryOrder(McpRequest req) {            │  │
│  │      String orderId = req.getParams().get("orderId");      │  │
│  │      Order o = orderService.queryById(orderId);            │  │
│  │      return McpResponse.success(Map.of(                    │  │
│  │           "orderId", o.getOrderId(),                        │  │
│  │           "productName", o.getProductName(),                │  │
│  │           "amount", o.getAmount(),                          │  │
│  │           "status", o.getStatus()                           │  │
│  │      ));                                                    │  │
│  │  }                                                          │  │
│  │                                                             │  │
│  │  Spring.ai.mcp.server 自动配置                               │  │
│  │  Endpoint = /mcp                                            │  │
│  └─────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                                  │ JSON-RPC 响应
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                           MCP Client                            │
│  // 解析 McpClientResponse 并返回前端结果                         │
└─────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                            前端浏览器                            │
│  // 浏览器接收到最终结果并展示                                     │
└─────────────────────────────────────────────────────────────────┘

八、常见问题与优化技巧

  1. 协议选择:STDIO vs HTTP vs SSE

    • STDIO:适用于本地命令行或单机部署,可靠但只能单机调用,不支持跨网络访问(CSDN, 博客园)。
    • HTTP(本文示例):最常用,支持分布式部署,通过标准 REST 端点传输 JSON-RPC。
    • SSE(Server-Sent Events):适用于服务器主动推送场景,能实现服务器向客户端的异步推送。
  2. 并发与性能

    • Spring WebMVC 默认采用 Tomcat 容器,典型并发性能可满足大多数场景。若需更高吞吐量,可使用 WebFlux(Reactor Netty)实现异步非阻塞。
    • 可以为 McpClient 配置连接池、超时、重试策略等,以保证客户端调用的稳定性与高可用。
  3. 安全与鉴权

    • application.yml 中可为 /mcp 端点添加鉴权过滤器,例如 Basic Auth、OAuth2 等。
    • 也可在 @McpCapability 方法中校验 McpRequest 中的身份信息,确保只有授权客户端可以调用敏感能力。
  4. 能力扩展

    • 除了订单查询外,可以再定义 @McpCapability(name="order.create")order.cancel 等方法,Server 端即可对应提供多种功能。
    • Client 侧只需调用不同的 capability,Server 会自动路由至对应方法。
  5. 日志与链路追踪

    • Spring AI 提供了对 MCP 通信流程的拦截器,可以将每次请求与响应记录到日志,方便排查问题。
    • 推荐集成 Zipkin/Jaeger 等分布式追踪组件,流水线中可追踪每一次从 Client → Server → Resource 的调用时间,以便优化。

九、总结与展望

通过本教程,我们完成了以下内容:

  1. 理解 MCP 架构:掌握 MCP 将 AI 模型、客户端与服务器解耦的三层架构思想。
  2. 搭建 MCP Server:利用 Spring AI MCP Server Starter,快速实现能力提供方(订单查询)。
  3. 构建 MCP Client:使用 Spring AI MCP Client Starter,将 AI 模型与后端能力衔接。
  4. 端到端测试:通过前端 HTTP 接口,从浏览器或 Postman 发起调用,完成整个请求链路。

未来,你可以基于本文示例进行以下扩展:

  • 引入 AI 模型:在 Client 端集成 OpenAI、DeepSeek 或自研 LLM,将用户自然语言直接转为 McpClientRequest,实现 AI 推理与工具调用闭环。
  • 复杂业务场景:Server 端可对接数据库、缓存、中间件,甚至调用外部微服务;并配合异步消息队列,实现大规模分布式任务处理。
  • 高级协议特性:使用 SSE 或 WebSocket,构建长连接场景下的实时推送能力(如 AI 生成的中间结果,增量流式返回)。
  • 安全与多租户:结合 Spring Security,为不同租户或用户提供隔离的能力访问,并根据角色控制不同的功能。

希望这篇教程能帮助你快速上手 Spring AI MCP,轻松构建符合模型上下文协议的 Client-Server 架构,释放大模型的全部潜力。如有疑问或深入探讨,欢迎随时交流。祝学习愉快!

2024-09-09

在Spring Cloud学习系列中,我们已经介绍了Elasticsearch的基本概念和安装配置。在这一部分中,我们将使用Spring Data Elasticsearch来实现分布式搜索功能。

首先,我们需要在Spring Boot项目中添加Spring Data Elasticsearch的依赖。




<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
    </dependency>
    <!-- 其他依赖 -->
</dependencies>

接下来,我们需要配置Elasticsearch的客户端。




@Configuration
public class ElasticsearchConfig {
 
    @Value("${elasticsearch.host}")
    private String hostname;
 
    @Value("${elasticsearch.port}")
    private int port;
 
    @Bean
    public RestHighLevelClient elasticsearchClient() {
        RestClientBuilder builder = RestClient.builder(new HttpHost(hostname, port));
        return new RestHighLevelClient(builder);
    }
}

然后,我们可以创建一个Elasticsearch的Repository接口。




public interface ProductRepository extends ElasticsearchRepository<Product, String> {
}

最后,我们可以使用这个Repository来执行搜索操作。




@Service
public class ProductSearchService {
 
    @Autowired
    private ProductRepository productRepository;
 
    public List<Product> searchByName(String name) {
        return productRepository.findByName(name);
    }
}

在这个例子中,我们定义了一个简单的搜索方法searchByName,它使用了Elasticsearch的Repository提供的查询方法findByName。这个方法会在Elasticsearch中搜索所有名称字段包含指定关键字的文档。

这只是一个基本的例子,实际应用中可能需要更复杂的查询逻辑,例如基于多个字段的搜索、分页、排序等。Spring Data Elasticsearch提供了丰富的查询方法定义,可以通过定义相应的接口来实现复杂的搜索需求。

2024-09-09

在Spring Cloud中使用Nacos作为配置中心,可以通过以下步骤实现:

  1. 引入Nacos客户端依赖:



<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>
  1. bootstrap.propertiesbootstrap.yml中配置Nacos服务器地址和应用名:



spring.cloud.nacos.config.server-addr=127.0.0.1:8848
spring.application.name=my-spring-cloud-application
  1. 在应用代码中注入配置:



import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
 
@RestController
public class ConfigController {
 
    @Value("${my.config}")
    private String myConfig;
 
    @GetMapping("/config")
    public String getConfig() {
        return myConfig;
    }
}
  1. 在Nacos控制台配置对应的配置数据。

以上步骤可以让你的Spring Cloud应用从Nacos配置中心加载配置。在Nacos控制台可以动态管理这些配置,修改后即时生效。