# rpc

**Repository Path**: yanyongzhitest/rpc

## Basic Information

- **Project Name**: rpc
- **Description**: dubbo
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-01-02
- **Last Updated**: 2026-01-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RPC Dubbo 微服务项目

## 项目简介

本项目是一个基于 **Spring Boot 3 + Dubbo 3 + Nacos + Sentinel + Redis + Seata** 的电商类微服务示例项目，展示了完整的微服务架构实现，包含服务注册发现、RPC 调用、分布式事务、消息队列、限流熔断、安全防护等核心功能。

## 服务模块

- **网关服务**（`gateway-service`）：统一入口，聚合用户/订单/商品/统计等接口，集成安全防护、限流熔断、JUC 高并发测试、Excel 导出、异步消息发送等
- **用户服务**（`user-service`）：提供用户基础信息的 CRUD 和查询能力
- **订单服务**（`order-service`）：提供订单创建/查询/状态流转/退款等能力，支持分布式事务、异步消息消费、状态流转日志记录
- **商品服务**（`product-service`）：提供商品管理、分类管理、库存管理和库存变动日志能力，支持分布式事务
- **CDC 服务**（`cdc-service`）：演示基于 Canal + Kafka 的数据变更采集和同步能力，集成 Redisson 分布式锁
- **AI Agent 服务**（`ai-agent-service`）：演示与大模型/向量库集成的业务 Agent 能力（可选模块）

## 核心技术栈

### 基础框架
- **Spring Boot 3.3.5**：应用框架，统一配置为 `.properties`，按功能拆分到 `config/*.properties`
- **Apache Dubbo 3.2.0**：RPC 框架，`@DubboService` 暴露服务，`@DubboReference` 调用服务
- **Nacos 2.3.2**：服务注册发现，Dubbo 注册中心
- **Java 17**：JDK 版本

### 数据存储
- **MySQL 8.0.33**：关系型数据库
- **MyBatis-Plus 3.5.5**：ORM 框架，简化数据访问层开发
- **Redis**：缓存、Token、验证码、防重复提交、限流等场景
- **Redisson 3.24.3**：Redis 客户端，提供分布式锁等分布式对象

### 分布式与消息
- **Seata 1.8.0**：分布式事务框架（AT 模式），用于跨服务事务管理
- **Kafka 3.6.0**：消息队列，用于异步订单处理
- **Canal 1.1.6**：MySQL binlog 增量订阅和消费组件（CDC 服务使用）

### 服务治理
- **Sentinel 1.8.8**：流量控制、熔断降级，结合 `@SentinelResource` 与统一 `SentinelBlockHandler`
- **Spring Boot Actuator**：应用监控（health / metrics / info 等）

### 其他组件
- **Swagger/Springfox 3.0.0**：REST API 文档生成
- **Apache POI 5.2.5**：Excel 文件导出
- **Log4j2 2.23.1**：统一日志框架（文件 + 控制台，按服务独立日志）
- **Jackson 2.16.1**：JSON 序列化/反序列化

## 核心功能

### 1. 分布式事务（Seata AT 模式）

- **集成说明**：`order-service` 和 `product-service` 已集成 Seata 1.8.0
- **配置位置**：`application-seata.properties`
- **使用方式**：在需要分布式事务的方法上使用 `@GlobalTransactional` 注解
- **配置项**：
  - 事务服务组：`order-service-tx-group` / `product-service-tx-group`
  - 注册中心：Nacos
  - 配置中心：Nacos
  - 回滚日志表：`undo_log`（已在 `rpc_database.sql` 中创建）
- **注意事项**：需要单独启动 Seata Server 1.8.0，并配置 Nacos 注册中心和配置中心

### 2. 异步订单处理（Kafka）

- **功能说明**：支持异步创建订单，提高系统吞吐量
- **实现方式**：
  - **生产者**：`gateway-service` 中的 `OrderEventProducer`，发送订单创建事件到 Kafka Topic `order-create`
  - **消费者**：`order-service` 中的 `OrderCreateConsumer`，监听 Topic 并异步处理订单创建
- **配置位置**：
  - Gateway：`gateway-service/src/main/resources/config/kafka.properties`
  - Order Service：`order-service/src/main/resources/config/kafka.properties`
- **API 接口**：`POST /api/orders/async`（异步创建订单）

### 3. Excel 导出

- **功能说明**：支持将订单列表导出为 Excel 文件
- **实现方式**：使用 Apache POI 5.2.5 生成 `.xlsx` 文件
- **API 接口**：`GET /api/orders/export`（导出订单列表 Excel）

### 4. 订单中心增强

- **订单状态流转日志**：表 `order_status_log`，自动记录创建/取消/退款等状态变更
- **简单退款接口**：支持将订单状态更新为 `REFUNDED` 并写入状态日志
- **订单备注/标签**：`remark` + `tags` 字段，支持标记订单类型、业务含义

### 5. 商品中心增强

