Microservices & APIs 5. Mai 2026 11 min Lesezeit

gRPC mit Claude Code: Protobuf & Service-Kommunikation 2026

gRPC ist das Google-Protokoll für hochperformante Microservice-Kommunikation — binäres Protokoll, vollständige Typisierung über Protobuf, Streaming-Support. Claude Code kennt den kompletten gRPC-Stack: Proto-Design, Code-Generierung, Server-Implementierung und gRPC-Web für Browser.

REST vs gRPC: Wann was wählen?

Kriterium	REST/JSON	gRPC/Protobuf
Payload-Größe	~100% (JSON Text)	~20-30% (binär)
Performance	Baseline	5-10x schneller
Type Safety	OpenAPI/Swagger	100% via Protobuf (codegen)
Streaming	SSE / WebSocket (manuell)	Eingebaut (4 Patterns)
Browser-Support	Nativ	gRPC-Web Proxy nötig
Debugging	curl/Postman einfach	grpcurl / Postman gRPC
Ideal für	Public APIs, Browser	Service-zu-Service intern

Protobuf Schema-Design

ProtoService und Messages definieren

# Prompt: "Definiere gRPC-Services für ein User- und Order-Management-System"

// user.proto
syntax = "proto3";
package user.v1;

option go_package = "gen/user/v1;userv1";

// Wiederverwendbare Basis-Typen:
message Timestamp {
  int64 seconds = 1;
  int32 nanos = 2;
}

message User {
  string id = 1;
  string email = 2;
  string name = 3;
  UserRole role = 4;
  Timestamp created_at = 5;
  bool active = 6;
}

enum UserRole {
  USER_ROLE_UNSPECIFIED = 0;  // IMMER 0 als default!
  USER_ROLE_ADMIN = 1;
  USER_ROLE_MEMBER = 2;
}

// Service-Definition:
service UserService {
  // Unary RPC (Request → Response):
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
  rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);

  // Server Streaming (1 Request → N Responses):
  rpc ListUsers(ListUsersRequest) returns (stream User);

  // Bidirektionales Streaming:
  rpc WatchUsers(stream WatchRequest) returns (stream User);
}

message GetUserRequest { string user_id = 1; }
message GetUserResponse { User user = 1; }

message CreateUserRequest {
  string email = 1;
  string name = 2;
  UserRole role = 3;
}
message CreateUserResponse { User user = 1; }

message ListUsersRequest {
  int32 page_size = 1;
  string page_token = 2;
  string filter = 3;
}

Code-Generierung für TypeScript

Codegenbuf + protoc-gen-ts

# buf.yaml — moderner Proto-Toolchain (statt protoc direkt):
version: v1
modules:
  - directory: proto
deps:
  - buf.build/googleapis/googleapis

# buf.gen.yaml — Code-Generierung konfigurieren:
version: v1
plugins:
  - plugin: es
    out: gen
    opt: target=ts
  - plugin: connect-es
    out: gen
    opt: target=ts

# Code generieren:
npm install -g @bufbuild/buf
buf generate

# Ergebnis in gen/:
# user_pb.ts        — Message-Klassen (User, GetUserRequest, ...)
# user_connect.ts   — Service-Definition für Connect-RPC
# Vollständige TypeScript-Typen, kein any, kein casting!

gRPC-Server in Node.js

ServerConnectRPC — modernes gRPC für Node.js

// Prompt: "Implementiere UserService mit ConnectRPC und Express"
import { ConnectRouter } from '@connectrpc/connect';
import { expressConnectMiddleware } from '@connectrpc/connect-express';
import { UserService } from './gen/user_connect';
import { User, UserRole } from './gen/user_pb';

function routes(router: ConnectRouter) {
  router.service(UserService, {
    // Unary RPC:
    async getUser(req) {
      const user = await db.users.findById(req.userId);
      if (!user) throw new ConnectError('User not found', Code.NotFound);
      return new GetUserResponse({ user: toProto(user) });
    },

    // Server Streaming — sendet User schrittweise:
    async *listUsers(req) {
      const cursor = db.users.stream({ filter: req.filter });
      for await (const user of cursor) {
        yield toProto(user);  // Jeder yield = eine Response
      }
    },

    // Bidirektionales Streaming:
    async *watchUsers(reqStream) {
      for await (const watchReq of reqStream) {
        // Client sendet welche Users er überwachen will
        const user = await db.users.findById(watchReq.userId);
        yield toProto(user);
      }
    },
  });
}

const app = express();
app.use(expressConnectMiddleware({ routes }));
app.listen(3001);

gRPC-Web: Browser-Client

gRPC-WebConnectRPC im Browser

// Browser-Client — identische API wie Server!
// Prompt: "Rufe UserService vom Browser aus auf"
import { createClient } from '@connectrpc/connect';
import { createConnectTransport } from '@connectrpc/connect-web';
import { UserService } from './gen/user_connect';

const transport = createConnectTransport({
  baseUrl: 'http://localhost:3001',
});

const client = createClient(UserService, transport);

// Unary Call:
const { user } = await client.getUser({ userId: 'abc123' });
console.log(user?.name);

// Server Streaming im Browser:
for await (const user of client.listUsers({ filter: 'active=true' })) {
  console.log(user.name);  // Jeder User kommt einzeln an
}

// React Hook dafür:
function useUser(userId: string) {
  return useQuery({
    queryKey: ['user', userId],
    queryFn: () => client.getUser({ userId }),
  });
}

ConnectRPC vs gRPC-Web: ConnectRPC ist der moderne Nachfolger — unterstützt gRPC, gRPC-Web und Connect-Protokoll (plain HTTP). Kein separater Envoy-Proxy nötig, direkter Zugriff vom Browser. Claude Code generiert Server und Client konsistent aus denselben Proto-Definitionen.

Error Handling und Interceptors

// Prompt: "Auth-Interceptor und strukturiertes Error Handling für gRPC"
import { ConnectError, Code, Interceptor } from '@connectrpc/connect';

// Server-seitiger Auth-Interceptor:
const authInterceptor: Interceptor = (next) => async (req) => {
  const token = req.header.get('authorization')?.replace('Bearer ', '');
  if (!token) throw new ConnectError('Unauthorized', Code.Unauthenticated);

  const user = await verifyToken(token);
  req.requestHeader.set('x-user-id', user.id);

  return next(req);
};

// gRPC-Fehlercodes (analog zu HTTP-Status-Codes):
// Code.NotFound        → 404
// Code.InvalidArgument → 400
// Code.Unauthenticated → 401
// Code.PermissionDenied → 403
// Code.Internal        → 500
// Code.Unavailable     → 503

// Client: Fehler strukturiert behandeln:
try {
  await client.createUser({ email, name });
} catch (error) {
  if (error instanceof ConnectError) {
    switch (error.code) {
      case Code.AlreadyExists:
        console.error('Email bereits vergeben'); break;
      case Code.Unauthenticated:
        router.push('/login'); break;
    }
  }
}

Microservices-Modul im Kurs

Im Claude Code Mastery Kurs: vollständiges gRPC-Modul mit Protobuf-Design, Code-Generierung, ConnectRPC-Server, Browser-Client, Auth-Interceptors und Service-Mesh-Integration — inkl. Vergleich mit REST und tRPC.

14 Tage kostenlos testen →