gRPC e Protocol Buffers

Anatomia do arquivo .proto

O arquivo .proto é o contrato central de um serviço gRPC. Ele define mensagens, campos, tipos e os serviços (conjuntos de RPCs) que o servidor implementa e os clientes chamam. Ao contrário de um contrato OpenAPI que descreve endpoints HTTP, um .proto descreve chamadas de procedimento com semântica forte de tipos.

syntax = "proto3";

package orders.v1;

option go_package = "github.com/empresa/orders/gen/orders/v1;ordersv1";
option csharp_namespace = "Empresa.Orders.V1";

import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";

// Enum de status do pedido
enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0; // sempre zero para proto3
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_PROCESSING = 2;
  ORDER_STATUS_SHIPPED = 3;
  ORDER_STATUS_DELIVERED = 4;
  ORDER_STATUS_CANCELLED = 5;
}

// Mensagem de item de pedido
message OrderItem {
  string product_id = 1;
  int32 quantity = 2;
  int64 unit_price_cents = 3; // preço em centavos para evitar float
}

// Mensagem principal de pedido
message Order {
  string id = 1;
  string customer_id = 2;
  repeated OrderItem items = 3; // lista de itens
  OrderStatus status = 4;
  google.protobuf.Timestamp created_at = 5;
  google.protobuf.Timestamp updated_at = 6;
  map<string, string> metadata = 7; // campo map
}

// Request para criação
message CreateOrderRequest {
  string customer_id = 1;
  repeated OrderItem items = 2;
  map<string, string> metadata = 3;
}

// Response de criação
message CreateOrderResponse {
  Order order = 1;
}

// Request para busca por ID
message GetOrderRequest {
  string id = 1;
}

// Request para stream de eventos
message WatchOrderRequest {
  string order_id = 1;
}

// Evento de mudança de status
message OrderEvent {
  string order_id = 1;
  OrderStatus previous_status = 2;
  OrderStatus new_status = 3;
  google.protobuf.Timestamp occurred_at = 4;
}

// Request para busca por cliente (lista)
message ListOrdersByCustomerRequest {
  string customer_id = 1;
  int32 page_size = 2;
  string page_token = 3;
}

// Response paginado
message ListOrdersByCustomerResponse {
  repeated Order orders = 1;
  string next_page_token = 2;
}

// Definição do serviço
service OrderService {
  // Unary RPC — padrão request-response
  rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
  rpc GetOrder(GetOrderRequest) returns (Order);

  // Server streaming — servidor envia múltiplas mensagens
  rpc WatchOrder(WatchOrderRequest) returns (stream OrderEvent);

  // Server streaming para paginação natural
  rpc ListOrdersByCustomer(ListOrdersByCustomerRequest) returns (stream Order);

  // Client streaming — cliente envia múltiplos itens, servidor responde uma vez
  rpc BulkCreateOrders(stream CreateOrderRequest) returns (CreateOrderResponse);

  // Bidirectional streaming — ambos enviam/recebem livremente
  rpc SyncOrderStatus(stream WatchOrderRequest) returns (stream OrderEvent);
}

Tipos escalares e suas correspondências

Proto3 define tipos escalares com semântica precisa. A tabela abaixo mostra os mais usados e como mapeiam para cada linguagem:

Well-known types e Google APIs

O pacote google/protobuf/ fornece tipos reutilizáveis que evitam reinventar estruturas comuns:

• Timestamp — ponto no tempo com precisão de nanosegundos (seconds + nanos desde Unix epoch)
• Duration — intervalo de tempo (seconds + nanos)
• Empty — equivalente a void como parâmetro ou retorno
• Any — envelope para qualquer mensagem proto, inclui type URL para desserialização
• Struct — mapa de valores JSON-like quando o schema não é conhecido em compile time
• FieldMask — lista de campos afetados em operações de update parcial (evita semântica ambígua de PATCH)
• Wrappers — Int32Value, StringValue, etc. para tipos nullable em proto3

Encoding binário do Protocol Buffers

A eficiência do gRPC vem em parte do encoding binário dos Protocol Buffers. Entender como o encoding funciona explica por que gRPC é substancialmente mais compacto que JSON e por que certas decisões de design no schema impactam performance.

