Glossary
Glossary
Section titled “Glossary”API DSL
Section titled “API DSL”go-zero’s domain-specific language for defining HTTP services. .api files describe routes, request/response types, and middleware groups. goctl api go compiles them into a complete Go project.
Proto / RPC DSL
Section titled “Proto / RPC DSL”Protobuf .proto files that define gRPC service contracts. goctl rpc protoc compiles them into both the gRPC stubs and the go-zero server/client scaffolding.
go-zero’s command-line code generation tool. It reads .api or .proto files and emits a complete, runnable project skeleton — handlers, logic stubs, config structs, routing, and Dockerfile.
ServiceContext
Section titled “ServiceContext”The single dependency-injection container for a go-zero service. Created once at startup in internal/svc/servicecontext.go, it holds database pools, Redis clients, downstream RPC clients, and any other shared resource. Every logic method receives a pointer to it.
Logic Layer
Section titled “Logic Layer”The business layer — one Go file per use case (e.g. CreateOrderLogic). Logic methods receive a typed request struct, call the model/cache/RPC layers, and return a typed response. This is the only layer goctl never regenerates.
Handler
Section titled “Handler”The HTTP adapter layer generated by goctl. A handler decodes the incoming request, calls exactly one logic method, and encodes the response. It should contain no business logic.
Middleware
Section titled “Middleware”A function that wraps an HTTP handler to add cross-cutting behaviour: JWT authentication, rate limiting, request logging, panic recovery, or trace injection. Registered via server.Use() globally or per route group.
Interceptor
Section titled “Interceptor”The gRPC equivalent of HTTP middleware. Unary interceptors wrap individual RPC calls; stream interceptors wrap streaming RPCs. go-zero registers circuit-breaking, tracing, and Prometheus interceptors by default.
go-zero’s gRPC client/server package. zrpc.Server wraps a grpc.Server and adds health checks, Prometheus metrics, and OpenTelemetry tracing. zrpc.Client adds service discovery, P2C load balancing, and the circuit breaker.
P2C (Pick of Two Choices)
Section titled “P2C (Pick of Two Choices)”go-zero’s default client-side load-balancing algorithm. On each request it picks two random candidates from the service registry and forwards to whichever has the lower weighted load (in-flight × latency). Avoids the slow-node hot-spot problem of round-robin.
Circuit Breaker
Section titled “Circuit Breaker”A resilience pattern: tracks the error ratio over a sliding window; when the ratio exceeds a threshold the breaker opens and subsequent requests fail immediately (fast-fail) without hitting the downstream. After a cooldown a probe request is allowed through — if it succeeds the breaker closes again.
Rate Limiter
Section titled “Rate Limiter”Controls how many requests per second a service accepts. go-zero uses a token-bucket algorithm; burst traffic consumes tokens and is rejected (429) once the bucket is empty.
Load Shedding
Section titled “Load Shedding”Adaptive overload protection. When CPU usage or queue depth exceeds a configured ceiling, go-zero drops the least-prioritised requests to keep the service responsive for the rest. Different from rate limiting — it reacts to actual system load rather than a fixed request-per-second cap.
Telemetry / Observability
Section titled “Telemetry / Observability”The Telemetry config block wires up OpenTelemetry tracing for a service. go-zero automatically creates spans for every HTTP handler and RPC method and propagates trace context across service boundaries.
go-zero’s structured logging package. Provides level-based methods (Info, Error, Slow), zero-allocation JSON output, context-aware field injection (trace ID, span ID), and log sampling for high-throughput paths.
goctl Template
Section titled “goctl Template”Customisable code templates stored in ~/.goctl/. Run goctl template init to export the defaults, then edit them to change the generated code style across all future goctl invocations.
Etcd Key
Section titled “Etcd Key”The service registry identifier used for discovery. An RPC server advertises its address under this key; RPC clients watch it to get the live instance list. Convention: <service-name>.rpc (e.g. user.rpc).
Model Layer
Section titled “Model Layer”The data-access layer generated by goctl model. Contains CRUD methods with optional two-level caching (in-process LRU + Redis). The generated code is in *_gen.go files; hand-written queries go in a companion file that goctl never overwrites.