grpc-service-designer

Concepteur de Services gRPC

Workflow en étapes

1. Qualifier la communication — choisir le bon pattern (voir tableau ci-dessous) avant d'ouvrir un éditeur.
2. Concevoir le contrat .proto — package versionné, messages dédiés par RPC, enums avec valeur 0 UNSPECIFIED.
3. Générer le code — protoc ou plugin SDK ; vérifier que le code généré ne doit jamais être édité manuellement.
4. Implémenter serveur puis client — gestion d'erreurs gRPC status codes, deadlines, idempotence.
5. Sécuriser et observer — TLS mutuel, intercepteurs logging/métriques, health checks.
6. Valider la compatibilité — tester la rétrocompatibilité binaire avant tout déploiement.

Critère de choix du pattern de communication

Règle heuristique : si la réponse tient dans une seule trame TCP et que le serveur répond immédiatement → unaire. Dès qu'une des parties envoie plusieurs messages → streaming.

Conception du contrat Protobuf

Structure de référence

syntax = "proto3";

package myapp.payments.v1;

option csharp_namespace = "MyApp.Payments.V1";
option go_package = "github.com/myapp/payments/v1;paymentsv1";

import "google/protobuf/timestamp.proto";

service PaymentService {
  // Unaire
  rpc CreatePayment(CreatePaymentRequest) returns (CreatePaymentResponse);
  // Server streaming
  rpc WatchStatus(WatchStatusRequest) returns (stream PaymentStatusEvent);
  // Client streaming
  rpc BatchImport(stream ImportTransactionRequest) returns (BatchImportResponse);
  // Bidirectionnel
  rpc SyncLedger(stream LedgerEntry) returns (stream LedgerAck);
}

message CreatePaymentRequest {
  string idempotency_key = 1;  // UUID v4, obligatoire
  int64  amount_cents    = 2;
  string currency        = 3;  // ISO 4217
  string recipient_id    = 4;
  map<string, string> metadata = 5;
}

message CreatePaymentResponse {
  string payment_id = 1;
  PaymentStatus status = 2;
  google.protobuf.Timestamp created_at = 3;
}

enum PaymentStatus {
  PAYMENT_STATUS_UNSPECIFIED = 0;  // obligatoire
  PAYMENT_STATUS_PENDING     = 1;
  PAYMENT_STATUS_PROCESSING  = 2;
  PAYMENT_STATUS_COMPLETED   = 3;
  PAYMENT_STATUS_FAILED      = 4;
}

// Champs supprimés → reserved, jamais effacés
// reserved 6, 7;
// reserved "old_field_name";