基础教程

本教程为 Objective-C 程序员提供了使用 gRPC 的基础入门知识。

通过此示例，您将学习如何

• 在 .proto 文件中定义服务。
• 使用协议缓冲区编译器生成客户端代码。
• 使用 Objective-C gRPC API 为您的服务编写一个简单的客户端。

本教程假设您对 Protocol Buffers 有所了解。请注意，本教程中的示例使用了 Protocol Buffers 的 proto3 版本：您可以在 proto3 语言指南 和 Objective-C 生成代码指南 中了解更多信息。

为什么使用 gRPC？

我们的示例是一个简单的路线映射应用程序，它允许客户端获取其路线上特征的信息，创建其路线摘要，并与服务器及其他客户端交换路线信息（例如交通更新）。

使用 gRPC，我们可以一次在 .proto 文件中定义服务，并生成 gRPC 支持的任何语言的客户端和服务器。这些客户端和服务器可以在各种环境中运行，从大型数据中心内的服务器到您的平板电脑，应有尽有——不同语言和环境之间通信的所有复杂性都由 gRPC 为您处理。我们还可以获得使用 Protocol Buffers 的所有优势，包括高效的序列化、简单的 IDL 和易于更新的接口。

示例代码和设置

本教程的示例代码位于 grpc/grpc/examples/objective-c/route_guide。要下载该示例，请通过运行以下命令克隆 grpc 仓库：

git clone -b v1.78.1 --depth 1 --shallow-submodules https://github.com/grpc/grpc
cd grpc
git submodule update --init

然后将当前目录更改为 examples/objective-c/route_guide：

cd examples/objective-c/route_guide

我们的示例是一个简单的路线映射应用程序，它允许客户端获取其路线上特征的信息，创建其路线摘要，并与服务器及其他客户端交换路线信息（例如交通更新）。

您还需要安装 Cocoapods，以及用于生成客户端库代码（以及用于测试的其他语言服务器）的相关工具。您可以按照 这些设置说明 来获取后者。

尝试一下！

要尝试示例应用程序，我们需要在本地运行一个 gRPC 服务器。例如，我们来编译并运行此仓库中的 C++ 服务器：

pushd ../../cpp/route_guide
make
./route_guide_server &
popd

现在让 Cocoapods 为我们的 .proto 文件生成并安装客户端库：

pod install

（如果您的计算机缓存中还没有 OpenSSL，此步骤可能需要编译它，大约需要 15 分钟）。

最后，打开 Cocoapods 创建的 XCode 工作区，并运行该应用程序。您可以在 ViewControllers.m 中查看调用代码，并在 XCode 的日志控制台中查看结果。

接下来的部分将逐步指导您了解如何定义此 proto 服务、如何从中生成客户端库，以及如何创建一个使用该库的应用程序。

定义服务

首先，让我们看看我们使用的服务是如何定义的。gRPC 服务及其方法的请求和响应类型使用 Protocol Buffers 定义。您可以在 examples/protos/route_guide.proto 中查看我们示例的完整 .proto 文件。

要定义服务，请在您的 .proto 文件中指定一个命名的service

service RouteGuide {
   ...
}

然后，您在服务定义内定义 rpc 方法，指定它们的请求和响应类型。Protocol Buffers 允许您定义四种类型的服务方法，它们在 RouteGuide 服务中都有用到：

• 简单 RPC：客户端向服务器发送请求并随后接收响应，就像普通的远程过程调用一样。

  // Obtains the feature at a given position.
  rpc GetFeature(Point) returns (Feature) {}
  

• 响应流式 RPC：客户端向服务器发送一个请求，并收回一连串的响应消息。您可以通过在响应类型前放置 stream 关键字来指定响应流式方法。

  // Obtains the Features available within the given Rectangle.  Results are
  // streamed rather than returned at once (e.g. in a response message with a
  // repeated field), as the rectangle may cover a large area and contain a
  // huge number of features.
  rpc ListFeatures(Rectangle) returns (stream Feature) {}
  

• 请求流式 RPC：客户端向服务器发送一系列消息。一旦客户端写完消息，它会等待服务器读取所有消息并返回其响应。您可以通过在请求类型前放置 stream 关键字来指定请求流式方法。

  // Accepts a stream of Points on a route being traversed, returning a
  // RouteSummary when traversal is completed.
  rpc RecordRoute(stream Point) returns (RouteSummary) {}
  

