从RPC到gRPC：了解远程过程调用、Protocol Buffers以及现代分布式系统的通信机制

所有这些代码都是从同一个banking.proto文件中自动生成的。

Go后端工程师无需编写序列化代码，Flutter前端工程师也无需编写反序列化代码；Python数据工程师不必手动解析二进制数据，TypeScript Web开发人员更不需要手动构建HTTP请求。所有这些工作都由团队共同约定的“契约”自动完成。

下面是各种语言生成的代码示例，以便大家更直观地了解这一过程：

生成的Go语言服务器接口代码（后端实现部分）：

// 生成代码，切勿修改
type BankingServiceServer interface {
    Login(context.Context, *LoginRequest) (*LoginResponse, error)
    WatchBalance(*BalanceRequest, BankingService_WatchBalanceServer) error
    mustEmbedUnimplementedBankingServiceServer()
}

// Go后端工程师负责编写实现代码
type bankingServer struct {
    pb.UnimplementedBankingServiceServer
}

func (s *bankingServer) Login(
    ctx context.Context,
    req *pb.LoginRequest,
) (*pbLoginResponse, error) {
    token, err := authService.login(req.Email, req.Password)
    if err != nil {
        return nil, status.Errorf(codes.Unauthenticated, "无效的凭证")
    }
    return &pb LoginResponse{
        Token:  token,
        UserId: user.Id,
    }, nil
}

import grpc
import banking_pb2
import banking_pb2_grpc

channel = grpc.secure_channel(
    'api.fintech-platform.com:50051',
    grpc.ssl_channel_credentials()
)
stub = banking_pb2_grpc.BankingServiceStub(channel)

response = stub.login(banking_pb2 LoginRequest(
    email='john@example.com',
    password='password123'
))

print(f"令牌：{response.token}")
print(f"用户ID：{response.user_id}")

import 'package:grpc/grpc.dart';
import 'generated/banking.pb grpc.dart';
import 'generated/banking.pb.dart';

final channel = ClientChannel('api.fintech-platform.com', port: 50051);
final client = BankingServiceClient(channel);

final response = await client.login(
  LoginRequest(email: 'john@example.com', password: 'password123'),
);

print('令牌：${response.token}`);
print('用户ID：${response.userId'));

三种不同的语言，三个不同的团队，但它们都是基于同一个`.proto`文件生成的。这些客户端都是强类型化的，并且能够确保与服务器端的数据保持同步。

什么是gRPC？

gRPC是谷歌开发的开源远程过程调用框架。它于2016年被开源，如今已经成为Cloud Native Computing Foundation（CNCF）认证的项目。这意味着它在云原生生态系统中已经经过了最高级别的生产环境验证。

gRPC结合了以下三种技术：

1. 远程过程调用作为编程模型：可以像调用本地函数一样调用远程函数。
2. Protocol Buffers作为接口定义语言和数据序列化格式：它支持强类型契约，并采用紧凑的二进制编码方式。
3. HTTP/2作为传输协议：HTTP/2支持多路复用、持久连接，同时还采用了二进制帧格式进行数据传输。

这三项技术的结合使得gRPC成为一种比REST更快、结构更清晰、功能也更强大的通信框架。

在谷歌内部，几乎所有的服务间通信都使用gRPC。Netflix、Uber、Square、Dropbox、Lyft等数百家机构也都将gRPC用于它们的微服务通信系统。目前，Go、Java、Python、C++、C#、Ruby、Node.js、PHP、Dart、Kotlin等多种语言都支持使用gRPC。

为什么HTTP/2对gRPC如此重要

gRPC是完全基于HTTP/2协议构建的。了解HTTP/2所提供的功能对于理解gRPC的工作原理至关重要。

目前大多数REST API所使用的HTTP/1.1存在一些根本性的性能限制：在同一连接上，必须先完成一个请求后才能开始下一个请求；所有请求头信息都会以文本形式发送；服务器也不能主动向客户端发送数据，除非客户端首先发起请求。

而HTTP/2正是为了解决这些限制而设计的。

多路复用

HTTP/2在单个连接中实现了数据流的分割传输。多个独立的请求可以同时通过同一个TCP连接进行发送。

使用单个TCP连接访问api.fintech-platform.com