Wire types e field tags

Cada campo serializado é precedido por um tag — um varint que codifica o field number e o wire type. Wire types determinam como ler os bytes seguintes:

O tag é calculado como (field_number << 3) | wire_type. Para o campo customer_id = 2 (string → wire type 2), o tag é (2 << 3) | 2 = 18 = 0x12.

Varint encoding

Varints são inteiros de tamanho variável: cada byte usa 7 bits para dados e 1 bit para indicar se há mais bytes. Números pequenos (0–127) ocupam 1 byte; números médios, 2 bytes; grandes, até 10 bytes. Isso é extremamente eficiente quando a maioria dos valores são pequenos — o caso típico em sistemas reais.

Para inteiros negativos, int32 é ineficiente (sempre 10 bytes por usar complemento de dois). Use sint32/sint64 que aplicam ZigZag encoding: n → (n << 1) ^ (n >> 31), mapeando negativos para positivos pequenos.

Comparação de tamanho: JSON vs Protobuf

Considere o objeto Order com id, customer_id, 3 itens, status e timestamps. Em JSON, o payload seria aproximadamente 380-450 bytes com chaves repetidas em cada item. Em Protobuf, o mesmo dado ocupa tipicamente 80-120 bytes — redução de 70-80%. Em sistemas com milhões de chamadas por segundo, isso se traduz em economia significativa de bandwidth e CPU de serialização/deserialização.

Campos desconhecidos e compatibilidade

Uma propriedade fundamental do encoding é que clientes que não conhecem um field number simplesmente preservam os bytes desconhecidos ao reserializar. Isso viabiliza compatibilidade bidirecional: novos clientes podem enviar campos que servidores antigos ignoram, e servidores novos podem retornar campos que clientes antigos passam adiante sem interpretar.

Geração de código e toolchain

O compilador protoc processa arquivos .proto e gera código para a linguagem alvo via plugins. O fluxo é: escrever .proto → executar protoc com plugins → código gerado vai para controle de versão ou build pipeline.

C# com grpc-dotnet

# Adicionar ao .csproj — protoc via Grpc.Tools
<PackageReference Include="Google.Protobuf" Version="3.*" />
<PackageReference Include="Grpc.Tools" Version="2.*" PrivateAssets="All" />
<PackageReference Include="Grpc.Net.Client" Version="2.*" />
<PackageReference Include="Grpc.AspNetCore" Version="2.*" />

<!-- No .csproj, declarar os .proto files -->
<ItemGroup>
  <Protobuf Include="Protos\orders.v1.proto" GrpcServices="Server" />
</ItemGroup>

<!-- Grpc.Tools roda protoc automaticamente no build -->

O MSBuild com Grpc.Tools gera automaticamente as classes OrderServiceBase (para implementar no servidor) e OrderServiceClient (para usar no cliente). O servidor herda de OrderServiceBase e sobrescreve os métodos que deseja expor.

Python com grpcio-tools

# Instalação
pip install grpcio grpcio-tools

# Geração de código
python -m grpc_tools.protoc \
  --proto_path=protos \
  --python_out=gen \
  --pyi_out=gen \
  --grpc_python_out=gen \
  protos/orders/v1/orders.proto

# Arquivos gerados:
# gen/orders/v1/orders_pb2.py        — classes de mensagens
# gen/orders/v1/orders_pb2.pyi       — type stubs para mypy
# gen/orders/v1/orders_pb2_grpc.py   — stubs de servidor e cliente

Go com protoc-gen-go

# Instalação dos plugins
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# Geração de código
protoc \
  --go_out=. \
  --go_opt=paths=source_relative \
  --go-grpc_out=. \
  --go-grpc_opt=paths=source_relative \
  orders/v1/orders.proto

# Arquivos gerados:
# orders/v1/orders.pb.go      — structs de mensagens
# orders/v1/orders_grpc.pb.go — interfaces de servidor e cliente

Estratégia de repositório de schemas

Existem duas estratégias para organizar arquivos .proto:

