← Alle Vorlagen

Protobuf ist der Vertrag, nur abwärtskompatible Änderungen, Deadlines bei jedem Aufruf.

Constitution — Go gRPC microservices

Version 1.0.0 · Ratified 2026-11-10

These principles hold for every spec, plan and task of the project. A spec may add rules; it never weakens these.

  1. Protobuf is the contract. Every service and message is defined in .proto files in one repository or module, and Go code is generated from them with buf. Hand-written structs never cross a service boundary.

  2. Backward-compatible changes only. buf breaking runs in CI against the main branch. Field numbers are never reused or renumbered, removed fields are marked reserved, and a breaking change means a new package version such as v2.

  3. Deadlines on every call. Every outgoing call carries a context with a deadline, and servers pass the incoming context to downstream calls so the deadline propagates. A call made with context.Background() fails the review.

  4. Status codes, not strings. Servers return errors built with status.Error and the right codes value (InvalidArgument, NotFound, Unavailable), adding details with errdetails when the caller can act on them. Clients branch on status.Code(err).

  5. Retries only where safe. Client retry policies are declared in the service config and apply only to idempotent methods and to Unavailable. Non-idempotent methods carry a request id that the server deduplicates.

  6. Interceptors for cross-cutting work. Authentication, logging, metrics and tracing (OpenTelemetry) are unary and stream interceptors registered once per server and client. Handlers contain no logging or auth boilerplate.

  7. Health and reflection. Every server registers the standard grpc.health.v1 health service and reports NOT_SERVING while draining on shutdown with GracefulStop. Reflection is enabled outside production only.

  8. Contract tests. Each method has tests against an in-process server over bufconn covering success, invalid argument and deadline exceeded.