数据流1：登录请求 ---------> 登录响应
数据流2：个人资料请求 ------->> 个人资料响应
数据流3：余额查询请求 ------->> 余额更新信息（持续发送中）
数据流4：交易记录请求 --> 交易详情信息（持续发送中）

这四个数据流同时通过同一个连接进行传输

在HTTP/1.1中，需要建立四个独立的连接，或者等待前一个请求完成后再开始下一个请求。而HTTP/2则可以通过一个持久的连接同时处理所有这些请求，无需等待。

这就是gRPC具备流式传输功能的基础所在。正是这种持久的多路复用连接机制，使得服务器能够在客户端继续发送其他请求的同时，持续向客户端推送余额更新信息及交易通知。

二进制帧格式

HTTP/1.1将所有数据都以文本形式进行传输；而HTTP/2则将所有数据打包成二进制帧进行传输。二进制格式更加紧凑，机器解析起来也速度更快。

每个gRPC消息都会被分解成二进制帧，然后通过HTTP/2连接发送出去。结合protobuf的二进制编码技术，gRPC的数据在每一层传输时都采用最为紧凑的形式。

头部信息压缩（HPACK)

HTTP/1.1会在每个请求中都发送完整的头部信息。例如，用于携带JWT令牌的Authorization头部信息，其大小可能达到500字节甚至更多，并且会在每次请求中都被重复发送。

HTTP/2采用了HPACK压缩技术。之前请求中已经发送过的头部信息会被缓存起来，后续的请求只需发送那些发生了变化的部分即可。一旦Authorization头部信息被发送过，之后就会通过一个简短的索引来引用它，而无需再次完整地传输该头部信息。

对于那些在每次会话中都要发送大量经过身份验证的请求的移动应用来说，这种压缩机制能够显著节省带宽，尤其是在网络速度较慢的情况下，每一字节的数据都显得非常宝贵。

服务器主动推送

HTTP/2允许服务器在不需要客户端发起请求的情况下，主动向客户端发送数据。客户端打开一个数据流后，服务器就会在有新数据需要发送时，通过这个数据流将它们推送给客户端。

这就是gRPC服务器流式传输机制的运作原理。客户端只需发送一次WatchBalance请求，服务器就会在余额发生变化时立即推送新的BalanceResponse响应给客户端。无需进行轮询或重复请求，连接会始终保持开放状态，只要服务器有新内容要发送，就会立刻将其推送给客户端。

gRPC的四种通信模式

这是本文最重要的部分。实际上，gRPC并不只有一种通信模式，而是共有四种不同的通信方式。每种通信模式的具体实现都在.proto文件中进行了明确规定，它们各自适用于不同的使用场景。

模式1：单例请求/响应

客户端发送一个请求，服务器返回多个响应。就请求与响应的流程而言，这种模式与REST API调用是完全相同的。

何时使用单向RPC： 登录、获取个人资料信息、发起支付请求、创建数据、检索配置信息——任何遵循“询问-响应”模式的操作都适合使用单向RPC。

模式2：服务器端流式RPC

客户端发送一个请求，服务器会连续不断地返回多个响应。连接会保持开启状态，服务器会在数据准备好时立即将其推送给客户端。

何时使用服务器端流式RPC： 账户实时余额、交易通知、股票实时价格、体育比赛比分、新闻推送、系统监控面板——任何需要服务器持续更新数据的场景都适合使用这种模式。

每当服务器发送新的余额信息时，StreamBuilder会再次调用builder，于是小部件就会显示更新后的数值。整个过程中不存在任何轮询机制或手动刷新操作——完全由服务器主动发送数据，小部件则被动接收并展示这些数据。

Go语言服务器实现：

func (s *bankingServer) WatchBalance(
    req *pb.BalanceRequest,
    stream pb.BankingService_WatchBalanceServer,
) error {
    ticker := time.NewTicker(time.Second)
    defer ticker.Stop()

    for {
        select {
        case <-stream.Context().Done():
            return nil
        case <-ticker.C:
            balance, err := s.accountService.GetBalance(reqUserId)
            if err != nil {
                return status.Errorf(codes.Internal, "failed to fetch balance: %v", err)
            }

            if err := stream.Send(&pb.BalanceResponse{
                Balance:   balance.Amount,
                Currency:  balance.Currency,
                Timestamp: time.Now().UnixMilli(),
            }); err != nil {
                return err
            }
        }
    }
}