• Schema-first no mesmo repositório: o .proto fica no repositório do serviço, o código gerado é commitado ou gerado no build. Funciona bem para serviços internos com poucos consumidores.
• Repositório centralizado de schemas: todos os .proto ficam em um repositório separado (ex: company/api-schemas), os consumidores o referenciam via BSR ou git submodule. Garante que múltiplos serviços compartilhem o mesmo schema evoluído de forma coordenada.

Quatro modos de streaming

O HTTP/2 como transporte permite que gRPC implemente quatro padrões distintos de comunicação. Escolher o padrão errado não apenas afeta performance — pode tornar a API semanticamente incorreta.

1. Unary RPC

O cliente envia uma requisição, o servidor processa e responde com uma mensagem. É o padrão mais simples e o mais comum. Equivale funcionalmente a uma chamada REST POST ou GET. O overhead é uma negociação de stream HTTP/2, headers de metadata e trailers de status.

// .proto
rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);

// Quando usar:
// - Operações CRUD simples
// - Queries que retornam um único resultado
// - Comandos com resposta de confirmação
// - Sempre que não há necessidade de streaming

2. Server Streaming RPC

O cliente envia uma requisição, o servidor responde com um stream de mensagens. O cliente lê até o servidor fechar o stream ou cancelar. O servidor pode enviar mensagens à medida que os dados ficam disponíveis — sem precisar acumular tudo na memória.

// .proto
rpc WatchOrder(WatchOrderRequest) returns (stream OrderEvent);
rpc ListOrdersByCustomer(ListOrdersByCustomerRequest) returns (stream Order);

// Casos de uso:
// - Notificações em tempo real (push de eventos)
// - Resultados de queries grandes (evita carregar tudo na memória)
// - Download de arquivos ou datasets
// - Log tailing
// - Dashboards com atualizações contínuas

Server streaming com gRPC é fundamentalmente diferente de Server-Sent Events (SSE): o protocolo é bidirecional em nível de transporte (HTTP/2), o schema é tipado, e o backpressure é gerenciado automaticamente pelo fluxo de controle do HTTP/2.

3. Client Streaming RPC

O cliente envia um stream de mensagens, o servidor processa e responde com uma única mensagem ao final. Útil para uploads em chunks, ingestão de dados em batch, e casos onde o cliente gera dados mais rápido do que o servidor processa — o fluxo de controle do HTTP/2 aplica backpressure automaticamente.

// .proto
rpc BulkCreateOrders(stream CreateOrderRequest) returns (BulkCreateOrdersResponse);
rpc UploadCsv(stream CsvChunk) returns (UploadResult);

// Casos de uso:
// - Upload de arquivos grandes em chunks
// - Ingestão de eventos em batch
// - Cálculos agregados sobre streams de entrada
// - ETL de grandes volumes de dados

4. Bidirectional Streaming RPC

Ambos os lados enviam e recebem streams de mensagens independentemente. O servidor não precisa esperar o cliente terminar para responder, e vice-versa. O protocolo de troca é definido pela aplicação — não pelo framework.

// .proto
rpc SyncOrderStatus(stream WatchOrderRequest) returns (stream OrderEvent);
rpc Chat(stream ChatMessage) returns (stream ChatMessage);

// Casos de uso:
// - Aplicações de chat
// - Colaboração em tempo real
// - Games multiplayer
// - Telemetria bidirecional (envio de comandos + recebimento de métricas)
// - Streaming de AI (tokens em stream com feedback do cliente)

HTTP/2 e multiplexing

Um detalhe fundamental: múltiplos streams gRPC compartilham uma única conexão TCP via multiplexing HTTP/2. Não há head-of-line blocking a nível de aplicação (o HOL blocking do TCP ainda existe, mas é menos frequente). Em sistemas com alta taxa de requisições, isso elimina o overhead de criar novas conexões TCP para cada RPC — um problema real em REST com HTTP/1.1.

Modelo de erro gRPC

gRPC define um modelo de erro estruturado baseado em status codes — diferente de HTTP que usa códigos no cabeçalho de resposta. O status é retornado nos trailers HTTP/2 ao final do stream, acompanhado de uma mensagem de texto e opcionalmente detalhes ricos.

Status codes

Rich error details

