The Complete Gin Framework Guide

• Martini-like API: clean, expressive syntax inspired by the earlier Martini framework but 40x faster thanks to zero-allocation routing.
• Middleware chain: stackable handlers via r.Use(...) with c.Next() and c.Abort() flow control.
• Built-in binding: c.ShouldBindJSON, ShouldBindQuery, ShouldBindUri, auto-dispatching by Content-Type via ShouldBind.
• Validation: integrated go-playground/validator via struct tags (binding:"required,email").
• Rendering: JSON, XML, YAML, ProtoBuf, HTML templates, SSE, static files — all via one-line c.JSON(), c.HTML(), etc.
• Route grouping: nest routes under common prefixes and middleware with r.Group("/api/v1").
• Crash-free: bundled Recovery() middleware catches panics and returns 500 instead of killing the server.

• vs raw net/http: Gin adds routing with path params (/users/:id), middleware chains, binding, and a richer context. Raw net/http is more verbose but has zero dependencies.
• vs Echo: Echo has a nearly identical API and performance, slightly more opinionated error handling (handlers return error), and built-in OpenAPI tooling. Gin has a larger community and more middleware plugins.
• vs Chi: Chi is closer to idiomatic net/http — handlers are http.HandlerFunc so any standard library middleware works unchanged. Gin uses its own gin.HandlerFunc signature and *gin.Context, so you trade compatibility for convenience.
• vs Fiber: Fiber mimics Express and runs on fasthttp (not net/http), trading standards compliance for raw speed. Gin works with the standard HTTP ecosystem (http.Handler, httptest, etc.).
• vs Beego: Beego is a full-stack MVC framework with ORM, cache, config, and scaffolding included. Gin is minimal — you pick GORM, Viper, Zap yourself.
• vs Express (Node): Similar middleware philosophy but Gin is compiled, statically typed, and handles concurrency via goroutines instead of an event loop.
• vs FastAPI (Python): FastAPI auto-generates OpenAPI/Swagger from type hints; Gin requires swaggo annotations. FastAPI is async Python; Gin is compiled Go with native concurrency.
• vs Spring Boot (Java): Spring Boot is a heavy DI-driven enterprise framework with annotations, AOP, and auto-config. Gin is 100x lighter — no DI container, no reflection magic, ~10ms startup vs multi-second Spring warmup.

• Don't forget c.Abort(): calling c.JSON(401, ...) in middleware without Abort() still runs downstream handlers — which may write a second response and panic.
• Context is not context.Context: *gin.Context implements the standard context.Context interface but they're distinct — pass c.Request.Context() (or c itself carefully) to DB/HTTP calls.
• Binding consumes the body: ShouldBindJSON reads c.Request.Body once. Call it twice and the second fails. Use ShouldBindBodyWith if you need multiple reads.

• gin.Default() — returns an *Engine pre-loaded with Logger and Recovery middleware. Best for local development.
• gin.New() — returns a bare engine with no middleware. Use in production when you want to plug in your own structured logger (Zap, Zerolog) and custom panic recovery.

• vs net/http setup: raw net/http requires manually constructing http.ServeMux, registering handlers with HandleFunc, and starting with http.ListenAndServe. Gin wraps all that into r := gin.Default(); r.Run().
• vs Echo: nearly identical — e := echo.New(); e.Start(":8080"). Both require manual middleware registration if you skip Default().
• vs Express: const app = express() is equivalent to r := gin.New(); Express needs body-parser and cors installed separately, while Gin bundles binding and CORS-ready middleware hooks.
• vs Spring Boot: Spring uses annotations like @SpringBootApplication plus a Maven/Gradle build. Gin has no classpath scanning — handlers are registered explicitly at startup.

• Port conflicts: r.Run() defaults to :8080. If another process holds it, you get bind: address already in use — kill with lsof -i :8080.
• Trusted proxies warning: Gin v1.9+ prints a warning if you don't call r.SetTrustedProxies(nil) — important for correct c.ClientIP() behind load balancers.
• Go version: Gin requires Go 1.20+. Older versions may compile but lose generics-based helpers.