• 双向流式 RPC：双方都向对方发送一系列消息。两个流独立运行，因此客户端和服务器可以以任何顺序读写：例如，服务器可以等待接收到所有客户端消息后再写其响应，或者它可以交替读取一条消息然后写一条消息，或者其他读写组合。每个流中的消息顺序都会被保留。您可以通过在请求和响应前都放置 stream 关键字来指定此类型的方法。

  // Accepts a stream of RouteNotes sent while a route is being traversed,
  // while receiving other RouteNotes (e.g. from other users).
  rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
  

我们的 .proto 文件还包含我们服务方法中使用的所有请求和响应类型的协议缓冲区消息类型定义——例如，这是 Point 消息类型

// Points are represented as latitude-longitude pairs in the E7 representation
// (degrees multiplied by 10**7 and rounded to the nearest integer).
// Latitudes should be in the range +/- 90 degrees and longitude should be in
// the range +/- 180 degrees (inclusive).
message Point {
  int32 latitude = 1;
  int32 longitude = 2;
}

您可以通过在文件顶部添加 objc_class_prefix 选项，为生成的类指定前缀。例如：

option objc_class_prefix = "RTG";

生成客户端代码

接下来，我们需要从我们的 .proto 服务定义中生成 gRPC 客户端接口。我们使用带有特殊 gRPC Objective-C 插件的协议缓冲区编译器 (protoc) 来完成此操作。

为简便起见，我们提供了一个 Podspec 文件，它会使用适当的插件、输入和输出为您运行 protoc，并描述如何编译生成的文件。您只需要在此目录 (examples/objective-c/route_guide) 下运行：

pod install

该命令在将生成的库安装到此示例的 XCode 项目之前，会运行：

protoc -I ../../protos --objc_out=Pods/RouteGuide --objcgrpc_out=Pods/RouteGuide ../../protos/route_guide.proto

运行此命令会在 Pods/RouteGuide/ 下生成以下文件：

• RouteGuide.pbobjc.h：声明生成的 Message 类的头文件。
• RouteGuide.pbobjc.m：包含 Message 类实现的文件。
• RouteGuide.pbrpc.h：声明生成的服务类的头文件。
• RouteGuide.pbrpc.m：包含服务类实现的文件。

这些文件包含：

• 所有用于填充、序列化和检索我们请求和响应消息类型的 Protocol Buffer 代码。
• 一个名为 RTGRouteGuide 的类，允许客户端调用 RouteGuide 服务中定义的方法。

您也可以使用提供的 Podspec 文件从任何其他 proto 服务定义生成客户端代码；只需替换名称（与文件名匹配）、版本和其他元数据即可。

创建客户端应用程序

在本节中，我们将介绍如何为我们的 RouteGuide 服务创建 Objective-C 客户端。您可以在 examples/objective-c/route_guide/ViewControllers.m 中查看我们完整的示例客户端代码。

构建服务对象

要调用服务方法，我们首先需要创建一个服务对象，即生成的 RTGRouteGuide 类的实例。该类的指定初始化程序需要一个包含我们要连接的服务器地址和端口的 NSString *：

#import <GRPCClient/GRPCCall+Tests.h>
#import <RouteGuide/RouteGuide.pbrpc.h>
#import <GRPCClient/GRPCTransport.h>

static NSString * const kHostAddress = @"localhost:50051";
...
GRPCMutableCallOptions *options = [[GRPCMutableCallOptions alloc] init];
options.transport = GRPCDefaultTransportImplList.core_insecure;

RTGRouteGuide *service = [[RTGRouteGuide alloc] initWithHost:kHostAddress callOptions:options];

请注意，我们的服务是使用不安全的传输方式构建的。这是因为我们将用于测试客户端的服务器不使用 TLS。这没问题，因为它将在我们的开发机器上本地运行。不过，最常见的情况是连接到互联网上的 gRPC 服务器，通过 TLS 运行 gRPC。对于这种情况，不需要设置 options.transport 选项，因为 gRPC 默认会使用安全的 TLS 传输。

调用服务方法

现在让我们看看如何调用我们的服务方法。正如您将看到的，所有这些方法都是异步的，因此您可以从应用程序的主线程调用它们，而不必担心冻结 UI 或操作系统杀掉您的应用程序。

简单 RPC