O status code sozinho raramente é suficiente para diagnóstico. A Google API Improvement Proposals (AIP) define um modelo de erros ricos via google.rpc.Status que embute mensagens Any com detalhes estruturados:

// google/rpc/status.proto (incluído via googleapis)
message Status {
  int32 code = 1;        // StatusCode como int
  string message = 2;   // Mensagem legível por humanos
  repeated google.protobuf.Any details = 3; // Detalhes ricos
}

// Tipos de detalhe disponíveis:
// google.rpc.ErrorInfo    — reason, domain, metadata
// google.rpc.RetryInfo    — retry_delay para quando tentar novamente
// google.rpc.DebugInfo    — stack_entries, detail
// google.rpc.QuotaFailure — violations com quota_id e description
// google.rpc.BadRequest   — field_violations com field e description
// google.rpc.PreconditionFailure — violations com type, subject, description

// C# — retornando erro rico
using Google.Rpc;
using Grpc.Core;

// No handler do servidor
var status = new Google.Rpc.Status
{
    Code = (int)StatusCode.InvalidArgument,
    Message = "Dados de pedido inválidos",
    Details =
    {
        Any.Pack(new BadRequest
        {
            FieldViolations =
            {
                new BadRequest.Types.FieldViolation
                {
                    Field = "items",
                    Description = "Lista de itens não pode estar vazia"
                },
                new BadRequest.Types.FieldViolation
                {
                    Field = "customer_id",
                    Description = "ID de cliente é obrigatório"
                }
            }
        })
    }
};

throw status.ToRpcException();

Mapeamento gRPC ↔ HTTP para transcoding

Infraestruturas como Envoy e gRPC-Gateway suportam transcoding — exposição de serviços gRPC como REST automaticamente. Para isso, o .proto usa anotações google.api.http:

import "google/api/annotations.proto";

service OrderService {
  rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse) {
    option (google.api.http) = {
      post: "/v1/orders"
      body: "*"
    };
  }
  rpc GetOrder(GetOrderRequest) returns (Order) {
    option (google.api.http) = {
      get: "/v1/orders/{id}"
    };
  }
}

Interceptors — middleware gRPC

Interceptors são o equivalente de middleware em gRPC — permitem adicionar comportamento transversal sem poluir a lógica de negócio: autenticação, logging, tracing, métricas, retry, circuit breaker. O padrão é Chain of Responsibility: cada interceptor chama o próximo na cadeia.

Interceptors no servidor (C#)

// Interceptor de logging e tracing
public class ObservabilityInterceptor : Interceptor
{
    private readonly ILogger<ObservabilityInterceptor> _logger;
    private readonly ActivitySource _activitySource;

    public ObservabilityInterceptor(
        ILogger<ObservabilityInterceptor> logger,
        ActivitySource activitySource)
    {
        _logger = logger;
        _activitySource = activitySource;
    }

    // Intercepta Unary RPCs
    public override async Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
        TRequest request,
        ServerCallContext context,
        UnaryServerMethod<TRequest, TResponse> continuation)
    {
        var method = context.Method; // "/orders.v1.OrderService/CreateOrder"
        var peer = context.Peer;
        var deadline = context.Deadline;

        using var activity = _activitySource.StartActivity(
            method,
            ActivityKind.Server);

        activity?.SetTag("rpc.system", "grpc");
        activity?.SetTag("rpc.method", method);
        activity?.SetTag("grpc.peer", peer);

        var sw = Stopwatch.StartNew();

        try
        {
            var response = await continuation(request, context);

            _logger.LogInformation(
                "gRPC {Method} OK in {ElapsedMs}ms",
                method, sw.ElapsedMilliseconds);

            GrpcMetrics.RecordDuration(method, "OK", sw.Elapsed);
            return response;
        }
        catch (RpcException ex)
        {
            _logger.LogWarning(
                "gRPC {Method} {Status} in {ElapsedMs}ms: {Message}",
                method, ex.StatusCode, sw.ElapsedMilliseconds, ex.Message);

            activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
            GrpcMetrics.RecordDuration(method, ex.StatusCode.ToString(), sw.Elapsed);
            throw;
        }
    }

    // Intercepta Server Streaming
    public override async Task ServerStreamingServerHandler<TRequest, TResponse>(
        TRequest request,
        IServerStreamWriter<TResponse> responseStream,
        ServerCallContext context,
        ServerStreamingServerMethod<TRequest, TResponse> continuation)
    {
        using var activity = _activitySource.StartActivity(context.Method, ActivityKind.Server);
        await continuation(request, responseStream, context);
    }
}

