@nakedev/go-scaffold 0.1.2 → 0.1.4

package/templates/create/features/docs/common/responses.yaml.hbs

@@ -18,3 +18,18 @@ UnprocessableEntityError:
   content:
     application/json:
       schema: { $ref: './schemas.yaml#/Error' }
+UnauthorizedError:
+  description: missing, invalid, or expired credentials
+  content:
+    application/json:
+      schema: { $ref: './schemas.yaml#/Error' }
+ForbiddenError:
+  description: authenticated but lacking the required permission
+  content:
+    application/json:
+      schema: { $ref: './schemas.yaml#/Error' }
+TooManyRequestsError:
+  description: rate limit exceeded, retry later
+  content:
+    application/json:
+      schema: { $ref: './schemas.yaml#/Error' }

package/templates/create/features/docs/observability/metrics.yaml.hbs

@@ -0,0 +1,12 @@
+get:
+  summary: Prometheus metrics
+  description: Text-format metrics for Prometheus to scrape — not part of the JSON API surface.
+  operationId: getMetrics
+  tags: [observability]
+  security: []
+  responses:
+    "200":
+      description: ok
+      content:
+        text/plain:
+          schema: { type: string }

package/templates/create/features/docs/openapi.yaml.hbs

@@ -1,11 +1,10 @@
 # ponytail: hand-written, not generated from annotations — cheap while the
-# endpoint count is low. Ceiling: must be updated by hand whenever an
-# endpoint/DTO changes beyond what `generate module` scaffolds.
+# endpoint count is low. Generated module/method stubs keep the index wired,
+# but request/response schemas still need to be completed with the code.
 # Switch to swaggo (comment-generated) if drift becomes a recurring problem.
 # multi-file: split by domain module (health/<domain>) + common/ for shared
-# pieces — this file is just the index. `generate module <name>`
-# adds its paths/schemas here automatically; `generate method` does not
-# (endpoint-specific docs stay hand-written).
+# pieces — this file is just the index. `generate module` and `generate method`
+# add path entries automatically.
 openapi: 3.0.3
 info:
   title: {{projectName}} API
@@ -19,6 +18,10 @@ paths:
     $ref: './health/health-livez.yaml'
   /readyz:
     $ref: './health/health-readyz.yaml'
