from zero to production: a hands‑on golang tutorial for building blazing‑fast cloud apis with ai‑powered dev tools

P
@pilput
8 months ago0views

what you’ll build

in this hands-on tutorial, you’ll go from zero to a production-ready go (golang) rest api. you’ll learn how to scaffold a project, write clean handlers, use ai-powered developer tools, containerize with docker, deploy to the cloud, and wire up devops essentials like ci/cd, logging, and metrics. this guide is beginner-friendly but grounded in full‑stack realities and devops best practices.

prerequisites

  • basic terminal knowledge and git installed
  • go 1.21+ installed
  • docker desktop (or docker engine) installed
  • a code editor (vs code recommended) with the go extension
  • optional: openai/anthropic key or github copilot for ai assistance

project goals

  • fast api: idiomatic go, low overhead
  • secure defaults: env configs, minimal attack surface
  • cloud-ready: dockerized, health checks, metrics
  • ai-powered dev: use ai to draft boilerplate, tests, and docs
  • seo-friendly: clear structure for docs and landing pages

step 1 — initialize the go module

create a folder and initialize your module:

mkdir go-blazing-api && cd go-blazing-api
go mod init github.com/yourname/go-blazing-api
go get github.com/go-chi/chi/v5
go get github.com/joho/godotenv
go get github.com/rs/zerolog/log
go get github.com/prometheus/client_golang/prometheus/promhttp

why these? chi = lightweight, fast router; godotenv = local env management; zerolog = structured logs; promhttp = metrics endpoint.

step 2 — project structure

.
├─ cmd/
│  └─ api/
│     └─ main.go
├─ internal/
│  ├─ http/
│  │  ├─ router.go
│  │  └─ handlers.go
│  ├─ config/
│  │  └─ config.go
│  ├─ health/
│  │  └─ health.go
│  └─ version/
│     └─ version.go
├─ pkg/
│  └─ middleware/
│     └─ middleware.go
├─ .env.example
├─ dockerfile
├─ docker-compose.yml
├─ makefile
└─ readme.md

tip: ask your ai assistant to generate file headers, docstrings, and basic tests for each package to speed up iteration.

step 3 — configuration and environment variables

create internal/config/config.go:

package config

import (
  "log"
  "os"
  "strconv"

  "github.com/joho/godotenv"
)

type config struct {
  env         string
  port        string
  readtimeout int
  writetimeout int
}

func mustatoi(key, def string) int {
  v := def
  if ev := os.getenv(key); ev != "" {
    v = ev
  }
  i, err := strconv.atoi(v)
  if err != nil {
    log.fatalf("invalid int for %s: %v", key, err)
  }
  return i
}

func load() config {
  _ = godotenv.load() // load .env if present
  cfg := config{
    env:          getenv("app_env", "development"),
    port:         getenv("port", "8080"),
    readtimeout:  mustatoi("read_timeout_sec", "5"),
    writetimeout: mustatoi("write_timeout_sec", "10"),
  }
  return cfg
}

func getenv(key, def string) string {
  if v := os.getenv(key); v != "" {
    return v
  }
  return def
}

create .env.example:

app_env=development
port=8080
read_timeout_sec=5
write_timeout_sec=10

step 4 — router and handlers

add internal/http/router.go:

package http

import (
  "net/http"

  "github.com/go-chi/chi/v5"
  "github.com/go-chi/chi/v5/middleware"
  "github.com/prometheus/client_golang/prometheus/promhttp"

  pmw "github.com/yourname/go-blazing-api/pkg/middleware"
)

func newrouter(h *handlers) http.handler {
  r := chi.newrouter()
  r.use(middleware.requestid)
  r.use(middleware.realip)
  r.use(pmw.logger)        // structured logging
  r.use(middleware.recoverer)

  r.get("/healthz", h.health)
  r.get("/v1/version", h.version)
  r.get("/v1/hello", h.hello)
  r.method("get", "/metrics", promhttp.handler())

  return r
}

add internal/http/handlers.go:

package http

import (
  "encoding/json"
  "net/http"
  "time"

  "github.com/rs/zerolog/log"
  "github.com/yourname/go-blazing-api/internal/version"
)

type handlers struct{}

func newhandlers() *handlers { return &handlers{} }

func (h *handlers) health(w http.responsewriter, r *http.request) {
  w.header().set("content-type", "application/json")
  _ = json.newencoder(w).encode(map[string]any{
    "status": "ok",
    "ts":     time.now().utc(),
  })
}

func (h *handlers) version(w http.responsewriter, r *http.request) {
  writejson(w, http.statusok, version.info())
}

func (h *handlers) hello(w http.responsewriter, r *http.request) {
  name := r.url.query().get("name")
  if name == "" {
    name = "world"
  }
  writejson(w, http.statusok, map[string]string{"message": "hello, " + name + "!"})
}

