Go API (chi + sqlc)

Project context

This is a Go HTTP service. We follow the Go community's "standard library first" instinct: chi for routing because it's idiomatic and tiny, sqlc for type-safe queries against Postgres, and as little framework as possible. Concurrency is structured; errors are values; context propagates through every call.

Stack

• Go 1.22+
• chi v5 for HTTP routing
• sqlc for SQL → Go type generation
• Postgres 15+ via pgx/v5
• slog (stdlib structured logging)
• testify or stdlib testing
• golangci-lint
• migrate for DB migrations

Folder structure

.
├── cmd/
│   └── api/
│       └── main.go         — entrypoint
├── internal/
│   ├── config/             — env config
│   ├── http/
│   │   ├── handlers/       — HTTP handlers
│   │   ├── middleware/
│   │   └── router.go
│   ├── service/            — business logic
│   ├── repo/               — data access (wraps sqlc)
│   ├── domain/             — pure types and interfaces
│   └── platform/           — DB, cache, queue clients
├── db/
│   ├── migrations/
│   ├── queries/            — .sql files for sqlc
│   └── sqlc/               — generated code (committed)
├── go.mod
├── go.sum
└── sqlc.yaml

internal/ keeps these packages from being imported by external Go code. cmd/<name> per binary.

Idioms

• Error wrapping: fmt.Errorf("doing X: %w", err) always; never fmt.Errorf("doing X: %s", err)
• errors.Is / errors.As to inspect wrapped errors; never string compare
• Sentinel errors in the package that defines the operation:

  var ErrNotFound = errors.New("not found")
  

• Context first: func (s *Service) GetPost(ctx context.Context, id string) (*Post, error)
• Accept interfaces, return structs. Define the interface in the consumer; the producer returns its concrete type.
• Zero-value usable when sensible. A struct with no init function reduces ceremony.

sqlc workflow

1. Write the CREATE TABLE migration in db/migrations/
2. Write the SQL query in db/queries/<resource>.sql with -- name: GetPost :one annotations
3. Run sqlc generate — produces type-safe Go in db/sqlc/
4. Wrap generated code in a repo type that takes context.Context and returns domain types

-- name: GetPostByID :one
SELECT id, title, body, created_at FROM posts WHERE id = $1;

-- name: ListPosts :many
SELECT id, title, body, created_at FROM posts ORDER BY created_at DESC LIMIT $1;

type PostRepo struct{ q *sqlc.Queries }

func (r *PostRepo) GetByID(ctx context.Context, id string) (*domain.Post, error) {
    row, err := r.q.GetPostByID(ctx, id)
    if err != nil {
        if errors.Is(err, pgx.ErrNoRows) { return nil, ErrNotFound }
        return nil, fmt.Errorf("get post: %w", err)
    }
    return toDomain(row), nil
}

HTTP handlers

func (h *Handler) ListPosts(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    posts, err := h.posts.List(ctx, 20)
    if err != nil {
        h.error(w, r, err)
        return
    }
    writeJSON(w, http.StatusOK, posts)
}

• Always thread r.Context() into service / repo calls
• Use one error(w, r, err) helper that maps domain errors → HTTP status
• Helpers like decodeJSON(r, &v) and writeJSON(w, status, v) keep handlers small

Concurrency

• Use errgroup.Group for "fan out, wait, propagate first error"
• Use sync.WaitGroup only when you genuinely don't want errors to short-circuit
• Always derive a child context with context.WithTimeout for outbound calls
• Never spawn a goroutine from a handler without a way to wait for or cancel it

Configuration

• Read env once in internal/config, return a typed struct
• Validate at startup; fail fast on missing or malformed values
• Never os.Getenv inside business logic

Logging

• slog with a structured handler; one logger at the root, child loggers per request
• Include request ID via middleware; pass through context
• Don't log secrets, tokens, or PII

Migrations

• migrate create -ext sql -dir db/migrations -seq <name>
• Always include up.sql and down.sql
• Never modify a committed migration; create a new one
• Run in CI/CD: migrate -path db/migrations -database $DATABASE_URL up

Patterns to avoid

• Naked returns in long functions
• panic for normal errors — return them
• init() for non-trivial setup — call from main
• Global state — pass dependencies explicitly
• Empty interface (any / interface{}) as a parameter type — be specific
• Long functions — extract once they grow past ~50 lines, but don't over-extract trivial logic

Testing

• Stdlib testing; testify only for assertions when stdlib is verbose
• Table-driven tests for any function with multiple inputs:

  for _, tc := range []struct{ name string; in, want X }{ ... } {
      t.Run(tc.name, func(t *testing.T) { ... })
  }
  

• Use httptest.NewRecorder for handler tests
• For DB tests, use a real Postgres in Docker; truncate between tests

Tooling

• go run ./cmd/api
• go build ./...
• go test ./... -race
• golangci-lint run
• sqlc generate after editing queries
• migrate up / migrate down

AI behavioral rules

• Always wrap errors with %w; never %s
• Always thread context.Context as the first parameter
• Use sentinel errors + errors.Is for typed checks; never string-compare
• After editing a .sql query file, run sqlc generate — don't hand-edit generated code
• Never modify a committed migration; create a new one
• Don't introduce a framework when the standard library suffices
• Run go test ./... -race and golangci-lint run before declaring a task done