Protobuf es el contrato, solo cambios compatibles hacia atrás, deadlines en cada llamada.
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.
-
Protobuf is the contract. Every service and message is defined in
.protofiles in one repository or module, and Go code is generated from them with buf. Hand-written structs never cross a service boundary. -
Backward-compatible changes only.
buf breakingruns in CI against the main branch. Field numbers are never reused or renumbered, removed fields are markedreserved, and a breaking change means a new package version such asv2. -
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. -
Status codes, not strings. Servers return errors built with
status.Errorand the rightcodesvalue (InvalidArgument,NotFound,Unavailable), adding details witherrdetailswhen the caller can act on them. Clients branch onstatus.Code(err). -
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. -
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.
-
Health and reflection. Every server registers the standard
grpc.health.v1health service and reportsNOT_SERVINGwhile draining on shutdown withGracefulStop. Reflection is enabled outside production only. -
Contract tests. Each method has tests against an in-process server over
bufconncovering success, invalid argument and deadline exceeded.