模式3：客户端流式RPC通信

客户端向服务器发送一系列消息，服务器会逐一处理这些消息，最后再统一给出响应。

rpc UploadDocument (stream DocumentChunk) returns (UploadResponse);

客户端 ---- 数据块1（字节0-1024）-----> 服务器
客户端 ---- 数据块2（字节1024-2048）--> 服务器
客户端 ---- 数据块3（字节2048-3072）--> 服务器
客户端 ---- 数据块4（最后一个数据块）-------> 服务器
客户端 <---收到UploadResponse-------------- 服务器（文档ID：「doc_001」）

何时使用客户端流式通信：当需要分块上传大文件（如身份验证文件、个人资料照片），或者批量发送传感器检测数据，又将大量记录提交给服务器时，这种通信方式非常适用。

Dart语言实现：

Future<UploadResponse>> uploadDocument(
  List<Uint8List>> chunks,
  String documentType,
) async {
  try {
    Stream<DocumentChunk>> chunkStream() async* {
      for (int i = 0; i < chunks.length; i++) {
        yield DocumentChunk(
          data: chunks[i],
          documentType: documentType,
          chunkIndex: i,
          isLast: i == chunks.length - 1,
        );
      }
    }

    return await _client.uploadDocument(chunkStream());
  } on GrpcError catch (e) {
    throw _mapGrpcError(e);
  }
}

chunkStream()是一个异步生成器函数。async*关键字表示该函数会逐步产生多个值，而不是直接返回一个值。每次调用yield时，都会生成一个DocumentChunk消息，由gRPC发送给服务器。服务器会依次接收这些消息并全部处理完毕，最后才返回一个UploadResponse作为最终结果。

Go语言服务器实现：

func (s *bankingServer) UploadDocument(
    stream pb.BankingService_UploadDocumentServer,
) error {
    var allData []byte
    var documentType string

    for {
        chunk, err := stream.Recv()
        if err == io.EOF {
            break
        }
        if err != nil {
            return status.Errorf(codes.Internal, "failed to receive chunk: %v", err)
        }

        allData = append(allData, chunk.Data...)
        documentType = chunk.DocumentType
    }

    docId, err := s.documentService.Store(allData, documentType)
    if err != nil {
        return status.Errorf(codes INTERNAL, "failed to store document: %v", err)
    }

    return stream.SendAndClose(&pbUploadResponse{
        Success:    true,
        DocumentId: docId,
        Message:    "Document uploaded successfully",
    })
}

模式4：双向流式RPC

客户端和服务器会同时发送消息，任何一方都可以随时发送数据，另一方不需要等待对方。

何时使用双向流式通信： 实时聊天、实时协作编辑文档、多人游戏状态同步、交互式交易终端、实时客户支持服务。

