# airy-rpc

**Repository Path**: open-byte/airy-rpc

## Basic Information

- **Project Name**: airy-rpc
- **Description**: Airy-RPC 是一款基于 Netty 开发的高性能、轻量级 RPC 框架，专注于提供简洁易用、可灵活扩展的远程服务调用能力。框架采用 SPI 机制实现注册中心、序列化器等核心组件的可插拔扩展，支持 Spring 生态整合与原生 Java 环境部署，适用于微服务架构中的跨服务通信场景。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 1
- **Created**: 2025-12-06
- **Last Updated**: 2026-02-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <img src="./docs/images/logo.png" width="200" alt="airy-raft logo">
</div>

# airy-rpc
![项目架构图](docs/images/java.svg "项目架构图")
![项目架构图](docs/images/netty.svg "项目架构图")
![项目架构图](docs/images/spi.svg "项目架构图")
![项目架构图](docs/images/apache2.0.svg "项目架构图")

#### 介绍
Airy-RPC 是一款基于Netty开发的高性能、轻量级RPC框架，专注于提供简洁易用、可灵活扩展的远程服务调用能力。框架采用 SPI 机制实现注册中心、序列化器等核心组件的可插拔扩展，支持 Spring 生态整合与原生 Java 环境部署，适用于微服务架构中的跨服务通信场景。

##### 核心特性
- 高性能通信：基于Netty实现网络通讯，支持多种主流序列化协议
- 服务治理：支持服务注册与发现、负载均衡（轮询 / 随机 / 权重）、超时重试、服务熔断降级
- 兼容性：通过SPI机制适配主流注册中心、也可以脱离注册中心使用
- 易用性：支持原生API、原生注解驱动、Spring注解多种使用方式
- 可靠性：通过SPI机制适配主流熔断降级组件、异常熔断机制，确保服务稳定性
- 插件化：支持开发插件，内置了Auth、RateLimiter、Metrics等各类插件
- 轻量化：核心依赖少、支持按需引入

#### 版本更新说明
- v3.0.5
  - [新增] 新增插件OTEL，兼容OpenTemplate规范，配合OTel Colletor + Zipkin/SkyWalking实现链路信息收集
  - [新增] 新增插件Zipkin, 直接兼容Zipkin实现链路信息收集
  - [优化] 优化插件SPI, 过滤器中增加AppMetadata参数支持对当前服务信息的获取
  - [优化] 优化注册到注册中心的逻辑
  - [优化] 补全部分代码注释
  - [修复] 修复其它部分已知问题
- [更多版本更新历史](./docs/versions.md)

#### 软件架构
Airy-RPC 采用分层设计思想，从上到下分为接入层、核心层、基础设施层，各层职责清晰
<div align="center">
  <img src="./docs/images/arpc_arch.png" width="80%" alt="airy-raft logo">
</div>

##### 核心组件说明
|  组件模块   | 核心职责  |
|  ----  | ----  |
| arpc-common  | 基础公共包 |
| arpc-core  | 框架核心逻辑，包含服务暴露 / 引用、协议解析、序列化、负载均衡等核心功能 |
| arpc-spi-registry  | 注册中心 SPI 抽象，定义注册中心的核心接口（注册 / 发现 / 注销） |
| arpc-spi-filter  | 过滤器 SPI 抽象，定义过滤器链的过滤器，可以利用过滤器拓展 |
| arpc-registry  | 注册中心具体实现，已内置支持 Nacos/Eureka/Consul/Zookeeper/Etcd/Redis |
| arpc-degrade  | 熔断降级适配，已内置支持 Sentinel/Resilience4j/Hystrix |
| arpc-plugins  | 插件模块，已内置支持 Auth、RateLimiter、Metrics |
| arpc-all  | 聚合模块，支持快速引入（纯Java） |
| arpc-spring-boot-starter  | Spring 生态适配，提供注解驱动、自动配置等功能，快速集成Spring |
| samples-spring  | SpringCloud 环境示例项目，包含服务端 / 客户端完整使用示例 |
| samples-java  | 纯 Java 环境示例项目(演示无 Spring 依赖的使用方式) |
| benchmark  | JMH性能测试 |

#### 快速开始
##### 环境要求
- JDK 8+
- Maven 3.6+
- 注册中心（可选，支持 Nacos 2.x/Zookeeper 3.5+/Eureka 1.x/Redis/Etcd/Consul...）

