Chương 24 — Case Study: Xây dựng REST API Golang chuẩn 12-Factor (kèm hành trình refactor)

// main.go — PHIÊN BẢN CŨ (đừng bắt chước)
package main

const dbDSN = "postgres://app:Prod@Pass99@10.0.3.17:5432/orders" // ① F3: secret trong code

var orderCache = map[string]*Order{}   // ② F6: cache không TTL, không giới hạn — state + memory leak
var cacheMu sync.Mutex

func main() {
	db, _ := sql.Open("postgres", dbDSN)
	runMigrations(db)                   // ③ F5/F12: N instance đua migration lúc khởi động

	f, _ := os.OpenFile("/var/log/orderly.log", os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
	log.SetOutput(f)                    // ④ F11: log ra file local

	http.HandleFunc("/orders", func(w http.ResponseWriter, r *http.Request) {
		// ... tạo order, lưu DB ...
		go sendConfirmationEmail(order) // ⑤ F8/F9: job nền trong process web — deploy là mất email
		go exportToAccounting(order)    //    và không retry, không dấu vết
	})

	c := cron.New()
	c.AddFunc("0 3 * * *", cleanupExpired) // ⑥ F6/F12: in-process cron — scale là chạy N lần
	c.Start()

	http.ListenAndServe(":8080", nil)   // ⑦ F7/F9: port cứng; không graceful shutdown; không probe
}

// internal/config/config.go
type Config struct {
	Port            string        `env:"PORT" envDefault:"8080"`
	LogLevel        string        `env:"LOG_LEVEL" envDefault:"info"`
	DrainDelay      time.Duration `env:"DRAIN_DELAY" envDefault:"5s"`
	ShutdownTimeout time.Duration `env:"SHUTDOWN_TIMEOUT" envDefault:"15s"`

	DatabaseURL  string   `env:"DATABASE_URL,required"`
	RedisURL     string   `env:"REDIS_URL,required"`
	KafkaBrokers []string `env:"KAFKA_BROKERS,required"`

	CacheTTL          time.Duration `env:"CACHE_TTL" envDefault:"5m"`
	WorkerConcurrency int           `env:"WORKER_CONCURRENCY" envDefault:"8"`
}

// internal/service/order.go (trích)
func (s *OrderService) Create(ctx context.Context, req CreateOrderRequest) (*Order, error) {
	if err := req.Validate(); err != nil {
		return nil, fmt.Errorf("%w: %v", ErrInvalid, err)
	}
	order := NewOrder(req)

	// Order + event: MỘT transaction — nguyên tử, chịu được crash bất kỳ lúc nào
	err := s.repo.CreateWithOutbox(ctx, order, OutboxEvent{
		Topic:   "orders.created",
		Key:     order.ID,
		Payload: mustJSON(OrderCreatedEvent{ID: order.ID, Amount: order.Amount}),
	})
	if err != nil {
		return nil, fmt.Errorf("create order: %w", err)
	}
	s.cache.Invalidate(ctx, order.UserID) // cache lỗi không fail request — chỉ log
	return order, nil
}

// internal/repository/postgres/order.go (trích)
func (r *OrderRepo) CreateWithOutbox(ctx context.Context, o *service.Order, ev service.OutboxEvent) error {
	tx, err := r.pool.Begin(ctx)
	if err != nil {
		return err
	}
	defer tx.Rollback(ctx)

	if _, err := tx.Exec(ctx,
		`INSERT INTO orders (id, user_id, amount, status, created_at)
		 VALUES ($1,$2,$3,$4,$5)`,
		o.ID, o.UserID, o.Amount, o.Status, o.CreatedAt); err != nil {
		return err
	}
	if _, err := tx.Exec(ctx,
		`INSERT INTO outbox (topic, key, payload) VALUES ($1,$2,$3)`,
		ev.Topic, ev.Key, ev.Payload); err != nil {
		return err
	}
	return tx.Commit(ctx)
}

// internal/cache/redis.go (trích) — sửa lỗi ② của bản cũ:
// TTL bắt buộc, tập trung (mọi instance nhìn cùng cache), fail-open
func (c *Cache) GetOrder(ctx context.Context, id string) (*service.Order, bool) {
	b, err := c.rdb.Get(ctx, "order:"+id).Bytes()
	if err != nil {
		return nil, false // Redis chết → miss → đọc DB: cache là TỐI ƯU, không phải sự thật
	}
	var o service.Order
	if json.Unmarshal(b, &o) != nil {
		return nil, false
	}
	return &o, true
}

func (c *Cache) SetOrder(ctx context.Context, o *service.Order) {
	b, _ := json.Marshal(o)
	if err := c.rdb.Set(ctx, "order:"+o.ID, b, c.ttl).Err(); err != nil {
		c.log.Warn("cache set failed", "err", err) // không bao giờ fail request vì cache
	}
}

// cmd/app: case "worker" → events.RunConsumer (trích)
func (c *Consumer) handle(ctx context.Context, msg kafka.Message) error {
	var ev OrderCreatedEvent
	if err := json.Unmarshal(msg.Value, &ev); err != nil {
		c.log.Error("poison message", "offset", msg.Offset, "err", err)
		return nil // commit bỏ qua + đẩy DLQ — đừng chặn partition vì một message hỏng
	}
	// Idempotency: outbox có thể gửi trùng, Kafka giao at-least-once —
	// khóa duy nhất chặn xử lý lặp
	done, err := c.markProcessed(ctx, ev.ID) // INSERT ... ON CONFLICT DO NOTHING
	if err != nil {
		return err // lỗi hạ tầng → không commit → thử lại
	}
	if !done {
		return nil // đã xử lý rồi — bỏ qua êm
	}
	return c.sendConfirmationEmail(ctx, ev) // sửa lỗi ⑤: có retry, có dấu vết, sống sót qua deploy
}

-- internal/migrate/sql/0001_init.up.sql
CREATE TABLE orders (
    id         TEXT PRIMARY KEY,
    user_id    TEXT NOT NULL,
    amount     BIGINT NOT NULL CHECK (amount > 0),
    status     TEXT NOT NULL DEFAULT 'pending',
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_orders_user ON orders (user_id, created_at DESC);

CREATE TABLE outbox (
    id         BIGSERIAL PRIMARY KEY,
    topic      TEXT NOT NULL,
    key        TEXT NOT NULL,
    payload    JSONB NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    sent_at    TIMESTAMPTZ
);
CREATE INDEX idx_outbox_unsent ON outbox (id) WHERE sent_at IS NULL;

CREATE TABLE processed_events (          -- idempotency của worker
    event_id     TEXT PRIMARY KEY,
    processed_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

services:
  app:
    build: .
    command: ["server"]
    ports: ["8080:8080"]
    environment: &appenv
      DATABASE_URL: postgres://app:dev@db:5432/orderly?sslmode=disable
      REDIS_URL: redis://redis:6379/0
      KAFKA_BROKERS: kafka:9092
      LOG_LEVEL: debug
    depends_on:
      db: { condition: service_healthy }
      kafka: { condition: service_started }
  worker:
    build: .
    command: ["worker"]
    environment: *appenv
    depends_on: [app]
  migrate:
    build: .
    command: ["migrate"]
    environment: *appenv
    depends_on:
      db: { condition: service_healthy }
  db:
    image: postgres:17.4-alpine        # đúng version RDS (F10)
    environment: { POSTGRES_USER: app, POSTGRES_PASSWORD: dev, POSTGRES_DB: orderly }
    healthcheck: { test: ["CMD-SHELL", "pg_isready -U app"], interval: 2s, retries: 15 }
  redis:
    image: redis:7.2-alpine
  kafka:
    image: apache/kafka:3.9.0          # KRaft — không cần ZooKeeper
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      # ... (cấu hình single-node chuẩn)