适用于 Delphi 的 gRPC 客户端

2026年6月2日 · 组件

sgcWebSockets 现已提供适用于 Delphi 和 C++Builder 的原生 gRPC 客户端。新的 TsgcGRPCClient 组件通过本库自带的 HTTP/2 传输来进行 gRPC 通信，因此无需任何外部 gRPC 运行时、无需 C 库，也无需部署额外的 DLL。它是 Enterprise 版本的一部分，可在 Windows、macOS、Linux、iOS 和 Android 上运行。

gRPC 本质上就是通过 HTTP/2 进行分帧的 Protocol Buffers 消息。sgcWebSockets 已经拥有完整的 HTTP/2 协议栈，因此 gRPC 客户端直接构建于其之上：它会对你的请求字节进行分帧，应用 gRPC 标头和超时设置，并将返回的状态与尾部信息解析为类型化结果。

构建于原生 HTTP/2 传输之上

一个 gRPC 通道就是一个 HTTP/2 连接。你创建一个 TsgcHTTP2Client，将其指向主机和端口，然后把它赋给 gRPC 组件的 Client 属性。TLS 由 HTTP/2 客户端通过 OpenSSL 或 Windows SChannel 来处理。

uses
  sgcHTTP2, sgcGRPC_Client, sgcGRPC_Classes, sgcGRPC_Types;

var
  HTTP2: TsgcHTTP2Client;
  GRPC: TsgcGRPCClient;
  oResponse: TsgcGRPCResponse;
begin
  HTTP2 := TsgcHTTP2Client.Create(nil);
  HTTP2.Host := 'grpc.example.com';
  HTTP2.Port := 443;
  HTTP2.TLS  := True;

  GRPC := TsgcGRPCClient.Create(nil);
  GRPC.Client := HTTP2;

  // metadata is sent on every call (auth, tracing...)
  GRPC.DefaultMetadata.Add('authorization', 'Bearer eyJ...');

  // unary call: the request is your serialized protobuf message as TBytes
  oResponse := GRPC.Call('helloworld.Greeter', 'SayHello', RequestBytes);
  if oResponse.StatusCode = grpcOK then
    Memo1.Text := oResponse.DataString
  else
    ShowMessage('gRPC error: ' + oResponse.StatusMessage);
end;

全部四种调用类型

该组件支持每一种 gRPC 交互模式，可同步或异步使用：

一元调用。Call 会阻塞并返回一个 TsgcGRPCResponse；CallAsync 会立即返回并触发 OnGRPCResponse。
服务端流式。ServerStreamingCall 发送一个请求并接收一系列消息，每条消息都会触发 OnGRPCStreamMessage，并在结束时触发 OnGRPCStreamEnd。
客户端流式。先调用 OpenClientStream，然后为每条消息调用 SendStreamMessage，最后调用 CloseClientStream 来读取单条回复。
双向流式。OpenBidiStream、SendBidiMessage 和 CloseBidiStream 在同一个 HTTP/2 流上运行一次全双工交换。

响应会携带该调用返回的所有内容：StatusCode、StatusMessage、原始的 Data 字节（或 DataString）以及 Trailers。

元数据、截止时间和通道选项

自定义标头可通过 DefaultMetadata 在整个通道上传递，也可按调用单独传递。按调用设置的超时会被转换为标准的 grpc-timeout 标头，CancelCall 则可中止一个进行中的流。通道本身则通过 ChannelOptions 进行调优。

// gzip compression and channel limits
GRPC.ChannelOptions.Compression := grpcGzip;
GRPC.ChannelOptions.MaxMessageSize := 16 * 1024 * 1024;

// abort a long-running stream
GRPC.CancelCall(StreamId);

拦截器、重试与可观测性

一个 Interceptors 链会包裹每一次调用，因此你可以在同一处添加日志记录、身份验证刷新或追踪。RetryPolicy 会在你选定的状态码上进行重试，ServiceConfig 可应用按方法划分的策略，而 MetricsCollector 则记录调用计数器和延迟。

GRPC.RetryPolicy.MaxAttempts := 4;
GRPC.RetryPolicy.RetryableStatusCodes :=
  GRPC.RetryPolicy.RetryableStatusCodes + [grpcUNAVAILABLE];

自带你自己的 Protocol Buffers

该客户端接收并返回原始消息字节（TBytes），因此不会将你绑定到任何单一的 Protocol Buffers 库。用你已经在使用的任何 protobuf 工具来编码你的请求，将字节传给 Call，再以同样的方式解码响应字节。该组件会为你处理 gRPC 的长度前缀分帧、压缩标志、状态码和尾部信息。

已包含 Google Cloud gRPC API

在通用客户端之上，sgcWebSockets 还为 Google Cloud 的 gRPC 服务提供了类型化客户端：Pub/Sub、Speech-to-Text、Translation、Vision、Natural Language、Cloud Storage、BigQuery 和 Vertex AI。它们会处理服务账户身份验证以及请求和响应消息，因此你可以调用高级方法，而无需手动构建 protobuf。

可用性

gRPC 客户端现已在适用于 Delphi 和 C++Builder 的 sgcWebSockets Enterprise 版本中提供。一个开箱即用的示例包含在 Demos\21.GRPC\01.GRPC_Client 中，完整的属性、方法和事件参考则位于 gRPC 客户端产品页面。

有问题、反馈，或需要入门帮助？联系我们。你将收到来自代码编写者本人的回复。