// Registro no Program.cs
builder.Services.AddGrpc(options =>
{
    options.Interceptors.Add<AuthInterceptor>();      // primeiro: auth
    options.Interceptors.Add<ObservabilityInterceptor>(); // depois: obs
    options.Interceptors.Add<ValidationInterceptor>();    // por último: validação
});

Interceptors no cliente — retry automático

// Interceptor de retry com backoff exponencial (cliente C#)
public class RetryInterceptor : Interceptor
{
    private static readonly HashSet<StatusCode> RetriableStatuses = new()
    {
        StatusCode.Unavailable,
        StatusCode.ResourceExhausted,
        StatusCode.Internal,
        StatusCode.DeadlineExceeded,
    };

    public override AsyncUnaryCall<TResponse> AsyncUnaryCall<TRequest, TResponse>(
        TRequest request,
        ClientInterceptorContext<TRequest, TResponse> context,
        AsyncUnaryCallContinuation<TRequest, TResponse> continuation)
    {
        // Delegar para lógica async com retry
        return new AsyncUnaryCall<TResponse>(
            ExecuteWithRetry(request, context, continuation),
            // ... headers, status, trailers, dispose
        );
    }

    private async Task<TResponse> ExecuteWithRetry<TRequest, TResponse>(
        TRequest request,
        ClientInterceptorContext<TRequest, TResponse> context,
        AsyncUnaryCallContinuation<TRequest, TResponse> continuation)
        where TRequest : class
        where TResponse : class
    {
        var attempt = 0;
        while (true)
        {
            try
            {
                var call = continuation(request, context);
                return await call.ResponseAsync;
            }
            catch (RpcException ex) when (RetriableStatuses.Contains(ex.StatusCode) && attempt < 3)
            {
                attempt++;
                var delay = TimeSpan.FromMilliseconds(Math.Pow(2, attempt) * 100);
                await Task.Delay(delay);
            }
        }
    }
}

Deadlines e cancelamento

Deadlines são uma das funcionalidades mais importantes do gRPC e das mais frequentemente ignoradas. Um deadline é um ponto absoluto no tempo após o qual a operação deve ser considerada falha — diferente de timeout, que é relativo ao início. A distinção importa: em chamadas em cadeia, o deadline original é propagado entre serviços, preservando o orçamento de tempo global da requisição.

Propagação de deadline em cadeia de serviços

// Serviço A chama Serviço B com o mesmo contexto (deadline propagado)
public override async Task<CreateOrderResponse> CreateOrder(
    CreateOrderRequest request,
    ServerCallContext context)
{
    // context.CancellationToken é cancelado quando o deadline expira
    // ou quando o cliente cancela a requisição

    // CORRETO: passar o token de cancelamento
    var customer = await _customerService.GetCustomerAsync(
        request.CustomerId,
        context.CancellationToken);  // ← deadline propagado

    // ERRADO: criar novo CancellationToken sem deadline
    var customer = await _customerService.GetCustomerAsync(
        request.CustomerId,
        CancellationToken.None);  // ← perde o deadline!

    // Para chamadas gRPC saindo deste serviço:
    // O deadline do contexto de entrada é propagado automaticamente
    // se você usar o mesmo CancellationToken no CallOptions de saída
    var inventoryCall = _inventoryClient.CheckStockAsync(
        new CheckStockRequest { ProductIds = { productIds } },
        new CallOptions(
            deadline: context.Deadline,  // mantém o deadline original
            cancellationToken: context.CancellationToken));

    return new CreateOrderResponse { Order = order };
}

Tratando DEADLINE_EXCEEDED vs CANCELLED

A distinção entre os dois status é crucial para operação:

