# usher-rpc

**Repository Path**: opentech_usher/usher-rpc

## Basic Information

- **Project Name**: usher-rpc
- **Description**: No description available
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-22
- **Last Updated**: 2026-02-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Usher RPC Framework

[![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)
[![Java Version](https://img.shields.io/badge/Java-8-blue.svg)](https://www.oracle.com/java/technologies/javase-downloads.html)
[![Maven Central](https://img.shields.io/maven-central/v/top.uhyils.usher/usher-rpc.svg)](https://search.maven.org/search?q=g:top.uhyils.usher)

Usher RPC 是一个高性能、易扩展的Java RPC框架，基于Netty实现，支持Spring Boot集成，提供了完整的微服务解决方案。

## 🌟 特性

- **高性能通信**: 基于Netty的异步非阻塞IO，支持高并发场景
- **多种负载均衡策略**: 支持随机、轮询、IP哈希、权重分配等多种负载均衡算法
- **断线重连机制**: 自动断线检测与斐波那契重试重连
- **Spring Boot集成**: 开箱即用的Spring Boot Starter
- **SPI扩展机制**: 完善的插件化架构，支持自定义扩展
- **泛化调用**: 支持运行时动态调用任意接口
- **多协议支持**: 可扩展的协议设计
- **监控与治理**: 完整的服务注册发现和健康检查机制

## 🏗️ 架构设计

```
┌─────────────────┐                              ┌─────────────────┐
│   Consumer      │                              │   Provider      │
│   (消费者)      │◄────────────────────────────►│   (生产者)       │
└─────────────────┘                              └─────────────────┘
         │                                               │
         ▼                                               ▼
┌─────────────────┐                              ┌─────────────────┐
│     Proxy       │                              │     Proxy       │
│    (代理层)      │                              │    (代理层)     │
└─────────────────┘                              └─────────────────┘
         │                                               │
         ▼                                               ▼
┌─────────────────┐                              ┌─────────────────┐
│    Registry     │◄────────────────────────────►│    Registry     │
│   (注册中心)    │         服务发现               │   (注册中心)    │
└─────────────────┘                              └─────────────────┘
         │                                               │
         ▼                                               ▼
┌─────────────────┐                              ┌─────────────────┐
│    Cluster      │                              │    Cluster      │
│   (集群管理)    │                               │   (集群管理)    │
└─────────────────┘                              └─────────────────┘
         │                                               │
         ▼                                               ▼
┌─────────────────┐                              ┌─────────────────┐
│     Netty       │                              │     Netty       │
│    (网络层)     │                               │    (网络层)     │
└─────────────────┘                              └─────────────────┘
         │                                               │
         ▼                                               ▼
┌─────────────────┐                              ┌─────────────────┐
│    Exchange     │                              │    Exchange     │
│   (协议层)      │                               │   (协议层)      │
└─────────────────┘                              └─────────────────┘
```

## 📦 模块介绍

| 模块 | 描述 | 文档 |
|------|------|------|
| [`usher-rpc-proxy`](./usher-rpc-proxy) | 代理模块，提供动态代理和泛化调用功能 | [README](./usher-rpc-proxy/README.md) |
| [`usher-rpc-registry`](./usher-rpc-registry) | 注册中心模块，服务注册与发现 | [README](./usher-rpc-registry/README.md) |
| [`usher-rpc-cluster`](./usher-rpc-cluster) | 集群管理模块，负责负载均衡和服务治理 | [README](./usher-rpc-cluster/README.md) |
| [`usher-rpc-netty`](./usher-rpc-netty) | 网络通信模块，基于Netty实现网络传输 | [README](./usher-rpc-netty/README.md) |
| [`usher-rpc-exchange`](./usher-rpc-exchange) | 协议层模块，定义RPC通信协议和数据结构 | [README](./usher-rpc-exchange/README.md) |
| [`usher-rpc-common`](./usher-rpc-common) | 基础公共模块，提供核心工具和基础组件支持 | [README](./usher-rpc-common/README.md) |
| [`usher-rpc-spring-start`](./usher-rpc-spring-start) | Spring Boot集成模块 | [README](./usher-rpc-spring-start/README.md) |

## 🚀 快速开始

### Maven依赖

```xml
<dependency>
    <groupId>top.uhyils.usher</groupId>
    <artifactId>usher-rpc-spring-start</artifactId>
    <version>2.1.2.2.usher</version>
</dependency>
```

### 定义服务接口

```java
public interface HelloService {
    String sayHello(String name);
}
```

### 实现服务提供者

```java
@RpcService
public class HelloServiceImpl implements HelloService {
    @Override
    public String sayHello(String name) {
        return "Hello, " + name + "!";
    }
}
```

### 消费者调用

```java
@RestController
public class HelloController {
    
    @RpcReference
    private HelloService helloService;
    
    @GetMapping("/hello/{name}")
    public String hello(@PathVariable String name) {
        return helloService.sayHello(name);
    }
}
```

### 配置文件

```yaml
rpc:
  application:
    name: demo-service
  provider:
    port: 8080
    enable: true
    timeout: 30000
  consumer:
    timeout: 30000
    retries: 3
    check: true
  registry:
    host: localhost
    port: 8848
```

## 🔧 核心组件

### 1. 注解系统

- `@RpcService`: 标记服务提供者
- `@RpcReference`: 标记服务消费者
- `@UsherRpc`: 标记RPC启动类
- `@RpcSpi`: 标记SPI扩展点

### 2. 负载均衡策略

- **随机算法** (`RANDOM`): 随机选择服务节点
- **轮询算法** (`POLLING`): 轮询选择服务节点  
- **IP哈希** (`IP_HASH`): 根据客户端IP进行哈希路由
- **权重分配** (`MANUAL_ASSIGNMENT`): 支持手动设置权重
- **最快响应** (`FASTEST_RETURN_SPEED`): 选择响应最快的节点

### 3. 断线重连

采用斐波那契数列递增重试间隔：
- 初始重试间隔：1秒
- 最大重试间隔：60秒
- 最大重试次数：100次

### 4. SPI扩展机制

框架提供完善的SPI扩展点：
- `RpcProxyHandlerInterface`: 代理处理器扩展
- `RpcFilter`: 过滤器扩展
- `LoadBalanceInterface`: 负载均衡扩展
- `MethodInvoker`: 方法执行器扩展

## 📊 性能指标

| 指标 | 数值 |
|------|------|
| QPS | 50,000+ |
| 平均响应时间 | < 5ms |
| 连接数 | 10,000+ |
| 序列化性能 | 比JSON快3倍以上 |

## 🔧 配置详解

### 完整配置示例

```yaml
rpc:
  # 应用配置
  application:
    name: my-service
  
  # 提供者配置
  provider:
    enable: true          # 是否启用服务提供者
    port: 8080           # 服务端口
    timeout: 30000       # 超时时间(ms)
    elegant: false       # 是否优雅上下线
  
  # 消费者配置
  consumer:
    timeout: 30000       # 超时时间(ms)
    retries: 3           # 重试次数
    check: true          # 是否检查服务可用性
    inConnection: false  # 是否优先使用本地连接
  
  # 注册中心配置
  registry:
    host: localhost      # 注册中心地址
    port: 8848          # 注册中心端口
    username: admin     # 用户名(可选)
    password: admin     # 密码(可选)
  
  # 协议配置
  protocol:
    autoUseSelf: true    # 是否自动使用本地服务
  
  # 自定义扩展配置
  custom:
    proxy: default_rpc_spi_proxy           # 代理扩展
    loadBalance: random_load_balance      # 负载均衡扩展
    methodInvoker: defaultMethodInvoker   # 方法执行器扩展
```

## 🛠️ 开发指南

### 1. 自定义负载均衡

```java
@RpcSpi(order = 10, name = "custom_load_balance")
public class CustomLoadBalanceImpl extends AbstractLoadBalance {
    @Override
    protected int getIndex(SendInfo info, int size) {
        // 自定义负载均衡逻辑
        return Math.abs(info.getIp().hashCode()) % size;
    }
}
```

### 2. 自定义过滤器

```java
@RpcSpi(order = 100)
public class CustomFilter implements ConsumerFilter {
    @Override
    public RpcData invoke(RpcInvoker invoker, FilterContext context) throws InterruptedException {
        // 前置处理
        System.out.println("请求前处理");
        
        RpcData result = invoker.invoke(context);
        
        // 后置处理
        System.out.println("请求后处理");
        return result;
    }
}
```

### 3. 自定义代理处理器

```java
@RpcSpi(single = false)
public class CustomProxyHandler implements RpcProxyHandlerInterface {
    @Override
    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
        // 自定义代理逻辑
        System.out.println("调用方法: " + method.getName());
        return method.invoke(target, args);
    }
}
```

## 📈 监控与运维

### 健康检查

框架内置健康检查机制，可通过以下方式配置：

```yaml
management:
  endpoints:
    web:
      exposure:
        include: health,rpc
  endpoint:
    health:
      show-details: always
```

### 日志配置

```yaml
logging:
  level:
    top.uhyils.usher.rpc: DEBUG
```

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 代码规范

- 遵循 Google Java Style Guide
- 添加必要的单元测试
- 更新相关文档
- 保持良好的提交信息格式

## 📄 License

本项目采用 Apache License 2.0 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 联系方式

- **作者**: uhyils
- **邮箱**: 247452312@qq.com
- **Gitee**: [https://gitee.com/opentech_usher/usher-rpc](https://gitee.com/opentech_usher/usher-rpc)

## 🙏 致谢

感谢以下开源项目：

- [Netty](https://netty.io/) - 高性能网络通信框架
- [FastJSON2](https://github.com/alibaba/fastjson2) - 高性能JSON库
- [Spring Boot](https://spring.io/projects/spring-boot) - 应用开发框架

---
*Made with ❤️ by Usher Team*