func writejson(w http.responsewriter, status int, v any) {
  w.header().set("content-type", "application/json")
  w.writeheader(status)
  if err := json.newencoder(w).encode(v); err != nil {
    log.error().err(err).msg("write response")
  }
}

step 5 — middleware with structured logging

add pkg/middleware/middleware.go:

package middleware

import (
  "net/http"
  "time"

  "github.com/rs/zerolog"
  "github.com/rs/zerolog/log"
)

func init() {
  zerolog.timefieldformat = time.rfc3339nano
}

func logger(next http.handler) http.handler {
  return http.handlerfunc(func(w http.responsewriter, r *http.request) {
    start := time.now()
    ww := &statuswriter{responsewriter: w, status: 200}
    next.servehttp(ww, r)
    log.info().
      str("method", r.method).
      str("path", r.url.path).
      int("status", ww.status).
      dur("duration_ms", time.since(start)).
      msg("request")
  })
}

type statuswriter struct {
  http.responsewriter
  status int
}

func (sw *statuswriter) writeheader(code int) {
  sw.status = code
  sw.responsewriter.writeheader(code)
}

step 6 — version info

add internal/version/version.go for build metadata:

package version

var (
  version   = "dev"
  commit    = "none"
  builddate = "unknown"
)

func info() map[string]string {
  return map[string]string{
    "version":   version,
    "commit":    commit,
    "builddate": builddate,
  }
}

step 7 — main application

create cmd/api/main.go:

package main

import (
  "context"
  "fmt"
  "net/http"
  "os"
  "os/signal"
  "syscall"
  "time"

  api "github.com/yourname/go-blazing-api/internal/http"
  "github.com/yourname/go-blazing-api/internal/config"
)

func main() {
  cfg := config.load()

  h := api.newhandlers()
  router := api.newrouter(h)

  srv := &http.server{
    addr:         ":" + cfg.port,
    handler:      router,
    readtimeout:  time.duration(cfg.readtimeout) * time.second,
    writetimeout: time.duration(cfg.writetimeout) * time.second,
  }

  go func() {
    fmt.printf("listening on :%s (%s)\n", cfg.port, cfg.env)
    if err := srv.listenandserve(); err != nil && err != http.errserverclosed {
      panic(err)
    }
  }()

  // graceful shutdown
  quit := make(chan os.signal, 1)
  signal.notify(quit, syscall.sigint, syscall.sigterm)
  <-quit

  ctx, cancel := context.withtimeout(context.background(), 10*time.second)
  defer cancel()
  _ = srv.shutdown(ctx)
}

step 8 — run and test locally

cp .env.example .env
go run ./cmd/api
# in another terminal:
curl -s http://localhost:8080/healthz | jq
curl -s http://localhost:8080/v1/hello?name=gopher | jq
curl -s http://localhost:8080/v1/version | jq

step 9 — containerize with docker

create a minimal, production-ready image using multi-stage builds.

# dockerfile
# ---------- builder ----------
from golang:1.22-alpine as builder
workdir /src
run apk add --no-cache git ca-certificates build-base
copy go.mod go.sum ./
run go mod download
copy . .
arg version=dev
arg commit=none
arg date=unknown
run cgo_enabled=0 goos=linux goarch=amd64 \
  go build -trimpath -ldflags "-s -w \
  -x github.com/yourname/go-blazing-api/internal/version.version=$version \
  -x github.com/yourname/go-blazing-api/internal/version.commit=$commit \
  -x github.com/yourname/go-blazing-api/internal/version.builddate=$date" \
  -o /bin/api ./cmd/api

# ---------- runtime ----------
from gcr.io/distroless/base-debian12
env port=8080
expose 8080
copy --from=builder /bin/api /bin/api
user nonroot:nonroot
entrypoint ["/bin/api"]

optional docker-compose.yml for local stacks:

services:
  api:
    build: .
    ports:
      - "8080:8080"
    environment:
      - app_env=development
      - port=8080

build and run:

docker build -t yourname/go-blazing-api:dev --build-arg version=0.1.0 \
  --build-arg commit=$(git rev-parse --short head) \
  --build-arg date=$(date -u +%y-%m-%dt%h:%m:%sz) .
docker run --rm -p 8080:8080 yourname/go-blazing-api:dev

step 10 — observability: metrics and health

  • /healthz for readiness/liveness checks in kubernetes or cloud run-times
  • /metrics exposes prometheus metrics: scrape with prometheus or use grafana cloud
  • structured logs via zerolog: pipe to cloudwatch, stackdriver, or loki

step 11 — ai-powered dev workflows

  • generate boilerplate: ask ai to draft handler skeletons, dtos, and tests
  • explain errors: paste stack traces for quick fixes
  • refactor: request performance or memory optimizations
  • docs/seo: have ai create user-facing docs and landing copy with clear headings and keywords like “devops”, “full stack”, and “coding”

prompt example:

refactor this go handler for lower allocations and add table-driven tests:
<paste handler.go>