• All HTTP verbs: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, plus Any() to match all methods.
• Path parameters: /users/:id captures a named segment accessible via c.Param("id").
• Wildcard / catch-all: /files/*filepath matches everything after the slash, useful for serving static directories.
• Route groups: r.Group("/api/v1") lets you share middleware and path prefixes across related endpoints.
• Method-not-allowed handling: enable with r.HandleMethodNotAllowed = true to auto-return 405 instead of 404 when the path exists but the verb doesn't.

• vs raw net/http: http.ServeMux only supports exact prefix matches — no :id parameters, no method routing. You'd write a big switch r.Method inside every handler.
• vs Echo: Echo uses the same radix tree approach and has nearly identical performance. API is very similar — e.GET("/users/:id", h) vs r.GET("/users/:id", h).
• vs Chi: Chi uses a trie too but embraces the standard http.Handler interface, so Chi middleware is compatible with any Go HTTP code. Gin middleware only works inside Gin.
• vs Express: Express uses a linear regex-based matcher — O(n) per request. Gin is literally 40x faster on synthetic benchmarks.
• vs FastAPI/Spring Boot: those frameworks use decorators/annotations; Gin uses plain function calls, which means routes are visible at runtime and easier to generate programmatically.

• Conflicting routes: you cannot register both /users/:id and /users/new on the same engine — Gin will panic at startup because the radix tree cannot disambiguate. Use /users/new and /users/id/:id instead, or put /new in a different route group.
• Trailing slash redirect: by default Gin auto-redirects /users/ to /users with a 301. Disable via r.RedirectTrailingSlash = false if building a strict REST API.
• Case sensitivity: routes are case-sensitive — /Users and /users are different. Enable r.RedirectFixedPath = true to redirect case-mismatched paths.

• c.Param("id") — reads a single named path param; returns empty string if missing.
• c.Query("q") — reads a single query value; returns empty if missing.
• c.DefaultQuery("page", "1") — returns a fallback when the key is absent.
• c.QueryArray("tags") — reads repeated values from ?tags=a&tags=b.
• c.QueryMap("filter") — reads nested keys from ?filter[name]=go.
• c.GetQuery("q") — returns (value, exists bool) so you can distinguish "missing" from "empty string".

• vs raw net/http: with stdlib you do r.URL.Query().Get("q") which is verbose and returns typed string; Gin wraps this in one-liners plus adds path param support (stdlib has none).
• vs Echo: essentially identical — c.QueryParam("q") in Echo vs c.Query("q") in Gin.
• vs Express: Express exposes req.params.id and req.query.page as object properties; Gin uses method calls which forces you to think about the "missing" case.
• vs FastAPI: FastAPI uses function signature type hints (page: int = 1) to auto-parse and validate. Gin requires manual strconv.Atoi or a struct binding via c.ShouldBindQuery().

• Everything is a string: c.Query("page") returns "" not 0. You must strconv.Atoi or use ShouldBindQuery with struct tags to get typed values.
• URL-encoded slashes: :id does not match a slash, so /users/foo/bar won't match /users/:id. Use *wildcard if you need to capture slashes.
• Case-sensitive query keys: c.Query("Page") and c.Query("page") are different.
• Query arrays: some clients send ?tags=a,b (comma-separated) — Gin treats this as a single string "a,b", not two values. Only ?tags=a&tags=b populates QueryArray.

• ShouldBindJSON — parses application/json request bodies.
• ShouldBindXML — parses application/xml.
• ShouldBindQuery — parses URL query string into struct fields (via form:"page" tag).
• ShouldBindUri — parses path parameters via uri:"id" tag.
• ShouldBindHeader — parses HTTP headers into a struct.
• ShouldBind — auto-detects based on Content-Type header (json → JSON, form → form, etc.).
• ShouldBindWith — explicit binder choice (e.g., binding.MsgPack).

• vs raw net/http: stdlib requires json.NewDecoder(r.Body).Decode(&v) plus manual validation — no unified path/query/body binding.
• vs Echo: Echo's c.Bind(&req) is similar but auto-detects less reliably; Gin's explicit methods are clearer.
• vs FastAPI: FastAPI uses Pydantic models via function signatures — even more automatic, with auto-generated OpenAPI docs. Gin requires explicit Swagger annotations.
• vs Spring Boot: Spring uses @RequestBody + Jackson. Both are reflection-based, but Gin's validator syntax is more concise.

• Pointer vs value: you must pass &req, not req. Passing by value silently "works" but fills a copy that's discarded.
• Body can only be read once: c.Request.Body is an io.ReadCloser. If middleware already read it, binding fails. Use c.ShouldBindBodyWith to cache the body for re-reads.
• Zero values vs missing: an absent JSON field and "field": 0 both produce 0. Use pointers (*int) to distinguish.
• Unknown fields: by default Gin ignores unknown JSON keys; enable DisallowUnknownFields on the decoder to reject them (you'll need a custom binder).

• Presence: required, required_with, required_without, omitempty.
• Strings: min=3, max=100, len=10, alpha, alphanum, email, url, uuid4, contains=foo.
• Numbers: gt=0, gte=18, lt=100, lte=65, eq, ne.
• Collections: min=1,dive,required (applies required to each slice element).
• Comparisons: eqfield=Password, nefield=Old (cross-field validation).
• Enums: oneof=admin user guest.

• vs manual if checks: declarative, co-located with the type definition, and impossible to forget when you add a new endpoint.
• vs Echo: Echo also supports go-playground/validator but requires explicit e.Validator = &MyValidator{} setup. Gin wires it up automatically.
• vs FastAPI/Pydantic: Pydantic uses Python type hints + class-based models, which auto-generates OpenAPI schemas. Gin's validator is string-tag-based and doesn't produce schemas without a separate tool (swaggo).
• vs Spring Boot: Spring uses JSR-303 (@NotNull, @Size, @Email) — conceptually identical, syntactically more verbose.

• Zero values trip required: required means "not the zero value", so int field with value 0 fails required. Use *int if 0 is legal.
• Error messages are developer-facing: the default err.Error() string is ugly ("Key: 'User.Email' Error:Field validation for 'Email' failed on the 'email' tag"). Convert to user-friendly messages by iterating err.(validator.ValidationErrors).
• Tag order doesn't matter for most rules, but omitempty must come first if you use it.
• Nested structs: validation descends automatically, but slices of structs need dive to validate each element.

• c.JSON(200, obj) — marshals to JSON, sets Content-Type: application/json. Most common.
• c.IndentedJSON — pretty-printed JSON (2-space indent). ~30% slower; debug only.
• c.SecureJSON — prefixes arrays with while(1); to defend against JSON hijacking in legacy browsers.
• c.AsciiJSON — escapes non-ASCII characters to \u sequences.
• c.JSONP — JSON with a callback wrapper for cross-domain JS.
• c.XML, c.YAML, c.ProtoBuf — alternative serializations.
• c.String(200, "hi %s", name) — plain text with printf-style formatting.
• c.HTML(200, "index.tmpl", data) — render a registered HTML template.
• c.Redirect(302, "/login") — HTTP redirect.
• c.Data(200, "image/png", bytes) — raw bytes with explicit Content-Type.
• c.File("./report.pdf") — stream a file from disk.
• c.Stream(func(w io.Writer) bool {...}) — server-sent events or chunked streaming.

• vs raw net/http: stdlib requires 3 lines minimum: set header, set status, call json.NewEncoder(w).Encode(v). Gin is one line.
• vs Echo: c.JSON(200, obj) is identical. Echo exposes slightly more formats out of the box (JSON Pretty, JSONP).
• vs Fiber: Fiber uses c.JSON(obj) (no status arg) and c.Status(200).JSON(obj) — a fluent chain.
• vs Express: res.status(200).json(obj) — also fluent, with the same underlying concept.

• Double write: calling c.JSON twice in one handler silently writes the second payload after the first — producing invalid JSON. Use return after writing a response.
• Can't change status after writing: once the first byte is flushed, c.Status(500) is a no-op (headers are locked). Set status via the render method itself.
• Nil slice vs empty array: a nil Go slice marshals to null in JSON, not []. Initialize with make([]T, 0) if clients expect an array.
• Time zones: time.Time marshals to RFC 3339 by default. Use a custom type if you need unix timestamps or a specific format.

• Request access: c.Request, c.ClientIP(), c.ContentType(), c.GetHeader("Auth"), c.Cookie("session").
• Parameter reads: c.Param, c.Query, c.PostForm, c.FormFile.
• Binding: c.ShouldBindJSON, c.ShouldBindQuery, etc.
• Response: c.JSON, c.String, c.Status, c.Header, c.SetCookie.
• Flow control: c.Next(), c.Abort(), c.AbortWithStatus, c.AbortWithStatusJSON.
• Key-value store: c.Set("user", user) in middleware, c.MustGet("user").(User) in the handler. Typed helpers: GetString, GetInt, GetBool.
• Errors: c.Error(err) appends to a per-request error list for centralized logging.
• Go context: c.Request.Context() — pass this to DB calls for cancellation on client disconnect.

• vs Go's context.Context: Gin's Context implements the standard interface, so you can pass c directly to any function expecting context.Context. But it's much richer — HTTP-specific sugar, not just cancellation.
• vs Echo: echo.Context is an interface, not a struct, which makes mocking in tests easier but adds a virtual call per access.
• vs Chi: Chi doesn't have a custom context at all — you use r.Context() directly and read URL params via chi.URLParam(r, "id").
• vs Express: Express's req/res/next triad is roughly equivalent but split into three objects instead of one.

• Onion model: c.Next() inside a middleware yields control to the next middleware/handler; code after c.Next() runs on the way back up.
• Abort: c.Abort() stops the chain — no subsequent handlers run. Combine with c.JSON to short-circuit with an error response.
• Built-in middleware: gin.Logger() (access log), gin.Recovery() (catches panics, returns 500). gin.Default() = gin.New() + Logger + Recovery.
• Route groups: apply middleware to a logical set — r.Group("/api", authMW, rateLimitMW).

• vs raw net/http: stdlib middleware wraps handlers: func(next http.Handler) http.Handler. It works but is verbose and doesn't natively understand aborting.
• vs Chi: Chi middleware is stdlib-compatible (func(next http.Handler) http.Handler), so you can reuse any community middleware. Gin middleware is Gin-specific.
• vs Echo: Echo middleware signature is func(next echo.HandlerFunc) echo.HandlerFunc — slightly different shape but same concept.
• vs Express: Express uses (req, res, next) => { ...; next() } — the same onion model with a next() callback.
• vs Spring Boot filters/interceptors: Spring splits middleware into Filter, HandlerInterceptor, and @Aspect. Gin has one unified concept.

• Forgetting c.Next(): if your middleware doesn't call Next(), the chain still continues because Gin auto-advances after the function returns. But if you need "post" logic (timing, logging), you MUST call Next() explicitly.
• Forgetting c.Abort(): writing an error response (c.JSON(401, ...)) without calling Abort() allows the handler to also run — producing a double write.
• Order matters: middleware registered before the route applies; registered after does not. Always r.Use() before r.GET.

func RateLimit(max int) gin.HandlerFunc {
  bucket := newTokenBucket(max)
  return func(c *gin.Context) {
    if !bucket.Allow() {
      c.AbortWithStatusJSON(429, gin.H{"error": "rate limited"})
      return
    }
    c.Next()
  }
}

• Before-only: validate, set a key on context, call c.Next().
• After-only: call c.Next() first, then log status/duration from c.Writer.Status().
• Short-circuit: call c.AbortWithStatusJSON to halt the chain with an error.
• Inject values: c.Set("userID", uid) before Next() so handlers can read it.
• Wrap the writer: replace c.Writer with a custom gin.ResponseWriter to capture the response body for audit logs or caching.

• vs stdlib wrapping: stdlib uses func(next http.Handler) http.Handler which composes nicely but can't easily share state across before/after phases without a context key.
• vs Chi: Chi middleware is stdlib-compatible, so you can literally reuse middleware from libraries like github.com/felixge/httpsnoop or rs/cors. Gin middleware is a closed ecosystem.
• vs Echo: Echo's echo.MiddlewareFunc takes and returns a HandlerFunc — more explicit composition, but requires returning the next call.
• vs Express: Express middleware takes (req, res, next); the same mental model. JavaScript's dynamic typing means Express middleware is more flexible but less type-safe.

• Shared state races: if your middleware mutates a shared map or counter, use sync.Mutex or sync/atomic. Remember: Gin runs handlers concurrently.
• Returning before c.Next(): if you want to cancel, call c.Abort() AND return. Otherwise the chain keeps going.
• Reading the request body: body is a stream and can only be read once. If your middleware reads it, cache it with c.Request.Body = io.NopCloser(bytes.NewBuffer(data)) for downstream handlers.
• Heavy work in middleware: middleware runs on every request — don't open DB connections or parse config inside the closure. Do that in the factory.

• Stateless: server doesn't store sessions — the token itself is the credential.
• Self-contained: payload carries user ID, role, expiration, and custom claims.
• Signed: HMAC-SHA256 (shared secret) or RSA/ECDSA (public/private key pair).
• Expiration: exp claim — tokens auto-expire so leaked tokens have limited lifetime.
• Standard claims: sub, iat, exp, nbf, iss, aud, jti.

• vs sessions: session IDs require a server-side store (Redis, DB). JWTs are stateless — no store needed — but cannot be revoked before expiration without a blocklist.
• vs OAuth2 access tokens: OAuth2 access tokens are often JWTs, but OAuth2 adds the whole authorization flow (authorize → code → token exchange). JWT is just the token format.
• vs API keys: API keys are opaque random strings; JWTs carry claims. API keys typically identify apps; JWTs typically identify users.
• vs Gin's BasicAuth: Gin ships gin.BasicAuth for HTTP Basic Authentication, fine for internal dashboards but not for public APIs.

• Algorithm confusion (alg=none): always assert the expected algorithm in the Keyfunc. Not doing so lets an attacker forge tokens by setting alg: none.
• Secret leakage: never hardcode the signing secret. Use env vars or a secrets manager.
• Storing JWTs in localStorage: vulnerable to XSS. Use HttpOnly cookies for browser clients.
• No revocation: a stolen token is valid until exp. Mitigate with short expirations (15 min) + refresh tokens, or a Redis-backed blocklist for forced logout.
• Clock skew: exp/nbf checks can fail if server clocks drift — allow a small leeway with jwt.WithLeeway(30*time.Second).

• Origin allowlist: AllowOrigins: []string{"https://app.example.com"}.
• Credentials: AllowCredentials: true lets cookies and Authorization headers flow across origins (requires a specific origin, not *).
• Methods & headers: AllowMethods, AllowHeaders declare what the browser can send.
• Exposed headers: ExposeHeaders lets JS read custom response headers like X-Total-Count.
• Max age: MaxAge caches preflight responses to reduce round trips.

• vs rs/cors (stdlib): github.com/rs/cors is a stdlib-compatible middleware — works with Chi, Echo, plain net/http. Gin's gin-contrib/cors is Gin-specific but integrates more cleanly.
• vs Express cors: identical config shape.
• vs Spring Boot: Spring uses @CrossOrigin annotations per-controller, or a global CorsConfiguration bean.

• * + credentials is illegal: browsers reject Access-Control-Allow-Origin: * when Allow-Credentials: true. You must return the exact origin instead.
• Preflight fails silently: if OPTIONS returns 404, the browser aborts the real request with a cryptic CORS error. Ensure your CORS middleware is before any route registration.
• Custom headers need explicit allowlisting: sending X-My-Custom-Header requires it in AllowHeaders, otherwise the preflight fails.
• SameSite cookies: cross-origin cookies need SameSite=None; Secure — CORS config alone isn't enough.
• Server-side requests don't need CORS: CORS is a browser-only concept. curl, Postman, and server-to-server calls ignore it entirely.

• Inline error response: c.JSON(400, gin.H{"error": err.Error()}); return — simple and explicit.
• Abort with status: c.AbortWithStatusJSON(500, gin.H{...}) — stops the chain AND writes a response.
• Error accumulation: c.Error(err) appends without writing a response; a later middleware reads c.Errors to format.
• Typed errors: define sentinel errors (var ErrNotFound = errors.New(...)) and switch on them in middleware to map to HTTP status codes.
• Panic recovery: r.Use(gin.Recovery()) (or CustomRecovery) catches panics and returns 500.

• vs Go 1.20+ error wrapping: Gin predates errors.Is/As but composes perfectly with them. Use errors.Is(err, ErrNotFound) to unwrap wrapped errors in your centralized handler.
• vs Echo: Echo has e.HTTPErrorHandler — a single function set globally that handles all errors, cleaner than Gin's c.Errors accumulation approach.
• vs FastAPI: FastAPI raises HTTPException(status_code, detail) which bubbles to a global handler. Gin requires explicit middleware.
• vs Spring Boot: Spring uses @ControllerAdvice + @ExceptionHandler for global exception mapping. Gin's equivalent is middleware + switch/type-assertion.

• Leaking internals: err.Error() may contain stack traces, SQL queries, or file paths. Log the full error server-side but return a sanitized message to clients.
• Forgetting to return: after c.JSON(400, ...), you MUST return or the handler keeps running and may write another response.
• Panic in goroutines: gin.Recovery() only catches panics in the request goroutine. Panics in goroutines you spawn are NOT caught — wrap them in their own defer recover().
• Nil pointer panics: the most common panic source. Always check pointers before dereferencing.

• Struct-to-table mapping: type User struct { ID uint; Name string } becomes the users table.
• Auto-migrate: db.AutoMigrate(&User{}) creates/updates the schema to match the struct.
• CRUD helpers: db.Create, db.First, db.Find, db.Where(...).Find(&users), db.Save, db.Delete.
• Associations: Preload("Orders") eager-loads related rows in one extra query.
• Transactions: db.Transaction(func(tx *gorm.DB) error {...}) with auto commit/rollback.
• Hooks: BeforeCreate, AfterUpdate for business logic (e.g., hash password before save).
• Soft delete: add gorm.DeletedAt field — deletes set the timestamp instead of removing the row.

• vs database/sql: stdlib is low-level — you write raw SQL and manually scan rows. GORM is high-level and concise but can hide expensive queries.
• vs sqlx: jmoiron/sqlx extends database/sql with struct scanning but no query builder or migrations. Faster and more predictable than GORM.
• vs sqlc: sqlc generates type-safe Go code from SQL queries you write — best of both worlds (raw SQL + type safety) but no runtime query builder.
• vs ent: Facebook's ent is a schema-first ORM with code generation and graph-like API. More opinionated than GORM.
• vs Hibernate/JPA: Java's Hibernate is conceptually similar but much heavier; GORM is leaner but supports fewer advanced features.
• vs ActiveRecord (Rails): GORM borrows the ActiveRecord pattern — chainable query builder, implicit persistence — but with Go's type safety.

• N+1 queries: iterating over a slice and calling db.First per row is the #1 GORM performance trap. Use Preload or Joins.
• Zero-value updates are ignored: db.Updates(&User{Name: "", Age: 0}) skips zero fields. Use map[string]any{...} or Select("Name", "Age") to update zero values.
• Context cancellation: always use db.WithContext(c.Request.Context()) so queries abort when the client disconnects.
• Connection pooling: configure sqlDB.SetMaxOpenConns, SetMaxIdleConns, SetConnMaxLifetime — defaults are often wrong for production.
• Auto-migrate in production: safe for adding columns, dangerous for schema changes. Use proper migrations (goose, atlas, golang-migrate).

• c.FormFile("file") — single file upload. Returns *multipart.FileHeader.
• c.MultipartForm() — parses the entire form; access files via form.File["files"].
• c.SaveUploadedFile(fh, dst) — one-line disk save.
• c.File(path) — streams a file to the response.
• c.FileAttachment(path, name) — forces Content-Disposition: attachment.
• c.FileFromFS(path, fs) — serve from an http.FileSystem (useful with embed.FS).
• r.Static("/assets", "./public") — serve a whole directory as static files.
• r.StaticFS("/embedded", http.FS(embedFS)) — serve an embedded filesystem.

• vs raw net/http: stdlib requires r.ParseMultipartForm(maxMemory), then r.FormFile, then manual io.Copy to save — 10+ lines vs Gin's 3.
• vs Echo: c.FormFile, c.SaveUploadedFile — identical.
• vs Express multer: Express needs a separate multer middleware; Gin has it built-in.
• vs FastAPI: FastAPI uses UploadFile as a type hint — more declarative.

• Memory limit: default MaxMultipartMemory is 32 MB — larger files spool to disk, but extremely large uploads can still exhaust disk. Set r.MaxMultipartMemory = 8 << 20 (8 MB) explicitly.
• Filename trust: file.Filename comes from the client — sanitize before using as a path! An attacker can send ../../etc/passwd.
• Content-type trust: a file claiming image/png might be an executable. Sniff with http.DetectContentType on the first 512 bytes.
• Disk usage: save to a temp directory with cleanup logic, or stream directly to S3/GCS instead of touching local disk.
• Virus scanning: integrate with ClamAV or a commercial scanner before accepting files.

• Template actions: {{.User.Name}}, {{if .Active}}...{{end}}, {{range .Items}}...{{end}}, {{with .Profile}}...{{end}}.
• Template inheritance: {{define "base"}} + {{template "content" .}} for layouts.
• Custom funcs: r.SetFuncMap(template.FuncMap{"upper": strings.ToUpper}) — then {{.Name | upper}}.
• Multi-template: use multitemplate (gin-contrib) for Django-style layouts with multiple blocks.
• Hot reload in dev: call r.LoadHTMLGlob on every request in debug mode.

• vs text/template: text/template doesn't escape — use it for config files, emails, YAML. Never use it for HTML output (XSS risk).
• vs Jinja2/Twig: Go templates are more restrictive by design — no arbitrary expressions, fewer built-in filters. This keeps logic out of templates.
• vs Handlebars/Mustache: Go templates support conditionals and loops; Mustache is strictly "logic-less".
• vs React/Vue: Go templates are server-rendered — no client-side JS runtime. Pair with HTMX for modern interactive server-rendered apps.
• vs templ: a-h/templ is a newer type-safe alternative — Go code generates HTML with compile-time checks. No runtime parsing. Highly recommended for greenfield projects.

• Unescaping with template.HTML: wrapping a string in template.HTML(s) bypasses escaping. Only do this for trusted content.
• Template name clashes: LoadHTMLGlob("templates/*") uses the filename as the template name, so two files named index.html in different subdirs collide.
• Missing fields: referencing a field that doesn't exist on the data struct is a runtime error. Consider using {{with}} or default values.
• Performance: templates are parsed once and cached. Don't call LoadHTMLGlob inside handlers in production.

• Set test mode: gin.SetMode(gin.TestMode) silences log output during tests.
• Build request: req := httptest.NewRequest("POST", "/users", strings.NewReader(body)).
• Record response: w := httptest.NewRecorder(); then router.ServeHTTP(w, req).
• Assert: assert.Equal(t, 200, w.Code), assert.JSONEq(t, expected, w.Body.String()) (using github.com/stretchr/testify).
• Table-driven tests: define a slice of test cases and loop — idiomatic Go pattern.
• Mocks: inject interfaces for DB/HTTP clients so handlers can be tested without real dependencies.

• vs supertest (Node): same concept — spin up the app in-memory, send requests, assert responses.
• vs pytest + FastAPI TestClient: FastAPI's TestClient uses httpx under the hood; same idea.
• vs Spring MockMvc: Spring tests inject a mock dispatcher servlet; conceptually identical.
• vs Rack::Test (Ruby): same in-memory pattern.

• testify (stretchr/testify): assert, require, mock, suite. De facto standard for Go tests.
• gomock (uber-go/mock): interface mocking with code generation.
• httpexpect: fluent HTTP test DSL — e.POST("/users").WithJSON(u).Expect().Status(201).
• testcontainers-go: spin up real Postgres/Redis in Docker for integration tests.

• Forgetting to set Content-Type: req.Header.Set("Content-Type", "application/json") — without it, Gin's ShouldBind may choose the wrong binder.
• Global state: tests that share a singleton DB or logger can cross-contaminate. Prefer per-test setup.
• Parallel tests: use t.Parallel() to speed up I/O-bound tests, but only when handlers have no shared mutable state.
• Flaky time-based tests: inject a clock interface instead of calling time.Now() directly.

• cmd/api/main.go — thin entry point that wires dependencies and starts the server.
• internal/ — private packages, not importable by other modules. Go enforces this at compile time.
• internal/handlers/ — HTTP handlers (thin layer, no business logic).
• internal/services/ — business logic, orchestration.
• internal/repositories/ — database access (or internal/store/).
• internal/models/ — domain types and DTOs.
• internal/middleware/ — custom Gin middleware.
• internal/config/ — config loading (env vars, files).
• migrations/ — SQL migration files.
• pkg/ — public reusable packages (optional).
• api/ — OpenAPI/protobuf specs.

• Flat (small apps): everything in main or 2-3 files — fastest to start, fine up to ~500 LOC.
• Layered (MVC-ish): handlers → services → repositories. Easy to understand, works for most CRUD apps.
• Clean Architecture / Hexagonal: domain types at the center, infrastructure on the outside. Enforces testability via interfaces. Overkill for small apps.
• Domain-Driven Design: group by bounded context (e.g., billing/, catalog/, auth/) instead of by technical layer.

• vs Django/Rails: those frameworks enforce a layout (models/, views/, controllers/). Go gives you freedom — and responsibility.
• vs Spring Boot: Spring uses package-based organization too, but relies heavily on annotations and dependency injection containers. Go uses explicit construction in main.
• vs Node/Express: Node is equally unopinionated, but NPM's flat dependency model differs from Go modules.

• Over-engineering: don't copy Uber-scale layouts for a 500-line API. Start flat, refactor when pain appears.
• Circular imports: Go forbids them. Careful with shared types — put them in a models or domain package that nothing else imports from.
• Global state: avoid package-level variables for DB/config. Pass dependencies explicitly via constructors.
• pkg/ is controversial: some Go teams consider pkg/ unnecessary — everything that's not cmd/ or internal/ is implicitly "public". Use it only if you publish reusable libraries.

• Build http.Server: srv := &http.Server{Addr: ":8080", Handler: r}.
• Start in goroutine: go srv.ListenAndServe() so main can wait on the signal.
• Trap signals: signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM).
• Shutdown with timeout: ctx, _ := context.WithTimeout(ctx, 30*time.Second); srv.Shutdown(ctx).
• Close resources: after shutdown returns, close DB pools, flush logs, drain background workers.

• vs r.Run(): the one-liner r.Run() blocks forever and has no shutdown hook. Fine for scripts, bad for production.
• vs Node.js: server.close() is the equivalent, but Node requires extra care because pending callbacks keep the event loop alive.
• vs nginx quit: nginx's graceful quit is similar — stop accepting, drain, exit.
• vs Kubernetes: K8s sends SIGTERM, waits for terminationGracePeriodSeconds (default 30s), then SIGKILL. Your shutdown timeout must be shorter.

• SIGKILL can't be trapped: if you only handle SIGTERM, kill -9 still kills abruptly.
• Long-running requests block shutdown: a 60s database query blocks shutdown past the timeout. Propagate c.Request.Context() to the DB so it cancels.
• WebSocket/SSE connections: Shutdown() doesn't close hijacked connections. Track them manually and close them before calling Shutdown.
• Pre-stop hook: in Kubernetes, use a preStop sleep of ~5s before SIGTERM so the service removal can propagate through the LB before you stop accepting.
• Goroutines leaking past shutdown: Shutdown doesn't wait for background goroutines you spawned — track them with sync.WaitGroup.

• Stage 1 (builder): FROM golang:1.22-alpine — compile with the full toolchain.
• Stage 2 (runtime): FROM scratch or gcr.io/distroless/static — copy only the compiled binary.
• Build flags: CGO_ENABLED=0 for a fully static binary, -ldflags="-s -w" to strip debug symbols (~30% smaller).
• Cache optimization: copy go.mod/go.sum before source so go mod download is cached when only code changes.

• Kubernetes: the de facto standard for Gin services. Use Deployments, Services, Ingress, HPA.
• Cloud Run / App Runner: serverless containers — pay per request, auto-scale to zero. Great for low-traffic APIs.
• Fly.io / Railway / Render: developer-friendly PaaS that runs your Dockerfile directly.
• Lambda: Gin works via the awslabs/aws-lambda-go-api-proxy adapter — it translates Lambda events to http.Request.
• systemd: a plain binary + systemd unit file is perfectly valid for small deployments.

• vs Node.js: Go images are 10-20x smaller because there's no runtime bundled. A Node Docker image is typically 100-300 MB; Gin can be ~10 MB.
• vs Java/Spring: Spring Boot images are 200-500 MB (JVM + dependencies). Go apps start in milliseconds vs seconds for JVM warm-up.
• vs Python (FastAPI): Python images need the interpreter + pip packages (~150 MB). Go is dramatically smaller.
• vs serverless frameworks: Go's fast cold start (<50ms) makes it ideal for Lambda/Cloud Run, whereas JVM cold starts can be seconds.

• Timezones: scratch has no /usr/share/zoneinfo. Either use alpine, copy tzdata into scratch, or import _ "time/tzdata" to embed it in the binary.
• CA certificates: scratch also lacks CA certs — outbound HTTPS fails. Copy /etc/ssl/certs/ca-certificates.crt from the builder, or use distroless which includes them.
• Health checks: expose /healthz for Kubernetes liveness/readiness probes. Liveness should be cheap; readiness should check DB connectivity.
• Logging: write to stdout/stderr (not files) — containers collect logs that way. Use structured JSON logs (zap, zerolog).
• Config: 12-factor — read from env vars. Never bake secrets into images.

• Self-test: toggle "Hide All" and try to answer each question from memory before peeking.
• Depth over breadth: interviewers care more about "why" than "what". If you know why Gin's radix tree beats http.ServeMux, you'll answer ten related questions correctly.
• Practice aloud: rubber-duck every answer in your own words before a real interview.
• Map to your experience: every concept here has a production anchor — tie each answer to something you've built or debugged.

• Core concepts: what is Gin, how does it compare to Echo/Chi/Fiber, what is *gin.Context, how does middleware work.
• Routing: radix tree, path params vs query params, route groups, route conflicts.
• Request handling: Bind vs ShouldBind, validation tags, file uploads, multipart forms.
• Middleware: custom middleware, Abort vs Next, onion model, error middleware.
• Auth: JWT flow, refresh tokens, storing tokens, revocation strategies.
• Production concerns: graceful shutdown, logging, health checks, observability, rate limiting.
• Testing: httptest, mocking, integration vs unit tests.
• System design: multi-tenant SaaS APIs, rate-limited public APIs, real-time WebSocket services, high-throughput event ingestion.

• Read the Gin source: gin.go, context.go, and tree.go together are fewer than 3000 lines. You'll understand the framework better than 90% of candidates.
• Build something non-trivial: a REST API with JWT + GORM + tests + Docker. Reference it in interviews.
• Benchmarks: be able to explain why Gin is fast (radix tree + sync.Pool + minimal allocations) and where it isn't (JSON encoding is the bottleneck).
• Compare frameworks honestly: know when Chi or Echo might be a better fit so you can answer "why Gin?" confidently.