+{{#if observability}}
+  /metrics:
+    $ref: './observability/metrics.yaml'
+{{/if}}
   # go-scaffold:paths
 
 components:
@@ -31,3 +34,12 @@ components:
     NotFoundError: { $ref: './common/responses.yaml#/NotFoundError' }
     ConflictError: { $ref: './common/responses.yaml#/ConflictError' }
     UnprocessableEntityError: { $ref: './common/responses.yaml#/UnprocessableEntityError' }
+    UnauthorizedError: { $ref: './common/responses.yaml#/UnauthorizedError' }
+    ForbiddenError: { $ref: './common/responses.yaml#/ForbiddenError' }
+    TooManyRequestsError: { $ref: './common/responses.yaml#/TooManyRequestsError' }
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: "access token from POST /auth/login or /auth/register, sent as `Authorization: Bearer <token>`"

package/templates/create/features/docs/patterns.md.hbs

@@ -17,8 +17,9 @@ internal/app/<domain>/
 ├── repository.go       # the only place that touches the DB for this domain, every method takes ctx
 ├── service.go          # business logic; declares the repository interface it needs (mockable in tests)
 ├── handler.go          # HTTP: routing, bind, delegate, respond
-├── service_test.go     # unit test, fake repo, no DB
-└── handler_test.go     # integration test, real Postgres, transaction rolled back per test
+├── service_test.go     # unit test, function-backed repository stub, no DB
+├── handler_test.go     # HTTP unit test, service stub, no DB
+└── repository_test.go  # Postgres integration test against migrated schema
 ```
 
 ### Model
@@ -137,10 +138,12 @@ placeholder fields.
 - Unit and integration tests live in the same directory as the code under
   test (Go convention) — never a separate `test/` folder. `test/` is only
   for e2e black-box suites or fixtures.
-- `service_test.go` uses a fake repository — no DB required, always runs.
-- `handler_test.go` runs against a real Postgres instance inside a
-  transaction that's rolled back after each test — skips automatically if
-  the DB isn't reachable.
+- `service_test.go` uses a function-backed repository stub so each dependency
+  method has independent behavior and argument assertions.
+- `handler_test.go` uses a service stub — HTTP tests never need Postgres.
+- `repository_test.go` runs against a migrated Postgres database inside a
+  transaction that's rolled back after each test. Local runs may skip when
+  `TEST_DB_DSN` is unset; CI sets `REQUIRE_TEST_DB=true` so it must run.
 
 ## Docs Maintenance
 

package/templates/create/features/docs/techstack.md.hbs

@@ -23,6 +23,7 @@
 - Graceful shutdown, structured logging, `/livez` + `/readyz`: always enabled
 - Docker Compose (local Postgres): `{{#if docker}}enabled{{else}}disabled{{/if}}`
 - OpenAPI docs (`docs/openapi.yaml`, whole `docs/` tree served at `/docs`): `{{#if openapiDocs}}enabled{{else}}disabled{{/if}}`
+- Metrics + tracing (Prometheus `/metrics`, OpenTelemetry for Gin + GORM): `{{#if observability}}enabled{{else}}disabled{{/if}}`
 - API route prefix: `{{#if apiPrefix}}/{{apiPrefix}}{{else}}(none){{/if}}`
 - CI (`.github/workflows/ci.yml` — build, vet, gofmt check, golangci-lint, `go test` with a real Postgres service): always enabled
 
@@ -34,5 +35,7 @@
   `false` in prod and run `migrate up` as a deploy step instead
 {{#if openapiDocs}}- `docs/openapi.yaml` is hand-written, not generated — update it whenever an
   endpoint or DTO changes
+{{/if}}{{#if observability}}- `OTEL_EXPORTER_OTLP_ENDPOINT` unset (dev default) means tracing exports
+  nowhere — set it to a real OTLP/HTTP collector address to see traces
 {{/if}}- Versions above are what `go-scaffold create` pinned in `go.mod` — bump them
   by hand (`go get -u` + `go mod tidy`) as the stack evolves

package/templates/create/features/observability/middleware/metrics.go.hbs

@@ -0,0 +1,41 @@
+package middleware
+
+import (
+	"strconv"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promauto"
+)
+
+var (
+	httpRequestsTotal = promauto.NewCounterVec(
+		prometheus.CounterOpts{Name: "http_requests_total", Help: "Total HTTP requests"},
+		[]string{"method", "path", "status"},
+	)
+	httpRequestDuration = promauto.NewHistogramVec(
+		prometheus.HistogramOpts{Name: "http_request_duration_seconds", Help: "HTTP request duration in seconds"},
+		[]string{"method", "path", "status"},
+	)
+)
+
+// Metrics records request count and latency per route for GET /metrics to
+// expose to Prometheus. Uses c.FullPath() (the route template, e.g.
+// "/v1/invoices/:id") rather than the raw request path — a UUID or other
+// path param would otherwise create one label series per distinct value,
+// growing unbounded with traffic instead of staying one series per route.
+func Metrics() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		start := time.Now()
+		c.Next()
+
+		path := c.FullPath()
+		if path == "" {
+			path = "unmatched" // no route matched (404) — one shared label, not the raw unbounded path
+		}
+		status := strconv.Itoa(c.Writer.Status())
+		httpRequestsTotal.WithLabelValues(c.Request.Method, path, status).Inc()
+		httpRequestDuration.WithLabelValues(c.Request.Method, path, status).Observe(time.Since(start).Seconds())
+	}
+}

package/templates/create/features/observability/middleware/tracing.go.hbs

@@ -0,0 +1,46 @@
+package middleware
+
+import (
+	"github.com/gin-gonic/gin"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/codes"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/trace"
+)
+
+// Tracing starts one span per request, propagating an incoming W3C
+// traceparent header (if any) so a request already being traced upstream
+// stays part of the same trace, not a new root.
+//
+// Hand-rolled instead of the official otelgin contrib package: pulling it in
+// forces this project's gin dependency to a newer minimum version than the
+// one this scaffold pins, which itself drags in HTTP/3 (quic-go) — weight
+// unrelated to tracing. Gin's middleware surface (Next/Writer.Status/Errors)
+// is small enough that duplicating just the part actually used isn't worth
+// that.
+func Tracing(serviceName string) gin.HandlerFunc {
+	tracer := otel.Tracer(serviceName)
+	return func(c *gin.Context) {
+		ctx := otel.GetTextMapPropagator().Extract(c.Request.Context(), propagation.HeaderCarrier(c.Request.Header))
+
+		spanName := c.FullPath()
+		if spanName == "" {
+			spanName = c.Request.URL.Path // no route matched (404) — still traced, just without a route template
+		}
+		ctx, span := tracer.Start(ctx, spanName, trace.WithSpanKind(trace.SpanKindServer))
+		defer span.End()
+		c.Request = c.Request.WithContext(ctx)
+
+		c.Next()
+
+		span.SetAttributes(
+			attribute.String("http.method", c.Request.Method),
+			attribute.Int("http.status_code", c.Writer.Status()),
+		)
+		if len(c.Errors) > 0 {
+			span.RecordError(c.Errors.Last())
+			span.SetStatus(codes.Error, c.Errors.String())
+		}
+	}
+}

package/templates/create/features/observability/platform/telemetry/tracing.go.hbs

@@ -0,0 +1,130 @@
+// Package telemetry wires OpenTelemetry tracing — it talks to a real
+// external system (the OTLP collector), so it lives in platform/, not
+// shared/, same split rule as internal/platform/database.
+package telemetry
+
+import (
+	"context"
+	"time"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/codes"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/sdk/resource"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	"go.opentelemetry.io/otel/trace"
+	"gorm.io/gorm"
+)
+
+// Init wires a global TracerProvider that exports spans via OTLP/HTTP to
+// endpoint. An empty endpoint (the default — see OTEL_EXPORTER_OTLP_ENDPOINT
+// in .env.example) skips exporter setup entirely and returns a no-op
+// shutdown: tracing quietly does nothing instead of trying to dial a
+// collector that isn't there, same "off unless configured" shape as the
+// rest of this app's optional integrations.
+func Init(ctx context.Context, serviceName, endpoint string) (shutdown func(context.Context) error, err error) {
+	noop := func(context.Context) error { return nil }
+	if endpoint == "" {
+		return noop, nil
+	}
+
+	exporter, err := otlptracehttp.New(ctx, otlptracehttp.WithEndpoint(endpoint), otlptracehttp.WithInsecure())
+	if err != nil {
+		return noop, err
+	}
+
+	res, err := resource.New(ctx, resource.WithAttributes(attribute.String("service.name", serviceName)))
+	if err != nil {
+		return noop, err
+	}
+
+	tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter), sdktrace.WithResource(res))
+	otel.SetTracerProvider(tp)
+	otel.SetTextMapPropagator(propagation.TraceContext{})
+
+	return func(shutdownCtx context.Context) error {
+		ctx, cancel := context.WithTimeout(shutdownCtx, 5*time.Second)
+		defer cancel()
+		return tp.Shutdown(ctx)
+	}, nil
+}
+
+const tracerName = "gorm"
+
+// gormPlugin wraps every GORM operation (query, create, update, delete, row,
+// raw) in a span — a hand-rolled GORM callback plugin instead of
+// gorm.io/plugin/opentelemetry: that module's go.mod pulls in every driver
+// it supports tracing for (MySQL, ClickHouse, MongoDB) plus their own
+// transitive trees (gRPC, QUIC, ...) as indirect requires, even though this
+// project only ever uses Postgres. GORM's callback API is small enough that
+// replicating just "start a span before, end it after, record the error if
+// any" isn't worth that weight.
+type gormPlugin struct{}
+
+// NewGormPlugin returns a gorm.Plugin — wire it in via db.Use(...).
+func NewGormPlugin() gorm.Plugin { return gormPlugin{} }
+
+func (gormPlugin) Name() string { return "otel-tracing" }
+
+// Initialize registers a before/after pair on each of GORM's six operation
+// callbacks (create/query/update/delete/row/raw) — spelled out individually,
+// not looped, because db.Callback().Create() etc. return GORM's unexported
+// *processor type: a package outside gorm can chain its methods but can't
+// name the type, so it can't be held in a slice/struct field to loop over.
+func (gormPlugin) Initialize(db *gorm.DB) error {
+	before := func(op string) func(*gorm.DB) {
+		return func(tx *gorm.DB) {
+			ctx, span := otel.Tracer(tracerName).Start(tx.Statement.Context, "gorm."+op)
+			span.SetAttributes(attribute.String("db.sql.table", tx.Statement.Table))
+			tx.Statement.Context = ctx
+		}
+	}
+	after := func(tx *gorm.DB) {
+		span := trace.SpanFromContext(tx.Statement.Context)
+		if tx.Error != nil {
+			span.RecordError(tx.Error)
+			span.SetStatus(codes.Error, tx.Error.Error())
+		}
+		span.End()
+	}
+
+	if err := db.Callback().Create().Before("gorm:create").Register("otel:before_create", before("create")); err != nil {
+		return err
+	}
+	if err := db.Callback().Create().After("gorm:create").Register("otel:after_create", after); err != nil {
+		return err
+	}
+	if err := db.Callback().Query().Before("gorm:query").Register("otel:before_query", before("query")); err != nil {
+		return err
+	}
+	if err := db.Callback().Query().After("gorm:query").Register("otel:after_query", after); err != nil {
+		return err
+	}
+	if err := db.Callback().Update().Before("gorm:update").Register("otel:before_update", before("update")); err != nil {
+		return err
+	}
+	if err := db.Callback().Update().After("gorm:update").Register("otel:after_update", after); err != nil {
+		return err
+	}
+	if err := db.Callback().Delete().Before("gorm:delete").Register("otel:before_delete", before("delete")); err != nil {
+		return err
+	}
+	if err := db.Callback().Delete().After("gorm:delete").Register("otel:after_delete", after); err != nil {
+		return err
+	}
+	if err := db.Callback().Row().Before("gorm:row").Register("otel:before_row", before("row")); err != nil {
+		return err
+	}
+	if err := db.Callback().Row().After("gorm:row").Register("otel:after_row", after); err != nil {
+		return err
+	}
+	if err := db.Callback().Raw().Before("gorm:raw").Register("otel:before_raw", before("raw")); err != nil {
+		return err
+	}
+	if err := db.Callback().Raw().After("gorm:raw").Register("otel:after_raw", after); err != nil {
+		return err
+	}
+	return nil
+}

package/templates/generate/module/docs/item.yaml.hbs

@@ -29,9 +29,9 @@ put:
     "400": { $ref: '../common/responses.yaml#/ValidationError' }
     "404": { $ref: '../common/responses.yaml#/NotFoundError' }
 delete:
-  summary: Delete {{pkg}}
+  summary: Delete {{name}}
+  description: Idempotent — deleting an already-missing resource also returns 204.
   operationId: delete{{pascalName}}
   tags: [{{plural}}]
   responses:
-    "204": { description: deleted }
-    "404": { $ref: '../common/responses.yaml#/NotFoundError' }
+    "204": { description: deleted or already absent }

package/templates/generate/module/handler.go.hbs

@@ -1,26 +1,57 @@
 package {{pkg}}
 
 import (
+	"context"
 	"net/http"
 
+	"{{goModule}}/internal/app/{{modulePath}}/model"
 	"{{goModule}}/internal/shared/httpx"
+{{#if auth}}
+	"{{goModule}}/internal/shared/middleware"
+{{/if}}
 	"{{goModule}}/internal/shared/pagination"
 
 	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
 )
 
+// service is the narrow application API required by this HTTP adapter. Keeping
+// the dependency as an interface makes handler tests fast and database-free.
+type service interface {
+	Create(context.Context, createInput) (*model.{{pascalName}}, error)
+	List(context.Context, int, int) ([]model.{{pascalName}}, error)
+	Get(context.Context, uuid.UUID) (*model.{{pascalName}}, error)
+	Update(context.Context, uuid.UUID, updateInput) (*model.{{pascalName}}, error)
+	Delete(context.Context, uuid.UUID) error
+	// go-scaffold:service-interface
+}
+
 // Handler = delivery for {{pkg}} (parses HTTP, calls the service, attaches errors for the middleware to render)
 type Handler struct {
-	svc *Service
+	svc service
+{{#if auth}}
+	jwtSecret string
+{{/if}}
+{{#if permission}}
+	authz *middleware.Authz
+{{/if}}
 }
 
-func NewHandler(svc *Service) *Handler {
-	return &Handler{svc: svc}
+func NewHandler(svc service{{#if auth}}, jwtSecret string{{/if}}{{#if permission}}, authz *middleware.Authz{{/if}}) *Handler {
+	return &Handler{
+		svc: svc,
+{{#if auth}}
+		jwtSecret: jwtSecret,
+{{/if}}
+{{#if permission}}
+		authz: authz,
+{{/if}}
+	}
 }
 
 // Register wires {{pkg}}'s routes onto the router group (takes an IRouter so it can be nested under /v1)
 func (h *Handler) Register(rg gin.IRouter) {
-	g := rg.Group("/{{plural}}")
+	g := rg.Group("/{{plural}}"{{#if auth}}, middleware.RequireAuth(h.jwtSecret){{/if}}{{#if permission}}, h.authz.Require("{{permission}}"){{/if}})
 	g.POST("", h.create)
 	g.GET("", h.list)
 	g.GET("/:id", h.get)
@@ -35,7 +66,7 @@ func (h *Handler) create(c *gin.Context) {
 		c.Error(httpx.BindErr(err))
 		return
 	}
-	m, err := h.svc.Create(c.Request.Context())
+	m, err := h.svc.Create(c.Request.Context(), in)
 	if err != nil {
 		c.Error(err)
 		return
@@ -80,7 +111,7 @@ func (h *Handler) update(c *gin.Context) {
 		c.Error(httpx.BindErr(err))
 		return
 	}
-	m, err := h.svc.Update(c.Request.Context(), id)
+	m, err := h.svc.Update(c.Request.Context(), id, in)
 	if err != nil {
 		c.Error(err)
 		return

package/templates/generate/module/handler_test.go.hbs

@@ -2,103 +2,165 @@ package {{pkg}}
 
 import (
 	"bytes"
-	"encoding/json"
+	"context"
 	"net/http"
 	"net/http/httptest"
-	"os"
-	"sync"
 	"testing"
+{{#if auth}}
+	"time"
+{{/if}}
 
 	"{{goModule}}/internal/app/{{modulePath}}/model"
 	"{{goModule}}/internal/shared/middleware"
 
 	"github.com/gin-gonic/gin"
+{{#if auth}}
+	"github.com/golang-jwt/jwt/v5"
+{{/if}}
 	"github.com/google/uuid"
-	"gorm.io/driver/postgres"
-	"gorm.io/gorm"
 )
 
-// integration test backed by real Postgres (same engine as prod, no sqlite) — skips if the DB isn't reachable
-// start the DB: docker compose up -d  (override with TEST_DB_DSN)
-var (
-	testDBOnce sync.Once
-	testDB     *gorm.DB
-	testDBErr  error
-)
+// serviceStub keeps handler tests at the HTTP boundary. It exercises binding,
+// routing, middleware, status codes, and serialization without a database.
+type serviceStub struct {
+	// Embedding keeps this stub source-compatible when `generate method` adds a
+	// new operation to the handler's service interface. Base CRUD methods below
+	// still override the promoted concrete methods for focused unit tests.
+	*Service
+	createFn func(context.Context, createInput) (*model.{{pascalName}}, error)
+	listFn   func(context.Context, int, int) ([]model.{{pascalName}}, error)
+	getFn    func(context.Context, uuid.UUID) (*model.{{pascalName}}, error)
+	updateFn func(context.Context, uuid.UUID, updateInput) (*model.{{pascalName}}, error)
+	deleteFn func(context.Context, uuid.UUID) error
+}
 
-func dbForTest(t *testing.T) *gorm.DB {
-	t.Helper()
-	testDBOnce.Do(func() {
-		dsn := os.Getenv("TEST_DB_DSN")
-		if dsn == "" {
-			dsn = "postgres://postgres:postgres@localhost:5432/{{dbName}}?sslmode=disable"
-		}
-		if testDB, testDBErr = gorm.Open(postgres.Open(dsn), &gorm.Config{TranslateError: true}); testDBErr == nil {
-			// drop first — AutoMigrate can't change an existing column's type, always start from a fresh schema
-			_ = testDB.Migrator().DropTable(&model.{{pascalName}}{})
-			testDBErr = testDB.AutoMigrate(&model.{{pascalName}}{})
-		}
-	})
-	if testDBErr != nil {
-		t.Skipf("postgres not ready (docker compose up -d, or set TEST_DB_DSN): %v", testDBErr)
+func (s *serviceStub) Create(ctx context.Context, in createInput) (*model.{{pascalName}}, error) {
+	if s.createFn == nil {
+		panic("unexpected service.Create call")
+	}
+	return s.createFn(ctx, in)
+}
+
+func (s *serviceStub) List(ctx context.Context, limit, offset int) ([]model.{{pascalName}}, error) {
+	if s.listFn == nil {
+		panic("unexpected service.List call")
+	}
+	return s.listFn(ctx, limit, offset)
+}
+
+func (s *serviceStub) Get(ctx context.Context, id uuid.UUID) (*model.{{pascalName}}, error) {
+	if s.getFn == nil {
+		panic("unexpected service.Get call")
+	}
+	return s.getFn(ctx, id)
+}
+
+func (s *serviceStub) Update(ctx context.Context, id uuid.UUID, in updateInput) (*model.{{pascalName}}, error) {
+	if s.updateFn == nil {
+		panic("unexpected service.Update call")
 	}
-	return testDB
+	return s.updateFn(ctx, id, in)
 }
 
-// setup builds the full stack on a transaction that's rolled back at the end → each test is isolated, no leftover rows
-func setup(t *testing.T) *gin.Engine {
+func (s *serviceStub) Delete(ctx context.Context, id uuid.UUID) error {
+	if s.deleteFn == nil {
+		panic("unexpected service.Delete call")
+	}
+	return s.deleteFn(ctx, id)
+}
+
+// go-scaffold:service-stub-methods
+
+func setupHandlerTest(t *testing.T, svc service) *gin.Engine {
 	t.Helper()
 	gin.SetMode(gin.TestMode)
-	tx := dbForTest(t).Begin()
-	t.Cleanup(func() { tx.Rollback() })
 	r := gin.New()
-	r.Use(middleware.RequestID(), middleware.Error())
-	NewHandler(NewService(NewRepository(tx))).Register(r)
+	r.Use(middleware.RequestID(), middleware.Error(true))
+{{#if permission}}
+	// The handler unit test verifies route composition, not the role repository.
+	authz := middleware.NewAuthz(func(_ context.Context, _ string) (map[string]struct{}, error) {
+		return map[string]struct{}{"{{permission}}": {}}, nil
+	}, time.Minute)
+{{/if}}
+	NewHandler(svc{{#if auth}}, testJWTSecret{{/if}}{{#if permission}}, authz{{/if}}).Register(r)
 	return r
 }
 
-func do(r *gin.Engine, method, path, body string) *httptest.ResponseRecorder {
-	req := httptest.NewRequest(method, path, bytes.NewBufferString(body))
+{{#if auth}}
+const testJWTSecret = "test-secret"
+
+func authHeader() string {
+	claims := jwt.MapClaims{
+		"typ":  "access",
+		"sub":  uuid.NewString(),
+		"role": "staff",
+		"exp":  time.Now().Add(time.Hour).Unix(),
+		"iat":  time.Now().Unix(),
+	}
+	tok, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(testJWTSecret))
+	return "Bearer " + tok
+}
+
+{{/if}}
+func doHandlerRequest(r *gin.Engine, method, requestPath, body string) *httptest.ResponseRecorder {
+	req := httptest.NewRequest(method, requestPath, bytes.NewBufferString(body))
 	req.Header.Set("Content-Type", "application/json")
+{{#if auth}}
+	req.Header.Set("Authorization", authHeader())
+{{/if}}
 	w := httptest.NewRecorder()
 	r.ServeHTTP(w, req)
 	return w
 }
 
 func TestHandler_Create_OK(t *testing.T) {
-	r := setup(t)
-	w := do(r, http.MethodPost, "/{{plural}}", `{}`)
+	svc := &serviceStub{
+		createFn: func(context.Context, createInput) (*model.{{pascalName}}, error) {
+			return &model.{{pascalName}}{ID: uuid.New()}, nil
+		},
+	}
+	r := setupHandlerTest(t, svc)
+
+	w := doHandlerRequest(r, http.MethodPost, "/{{plural}}", `{}`)
+
 	if w.Code != http.StatusCreated {
 		t.Fatalf("want 201, got %d body=%s", w.Code, w.Body)
 	}
 }
 
 func TestHandler_Get_NotFound(t *testing.T) {
-	r := setup(t)
-	w := do(r, http.MethodGet, "/{{plural}}/"+uuid.NewString(), "")
+	svc := &serviceStub{
+		getFn: func(context.Context, uuid.UUID) (*model.{{pascalName}}, error) {
+			return nil, errNotFound()
+		},
+	}
+	r := setupHandlerTest(t, svc)
+
+	w := doHandlerRequest(r, http.MethodGet, "/{{plural}}/"+uuid.NewString(), "")
+
 	if w.Code != http.StatusNotFound {
 		t.Fatalf("want 404, got %d body=%s", w.Code, w.Body)
 	}
 }
 
-func TestHandler_Get_InvalidID(t *testing.T) {
-	r := setup(t)
-	w := do(r, http.MethodGet, "/{{plural}}/not-a-uuid", "")
+func TestHandler_Get_InvalidID_DoesNotCallService(t *testing.T) {
+	r := setupHandlerTest(t, &serviceStub{})
+
+	w := doHandlerRequest(r, http.MethodGet, "/{{plural}}/not-a-uuid", "")
+
 	if w.Code != http.StatusBadRequest {
 		t.Fatalf("want 400, got %d body=%s", w.Code, w.Body)
 	}
 }
 
 func TestHandler_Delete_OK(t *testing.T) {
-	r := setup(t)
-	created := do(r, http.MethodPost, "/{{plural}}", `{}`)
-	var body struct {
-		ID string `json:"id"`
+	svc := &serviceStub{
+		deleteFn: func(context.Context, uuid.UUID) error { return nil },
 	}
-	if err := json.Unmarshal(created.Body.Bytes(), &body); err != nil {
-		t.Fatalf("decode create response: %v", err)
-	}
-	w := do(r, http.MethodDelete, "/{{plural}}/"+body.ID, "")
+	r := setupHandlerTest(t, svc)
+
+	w := doHandlerRequest(r, http.MethodDelete, "/{{plural}}/"+uuid.NewString(), "")
+
 	if w.Code != http.StatusNoContent {
 		t.Fatalf("want 204, got %d body=%s", w.Code, w.Body)
 	}

package/templates/generate/module/migration.down.sql.hbs

@@ -1 +1 @@
-DROP TABLE IF EXISTS {{plural}};
+DROP TABLE IF EXISTS {{tableName}};

package/templates/generate/module/migration.up.sql.hbs

@@ -1,4 +1,4 @@
-CREATE TABLE {{plural}} (
+CREATE TABLE {{tableName}} (
     id         UUID PRIMARY KEY,
     created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
     updated_at TIMESTAMPTZ NOT NULL DEFAULT now()