- **商品分类管理**：表 `product_category`，支持编码/名称/父子层级，Dubbo 接口 `ProductCategoryService` + 网关分类查询接口
- **库存变动日志**：表 `inventory_change_log`，记录每次库存变动的类型/数量/前后库存/关联信息，方便排查库存问题

### 6. 用户中心增强

- **基于 SSO 权限列表的角色/权限接口**：
  - 通过 Token 拦截器从 `Authorization: Bearer xxx` 中解析用户信息和权限
  - `GET /api/auth/me/permissions` 返回 `UserPermissionDTO`：用户基本信息 + 角色列表 + 权限列表
  - 简单角色推断：含 `*:write` 权限视为 `ADMIN`，否则为 `USER`

### 7. 安全与防护

- **防重复提交**：`RepeatSubmitService`，基于 Redis + 提交 Token
- **DDoS 防护**：IP 级简单限流与黑名单封禁
- **XSS 防护**：请求过滤 + 输出转义
- **CSRF 防护**：基于 Token 的简单 CSRF 机制
- **图形滑块验证码**：`SliderCaptchaService` + `CaptchaController`，登录前置验证

### 8. 限流熔断（Sentinel）

- 为用户、订单、商品、业务编排、高并发测试等核心接口统一打上 `@SentinelResource`
- 通过 `SentinelConfig` 统一初始化限流/熔断规则，`SentinelBlockHandler` 统一处理 Block 和 Fallback

### 9. 高并发与 JUC 示例

- **ConcurrentTestController** 提供多种并发测试接口：
  - `CompletableFuture` 并行任务
  - `CountDownLatch` 同步等待
  - `Semaphore` 控制并发数
  - Sentinel 高并发限流测试
- **BusinessController** 中的订单聚合查询使用 `CompletableFuture + ConcurrentHashMap` 并行拉取商品详情

### 10. 监控与告警

- **Actuator**：健康检查、指标、环境信息等
- **自定义 AlertMonitor**：控制器中埋点记录性能指标和错误信息，便于后续扩展邮件/IM 告警

### 11. 分布式锁（Redisson）

- **使用场景**：CDC 服务中使用 Redisson 实现分布式锁，保证数据同步的线程安全
- **配置位置**：`cdc-service` 中的 `RedissonConfig`
- **说明**：Redisson 分布式锁与 Seata 分布式事务互不干扰，分别处理 Redis 层面的并发控制和数据库层面的事务管理

## 数据库与 SQL 脚本

所有 SQL 已统一整理到 `sql` 目录：

### 主数据库脚本

- **`sql/rpc_database.sql`**：业务库 `rpc` 完整初始化脚本，包含：
  - 用户表 `user`
  - 商品表 `product`
  - 商品分类表 `product_category`
  - 订单表 `order` + 订单项表 `order_item`
  - 订单状态日志表 `order_status_log`
  - 库存变动日志表 `inventory_change_log`
  - **Seata AT 模式 `undo_log` 表**（分布式事务回滚日志）
  - 基础索引与性能优化 DDL

### 初始化说明

> 建议：在 MySQL 客户端执行 `SOURCE sql/rpc_database.sql;` 或直接导入该文件完成数据库初始化。

## 配置说明

### 配置文件结构

所有配置统一使用 `.properties` 格式，按功能拆分到 `config/*.properties`：

- 各模块 `src/main/resources/application.properties` 为入口配置
- 网关 `gateway-service` 通过 `spring.config.import` 导入以下配置文件：
  - `config/dubbo.properties`：Dubbo 配置
  - `config/redis.properties`：Redis 配置
  - `config/sso.properties`：SSO 配置
  - `config/security.properties`：安全配置
  - `config/common.properties`：通用配置
  - `config/alert.properties`：告警配置
  - `config/actuator.properties`：Actuator 配置
  - `config/sentinel.properties`：Sentinel 配置
  - `config/kafka.properties`：Kafka 配置（新增）

- 订单服务 `order-service` 额外导入：
  - `config/kafka.properties`：Kafka 消费者配置
  - `application-seata.properties`：Seata 分布式事务配置

- 商品服务 `product-service` 额外导入：
  - `application-seata.properties`：Seata 分布式事务配置

### 配置特点

- 全部使用 `.properties` 形式，无任何 `@PropertySource` 硬编码加载
- 使用 Spring Boot 原生的 `spring.config.import` 机制加载配置文件
- 配置按功能模块拆分，便于管理和维护

## 快速启动

### 1. 环境准备

- **JDK 17+**
- **Maven 3.6+**
- **MySQL 8.0+**
- **Redis 6.0+**
- **Nacos 2.3.2+**
- **Kafka 3.6.0+**（用于异步订单处理）
- **Seata Server 1.8.0**（用于分布式事务，可选）

### 2. 依赖组件启动

按以下顺序启动依赖组件：

1. **MySQL**：启动 MySQL 数据库
2. **Redis**：启动 Redis 服务
3. **Nacos**：启动 Nacos（单机模式）
   ```bash
   # Windows
   startup.cmd -m standalone
   
   # Linux/Mac
   sh startup.sh -m standalone
   ```
