service-layer

To structure a Golang service layer with clean boundaries, define a Service interface in contract.go using domain-shaped inputs and outputs, then implement it in service.go with a Deps struct for injecting database handles and deterministic helpers like time and ID generators.

The best way to handle domain errors in a Go service layer is to route storage and driver failures into shared sentinel errors using a dedicated error package, and return typed errors that unwrap to those sentinels so handlers can map them consistently to client-facing responses.

To make a Golang service layer testable, use dependency injection by passing a Deps struct to the service constructor, injecting database handles and deterministic helpers like time.Now and ID generators so unit tests can run at the service boundary without external dependencies.

Observability like logging, tracing, and metrics should live at the handler edge rather than inside the service layer, applied uniformly via interceptors so middleware wrappers are not sprinkled through the domain business logic.

Yes, a Go service layer needs a separate contract file to declare the Service interface with domain-shaped method signatures, keeping the domain operations callable by handlers while remaining independent from proto and DB row types.

Typed errors need to unwrap to sentinel errors in a Go service layer so that handlers can correctly map storage and driver failures to client-facing responses, keeping error handling consistent across the domain boundary without leaking internal error types.