Guide complet pour débuter avec gRPC-web : créez des applications web modernes

Qu'est-ce que gRPC-web et quels sont ses avantages ?

gRPC-web est une solution client web pour le framework gRPC. Elle permet aux applications tournant dans un navigateur de communiquer directement avec un serveur gRPC, sans passer par une couche de conversion complexe. Elle utilise le protocole HTTP/1.1 ou HTTP/2, et peut fonctionner sans proxy dédié (bien que certaines fonctionnalités avancées puissent nécessiter Envoy).

Protocole binaire performant : les données sont sérialisées avec Protocol Buffers, plus compact et rapide à analyser que le JSON.
Interfaces fortement typées : les services sont définis dans des fichiers .proto, offrant une vérification de type à la compilation.
Génération automatique de code : les clients JavaScript ou TypeScript sont générés automatiquement, réduisant le travail manuel.
Support du streaming bidirectionnel : communication temps réel entre client et serveur.
Compatibilité avec l'écosystème gRPC existant : s'intègre facilement avec les services gRPC déjà en place.

Installation de l'environnement de développement

Assurez-vous d'avoir Node.js et npm. Installez l'outil gRPC-web globalement :

npm install -g grpc-web

Clonez le dépôt officiel pour avoir les exemples :

git clone https://gitcode.com/gh_mirrors/gr/grpc-web && cd grpc-web
npm install

Concepts clés : définition des services et generation de code

Les services sont décrits dans des fichiers .proto avec la syntaxe protobuf. Exemple minimal :

syntax = "proto3";

service EchoService {
  rpc Echo(EchoRequest) returns (EchoResponse);
}

message EchoRequest {
  string message = 1;
}

message EchoResponse {
  string message = 1;
}

Pour générer le code client JavaScript :

protoc -I=$DIR echo.proto \
  --js_out=import_style=commonjs:$OUT_DIR \
  --grpc-web_out=import_style=commonjs,mode=grpcwebtext:$OUT_DIR

Construire une application web complète : l'exemple Echo

1. Définir le service

Créez un fichier echo.proto avec les services Echo (unaire) et ServerStreamingEcho (streaming serveur).

2. Générer le code client

Utilisez la commande protoc avec les plugins.

3. Client web HTML/JavaScript

<html>
<head>
  <title>Exemple Echo avec gRPC-web</title>
</head>
<body>
  <input type="text" id="msg" placeholder="Votre message">
  <button onclick="envoyerMessage()">Envoyer</button>
  <div id="resultat"></div>

  <script src="client/echo_grpc_web_pb.js"></script>
  <script src="client/echo_pb.js"></script>
  <script>
    const clientEcho = new echo.EchoServiceClient('http://localhost:8080');
    
    function envoyerMessage() {
      const texte = document.getElementById('msg').value;
      const requete = new echo.EchoRequest();
      requete.setMessage(texte);
      
      clientEcho.echo(requete, {}, (erreur, reponse) => {
        const zoneResultat = document.getElementById('resultat');
        if (erreur) {
          zoneResultat.innerText = `Erreur : ${erreur.message}`;
        } else {
          zoneResultat.innerText = `Réponse : ${reponse.getMessage()}`;
        }
      });
    }
  </script>
</body>
</html>

4. Serveur Node.js et proxy Envoy

L'exemple net/grpc/gateway/examples/echo/node-server/server.js fournit un serveur gRPC. Lancez-le avec node server.js. Configurez Envoy avec le fichier envoy.yaml fourni et démarrez-le :

envoy -c envoy.yaml

5. Tester

Ouvrez la page HTML dans votre navigateur, saisissez un message et cliquez sur le bouton. La réponse du serveur s'affiche.

Fonctionnalités avancées

Streaming serveur

const flux = clientEcho.serverStreamingEcho(requete, {});
flux.on('data', (reponse) => console.log('Message reçu :', reponse.getMessage()));
flux.on('end', () => console.log('Flux terminé'));
flux.on('error', (err) => console.error('Erreur de flux :', err));

Intercepteurs

Disponibles dans javascript/net/grpc/web/interceptor.js pour la gestion des requêtes/réponses.

Support TypeScript

La base de code migre vers TypeScript (voir doc/roadmap.md).

Déploiement et optimisation

Utilisez les proxies in-process pour éviter Envoy en production.
Configurez les en-têtes CORS.
Activez HTTP/2 pour de meilleures performances.
Préférez le mode binaire grpcweb au mode texte.
Optimisez la structure des messages protobuf.
Implémentez un cache client pour les données fréquentes.

Problèmes fréquents

CORS

Assurez-vous que le serveur répond avec les en-têtes CORS appropriés.

Compatibilité navigateur

Tous les navigateurs modernes sont supportés. Voir doc/browser-features.md pour les polyfills.

Débogage

Activez le mode verbeux :

const options = { 'grpc.verbose': true };

Utilisez la console développeur pour isnpecter les appels.

Ressources pour continuer

Documentation officielle : doc/
Exemples : net/grpc/gateway/examples/
Tests : packages/grpc-web/test/

Les futures versions apporteront le streaming bidirectionnel et l'intégration WebTransport. Consultez roadmap.md pour les nouveautés.

Étiquettes: grpc-web Protocol Buffers JavaScript TypeScript Envoy

Publié le 17 juin à 18h52

L'Atelier Monstre