step 12 — ci/cd pipeline (github actions)

add .github/workflows/ci.yml:

name: ci
on:
  push:
    branches: [ main ]
  pull_request:
jobs:
  build-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: "1.22"
      - run: go mod download
      - run: go vet ./...
      - run: go test ./... -coverprofile=coverage.out
      - run: |
          docker build -t ghcr.io/${{ github.repository }}:sha-${{ github.sha }} \
            --build-arg version=${{ github.ref_name }} \
            --build-arg commit=${{ github.sha }} \
            --build-arg date=$(date -u +%y-%m-%dt%h:%m:%sz) .

tip: add a deploy job that pushes to ghcr and triggers your cloud deployment.

step 13 — deploy to the cloud (examples)

option a: render/fly.io

deploy the docker image with a simple service definition. configure env vars in the dashboard. add health checks pointing to /healthz.

option b: google cloud run

gcloud run deploy go-blazing-api \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars app_env=production,port=8080

option c: kubernetes (k8s)

apiversion: apps/v1
kind: deployment
metadata:
  name: go-blazing-api
spec:
  replicas: 2
  selector:
    matchlabels: { app: go-blazing-api }
  template:
    metadata:
      labels: { app: go-blazing-api }
    spec:
      containers:
        - name: api
          image: yourname/go-blazing-api:0.1.0
          ports: [{ containerport: 8080 }]
          readinessprobe:
            httpget: { path: /healthz, port: 8080 }
            initialdelayseconds: 3
          livenessprobe:
            httpget: { path: /healthz, port: 8080 }
          env:
            - { name: app_env, value: "production" }
            - { name: port, value: "8080" }
---
apiversion: v1
kind: service
metadata:
  name: go-blazing-api
spec:
  selector: { app: go-blazing-api }
  ports:
    - port: 80
      targetport: 8080
      protocol: tcp

step 14 — basic security and performance

  • time-outs and recoverer middleware to avoid slowloris and panics
  • distroless image with non-root user
  • rate limiting: add token bucket (e.g., golang.org/x/time/rate)
  • cors if serving browser clients
  • validation for inputs; never trust query/body without checks

example rate limit middleware:

import "golang.org/x/time/rate"

var limiter = rate.newlimiter(10, 20) // 10 req/s, burst 20

func ratelimit(next http.handler) http.handler {
  return http.handlerfunc(func(w http.responsewriter, r *http.request) {
    if !limiter.allow() {
      http.error(w, "rate limit exceeded", http.statustoomanyrequests)
      return
    }
    next.servehttp(w, r)
  })
}

step 15 — add a simple ai endpoint (optional)

demonstrates integrating ai tools from your api. use env vars for keys.

# go get github.com/sashabaranov/go-openai

// internal/http/handlers_ai.go
package http

import (
  "context"
  "net/http"
  "os"

  openai "github.com/sashabaranov/go-openai"
)

func (h *handlers) complete(w http.responsewriter, r *http.request) {
  apikey := os.getenv("openai_api_key")
  if apikey == "" {
    http.error(w, "ai disabled", http.statusserviceunavailable)
    return
  }
  q := r.url.query().get("q")
  if q == "" {
    http.error(w, "missing q", http.statusbadrequest)
    return
  }
  client := openai.newclient(apikey)
  resp, err := client.createchatcompletion(context.background(), openai.chatcompletionrequest{
    model: "gpt-4o-mini",
    messages: []openai.chatcompletionmessage{
      {role: "user", content: q},
    },
  })
  if err != nil || len(resp.choices) == 0 {
    http.error(w, "ai error", http.statusbadgateway)
    return
  }
  writejson(w, http.statusok, map[string]string{"answer": resp.choices[0].message.content})
}

register the route in router.go:

r.get("/v1/ai/complete", h.complete)

seo tips for your project docs

  • use keyword-rich headings like “golang devops deployment guide”, “full-stack coding with go apis”
  • add a concise meta description and an faq section
  • structure with h2/h3 and bullet lists for readability
  • include code snippets and performance claims backed by metrics

troubleshooting

  • port already in use: change port or stop the other service
  • docker build fails: verify go version and go mod download
  • 404s: ensure routes match the path and method
  • ai requests failing: check openai_api_key and model name

next steps

  • add persistence: postgres with sqlc or gorm, run migrations
  • jwt auth and rbac roles
  • more observability: tracing with opentelemetry
  • performance tuning: pprof, wrk/hey load tests, caching layers

summary

you’ve built a blazing-fast, cloud-ready golang api with devops foundations, ai-assisted development, and production essentials: health checks, metrics, structured logs, docker, and ci/cd. with this scaffold, you can iterate confidently, scale to production, and document your work with seo-friendly content that helps users and search engines alike.

Comments

Discussion

Share your thoughts and join the conversation

Loading comments...

Join the Discussion

Please log in to share your thoughts and engage with the community.

Log InSign Up