• DEADLINE_EXCEEDED: o servidor excedeu o tempo — pode ser retriável. O servidor pode ou não ter completado a operação antes de retornar o erro. Para operações não-idempotentes, isso exige cuidado: a operação pode ter sido executada.
• CANCELLED: o cliente cancelou — o cliente não está mais interessado. Não há sentido em retornar resultado. O servidor deve abortar o trabalho em andamento o mais rápido possível ao detectar cancelamento via CancellationToken.IsCancellationRequested.

Reflection e grpcurl

gRPC Server Reflection é um protocolo que permite que clientes descubram os serviços disponíveis e seus schemas sem acesso ao arquivo .proto. É o equivalente do Swagger UI para gRPC — fundamental para debugging interativo em desenvolvimento e staging.

Habilitando reflection

// C# — Program.cs
builder.Services.AddGrpcReflection();
// ...
if (app.Environment.IsDevelopment())
{
    app.MapGrpcReflectionService();
}

// Go — importar o pacote de reflection
import _ "google.golang.org/grpc/reflection"
// ...
reflection.Register(grpcServer) // registra no servidor gRPC

# Python
pip install grpcio-reflection
from grpc_reflection.v1alpha import reflection
SERVICE_NAMES = (
    orders_pb2.DESCRIPTOR.services_by_name['OrderService'].full_name,
    reflection.SERVICE_NAME,
)
reflection.enable_server_reflection(SERVICE_NAMES, server)

grpcurl — curl para gRPC

# Listar serviços disponíveis
grpcurl -plaintext localhost:5000 list

# Descrever um serviço específico
grpcurl -plaintext localhost:5000 describe orders.v1.OrderService

# Descrever uma mensagem
grpcurl -plaintext localhost:5000 describe orders.v1.Order

# Chamar um RPC unary com JSON
grpcurl -plaintext \
  -d '{"customer_id": "cust-123", "items": [{"product_id": "prod-1", "quantity": 2, "unit_price_cents": 1000}]}' \
  localhost:5000 \
  orders.v1.OrderService/CreateOrder

# Chamar com headers (metadata gRPC)
grpcurl -plaintext \
  -H "Authorization: Bearer eyJhbG..." \
  -d '{"id": "order-abc"}' \
  localhost:5000 \
  orders.v1.OrderService/GetOrder

# Server streaming — exibe mensagens conforme chegam
grpcurl -plaintext \
  -d '{"order_id": "order-abc"}' \
  localhost:5000 \
  orders.v1.OrderService/WatchOrder

Outras ferramentas do ecossistema

• Evans: client REPL interativo para gRPC com autocompletion de campos
• Postman: suporte nativo a gRPC desde 2022, incluindo streaming
• gRPC UI: interface web para explorar e chamar serviços gRPC com reflection
• BloomRPC: GUI para macOS/Linux/Windows similar ao Postman para gRPC
• buf curl: alternativa ao grpcurl integrada ao Buf toolchain

gRPC-Web — bridging para browsers

gRPC nativo requer HTTP/2 com acesso de baixo nível às trailers — algo que os browsers não expõem via fetch/XMLHttpRequest. gRPC-Web é uma especificação alternativa que usa uma camada de tradução entre o browser e o servidor, permitindo que frontends se comuniquem com serviços gRPC.

Arquitetura com proxy

Browser
  ↓ gRPC-Web (HTTP/1.1 ou HTTP/2 + base64 encoding de trailers)
Envoy Proxy / nginx com módulo grpc-web
  ↓ gRPC nativo (HTTP/2 com trailers reais)
Backend gRPC Server

Limitações do gRPC-Web

gRPC-Web suporta apenas unary RPC e server streaming. Client streaming e bidirectional streaming não são suportados — para esses casos, use WebSockets ou SSE. Além disso, o encoding de trailers varia entre implementações.

Connect: alternativa moderna

O protocolo Connect (da Buf) resolve limitações do gRPC-Web sendo nativo ao browser, compatível com gRPC e gRPC-Web, e usando JSON legível por padrão (com Protobuf como opção). Um único servidor Connect responde corretamente a clientes gRPC nativos, gRPC-Web e clientes HTTP simples com curl — sem proxy.

Quando usar gRPC — e quando não usar

gRPC vence quando:

