Go for Backend Devs: Concurrency, Context, and Clean APIs

What you’ll learn

• Concurrency: goroutines, channels, worker pools, and backpressure (so work doesn’t explode)
• Context: cancellation, deadlines, and request-scoped work (so slow clients don’t waste resources)
• Clean APIs: handlers, error mapping, and boundaries between layers (so the codebase stays readable)

A helpful rule of thumb

Every goroutine should have a clear lifetime and a clear exit signal: return naturally, receive a done signal, or observe ctx.Done().

Minimal service skeleton (timeouts + context + clean handler)

This example shows an endpoint that creates a note. The handler derives a short timeout, validates input, calls the store, and returns a stable JSON shape.

package main

import (
	"context"
	"encoding/json"
	"errors"
	"log"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"
)

type Note struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Content string `json:"content,omitempty"`
}

type Store interface {
	CreateNote(ctx context.Context, n Note) (Note, error)
}

type InMemoryStore struct{}

func (s *InMemoryStore) CreateNote(ctx context.Context, n Note) (Note, error) {
	// Pretend we do I/O. Always respect ctx.Done() in real stores.
	select {
	case <-time.After(30 * time.Millisecond):
		n.ID = time.Now().UTC().Format("20060102150405.000000000")
		return n, nil
	case <-ctx.Done():
		return Note{}, ctx.Err()
	}
}

type createNoteReq struct {
	Title   string `json:"title"`
	Content string `json:"content"`
}

func main() {
	logger := log.New(os.Stdout, "notes-api ", log.LstdFlags|log.Lmicroseconds)

	store := &InMemoryStore{}
	mux := http.NewServeMux()

	mux.HandleFunc("POST /notes", func(w http.ResponseWriter, r *http.Request) {
		// Always start from the request context.
		ctx := r.Context()

		// Put an upper bound on downstream work for this handler.
		ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
		defer cancel()

		// Limit request size (prevents accidental large payloads).
		r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // 1 MiB

		var req createNoteReq
		dec := json.NewDecoder(r.Body)
		dec.DisallowUnknownFields()
		if err := dec.Decode(&req); err != nil {
			writeError(w, http.StatusBadRequest, "bad_request", "Invalid JSON body", err)
			return
		}
		if req.Title == "" {
			writeError(w, http.StatusBadRequest, "validation_error", "title is required", nil)
			return
		}

		created, err := store.CreateNote(ctx, Note{Title: req.Title, Content: req.Content})
		if err != nil {
			if errors.Is(err, context.DeadlineExceeded) {
				writeError(w, http.StatusGatewayTimeout, "timeout", "Request timed out", err)
				return
			}
			if errors.Is(err, context.Canceled) {
				// Client disconnected or server shutting down.
				writeError(w, 499, "canceled", "Request canceled", err) // 499 (Nginx-style) is sometimes used internally.
				return
			}
			writeError(w, http.StatusInternalServerError, "internal", "Internal error", err)
			return
		}

		writeJSON(w, http.StatusCreated, created)
	})

	srv := &http.Server{
		Addr:              ":8080",
		Handler:           mux,
		ReadHeaderTimeout: 5 * time.Second,
		ReadTimeout:       10 * time.Second,
		WriteTimeout:      10 * time.Second,
		IdleTimeout:       60 * time.Second,
	}

	// Graceful shutdown.
	stop := make(chan os.Signal, 1)
	signal.Notify(stop, os.Interrupt, syscall.SIGTERM)

	go func() {
		logger.Printf("listening on %s", srv.Addr)
		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
			logger.Printf("server error: %v", err)
		}
	}()

	<-stop
	logger.Println("shutting down...")

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()
	_ = srv.Shutdown(ctx)
	logger.Println("bye")
}

func writeJSON(w http.ResponseWriter, status int, v any) {
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	w.WriteHeader(status)
	_ = json.NewEncoder(w).Encode(v)
}

type apiError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

func writeError(w http.ResponseWriter, status int, code, message string, err error) {
	// Avoid leaking internal errors to clients. Log them instead.
	if err != nil {
		log.Printf("error code=%s status=%d err=%v", code, status, err)
	}
	writeJSON(w, status, apiError{Code: code, Message: message})
}

Worker pool pattern with cancellation

Use this for batch tasks (sync jobs, fan-out work, background processing) where you want a fixed upper bound on concurrency. Notice the repeated select on ctx.Done() to avoid leaks.

package workerpool

import (
	"context"
	"sync"
)

type Job func(ctx context.Context) error

// Run executes jobs with a fixed number of workers.
// It stops early when ctx is canceled or when any job returns an error.
func Run(ctx context.Context, workers int, jobs []Job) error {
	if workers < 1 {
		workers = 1
	}

	jobCh := make(chan Job)
	errCh := make(chan error, 1)

	var wg sync.WaitGroup
	worker := func() {
		defer wg.Done()
		for {
			select {
			case <-ctx.Done():
				return
			case job, ok := <-jobCh:
				if !ok {
					return
				}
				if err := job(ctx); err != nil {
					// Send the first error and let other workers drain/exit via ctx cancellation upstream.
					select {
					case errCh <- err:
					default:
					}
					return
				}
			}
		}
	}

	wg.Add(workers)
	for i := 0; i < workers; i++ {
		go worker()
	}

	// Producer
	go func() {
		defer close(jobCh)
		for _, job := range jobs {
			select {
			case <-ctx.Done():
				return
			case jobCh <- job:
			}
		}
	}()

	wg.Wait()

	select {
	case err := <-errCh:
		return err
	default:
		return ctx.Err() // nil if ctx wasn’t canceled
	}
}

Domain errors + HTTP mapping (stable codes)

Use sentinel errors (or typed errors) in domain logic, then map them to HTTP at the boundary. This keeps your core code testable and your HTTP surface consistent.

package apperr

import (
	"errors"
	"net/http"
)

var (
	ErrNotFound   = errors.New("not_found")
	ErrConflict   = errors.New("conflict")
	ErrForbidden  = errors.New("forbidden")
	ErrValidation = errors.New("validation")
)

// HTTP maps domain errors to an HTTP status and a stable error code.
// You can expand this as your API grows.
func HTTP(err error) (status int, code string) {
	switch {
	case err == nil:
		return http.StatusOK, ""
	case errors.Is(err, ErrValidation):
		return http.StatusBadRequest, "validation_error"
	case errors.Is(err, ErrForbidden):
		return http.StatusForbidden, "forbidden"
	case errors.Is(err, ErrNotFound):
		return http.StatusNotFound, "not_found"
	case errors.Is(err, ErrConflict):
		return http.StatusConflict, "conflict"
	default:
		return http.StatusInternalServerError, "internal"
	}
}

Conventions that pay off immediately

• Handlers: small, composable, no business logic hidden in them
• Request/response DTOs: explicit structs with validation rules
• Error codes: stable strings; don’t couple clients to internal messages
• Context: always pass; never store globally; never ignore cancellation
• Observability: log errors at the edge; keep logs structured and consistent