4. **Kafka**：启动 Kafka 服务（用于异步订单处理）
5. **Seata Server**（可选）：如需使用分布式事务，需要启动 Seata Server
   - 下载 Seata 1.8.0
   - 配置 Nacos 注册中心和配置中心
   - 启动 Seata Server

### 3. 数据库初始化

在 MySQL 客户端执行：

```sql
SOURCE sql/rpc_database.sql;
```

或直接导入 `sql/rpc_database.sql` 文件。

### 4. 编译项目

在 `dubbo-parent` 目录执行：

```bash
mvn clean install -DskipTests
```

### 5. 启动服务（推荐顺序）

1. `user-service`（端口：8081）
2. `product-service`（端口：8083）
3. `order-service`（端口：8082）
4. `cdc-service`（端口：8084，可选）
5. `gateway-service`（端口：8080）
6. `ai-agent-service`（端口：8085，可选）

### 6. 访问接口

- **Swagger API 文档**：http://localhost:8080/swagger-ui.html
- **健康检查**：http://localhost:8080/actuator/health
- **示例接口**：
  - 用户接口：`/api/users/**`
  - 商品接口：`/api/products/**`
  - 订单接口：`/api/orders/**`
  - 统计接口：`/api/statistics/**`
  - 并发测试：`/api/concurrent/**`
  - SSO 登录：`/api/auth/**`

## 技术特性说明

### 分布式事务（Seata AT 模式）

- **适用场景**：跨服务的数据一致性保证（如创建订单同时扣减库存）
- **实现方式**：在订单服务的方法上使用 `@GlobalTransactional` 注解
- **注意事项**：
  - 需要启动 Seata Server
  - 确保 Seata Server 连接到相同的 Nacos 注册中心
  - 数据库需要创建 `undo_log` 表（已在 `rpc_database.sql` 中包含）

### 异步订单处理

- **适用场景**：高并发下单场景，提高系统吞吐量
- **使用方式**：调用 `POST /api/orders/async` 接口
- **处理流程**：
  1. 网关服务接收请求，发送消息到 Kafka
  2. 订单服务消费消息，异步创建订单
  3. 返回 traceId，用于后续查询订单状态

### Excel 导出

- **适用场景**：批量导出订单数据
- **使用方式**：调用 `GET /api/orders/export` 接口，支持查询条件过滤
- **文件格式**：`.xlsx`（Excel 2007+ 格式）

### 分布式锁（Redisson）

- **适用场景**：CDC 服务中的数据同步，保证并发安全
- **实现方式**：使用 Redisson 提供的分布式锁 API
- **说明**：与 Seata 分布式事务独立，互不干扰

## 项目结构

```
dubbo-parent/
├── dubbo-common/           # 公共模块（DTO、API、工具类等）
├── gateway-service/        # 网关服务
├── user-service/           # 用户服务
├── order-service/          # 订单服务
├── product-service/        # 商品服务
├── cdc-service/            # CDC 服务
├── ai-agent-service/       # AI Agent 服务
├── sql/                    # SQL 脚本目录
│   └── rpc_database.sql    # 主数据库初始化脚本
├── pom.xml                 # 父 POM，统一管理依赖版本
└── README.md               # 本文件
```

## 文档说明

项目根目录下的其他技术文档：

- **`技术文档.md`**：整体技术选型、Dubbo/Nacos/Log4j2 等框架详细说明
- **`Sentinel限流熔断集成说明.md`** + **`Sentinel集成完成总结.md`**：Sentinel 集成与规则说明
- **`SSO双Token实现说明.md`** + **`SSO双Token优化完成总结.md`**：SSO 双 Token 与权限体系说明
- **`Log4j2日志框架技术文档.md`**：日志体系详细说明
- **`CDC系统实现说明.md`**：CDC 相关详细说明
- **`报警系统使用说明.md`** / **`高可用性架构说明.md`**：监控与高可用说明

## 版本信息

- **Spring Boot**：3.3.5
- **Dubbo**：3.2.0
- **Nacos**：2.3.2
- **Seata**：1.8.0
- **Sentinel**：1.8.8
- **Kafka**：3.6.0
- **Redisson**：3.24.3
- **MyBatis-Plus**：3.5.5
- **JDK**：17

## 注意事项

1. **Seata Server**：如需使用分布式事务，必须启动 Seata Server 1.8.0，并配置 Nacos 注册中心和配置中心
2. **Kafka**：异步订单处理功能需要 Kafka 服务运行
3. **数据库**：确保 MySQL 版本 >= 8.0，并正确执行 SQL 初始化脚本
4. **端口占用**：各服务使用不同端口，确保端口未被占用
5. **配置检查**：启动前检查各服务的配置文件，确保 Nacos、Redis、MySQL 等连接信息正确

## 许可证

本项目仅供学习和参考使用。