调用简单 RPC GetFeature 和调用 Cocoa 上的任何其他异步方法一样简单。

RTGPoint *point = [RTGPoint message];
point.latitude = 40E7;
point.longitude = -74E7;

GRPCUnaryResponseHandler *handler =
    [[GRPCUnaryResponseHandler alloc] initWithResponseHandler:
        ^(RTGFeature *response, NSError *error) {
          if (response) {
            // Successful response received
          } else {
            // RPC error
          }
        }
                                        responseDispatchQueue:nil];

[[service getFeatureWithMessage:point responseHandler:handler callOptions:nil] start];

如您所见，我们创建并填充了一个请求 Protocol Buffer 对象（在我们的例子中为 RTGPoint）。然后，我们在服务对象上调用该方法，将请求和一个用于处理响应（或任何 RPC 错误）的 block 传递给它。如果 RPC 成功完成，处理程序 block 将被调用，错误参数为 nil，我们可以从响应参数中读取服务器返回的信息。相反，如果发生任何 RPC 错误，处理程序 block 将被调用，响应参数为 nil，我们可以从错误参数中读取问题的详细信息。

流式 RPC

现在让我们看看我们的流式方法。这里我们将调用响应流式方法 ListFeatures，这会导致我们的客户端应用程序接收到一连串的地理 RTGFeature。

- (void)didReceiveProtoMessage(GPBMessage *)message {
  if (message) {
    NSLog(@"Found feature at %@ called %@.", response.location, response.name);
  }
}

- (void)didCloseWithTrailingMetadata:(NSDictionary *)trailingMetadata error:(NSError *)error {
  if (error) {
    NSLog(@"RPC error: %@", error);
  }
}

- (void)execRequest {
  ...
  [[service listFeaturesWithMessage:rectangle responseHandler:self callOptions:nil] start];
}

请注意，视图控制器对象本身会处理响应，而不是提供响应处理程序对象。当收到消息时，会调用 didReceiveProtoMessage: 方法；该方法可以被调用任意次数。当调用完成并从服务器收到 gRPC 状态（或在调用期间发生任何错误）时，会调用 didCloseWithTrailingMetadata: 方法。

请求流式方法 RecordRoute 期望客户端提供一系列 RTGPoint。在调用开始后，可以将此流写入 gRPC 调用对象。

RTGPoint *point1 = [RTGPoint message];
point.latitude = 40E7;
point.longitude = -74E7;

RTGPoint *point2 = [RTGPoint message];
point.latitude = 40E7;
point.longitude = -74E7;

GRPCUnaryResponseHandler *handler =
    [[GRPCUnaryResponseHandler alloc] initWithResponseHandler:
        ^(RTGRouteSummary *response, NSError *error) {
            if (response) {
              NSLog(@"Finished trip with %i points", response.pointCount);
              NSLog(@"Passed %i features", response.featureCount);
              NSLog(@"Travelled %i meters", response.distance);
              NSLog(@"It took %i seconds", response.elapsedTime);
            } else {
              NSLog(@"RPC error: %@", error);
            }
        }
                                        responseDispatchQueue:nil];
GRPCStreamingProtoCall *call =
    [service recordRouteWithResponseHandler:handler callOptions:nil];
[call start];
[call writeMessage:point1];
[call writeMessage:point2];
[call finish];

注意，由于 gRPC 调用对象不知道请求流的结尾，用户必须在请求流完成时调用 finish: 方法。

最后，让我们看看我们的双向流式 RPC RouteChat()。调用双向流式 RPC 的方式只是如何调用请求流式 RPC 和响应流式 RPC 的结合。

- (void)didReceiveProtoMessage(GPBMessage *)message {
  RTGRouteNote *note = (RTGRouteNote *)message;
  if (note) {
    NSLog(@"Got message %@ at %@", note.message, note.location);
  }
}

- (void)didCloseWithTrailingMetadata:(NSDictionary *)trailingMetadata error:(NSError *)error {
  if (error) {
    NSLog(@"RPC error: %@", error);
  } else {
    NSLog(@"Chat ended.");
  }
}

- (void)execRequest {
  ...
  GRPCStreamingProtoCall *call =
      [service routeChatWithResponseHandler:self callOptions:nil];
  [call start];
  [call writeMessage:note1];
  ...
  [call writeMessage:noteN];
  [call finish];
}