gRPC ve REST — Aynı Havale, İki Dil

Bir mektup yazarken her bilginin önüne ne olduğunu yazarsın: “tutar: 2500 lira”. Bir resmî form ise yalnızca numaralı kutulardan oluşur; 2 numaralı kutuya tutarı yazarsın. Mektubu herkes okur, form kısadır ama hangi kutunun ne olduğunu bilmek için şablon gerekir.

İki biçim, aynı veri

REST çağrıları çoğu zaman JSON taşır: {"amountKurus": 250000, …}. Her mesaj alan adlarını da taşır; okunur ve curl ile denenebilir.

gRPC?Terimin tanımını açgRPCHTTP/2 üzerinde çalışan, mesajları protobuf ile taşıyan uzak çağrı çerçevesi. Şemadan istemci ve sunucu kodu üretilir; akışları destekler.Sözlükte gör → ise protobuf?Terimin tanımını açprotobufProtocol Buffers: alanları adla değil numarayla taşıyan ikili mesaj biçimi. Küçüktür ve şemayla okunur; numara bir kez verilir, değişmez.Sözlükte gör → taşır. Şemada her alanın bir numarası vardır ve kablodan yalnızca numara ile sıkıştırılmış değer geçer. Bizim havale JSON’da 89 bayt, protobuf’ta 41 bayt.

Sözleşme ad mı, numara mı?

JSON alanları adla eşler: amountKurus adını amountMinor yaparsan eski istemci tutarı bulamaz. Protobuf alanları numarayla eşler: adı değiştirmek zararsızdır, numarayı değiştirmek ise veriyi sessizce kaybettirir.

Bu yüzden protobuf’ta kural nettir: bir numara bir kez verilir ve bir daha değişmez. Kaldırdığın alanın numarasını reserved yaparak yeniden kullanılmasını engellersin.

Kendin gör

1. Varsayılanla oynat. JSON mesajı 89 bayt.
2. Protokolü gRPC yap. Aynı havale 41 bayt.
3. “Bir alanın adını değiştirdi” seç. JSON’da eski istemci kırıldı, gRPC’de kırılmadı.
4. “Numarasını değiştirdi” seç, gRPC’de kal. Hata yok ama IBAN kayboldu.
5. “Tarayıcıdan fetch” seç. gRPC için gRPC-Web ve bir proxy gerekiyor.

Tuzaklar

Tarayıcıdan doğrudan gRPC. Tarayıcılar yerel gRPC’nin ihtiyaç duyduğu HTTP/2 ayrıntılarına erişemez. gRPC-Web?Terimin tanımını açgRPC-WebTarayıcıların gRPC servislerini çağırabilmesi için kullanılan uyarlama. Tarayıcı gRPC-Web konuşur, bir proxy onu gerçek gRPC'ye çevirir.Sözlükte gör → ve onu çeviren bir proxy gerekir; çoğu ekip dışarıya REST sunar.

Okunamayan mesajlar. Protobuf mesajını curl ya da log’da gözle okuyamazsın. grpcurl gibi araçlar ve şema dosyasının kendisi hata ayıklamanın parçası olur.

Zorunlu alan beklemek: protobuf 3’te gönderilmeyen bir alan varsayılan değerle (0, boş metin) okunur. “Tutar 0 mı, yoksa hiç gönderilmedi mi?” sorusunu şemada ayrıca çözmen gerekir.

Aşağıdaki örnek bir bankanın ödeme servisinden: protobuf şeması, kaldırılan alan için reserved, Spring ile gRPC servisi ve dışarıya açılan REST uç noktası.

1
syntax = "proto3";
2

3
package bank.transfer.v1;
4

5
message Transfer {
6
  int64  id           = 1;
7
  int64  amount_minor = 2;   // renamed from amount_kurus: same number, wire-compatible
8
  string currency     = 3;
9
  string to_iban      = 4;   // never renumber
10
  reserved 5;                // was "channel", removed; its number can never come back
11
  reserved "channel";
12
}
13

14
service TransferService {
15
  rpc Send (Transfer) returns (TransferResult);
16
}
17

18
message TransferResult {
19
  int64  id     = 1;
20
  string status = 2;
21
}

1
// Service-to-service: small, schema-checked messages over HTTP/2.
2
@GrpcService
3
class TransferGrpcService extends TransferServiceGrpc.TransferServiceImplBase {
4

5
    private final Transfers transfers;
6

7
    TransferGrpcService(Transfers transfers) {
8
        this.transfers = transfers;
9
    }
10

11
    @Override
12
    public void send(Transfer request, StreamObserver<TransferResult> response) {
13
        TransferResult result = transfers.send(request);
14
        response.onNext(result);
15
        response.onCompleted();
16
    }
17
}

1
// The browser and external partners get the same operation as JSON over REST.
2
@RestController
3
@RequestMapping("/api/transfers")
4
class TransferController {
5

6
    private final Transfers transfers;
7

8
    TransferController(Transfers transfers) {
9
        this.transfers = transfers;
10
    }
11

12
    @PostMapping
13
    TransferResponse send(@RequestBody TransferRequest request) {
14
        return TransferResponse.from(transfers.send(request.toProto()));
15
    }
16
}

1
class WireCompatibilityTest {
2

3
    @Test
4
    void aMessageWrittenBeforeTheRenameIsReadByTheNewCode() throws Exception {
5
        // Bytes captured from the old schema, where field 2 was called amount_kurus.
6
        byte[] oldBytes = OldTransfer.newBuilder().setId(1).setAmountKurus(250_000).build().toByteArray();
7

8
        Transfer parsed = Transfer.parseFrom(oldBytes);
9

10
        assertThat(parsed.getAmountMinor()).isEqualTo(250_000);
11
    }
12
}

Kendini sına