TsgcGRPCClient

TsgcGRPCClient 实现了基于 HTTP/2 的 gRPC 客户端（使用 TsgcHTTP2Client 作为传输），并支持四种 gRPC RPC 模式。

简介

TsgcGRPCClient 实现了一个运行在 HTTP/2 之上的 gRPC 客户端。请按照以下步骤配置此组件：

1. 将一个 TsgcHTTP2Client 实例赋值给 Client 属性；该组件用作 HTTP/2 传输。设置该传输的 Host、Port 和 TLS，使其指向 gRPC 服务器。

2. 使用 OnGRPCResponse 事件处理响应，然后连接并调用一个一元方法。示例：


    oHTTP2 := TsgcHTTP2Client.Create(nil);
    oHTTP2.Host := 'grpc.example.com';
    oHTTP2.Port := 443;
    oHTTP2.TLS := True;

    oGRPC := TsgcGRPCClient.Create(nil);
    oGRPC.Client := oHTTP2;
    oGRPC.OnGRPCResponse := OnGRPCResponseEvent;
    oGRPC.CallAsync('helloworld.Greeter', 'SayHello', vRequestBytes);

    procedure OnGRPCResponseEvent(Sender: TObject; const aResponse: TsgcGRPCResponse);
    begin
      if aResponse.StatusCode = grpcOK then
        ShowMessage(aResponse.DataString);
    end;

RPC 模式

gRPC 定义了四种 RPC 模式。TsgcGRPCClient 为每一种模式公开了一组成员：

一元：使用 Call 进行返回 TsgcGRPCResponse 的同步调用，或使用 CallAsync 通过 OnGRPCResponse 事件异步接收响应。
服务器流式传输：使用 ServerStreamingCall；服务器发送的每条消息都会在 OnGRPCStreamMessage 中到达，流在 OnGRPCStreamEnd 中完成。
客户端流式传输：使用 OpenClientStream，然后通过 SendStreamMessage 发送一条或多条消息，并以 CloseClientStream 或 CloseClientStreamAsync 结束。
双向流式传输：使用 OpenBidiStream，通过 SendBidiMessage 发送消息，并以 CloseBidiStream 结束；传入的消息会在 OnGRPCStreamMessage 中到达。

以下示例执行服务器流式调用，并读取服务器投递的每条消息：


    oGRPC.OnGRPCStreamMessage := OnGRPCStreamMessageEvent;
    oGRPC.ServerStreamingCall('routeguide.RouteGuide', 'ListFeatures', vRequestBytes);

    procedure OnGRPCStreamMessageEvent(Sender: TObject; const aMessage: TsgcGRPCStreamMessage);
    begin
      ShowMessage(aMessage.DataString);
    end;

功能特性

Channel Options

ChannelOptions 属性配置通道级行为，例如消息 Compression、ContentType、最大发送和接收消息大小以及 HTTP/2 keep-alive ping。

Metadata

使用 DefaultMetadata 为每次调用附加自定义标头，或向任意调用方法传递单次调用的元数据。这就是诸如 Bearer 令牌之类的授权标头被发送到服务器的方式。

截止时间与重试

每次调用都接受一个截止时间，因此当服务器响应缓慢时会快速失败。RetryPolicy 控制自动重试：MaxAttempts、指数退避以及可重试状态码的集合。

负载均衡

TsgcGRPCLoadBalancer 使用 Pick First 或 Round Robin 策略在多个后端之间分配调用，并通过 DNS 名称解析器解析后端地址。

健康检查

TsgcGRPCHealthClient 实现了标准的 grpc.health.v1.Health 服务，提供用于一次性状态查询的 Check，以及用于以流形式接收健康状态变化的 Watch。

服务器反射

TsgcGRPCReflectionClient 使用 gRPC 服务器反射服务来列出某个服务器公开的服务，并在运行时获取它们的文件描述符。

Interceptors

拦截器可以通过 Interceptors 属性链接起来。该库包含 TsgcGRPCLoggingInterceptor、TsgcGRPCTimeoutInterceptor 和 TsgcGRPCMetadataInterceptor。

遥测

MetricsCollector 公开每个方法的遥测数据，包括调用次数、成功率和延迟，对于监控和诊断非常有用。

Protocol Buffers

gRPC 请求和响应采用 Protocol Buffers (protobuf) 编码。该库包含 TsgcProtobufWriter 和 TsgcProtobufMessage，用于按字段编号构建和解析消息。Google Cloud 接口提供类型化的请求和响应类，因此在调用这些服务时您无需手动编码 protobuf。

参考

属性

名称	描述
Client	用作所有 gRPC 调用的 HTTP/2 传输的 TsgcHTTP2Client 实例。
ChannelOptions	通道级选项：压缩、内容类型、最大消息大小以及 HTTP/2 keep-alive。
DefaultMetadata	添加到每次调用的元数据（自定义标头），例如授权 Bearer 令牌。
Interceptors	应用于每次调用的拦截器链（日志记录、超时、元数据）。
RetryPolicy	自动重试配置：最大尝试次数、指数退避以及可重试的状态码。
ServiceConfig	每个服务的配置，包括方法默认值、重试设置和负载均衡策略。
MetricsCollector	收集每个方法的遥测数据：调用次数、成功率和延迟。

方法

名称	描述
Call	执行同步一元调用并返回 TsgcGRPCResponse。
CallAsync	执行异步一元调用；响应通过 OnGRPCResponse 事件传递。
ServerStreamingCall	启动服务器流式调用；每条服务器消息都会在 OnGRPCStreamMessage 中到达。
OpenClientStream	打开一个客户端流式调用，以便客户端可以发送一系列消息。
SendStreamMessage	在已打开的客户端流上发送一条消息。
CloseClientStream	同步关闭客户端流并返回服务器响应。
CloseClientStreamAsync	异步关闭客户端流；响应通过 OnGRPCResponse 到达。
OpenBidiStream	打开一个双向流式调用，双方在其中交换消息。
SendBidiMessage	在已打开的双向流上发送一条消息。
CloseBidiStream	关闭双向流并向服务器发出流结束信号。
CancelCall	在活动调用或流完成之前取消它。
CallString	一元辅助方法，用于发送请求并以字符串形式返回响应。

事件

名称	描述
OnGRPCConnect	当与 gRPC 服务器的底层 HTTP/2 连接建立时触发。
OnGRPCDisconnect	当与 gRPC 服务器的连接关闭时触发。
OnGRPCResponse	当一元调用完成时触发，传递 TsgcGRPCResponse。
OnGRPCStreamMessage	针对服务器流式或双向流上接收到的每条消息触发。
OnGRPCStreamEnd	当流完成时触发，携带最终的 gRPC 状态。
OnGRPCError	当调用以非 OK 的 gRPC 状态码结束时触发。
OnGRPCException	在处理调用过程中发生异常时触发。
OnGRPCBeforeRequest	在发送请求之前触发，允许检查或修改标头和元数据。