• Comunicação interna entre microsserviços — ambos os lados controlados, schema evolui coordenadamente, performance importa
• Performance crítica — serialização Protobuf é 5-10x mais rápida que JSON, overhead de HTTP/2 é menor que HTTP/1.1
• Contratos fortemente tipados — geração de código elimina divergência de schema entre times, breaking changes detectados em compile time
• Streaming real — server streaming, client streaming, bidirecional — REST não tem equivalente nativo eficiente
• Polyglot teams — código gerado garante consistência entre C#, Python, Go, Java, Rust, etc.
• Sistemas com múltiplos clientes internos — SDK gerado é mais ergonômico que HTTP client manual

gRPC perde quando:

• APIs públicas — REST + JSON é universalmente acessível; gRPC requer tooling específico e nem todo cliente suporta HTTP/2
• Browser como cliente direto — gRPC nativo não funciona em browsers sem proxy ou gRPC-Web
• Debugging ad-hoc — curl funciona com REST; grpcurl requer reflection habilitado ou acesso ao .proto
• Caches HTTP — CDNs e proxies cachean GET requests HTTP; gRPC usa POST para tudo e não é cacheable por intermediários padrão
• Times pequenos sem infraestrutura — toolchain mais complexo (protoc, geração de código, BSR) não compensa para 2 serviços
• Firewalls e proxies legados — alguns proxies corporativos bloqueiam ou não interpretam corretamente HTTP/2

Decisões de engenharia

Perguntas de entrevista

Exercícios práticos

1. Defina um arquivo .proto para um serviço de notificações com unary SendNotification e server streaming SubscribeToNotifications. Inclua enums de canal (EMAIL, SMS, PUSH) com valor 0 UNSPECIFIED, well-known types para timestamps, e campos opcionais para template_id e metadata.
   Critério: enum deve ter valor 0 UNSPECIFIED obrigatório; usar google.protobuf.Timestamp para datas; campos opcionais declarados com optional; serviço com pelo menos 3 RPCs com mix de unary e streaming; campos removidos marcados como reserved.
2. Implemente um interceptor de autenticação que extrai um Bearer token dos metadados gRPC (context.Metadata), valida contra um serviço de identidade, e injeta o UserId no contexto. Trate UNAUTHENTICATED vs PERMISSION_DENIED corretamente.
   Critério: ausência de token retorna UNAUTHENTICATED; token inválido/expirado retorna UNAUTHENTICATED; token válido mas sem permissão para o método retorna PERMISSION_DENIED; o interceptor deve funcionar tanto para Unary quanto para Streaming RPCs; deve logar o método chamado e o UserId extraído.
3. Crie um client streaming RPC BulkImportProducts(stream ImportProductRequest) returns (ImportResult) onde o servidor processa em lotes de 500 itens. Implemente backpressure: se a fila interna do servidor tiver mais de 1000 itens pendentes, pause o recebimento.
   Critério: ImportResult deve conter total_processed, total_failed e lista de erros por item (field + reason); cliente deve enviar ao menos 2000 itens para validar o backpressure; falhas em itens individuais não devem abortar o batch inteiro; processar com uma única transação de banco por batch de 500.
4. Implemente propagação de deadline em um handler CheckoutOrder que chama três serviços downstream (inventory, payment, shipping) sequencialmente. Passe o deadline original para cada chamada e trate DEADLINE_EXCEEDED de forma diferente de erros de negócio.
   Critério: verificar se o deadline restante é suficiente (>50ms) antes de cada chamada downstream; retornar erro descritivo identificando em qual serviço o deadline foi atingido; DEADLINE_EXCEEDED de downstream não deve vazar como INTERNAL — propagar como DEADLINE_EXCEEDED ou UNAVAILABLE com contexto do estágio.
5. Compare a payload size de uma lista de 100 pedidos (cada um com ao menos 3 itens) serializada como JSON vs Protobuf. Meça tamanho em bytes e tempo médio de serialização e deserialização em 1000 iterações.
   Critério: documentar resultados em tabela com colunas: formato, tamanho (bytes), serialização (µs/op), deserialização (µs/op), tamanho JSON comprimido com gzip (bytes); calcular razão Protobuf/JSON para cada métrica; rodar em pelo menos duas linguagens (ex: Go e Python) e comparar os resultados.