Dart语言实现示例： void startChat(String userId) { final outgoing = StreamController<ChatMessage>>(); final incoming = _client.chat(outgoing.stream); incoming.listen( (message) { print '${message.senderId}: ${message.content}`); }, onError: (error) { print('聊天错误: $error'); }, onDone: () { print('聊天会话结束'); }, ); outgoing.add(ChatMessage( senderId: userId, content: 'Hello, I need help with my account', timestamp: DateTime.now().millisecondsSinceEpoch, )); } StreamController负责管理发送方的消息流。每当用户发送消息时，就可以将这些消息添加到outgoing中。而incoming流则会接收来自服务器的消息。这两条消息流会通过同一个HTTP/2连接同时传输。

protobuf仓库：组织级的最佳实践

在小型项目中，.proto文件可以直接保存在后端代码库中。移动开发人员可以通过克隆后端代码库来获取这些文件，这种做法在规模较小的项目中确实可行。

但对于任何规模较大的组织来说，这种做法就会出现问题。后端代码库会成为“事实的权威”，从而使后端团队对协议内容拥有单方面的控制权；其他团队只有在他们的开发环境出现故障时，才会发现这些变更。

业界公认的最佳实践是专门设立一个protobuf仓库：这个仓库属于所有团队，但没有任何一个团队能够单独拥有它。

fintech-api-contracts/
  proto/
    auth/
      auth.proto
    banking/
      banking.proto
    payments/
      payments.proto
    notifications/
      notifications.proto
    kyc/
      kyc.proto
  scripts/
    generate_dart.sh
    generate_go.sh
    generate_python.sh
  README.md

合同变更的运作机制

任何API的变更都会遵循相同的流程：

开发人员提出对banking.proto文件的修改建议
          |
          在fintech-api-contracts仓库中提交Pull Request
          |
>Flutter团队的负责人进行审核：
  “这个修改会不会影响客户端的功能？我们需要进行更新吗？”
>Go后端团队的负责人进行审核：
  “这个修改是否可行？是否符合我们的开发规范？”
>React Web团队的负责人进行审核：
  “Web客户端是否需要做出相应的调整？”
>Python数据团队的负责人进行审核：
  “这个修改会不会影响我们的数据处理流程？”
          |
>所有团队都批准后，
          |
>Pull Request会被合并，此时该变更就正式成为标准规范
          |
>每个团队都会运行他们的代码生成脚本
          |
>如果存在会导致故障的变更，构建过程就会失败
>这样，这些变更就能在编译阶段就被发现，
>在任何代码被部署到生产环境之前，问题就能得到解决。

这种流程能够带来REST架构与文档所无法实现的优势：通过编译器的强制检查，确保所有团队都能使用相同版本的协议规范，从而保证合同内容在各个团队之间保持一致。
使用Dart和Flutter构建完整的gRPC系统
现在，让我们将这些知识点应用到一个实际的生产环境示例中，来看看整个系统的构建过程。
项目设置
首先，在你的Flutter项目中添加gRPC依赖：
# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  grpc: ^3.2.4
  protobuf: ^3.1.0

dev_dependencies:
  protoc_plugin: ^21.1.2

接下来，安装protoc编译器以及Dart的protoc插件：
# macOS
brew install protobuf

# 安装Dart的protoc插件
dart pub global activate protoc_plugin

然后，使用protoc工具从.proto文件生成Dart代码：
protoc \
  --dart_out=grpc:lib/generated \
  -I proto \
  proto/banking/banking.proto

数据源层
// lib/features/banking/data/datasources/banking_remote_datasource.dart

import 'package:grpc/grpc.dart';
import '__generated/banking.pb.dart';
import '__generated/banking.pb grpc.dart';
import '__core/error/app_exception.dart';

class BankingRemoteDataSource {
  late final BankingServiceClient _client;
  late final ClientChannel _channel;

  BankingRemoteDataSource({
    required String host,
    required int port,
    required String authToken,
  }) {
    _channel = ClientChannel(
      host,
      port: port,
      options: const ChannelOptions(
        credentials: ChannelCredentials.secure(),
        connectionTimeout: Duration(seconds: 10),
      ),
    );

    _client = BankingServiceClient(
      _channel,
      options: CallOptions(
        metadata: {'authorization': 'Bearer $authToken'},
        timeout: const Duration(seconds: 30),
      ),
    );
  }

  Future login(String email, String password) async {
    try {
      return await _client.login(
        LoginRequest(email: email, password: password),
      );
    } on GrpcError catch (e) {
      throw _mapGrpcError(e);
    }
  }

  Future getProfile(String userId) async {
    try {
      return await _client.getProfile(
        ProfileRequest(userId: userId),
      );
    } on GrpcError catch (e) {
      throw _mapGrpcError(e);
    }
  }

  Stream watchBalance(String userId) {
    return _client
      .watchBalance(BalanceRequest(userId: userId))
      .handleError((error) {
        if (error is GrpcError) throw _mapGrpcError(error);
        throw error;
      });
  }

  Stream streamTransactions(String userId, {int limit = 20}) {
    return _client
      .streamTransactions(
        TransactionRequest(userId: userId, limit: limit),
      )
      .handleError((error) {
        if (error is GrpcError) throw _mapGrpcError(error);
        throw error;
      });
  }

  Future uploadDocument(
    List Uint8List chunks,
    String documentType,
  ) async {
    try {
      Stream chunkStream() async* {
        for (int i = 0; i < chunks.length; i++) {
          yield DocumentChunk(
            data: chunks[i],
            documentType: documentType,
            chunkIndex: i,
            isLast: i == chunks.length - 1,
          );
        }
      }
      return await _client.uploadDocument(chunkStream());
    } on GrpcError catch (e) {
      throw _mapGrpcError(e);
    }
  }

  ResponseStream startChat(Stream outgoing) {
    return _client.chat(outgoing);
  }

  Future dispose() async {
    await _channel.shutdown();
  }

  AppException _mapGrpcError(GrpcError error) {
    switch (error.code) {
      case StatusCode.unauthenticated:
        return AppException.unauthorized(
          message: error.message ?? '未经授权',
        );
      caseStatusCode.notFound:
        return AppException_notFound(
          message: error.message ?? '未找到',
        );
      case StatusCode.deadlineExceeded:
        return AppException.timeout(message: '请求超时');
      case StatusCode.unavailable:
        return AppException.serverUnavailable(
          message: '服务不可用',
        );
      default:
        return AppException.unknown(
          message: error.message ?? '未知错误',
        );
    }
  }
}
让我们来了解一下这个数据源中的一些关键决策。
通道：
_channel = ClientChannel(
  host,
  port: port,
  options: const ChannelOptions(
    credentials: ChannelCredentials.secure(),
    connectionTimeout: Duration(seconds: 10),
  ),
);

通道实际上是应用程序与服务器之间建立的HTTP/2连接。你只需创建一次这个通道，之后就可以在所有的请求中重复使用它。ChannelCredentials.secure()用于启用TLS加密功能，而connectionTimeout则可以防止应用程序在服务器无法响应时无限期地等待。
通道正是gRPC能够实现高性能的关键所在。通过一个持久的通道，所有请求都可以通过同一个HTTP/2连接来发送；如果为每个请求都创建一个新的通道，那么这种性能优势就会完全丧失，其运行效率甚至会低于REST接口。
通过元数据进行身份验证：
_client = BankingServiceClient(
  _channel,
  options: CallOptions(
    metadata: {'authorization': 'Bearer $authToken'},
    timeout: const Duration(seconds: 30),
  ),
);

gRPC使用元数据（键值对）来实现类似HTTP头部信息的功能。将认证令牌作为元数据传递给CallOptions，意味着通过这个客户端发出的所有请求都会自动包含“Authorization”元数据。你只需要编写一次这样的代码，它就会在所有地方发挥作用。
错误映射：
AppException _mapGrpcError(GrpcError error) {
  switch (error.code) {
    case StatusCode.unauthenticated:
      return AppException.unauthorized(...);
    caseStatusCode_deadlineExceeded:
      return AppException.timeout(...);
    ...
  }
}

gRPC有一套自己的状态码，这些状态码与HTTP的状态码类似，但并不完全相同。在数据源层将这些状态码映射到应用程序中的异常类型上，就可以确保应用程序的其他部分永远不会直接处理那些特定于gRPC的错误。这样一来，你的代码结构就会更加清晰，且不会受到任何框架的限制。
仓库层

abstract class BankingRepository {
  Future<Result<UserProfile, AppException>>> getProfile(String userId);
  Stream<BalanceResponse>> watchBalance(String userId);
  Stream<Transaction>> streamTransactions(String userId);
  Future<Result<UploadResponse, AppException>>>> uploadDocument(
    List<Uint8List>> chunks,
    String documentType,
  );
}

class BankingRepositoryImpl implements BankingRepository {
  final BankingRemoteDataSource _dataSource;

  BankingRepositoryImpl(this._dataSource);

  @override
  Future<Result<UserProfile, AppException>>>> getProfile(String userId) async {
    try {
      final profile = await _dataSource.getProfile(userId);
      return Result.success(profile);
    } on AppException catch (e) {
      return Result.failure(e);
    }
  }

  @override
  Stream<BalanceResponse>> watchBalance(String userId) {
    return _dataSource.watchBalance(userId);
  }

  @override
  Stream<Transaction>> streamTransactions(String userId) {
    return _dataSource.streamTransactions(userId);
  }

  @override
  Future<Result<UploadResponse, AppException>>>> uploadDocument(
    List<Uint8List>> chunks,
    String documentType,
  ) async {
    try {
      final response = await _dataSource.uploadDocument(chunks, documentType);
      return Result.success(response);
    } on AppException catch (e) {
      return Result.failure(e);
    }
  }
}
Riverpod提供者

part 'banking_providers.g.dart';

@riverpod
Stream balanceStream(BalanceStreamRef ref, String userId) {
  final repository = ref.watch(bankingRepositoryProvider);
  return repository.watchBalance(userId);
}

@riverpod
Stream transactionStream(
  TransactionStreamRef ref,
  String userId,
) {
  final repository = ref.watch(bankingRepositoryProvider);
  return repository.streamTransactions(userId);
}

通过Riverpod，任何返回Stream的提供者都会自动变成一个可供组件监听的AsyncValue。每当gRPC服务器发送新的数据时，相关的组件就会自动重新更新。
用户界面
// lib/features/banking/presentation/pages/dashboard_page.dart
class DashboardPage extends ConsumerWidget {
  final String userId;

  const DashboardPage({required this.userId, super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final balanceAsync = ref.watch(balanceStreamProvider(userId));
    final transactionsAsync = ref.watch(transactionStreamProvider(userId));

    return Scaffold(
      appBar: AppBar(title: const Text('仪表盘')),
      body: Column(
        children: [
          balanceAsync.when(
            data: (balance) => BalanceCard(
              amount: balance.balance,
              currency: balance(currency,
            ),
            loading: () => const BalanceShimmer(),
            error: (e, _) => ErrorCard(message: e.toString()),
          ),

          const SizedBox(height: 24),

          Expanded(
            child: transactionsAsync.when(
              data: (transaction) => TransactionTile(
                transaction: transaction,
              ),
              loading: () => const TransactionShimmer(),
              error: (e, _) => ErrorCard(message: e.toString()),
            ),
          ),
        ],
      ),
    );
  }
}

余额信息和交易记录都是通过gRPC服务器流传输过来的。每当服务器有新数据发送时，这些信息都会实时更新。而Riverpod的AsyncValue机制使得这两种数据的处理方式完全相同。这个框架确实涵盖了所有必要的功能模式。
生产环境相关问题
使用拦截器进行身份验证
如果你需要更精细的身份验证控制机制，比如刷新过期的令牌或自动重试请求，你可以实现一个客户端拦截器：
class AuthInterceptor extends ClientInterceptor {
  final TokenService _tokenService;

  AuthInterceptor(this._tokenService);

  @override
  ResponseFuture interceptUnary( 
    ClientMethod method, 
    Q request, 
    CallOptions options, 
    ClientUnaryInvoker invoker, 
  ) {
    final token = _tokenService.currentToken;
    final authenticatedOptions = options.mergedWith(
      CallOptionsmetadata: {'authorization': 'Bearer $token'},
    );
    return invoker(method, request, authenticatedOptions);
  }

  @override
  ResponseStream interceptServerStreaming( 
    ClientMethod method, 
    Q request, 
    CallOptions options, 
    ClientServerStreamingInvoker invoker, 
  ) {
    final token = _tokenService.currentToken;
    final authenticatedOptions = options.mergedWith(
      CallOptionsmetadata: {'authorization': 'Bearer $token'},
    );
    return invoker(method, request, authenticatedOptions);
  }
}
在创建客户端时，需要添加拦截器：
_client = BankingServiceClient(
  _channel,
  interceptors: [AuthInterceptor(tokenService)],
);

该拦截器会在每次调用时自动被触发。数据源代码永远不会直接处理认证逻辑。
错误处理：gRPC状态码
gRPC定义了一组标准的状态码，所有实现都必须遵循这些状态码：

>



状态码
含义
建议采取的措施



OK (0)
操作成功
可以直接使用响应结果


CANCELLED (1)
客户端主动取消了调用
忽略该错误或记录日志


UNKNOWN (2)
服务器出现未知错误
显示通用错误提示


INVALID_ARGUMENT (3)
请求数据无效
显示验证错误信息


DEADLINE_EXCEEDED (4)
调用超时
重试或显示超时提示


NOT_FOUND (5)
资源不存在
显示“未找到”界面


ALREADY_EXISTS (6)
资源重复
显示冲突提示信息


PERMISSION_DENIED (7)
权限不足
显示“访问被拒绝”提示


UNAUTHENTICATED (16)
凭证无效或已过期
跳转到登录页面


RESOURCE_EXHAUSTED (8)
达到请求速率限制
稍后重试


UNAVAILABLE (14)
服务器暂时不可用
显示“离线”提示


AppException _mapGrpcError(GrpcError error) {
  switch (error.code) {
    case StatusCode.unauthenticated:
      return AppException.unauthorized(message: '会话已过期');
    caseStatusCode.permissionDenied:
      return AppException.forbidden(message: '访问被拒绝');
    case StatusCode.notFound:
      return AppException.notFound(message: error.message ?? '未找到');
    case StatusCode.deadlineExceeded:
      return AppException.timeout(message: '请求超时');
    caseStatusCode.unavailable:
      return AppException.serverUnavailable(message: '服务当前不可用');
    case StatusCode.resourceExhausted:
      return AppException.rateLimited(message: '请求次数过多');
    case StatusCode.invalidArgument:
      return AppException.validation(
        message: error.message ?? '输入无效',
      );
    default:
      return AppException.unknown(
        message: error.message ?? '发生了错误',
      );
  }
}

截止时间与超时机制
每个gRPC调用都应该设定截止时间。如果没有截止时间，即使服务器响应缓慢，应用程序也可能会无限期地等待响应。
针对每次调用的截止时间设置：
Future<UserProfile>> getProfile(String userId) async {
  return await _client.getProfile(
    ProfileRequest(userId: userId),
    options: CallOptions(timeout: const Duration(seconds: 10)),
  );
}
所有调用的默认截止时间：
_client = BankingServiceClient(
  _channel,
  options: CallOptions(
    timeout: const Duration(seconds: 30),
    metadata: {'authorization': 'Bearer $authToken'},
  ),
);

当超过截止时间时，调用会抛出带有StatusCode.deadlineExceeded的GrpcError异常，你的错误处理机制会对此进行相应的处理。
日志拦截器
class LoggingInterceptor extends ClientInterceptor {
  @override
  ResponseFuture<R>> interceptUnary<Q, R>>(
    ClientMethod<Q, R>> method,
    Q request,
    CallOptions options,
    Client UnaryInvoker<Q, R>> invoker,
  ) {
    final stopwatch = Stopwatch()..start();
    debugPrint('[gRPC] --> ${method.path}');

    final response = invoker(method, request, options);

    response.then((_) {
      stopwatch.stop();
      debugPrint(
        '[gRPC] <-- ${method.path} (${stopwatch.elapsedMilliseconds}ms)',
      );
    }).catchError((error) {
      stopwatch.stop();
      debugPrint(
        '[gRPC] ERROR ${method.path}: $error (${stopwatch.elapsedMilliseconds}ms)',
      );
    });

    return response;
  }
}

gRPC、REST与WebSockets：何时使用哪种技术
何时使用REST
如果API被第三方开发者或外部合作伙伴使用，那么通过HTTP传输JSON数据是一种通用方案——任何语言的开发者都可以直接使用这种技术，而无需学习新的工具或技术。
REST采用简单的请求-响应模型，不需要进行流式数据处理，也只需要一个客户端平台即可。对于那些需要进行基本的CRUD操作的场景来说，REST更易于实现、更便于调试，也更容易进行测试。
公开文档的易读性也非常重要。使用OpenAPI/Swagger技术，REST接口可以生成结构清晰、便于浏览和测试的文档，开发者可以直接在浏览器中查看这些文档。
缓存也是非常重要的一项功能。REST请求的响应结果可以在CDN、反向代理以及浏览器缓存层中进行缓存；而gRPC请求则无法利用标准的HTTP缓存机制。
何时使用WebSockets
当你需要实现真正的双向实时通信，而且你的技术栈中还没有包含gRPC时，WebSockets就是最佳选择。聊天应用、多人游戏以及需要双方能够自由交流的合作工具，都是WebSockets的典型应用场景。
此外，浏览器必须直接支持WebSockets，而不能通过代理层来转发请求。现代所有的浏览器都原生支持WebSockets；而在浏览器中使用gRPC，则需要借助gRPC-Web框架以及代理层才能实现通信功能。
何时使用gRPC
当多个开发团队需要共享相同的服务接口时，gRPC是一个非常实用的选择。例如，如果Flutter、React、Go和Python这些不同语言编写的应用程序都需要调用同一个后端服务，那么使用.proto文件作为接口定义标准，就可以有效避免各个团队在接口实现上出现偏差。
对于那些需要传输大量数据的应用程序来说，gRPC也是更好的选择。因为protobuf支持二进制编码，而且生成的客户端代码也更加简洁高效。特别是当有大量的字段需要被传输，或者有很多应用程序都在使用这些数据时，使用gRPC的优势就更加明显了。
网络环境是多变的，数据包的大小也至关重要。使用2G或3G连接的用户，会直接从protobuf的紧凑二进制格式中受益。用protobuf表示的相同数据，其大小可能会比用JSON表示的数据小3到10倍，这样一来，对于那些数据流量有限的用户来说，加载速度就会更快，数据消耗也会更少。
如果需要进行实时流式传输，那么就需要一个能够适用于所有通信模式的统一框架。gRPC所提供的四种通信模式可以覆盖各种场景，而且无需在API之外再单独部署WebSocket服务器。
当需要高频进行服务之间的交互时，两种内部服务如果通过持久化的、多路复用的HTTP/2连接，并使用二进制protobuf格式进行数据传输，其性能将会显著优于通过HTTP/1.1使用JSON进行的通信。
混合架构
一个成熟的工程决策并不是在gRPC和REST之间做出选择，而是要明确两者各自适用的场景，并有意识地同时使用它们。
大多数规模较大的组织最终都会采用混合架构：公共的REST API用于满足外部用户对简洁性和JSON格式的需求；内部的gRPC网络则负责处理高频、高性能的服务间通信；而移动端的gRPC接口则能够通过高效的二进制连接，为Flutter客户端提供实时数据传输功能。
每一层都使用最适合自身需求的工具。这里不存在对某种协议的盲目推崇，纯粹是出于工程实践的考虑。
结论
远程过程调用的理念起源于这样一个简单的想法：网络通信不应该让开发人员花费额外的精力去处理相关细节。在另一台机器上调用一个函数，应该就像在自己的机器上调用该函数一样自然。
Protocol Buffers进一步解决了数据编码的问题。JSON格式虽然易于阅读，但文本量较大；而通过编译器强制执行的二进制编码方式，能够生成体积更小、解析速度更快的数据包，并且能确保这些数据包符合所有团队事先约定的格式规范。对于那些处于网络环境较差的环境中，或者需要每天处理海量请求的内部系统来说，这种效率无疑具有重大的商业价值。
gRPC将远程过程调用的语义、Protocol Buffers的编码方式以及HTTP/2传输协议结合在一起，形成了一个能够支持四种不同通信模式的框架：单向请求-响应模式、服务器端流式传输模式、客户端流式传输模式以及双向流式传输模式。所有这些功能都是通过同一个生成的客户端接口实现的，使用的是同一条持久化的连接，同时也受到相同的`.proto`协议规范的约束。
如果整个组织都共享一个Protocol Buffers代码库，那么gRPC就不仅仅是一种技术工具，而会真正成为一种工程实践标准。任何对协议规范的修改都会经过审查流程；那些可能破坏系统稳定性的变更也会被编译器及时检测出来。每个团队都会根据同一个源代码生成自己所需的强类型客户端程序，因此无论使用哪种编程语言，各个团队之间的开发进度都能保持同步。
在Flutter框架中，gRPC服务器端的流式传输功能可以与Dart语言中的`Stream`类型以及Riverpod提供的流处理机制完美结合。那些原本需要通过REST进行轮询查询，或者单独部署WebSocket服务器才能实现的实时余额更新和交易数据推送功能，现在都可以通过简单的流式订阅方式轻松实现。服务器负责发送数据，客户端负责接收数据，除此之外再不需要任何额外的配置。在选择使用 gRPC、REST 还是 WebSockets 时，关键不在于个人偏好，而在于让所选工具能够满足具体需求。公共 API 应该使用 REST 来实现；高频的内部服务通信则更适合使用 gRPC；那些被众多内部系统使用的、数据量较大的通信协议，应该选择 protobuf；而需要实时双向通信的场景，则应该采用 gRPC 流式传输技术。对于那些处于不稳定网络环境中的用户来说，提供数据量尽可能小的通信方案才是最合理的选择。
真正理解这些工具的作用原理、明白它们存在的意义，并且知道在什么情况下该使用哪种工具，这才是区分那些只会机械使用工具的工程师与那些能够从系统整体角度进行思考的工程师的关键所在。
祝编程愉快！