##### 引入依赖
核心依赖， ${lastVersion}为当前最新版本，可到项目仓库查看
~~~xml
<!-- 纯Java依赖 -->
<dependency>
    <groupId>org.openbyte</groupId>
    <artifactId>arpc-all</artifactId>
    <version>${lastVersion}</version>
</dependency>

<!-- springboot starter -->
<dependency>
  <groupId>org.openbyte</groupId>
  <artifactId>arpc-spring-boot-starter</artifactId>
  <version>${lastVersion}</version>
</dependency>
~~~

以下依赖均按需引入
- [注册中心](./docs/registry_center.md)
- [降级熔断](./docs/degrade.md)
- [拓展插件](./docs/plugins.md)

##### 纯Java环境下使用
参考示例：samples-java

##### 在SpringCloud环境下使用
参考示例：samples-spring

#### 高级特性
- [负载均衡策略](./docs/ext/loadbalance.md)
- [数据序列化](./docs/ext/data_serializer.md)
- [注册中心拓展](./docs/ext/registry_center.md)
- [降级熔断拓展](./docs/ext/degrade.md)
- [自定义插件](./docs/ext/plugins.md)


#### 性能测试
Benchmark（v2.1.5 单节点测试环境，结果仅供参考）
|  测试场景   | 测试线程数  | 平均响应时间   | QPS  | 成功率  |
|  ----  | ----  | ----  | ----  | ----  |
| 单线程测试（100B）  | 1 | 1.2-1.6ms | 650-880 | 99.99% |
| 多线程测试（100B）  | 10 | 1.5-1.9ms | 6000-7500 | 99.99% |
| GRPC（类似场景，仅作对比）  | 10 | 1.3-1.5ms | 8500-9500 | 99.99% |
| DUBBO（类似场景，仅作对比）  | 10 | 1.2-1.4ms | 9000-10000 | 99.99% |
| Thrift（类似场景，仅作对比）  | 10 | 1.4-1.6ms | 8000-8500 | 99.99% |

总结：根据测试结果可以大概看出本框架的整体性能已经很接近Dubbo、GRPC、Thrift等主流RPC开源框架，表现不俗。

测试环境
- 工具：JMH
- CPU：Intel i5-13400H（12 核 16 线程）
- 内存：32GB DDR5 4800MHz
- JDK：1.8.0_381
- 注册中心：无

#### 常见示例
##### Meta
本框架使用meta作为请求链路中传递元数据的载体，分为 request meta 和 response meta.
如果您的HttpHeader、cookie、session需要在请求链路中透传，需要通过转换成meta进行传递
~~~java
// 设置请求meta给下游服务, isTransfer为true时则表示该meta将会在整个链路中透传
MetaContext.request().addMeta("request-header", "request-header-value", true);

// 在下游服务中被调用的方法内使用
String requestHeader = MetaContext.request().getMeta("request-header");

// 设置响应头给上游服务
MetaContext.response().addMeta("response-header", "response-header-value");

// 上游服务获取响应头
String responseHeader = MetaContext.response().getMeta("response-header");
~~~

#### 参与贡献
1.Fork 本仓库（点击仓库右上角 Fork 按钮）
2.新建分支（git checkout -b Feat/xxx，如 Feat/add-zookeeper-registry）
3.提交代码（git commit -m "feat: 新增 Zookeeper 注册中心支持"）
4.推送分支（git push origin Feat/xxx）
5.新建 Pull Request（在 Gitee 仓库页面提交 PR，描述功能细节）

##### 贡献代码规范
- 代码风格遵循 Google Java 编码规范
- 新增功能需配套单元测试（覆盖率≥80%）
- 提交信息格式：type: 描述（type 可选：feat/fix/docs/style/refactor/test/chore）
- 新增核心功能需先提交 Issue 讨论，达成共识后再开发

#### 许可证
本项目基于 Apache License 2.0 开源协议，详情请查看 LICENSE 文件。

#### 联系与反馈
- 项目地址：https://gitee.com/open-byte/airy-rpc
- Issue 反馈：提交问题
- 开发交流：欢迎通过 Gitee 仓库留言或提交 PR 交流想法

#### QQ交流群（欢迎入群一起探讨）
群1：1079580734