backend-patterns

Backend Patterns

Structural patterns for server-side code, independent of any one framework. For the shape of the request/response contract itself, see api-design; for query- and index-level database patterns, see postgres-patterns; for structured logs/metrics/traces, see observability-and-instrumentation.

Layering: handler → service → repository

Keep three concerns separate so each can be tested and changed independently:

// repository: only knows SQL, returns domain types or a wrapped error
type ReservationRepo struct{ db *sql.DB }

func (r *ReservationRepo) ByID(ctx context.Context, hotelID int64, id string) (*Reservation, error) {
    const q = `SELECT id, hotel_id, status FROM reservations WHERE hotel_id = $1 AND id = $2`
    var res Reservation
    if err := r.db.QueryRowContext(ctx, q, hotelID, id).Scan(&res.ID, &res.HotelID, &res.Status); err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, fmt.Errorf("reservation %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("query reservation %s: %w", id, err)
    }
    return &res, nil
}

// service: business logic, orchestrates repositories, knows nothing about HTTP
type ReservationService struct{ repo *ReservationRepo }

func (s *ReservationService) Cancel(ctx context.Context, hotelID int64, id string) error {
    res, err := s.repo.ByID(ctx, hotelID, id)
    if err != nil {
        return err
    }
    if res.Status == StatusCheckedOut {
        return fmt.Errorf("cancel reservation %s: %w", id, ErrAlreadyCheckedOut)
    }
    return s.repo.SetStatus(ctx, hotelID, id, StatusCancelled)
}

// handler: only knows HTTP — decode, call service, map errors to status codes
func (h *Handler) CancelReservation(w http.ResponseWriter, r *http.Request) {
    hotelID, id := parseParams(r)
    if err := h.svc.Cancel(r.Context(), hotelID, id); err != nil {
        writeError(w, err) // maps ErrNotFound -> 404, ErrAlreadyCheckedOut -> 409, else 500
        return
    }
    w.WriteHeader(http.StatusNoContent)
}