# Quickuse.Grpc

**Repository Path**: quickuse/Quickuse.Grpc

## Basic Information

- **Project Name**: Quickuse.Grpc
- **Description**: Quickuse.Grpc
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-04-27
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Quickuse.GrpcSimplifier

[![NuGet](https://img.shields.io/nuget/v/Quickuse.GrpcSimplifier.svg)](https://www.nuget.org/packages/Quickuse.GrpcSimplifier)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Quickuse.GrpcSimplifier 是一个面向 .NET 微服务架构的 gRPC 简化器组件库，基于 MagicOnion 和 Redis 提供开箱即用的服务注册、服务发现、负载均衡和健康检查能力。

## 特性

- ✅ **开箱即用**：一行 `AddGrpcService()` 完成服务端全部注册
- ✅ **自动服务发现**：客户端通过服务名自动解析地址，无需硬编码 IP
- ✅ **健康检查**：后台定时上报，自动摘除失效节点
- ✅ **负载均衡**：支持轮询和最小线程数两种策略
- ✅ **IP 透传**：跨服务调用保留原始客户端 IP
- ✅ **环境变量配置**：所有关键参数支持环境变量覆盖
- ✅ **日志注入**：支持注入外部 `ILogger`，降级为彩色控制台输出

## 安装

### 方式 1：NuGet 包管理器控制台

```bash
Install-Package Quickuse.GrpcSimplifier
```

### 方式 2：.NET CLI

```bash
dotnet add package Quickuse.GrpcSimplifier
```

### 方式 3：PackageReference

```xml
<PackageReference Include="Quickuse.GrpcSimplifier" Version="3.0.2.9" />
```

## 快速开始

### 服务端接入

```csharp
// Program.cs 或 Startup.cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpcService(options =>
    {
        options.ServiceName = "order-service";
        options.ServicePort = 5001;
        options.HealthReportingInterval = 5; // 健康上报间隔（秒）
    }, startup =>
    {
        startup.CheckRedisOnStartup = true;  // 启动时阻塞等待 Redis 可用
        // 可选：代码中直接指定 Redis 连接参数，优先级高于环境变量
        // startup.Redis = new RedisOptions { Host = "10.0.0.1", Password = "pwd" };
    },
    filters =>
    {
        // 可选：添加全局 MagicOnion 过滤器
        // filters.Add(new MyCustomFilter());
    });
}
```

### 客户端接入

```csharp
// 1. 继承 BaseGrpcClient
public class OrderServiceClient : BaseGrpcClient
{
    public override string ServiceName => "order-service";
    public override int ServicePort => 5001;
    public override int UnavailableStatusCode => 503;

    public IOrderService CreateOrderService()
    {
        return CreateClient<IOrderService>();
    }
}

// 2. 使用客户端
var client = new OrderServiceClient();
var orderService = client.CreateOrderService();
var result = await orderService.GetOrderAsync(orderId);
```

## 环境变量配置

| 环境变量 | 说明 | 默认值 |
|----------|------|--------|
| `REDIS_HOST` | Redis 主机地址 | `localhost` |
| `REDIS_PORT` | Redis 端口 | `6379` |
| `REDIS_PASSWORD` | Redis 密码 | 空 |
| `REDIS_DATABASE` | Redis 数据库编号 | `0` |
| `REDIS_CLUSTER_NODES` | Redis 集群节点（逗号分隔） | 空（单节点模式） |
| `GRPC_MAX_RECEIVE_MESSAGE_SIZE` | gRPC 最大接收消息大小（MB） | `10` |
| `GRPC_MAX_SEND_MESSAGE_SIZE` | gRPC 最大发送消息大小（MB） | `10` |
| `GRPC_LOAD_BALANCING_STRATEGY` | 负载均衡策略（`0`=轮询，`1`=最小线程数） | `0` |
| `GRPC_HEALTH_TIMEOUT_SECONDS` | 健康检查超时判断基准（秒） | `10` |
| `GRPC_HOST_MACHINE_IP` | 强制指定本机 IP（容器场景） | 自动检测 |
| `GRPC_HEALTH_CHECK_INTERVAL_MS` | 客户端服务监控扫描间隔（毫秒） | `5000` |
| `GRPC_SERVICE_EXPIRE_HOURS` | 服务注册数据在 Redis 中的过期时间（小时） | `2` |
| `DEBUG_LOG` | 启用控制台 Debug 级别输出 | `false` |

> 所有 Redis 环境变量均支持 `GRPC_` 前缀优先读取，例如 `GRPC_REDIS_HOST` 优先于 `REDIS_HOST`。

### 容器化部署示例

```yaml
# docker-compose.yml
services:
  order-service:
    image: my-order-service:latest
    environment:
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - REDIS_PASSWORD=your-password
      - GRPC_HOST_MACHINE_IP=10.0.0.1  # 容器场景必配
      - GRPC_MAX_RECEIVE_MESSAGE_SIZE=20
      - GRPC_MAX_SEND_MESSAGE_SIZE=20
    ports:
      - "5001:5001"
```

## 架构说明

### 服务注册流程

1. 服务启动时，`BackgroundRegisterService` 自动向 Redis 注册
2. 注册信息包括：服务名、IP、端口、线程数
3. 后台定时（默认 5 秒）上报健康状态
4. 通过 Redis Pub/Sub 通知客户端服务变更

### 服务发现流程

1. 客户端调用 `CreateClient<T>()` 时自动从 Redis 查询服务列表
2. 根据负载均衡策略选择节点（轮询或最小线程数）
3. 订阅 Redis Pub/Sub，实时更新本地缓存
4. 定时扫描健康检查时间戳，自动摘除失效节点

### Redis 键结构

```
grpc:discovery:services                          # 所有已注册服务名
grpc:discovery:instances:{serviceName}           # 某服务的实例列表（score=线程数）
grpc:discovery:health:{serviceName}              # 某服务的健康时间戳（score=Unix时间戳）
grpc:discovery:changes                           # Pub/Sub 频道
```

## 高级特性

### IP 透传拦截器

跨服务调用时自动透传原始客户端 IP：

```csharp
// 服务端（AddGrpcService 已自动包含，无需单独调用）

// 客户端激活（在 Configure/中间件管道中调用）
app.UseGrpcClientIpForwarding();
```

透传 Header 名称：`X-Origin-Request-IP`

### 自定义重试策略

```csharp
public class MyGrpcClient : BaseGrpcClient
{
    public MyGrpcClient()
    {
        GrpcMethodConfig = new MethodConfig
        {
            Names = { MethodName.Default },
            RetryPolicy = new RetryPolicy
            {
                MaxAttempts = 3,
                InitialBackoff = TimeSpan.FromSeconds(0.5),
                MaxBackoff = TimeSpan.FromSeconds(2),
                BackoffMultiplier = 2,
                RetryableStatusCodes = { StatusCode.Unavailable }
            }
        };
    }
}
```

### 注册全局客户端拦截器

```csharp
// 在应用启动阶段注册，运行时不建议动态修改
BaseGrpcClient.AddInterceptor(new MyCustomInterceptor());
```

## 依赖项

| 包 | 版本 |
|----|------|
| MagicOnion | 6.1.6 |
| MessagePack | 3.1.0 |
| StackExchange.Redis | 2.8.24 |
| Grpc.Net.Client | 2.67.0 |
| Grpc.HealthCheck | 2.67.0 |
| Microsoft.Extensions.Logging | 6.0.0 |
| Microsoft.Extensions.Hosting.Abstractions | 6.0.0 |

**运行时要求**：.NET 6.0 / 8.0 / 9.0

## 许可证

本项目采用 [MIT 许可证](LICENSE)。