Flujo Completo de Desarrollo: API CRUD de Notas en Go

Arquitectura Hexagonal + DDD desde Cero, Sin Dependencias Externas

Principio Fundamental (Bushido del Software): “El maestro espadachín no depende de su arma, sino de su técnica.” — Construiremos solo con la biblioteca estándar de Go. SQLite vía database/sql (con el driver puro Go más adelante, o modernc.org/sqlite si aceptas una dependencia mínima).

---

Fase 0: La Mentalidad Antes del Código

Antes de tocar el teclado, piensa en capas como membranas de una célula. La información fluye de afuera (HTTP) hacia adentro (dominio) y vuelve. El dominio es el núcleo: nunca conoce el exterior.

            ┌─────────────────────────────────────┐
            │         INFRASTRUCTURE (Adapters)     │
            │  ┌──────────┐         ┌────────────┐  │
            │  │   HTTP   │         │   SQLite   │  │
            │  │ (driving)│         │  (driven)  │  │
            │  └────┬─────┘         └─────┬──────┘  │
            │       │                     │         │
            │  ┌────▼─────────────────────▼──────┐  │
            │  │      APPLICATION (Use Cases)     │  │
            │  │  ┌────────────────────────────┐  │  │
            │  │  │        DOMAIN (Core)        │  │  │
            │  │  │  Entities + Value Objects   │  │  │
            │  │  │  + Ports (interfaces)       │  │  │
            │  │  └────────────────────────────┘  │  │
            │  └──────────────────────────────────┘  │
            └─────────────────────────────────────┘

   Driving Adapters → Application → Domain ← Driven Adapters

Concepto Hexagonal	Significado	En nuestro proyecto
Port	Interfaz (contrato)	NoteRepository interface
Driving Adapter	Quien inicia la acción	HTTP handlers
Driven Adapter	Quien es invocado	SQLite repository
Domain	Lógica pura de negocio	Entidad Note

---

Fase 1: Inicialización del Proyecto

Paso 1.1 — Crear el directorio y entrar

mkdir notes-api && cd notes-api

Paso 1.2 — Inicializar el módulo Go

# El path debe reflejar tu repo real. Si lo subes a GitHub:
go mod init github.com/tu-usuario/notes-api

¿Por qué este path? El módulo path es el prefijo de identidad de tus imports. Como una dirección IP en una red: único e inmutable conceptualmente. Cambiarlo después es doloroso.

Paso 1.3 — Verificar versión de Go

go version  # Asegúrate de tener 1.22+ para el nuevo router HTTP

Crítico: Go 1.22 introdujo enhanced routing en net/http. Esto nos permite hacer routing con métodos y wildcards (GET /notes/{id}) sin frameworks. Si tienes una versión anterior, el flujo cambia significativamente.

---

Fase 2: Inicialización de Git

Paso 2.1 — Inicializar el repositorio

git init

Paso 2.2 — Crear .gitignore

cat > .gitignore << 'EOF'
# Binarios compilados
/bin/
/notes-api
*.exe

# Base de datos local
*.db
*.sqlite
*.sqlite3

# Variables de entorno
.env

# IDE / Editor
.idea/
.vscode/
*.swp

# Go workspace
go.work
go.work.sum
EOF

Paso 2.3 — Primer commit (estructura base)

git add .gitignore go.mod
git commit -m "chore: initialize go module and gitignore"

Filosofía de commits: Usa Conventional Commits (feat:, fix:, chore:, refactor:). No es burocracia; es trazabilidad termodinámica — cada commit reduce la entropía de tu historial al hacerlo legible.

---

Fase 3: Construcción de la Estructura de Carpetas

Paso 3.1 — Crear el esqueleto completo

mkdir -p cmd/api
mkdir -p internal/domain/note
mkdir -p internal/application
mkdir -p internal/infrastructure/persistence/sqlite
mkdir -p internal/infrastructure/http
mkdir -p internal/config

Estructura resultante:

notes-api/
├── cmd/
│   └── api/
│       └── main.go              # Composition Root (wiring)
├── internal/
│   ├── domain/
│   │   └── note/
│   │       ├── note.go          # Entity + Value Objects
│   │       ├── repository.go    # Port (interface)
│   │       └── errors.go        # Domain errors
│   ├── application/
│   │   └── note_service.go      # Use Cases
│   ├── infrastructure/
│   │   ├── persistence/
│   │   │   └── sqlite/
│   │   │       ├── connection.go    # DB setup + migrations
│   │   │       └── note_repo.go     # Driven Adapter
│   │   └── http/
│   │       ├── router.go            # Routing
│   │       ├── note_handler.go      # Driving Adapter
│   │       └── response.go          # Helpers JSON
│   └── config/
│       └── config.go            # Configuración
├── go.mod
└── .gitignore

¿Por qué internal/? Go trata internal/ como un campo de fuerza: ningún módulo externo puede importar paquetes dentro de él. Es encapsulación a nivel de compilador. Tu dominio queda blindado.

---

Fase 4: El Núcleo — Capa de Dominio

Regla de oro: El dominio NO importa nada de application, infrastructure, ni librerías de I/O. Solo la stdlib pura (y mínima). Es el átomo indivisible de tu sistema.

Paso 4.1 — Errores del dominio (internal/domain/note/errors.go)

package note

import "errors"

// Domain errors son sentinelas: valores comparables con errors.Is().
// Representan estados de negocio inválidos, NO errores técnicos (esos van en infraestructura).
var (
	// ErrNotFound indica que una nota no existe en el sistema.
	ErrNotFound = errors.New("note not found")

	// ErrEmptyTitle viola la invariante: toda nota debe tener título.
	ErrEmptyTitle = errors.New("note title cannot be empty")

	// ErrTitleTooLong protege contra abuso de almacenamiento.
	ErrTitleTooLong = errors.New("note title exceeds maximum length")

	// ErrInvalidID indica un identificador malformado.
	ErrInvalidID = errors.New("invalid note id")
)

Paso 4.2 — La Entidad y Value Objects (internal/domain/note/note.go)

package note

import (
	"strings"
	"time"
)

// Límites de negocio definidos como invariantes del dominio.
const (
	maxTitleLength   = 200
	maxContentLength = 10000
)

// Note es la Entidad raíz del agregado.
// Tiene identidad (ID) y encapsula sus invariantes de negocio.
//
// Decisión de diseño: campos privados + getters.
// Esto impide la mutación descontrolada desde fuera del agregado,
// forzando que todo cambio pase por métodos que validan invariantes.
type Note struct {
	id        string
	title     string
	content   string
	createdAt time.Time
	updatedAt time.Time
}

// New es el constructor (Factory). Garantiza que NUNCA exista
// una Note en estado inválido. Es la "ley de conservación" del agregado:
// no se puede crear materia (Note) que viole las reglas físicas (invariantes).
func New(id, title, content string) (*Note, error) {
	title = strings.TrimSpace(title)

	if err := validateTitle(title); err != nil {
		return nil, err
	}
	if err := validateContent(content); err != nil {
		return nil, err
	}

	now := time.Now().UTC()
	return &Note{
		id:        id,
		title:     title,
		content:   content,
		createdAt: now,
		updatedAt: now,
	}, nil
}

// Reconstitute reconstruye una Note desde datos persistidos.
// CLAVE: este constructor NO valida ni genera timestamps, porque los datos
// ya fueron validados al crearse. Reconstruir != Crear.
// Esto evita el anti-patrón de "re-validar" datos que ya viven en la DB.
func Reconstitute(id, title, content string, createdAt, updatedAt time.Time) *Note {
	return &Note{
		id:        id,
		title:     title,
		content:   content,
		createdAt: createdAt,
		updatedAt: updatedAt,
	}
}

// UpdateContent muta el estado respetando invariantes.
// Es la única vía legítima para cambiar el contenido.
func (n *Note) UpdateContent(title, content string) error {
	title = strings.TrimSpace(title)

	if err := validateTitle(title); err != nil {
		return err
	}
	if err := validateContent(content); err != nil {
		return err
	}

	n.title = title
	n.content = content
	n.updatedAt = time.Now().UTC() // Touch: marca la modificación temporal
	return nil
}

// --- Getters: acceso de solo lectura al estado interno ---

func (n *Note) ID() string           { return n.id }
func (n *Note) Title() string        { return n.title }
func (n *Note) Content() string      { return n.content }
func (n *Note) CreatedAt() time.Time { return n.createdAt }
func (n *Note) UpdatedAt() time.Time { return n.updatedAt }

// --- Validadores privados: la lógica de invariantes ---

func validateTitle(title string) error {
	if title == "" {
		return ErrEmptyTitle
	}
	if len(title) > maxTitleLength {
		return ErrTitleTooLong
	}
	return nil
}

func validateContent(content string) error {
	if len(content) > maxContentLength {
		return ErrTitleTooLong // Reutilizamos o creamos ErrContentTooLong
	}
	return nil
}

Paso 4.3 — El Puerto / Repository (internal/domain/note/repository.go)

package note

import "context"

// Repository es un PUERTO (Port) en la arquitectura hexagonal.
// El dominio DEFINE qué necesita, sin saber CÓMO se implementa.
//
// Analogía física: es como definir las leyes de la termodinámica
// sin especificar si el sistema es un motor de vapor o una refrigeradora.
// La interfaz es la "ley"; la implementación es la "máquina".
//
// context.Context se propaga para soportar cancelación y timeouts:
// si el cliente HTTP corta la conexión, la query a la DB también se cancela.
type Repository interface {
	// Save persiste una nota (insert o update según exista).
	Save(ctx context.Context, n *Note) error

	// FindByID recupera una nota. Retorna ErrNotFound si no existe.
	FindByID(ctx context.Context, id string) (*Note, error)

	// FindAll recupera todas las notas (en producción: paginar).
	FindAll(ctx context.Context) ([]*Note, error)

	// Delete elimina una nota. Retorna ErrNotFound si no existe.
	Delete(ctx context.Context, id string) error
}

Paso 4.4 — Commit del dominio

git add internal/domain
git commit -m "feat(domain): add Note entity, repository port and domain errors"

---

Fase 5: Capa de Aplicación (Use Cases)

Filosofía: La aplicación es el director de orquesta. No toca los instrumentos (dominio) ni el sonido físico (infraestructura), pero coordina la sinfonía.

Paso 5.1 — El Service y los DTOs (internal/application/note_service.go)

package application

import (
	"context"
	"crypto/rand"
	"encoding/hex"
	"fmt"

	"github.com/tu-usuario/notes-api/internal/domain/note"
)

// --- DTOs: contratos de datos en la frontera de la aplicación ---
// Separamos DTOs de entidades de dominio. Esto desacopla la API pública
// de la estructura interna. La entidad puede evolucionar sin romper la API.

type CreateNoteInput struct {
	Title   string
	Content string
}

type UpdateNoteInput struct {
	ID      string
	Title   string
	Content string
}

// NoteOutput es la representación de salida (read model).
type NoteOutput struct {
	ID        string
	Title     string
	Content   string
	CreatedAt string // ISO 8601
	UpdatedAt string
}

// NoteService implementa los casos de uso del sistema.
// Depende del PUERTO (note.Repository), no de una implementación concreta.
// Esto es Inversión de Dependencias (la D de SOLID): el detalle (SQLite)
// depende de la abstracción (interface), no al revés.
type NoteService struct {
	repo note.Repository
}

// NewNoteService inyecta la dependencia vía constructor (DI manual).
func NewNoteService(repo note.Repository) *NoteService {
	return &NoteService{repo: repo}
}

// Create: caso de uso de creación.
func (s *NoteService) Create(ctx context.Context, in CreateNoteInput) (*NoteOutput, error) {
	id, err := generateID()
	if err != nil {
		return nil, fmt.Errorf("application: failed to generate id: %w", err)
	}

	// El dominio valida las invariantes; la app solo orquesta.
	n, err := note.New(id, in.Title, in.Content)
	if err != nil {
		return nil, err // Error de dominio se propaga tal cual
	}

	if err := s.repo.Save(ctx, n); err != nil {
		return nil, fmt.Errorf("application: failed to save note: %w", err)
	}

	return toOutput(n), nil
}

// GetByID: caso de uso de lectura.
func (s *NoteService) GetByID(ctx context.Context, id string) (*NoteOutput, error) {
	n, err := s.repo.FindByID(ctx, id)
	if err != nil {
		return nil, err // ErrNotFound se propaga
	}
	return toOutput(n), nil
}

// List: caso de uso de listado.
func (s *NoteService) List(ctx context.Context) ([]*NoteOutput, error) {
	notes, err := s.repo.FindAll(ctx)
	if err != nil {
		return nil, fmt.Errorf("application: failed to list notes: %w", err)
	}

	out := make([]*NoteOutput, 0, len(notes))
	for _, n := range notes {
		out = append(out, toOutput(n))
	}
	return out, nil
}

// Update: caso de uso de actualización.
// Patrón: cargar -> mutar -> persistir. Garantiza que las invariantes
// del dominio se respeten incluso en updates parciales.
func (s *NoteService) Update(ctx context.Context, in UpdateNoteInput) (*NoteOutput, error) {
	n, err := s.repo.FindByID(ctx, in.ID)
	if err != nil {
		return nil, err
	}

	if err := n.UpdateContent(in.Title, in.Content); err != nil {
		return nil, err
	}

	if err := s.repo.Save(ctx, n); err != nil {
		return nil, fmt.Errorf("application: failed to update note: %w", err)
	}

	return toOutput(n), nil
}

// Delete: caso de uso de eliminación.
func (s *NoteService) Delete(ctx context.Context, id string) error {
	if err := s.repo.Delete(ctx, id); err != nil {
		return err
	}
	return nil
}

// --- Helpers internos ---

// toOutput mapea Entity -> DTO. Frontera de traducción.
func toOutput(n *note.Note) *NoteOutput {
	return &NoteOutput{
		ID:        n.ID(),
		Title:     n.Title(),
		Content:   n.Content(),
		CreatedAt: n.CreatedAt().Format("2006-01-02T15:04:05Z07:00"),
		UpdatedAt: n.UpdatedAt().Format("2006-01-02T15:04:05Z07:00"),
	}
}

// generateID crea un identificador aleatorio de 16 bytes (128 bits).
// Usamos crypto/rand (no math/rand) porque los IDs deben ser
// impredecibles para evitar enumeración. Sin dependencias externas (UUID).
func generateID() (string, error) {
	b := make([]byte, 16)
	if _, err := rand.Read(b); err != nil {
		return "", err
	}
	return hex.EncodeToString(b), nil
}

Paso 5.2 — Commit

git add internal/application
git commit -m "feat(application): add NoteService with CRUD use cases and DTOs"

---

Fase 6: Infraestructura — Adaptador SQLite

Decisión técnica honesta: Go no trae un driver SQLite en la stdlib. Tienes dos caminos:

Opción	Pros	Contras
modernc.org/sqlite	Go puro, sin CGO, multiplataforma	1 dependencia
mattn/go-sqlite3	Maduro, rápido	Requiere CGO + compilador C

Como pediste sin dependencias, lo idealmente puro sería implementar persistencia en memoria o en archivo plano. Pero SQLite real requiere un driver. Usaré modernc.org/sqlite (Go puro, lo más cercano a “sin dependencias nativas”). Si quieres CERO dependencias, el adaptador in-memory es el siguiente paso natural.

Paso 6.1 — Agregar el driver

go get modernc.org/sqlite

Paso 6.2 — Conexión y migraciones (internal/infrastructure/persistence/sqlite/connection.go)

package sqlite

import (
	"context"
	"database/sql"
	"fmt"
	"time"

	_ "modernc.org/sqlite" // Driver registrado vía side-effect import
)

// NewConnection abre y configura la conexión a SQLite.
// Decisiones de configuración explicadas inline.
func NewConnection(ctx context.Context, dsn string) (*sql.DB, error) {
	// El driver se llama "sqlite" (no "sqlite3") en modernc.
	db, err := sql.Open("sqlite", dsn)
	if err != nil {
		return nil, fmt.Errorf("sqlite: failed to open: %w", err)
	}

	// SQLite es un archivo único: múltiples escritores causan "database is locked".
	// Limitamos a 1 conexión para serializar escrituras y evitar el error.
	// Este es el trade-off de SQLite: simplicidad a costa de concurrencia de escritura.
	db.SetMaxOpenConns(1)

	// Verificamos conectividad con timeout.
	pingCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()
	if err := db.PingContext(pingCtx); err != nil {
		return nil, fmt.Errorf("sqlite: failed to ping: %w", err)
	}

	// Habilitamos foreign keys y WAL para mejor concurrencia de lectura.
	if _, err := db.ExecContext(ctx, `PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON;`); err != nil {
		return nil, fmt.Errorf("sqlite: failed to set pragmas: %w", err)
	}

	if err := migrate(ctx, db); err != nil {
		return nil, err
	}

	return db, nil
}

// migrate crea el schema si no existe.
// En proyectos grandes usarías migraciones versionadas; aquí es idempotente y simple.
func migrate(ctx context.Context, db *sql.DB) error {
	const schema = `
    CREATE TABLE IF NOT EXISTS notes (
        id         TEXT PRIMARY KEY,
        title      TEXT NOT NULL,
        content    TEXT NOT NULL DEFAULT '',
        created_at TEXT NOT NULL,
        updated_at TEXT NOT NULL
    );`

	if _, err := db.ExecContext(ctx, schema); err != nil {
		return fmt.Errorf("sqlite: migration failed: %w", err)
	}
	return nil
}

Paso 6.3 — El Repository concreto (internal/infrastructure/persistence/sqlite/note_repo.go)

package sqlite

import (
	"context"
	"database/sql"
	"errors"
	"fmt"
	"time"

	"github.com/tu-usuario/notes-api/internal/domain/note"
)

// timeLayout es el formato ISO 8601 que SQLite almacena como TEXT.
const timeLayout = time.RFC3339

// NoteRepository es el DRIVEN ADAPTER que implementa note.Repository.
// Traduce entre el lenguaje del dominio (Note) y el de la DB (filas SQL).
//
// Verificación en compile-time de que implementa el puerto:
var _ note.Repository = (*NoteRepository)(nil)

type NoteRepository struct {
	db *sql.DB
}

func NewNoteRepository(db *sql.DB) *NoteRepository {
	return &NoteRepository{db: db}
}

// Save usa UPSERT: inserta o actualiza según la PK exista.
// SQLite soporta ON CONFLICT DO UPDATE desde la versión 3.24.
func (r *NoteRepository) Save(ctx context.Context, n *note.Note) error {
	const query = `
        INSERT INTO notes (id, title, content, created_at, updated_at)
        VALUES (?, ?, ?, ?, ?)
        ON CONFLICT(id) DO UPDATE SET
            title      = excluded.title,
            content    = excluded.content,
            updated_at = excluded.updated_at;`

	_, err := r.db.ExecContext(ctx, query,
		n.ID(),
		n.Title(),
		n.Content(),
		n.CreatedAt().Format(timeLayout),
		n.UpdatedAt().Format(timeLayout),
	)
	if err != nil {
		return fmt.Errorf("sqlite: save failed: %w", err)
	}
	return nil
}

func (r *NoteRepository) FindByID(ctx context.Context, id string) (*note.Note, error) {
	const query = `SELECT id, title, content, created_at, updated_at FROM notes WHERE id = ?;`

	row := r.db.QueryRowContext(ctx, query, id)
	n, err := scanNote(row)
	if err != nil {
		if errors.Is(err, sql.ErrNoRows) {
			// Traducimos el error técnico de SQL al error de DOMINIO.
			// La capa superior nunca sabrá que existe "sql.ErrNoRows".
			return nil, note.ErrNotFound
		}
		return nil, fmt.Errorf("sqlite: find failed: %w", err)
	}
	return n, nil
}

func (r *NoteRepository) FindAll(ctx context.Context) ([]*note.Note, error) {
	const query = `SELECT id, title, content, created_at, updated_at FROM notes ORDER BY created_at DESC;`

	rows, err := r.db.QueryContext(ctx, query)
	if err != nil {
		return nil, fmt.Errorf("sqlite: findall query failed: %w", err)
	}
	defer rows.Close() // CRÍTICO: liberar recursos siempre

	var notes []*note.Note
	for rows.Next() {
		n, err := scanNote(rows)
		if err != nil {
			return nil, fmt.Errorf("sqlite: scan failed: %w", err)
		}
		notes = append(notes, n)
	}

	// rows.Err() captura errores que ocurren DURANTE la iteración (no en Next()).
	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("sqlite: rows iteration error: %w", err)
	}
	return notes, nil
}

func (r *NoteRepository) Delete(ctx context.Context, id string) error {
	const query = `DELETE FROM notes WHERE id = ?;`

	res, err := r.db.ExecContext(ctx, query, id)
	if err != nil {
		return fmt.Errorf("sqlite: delete failed: %w", err)
	}

	// Verificamos que algo se haya borrado; si no, la nota no existía.
	affected, err := res.RowsAffected()
	if err != nil {
		return fmt.Errorf("sqlite: rows affected check failed: %w", err)
	}
	if affected == 0 {
		return note.ErrNotFound
	}
	return nil
}

// scanner abstrae *sql.Row y *sql.Rows (ambos tienen Scan).
// Permite reutilizar scanNote en queries de uno o muchos resultados.
type scanner interface {
	Scan(dest ...any) error
}

// scanNote mapea una fila SQL a una Entidad de dominio.
// Usa Reconstitute (no New) porque los datos ya fueron validados al insertarse.
func scanNote(s scanner) (*note.Note, error) {
	var id, title, content, createdStr, updatedStr string

	if err := s.Scan(&id, &title, &content, &createdStr, &updatedStr); err != nil {
		return nil, err
	}

	createdAt, err := time.Parse(timeLayout, createdStr)
	if err != nil {
		return nil, fmt.Errorf("sqlite: invalid created_at format: %w", err)
	}
	updatedAt, err := time.Parse(timeLayout, updatedStr)
	if err != nil {
		return nil, fmt.Errorf("sqlite: invalid updated_at format: %w", err)
	}

	return note.Reconstitute(id, title, content, createdAt, updatedAt), nil
}

Patrón clave aquí — Traducción de errores: El adaptador convierte sql.ErrNoRows → note.ErrNotFound. El dominio nunca conoce SQL. Esta es la membrana semántica entre capas.

Paso 6.4 — Commit

git add internal/infrastructure/persistence go.mod go.sum
git commit -m "feat(infra): add SQLite connection, migrations and note repository"

---

Fase 7: Infraestructura — Adaptador HTTP

Paso 7.1 — Helpers de respuesta JSON (internal/infrastructure/http/response.go)

package http

import (
	"encoding/json"
	"log/slog"
	"net/http"
)

// writeJSON serializa y escribe una respuesta JSON con el status dado.
// Centralizar esto evita repetir headers y manejo de errores de encoding.
func writeJSON(w http.ResponseWriter, status int, payload any) {
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	w.WriteHeader(status)

	if payload == nil {
		return
	}

	if err := json.NewEncoder(w).Encode(payload); err != nil {
		// Si falla el encoding, el header ya se envió: solo logueamos.
		slog.Error("failed to encode response", "error", err)
	}
}

// errorResponse es el contrato uniforme de errores de la API.
type errorResponse struct {
	Error   string `json:"error"`
	Message string `json:"message,omitempty"`
}

func writeError(w http.ResponseWriter, status int, message string) {
	writeJSON(w, status, errorResponse{
		Error:   http.StatusText(status),
		Message: message,
	})
}

Paso 7.2 — El Handler / Driving Adapter (internal/infrastructure/http/note_handler.go)

package http

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

	"github.com/tu-usuario/notes-api/internal/application"
	"github.com/tu-usuario/notes-api/internal/domain/note"
)

// NoteHandler es el DRIVING ADAPTER: traduce HTTP <-> casos de uso.
// Depende del service de aplicación, no del dominio directamente.
type NoteHandler struct {
	service *application.NoteService
}

func NewNoteHandler(service *application.NoteService) *NoteHandler {
	return &NoteHandler{service: service}
}

// --- DTOs de transporte HTTP (request bodies) ---

type createNoteRequest struct {
	Title   string `json:"title"`
	Content string `json:"content"`
}

type updateNoteRequest struct {
	Title   string `json:"title"`
	Content string `json:"content"`
}

// Create maneja POST /notes
func (h *NoteHandler) Create(w http.ResponseWriter, r *http.Request) {
	var req createNoteRequest
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		writeError(w, http.StatusBadRequest, "invalid JSON body")
		return
	}

	out, err := h.service.Create(r.Context(), application.CreateNoteInput{
		Title:   req.Title,
		Content: req.Content,
	})
	if err != nil {
		h.handleDomainError(w, err)
		return
	}

	writeJSON(w, http.StatusCreated, out)
}

// Get maneja GET /notes/{id}
func (h *NoteHandler) Get(w http.ResponseWriter, r *http.Request) {
	// r.PathValue extrae wildcards del router de Go 1.22. Sin frameworks.
	id := r.PathValue("id")

	out, err := h.service.GetByID(r.Context(), id)
	if err != nil {
		h.handleDomainError(w, err)
		return
	}

	writeJSON(w, http.StatusOK, out)
}

// List maneja GET /notes
func (h *NoteHandler) List(w http.ResponseWriter, r *http.Request) {
	out, err := h.service.List(r.Context())
	if err != nil {
		h.handleDomainError(w, err)
		return
	}

	writeJSON(w, http.StatusOK, out)
}

// Update maneja PUT /notes/{id}
func (h *NoteHandler) Update(w http.ResponseWriter, r *http.Request) {
	id := r.PathValue("id")

	var req updateNoteRequest
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		writeError(w, http.StatusBadRequest, "invalid JSON body")
		return
	}

	out, err := h.service.Update(r.Context(), application.UpdateNoteInput{
		ID:      id,
		Title:   req.Title,
		Content: req.Content,
	})
	if err != nil {
		h.handleDomainError(w, err)
		return
	}

	writeJSON(w, http.StatusOK, out)
}

// Delete maneja DELETE /notes/{id}
func (h *NoteHandler) Delete(w http.ResponseWriter, r *http.Request) {
	id := r.PathValue("id")

	if err := h.service.Delete(r.Context(), id); err != nil {
		h.handleDomainError(w, err)
		return
	}

	writeJSON(w, http.StatusNoContent, nil)
}

// handleDomainError mapea errores de DOMINIO a códigos HTTP.
// Este es el punto único de traducción error-de-negocio -> status-HTTP.
// Usar errors.Is permite comparar errores envueltos (%w) correctamente.
func (h *NoteHandler) handleDomainError(w http.ResponseWriter, err error) {
	switch {
	case errors.Is(err, note.ErrNotFound):
		writeError(w, http.StatusNotFound, err.Error())
	case errors.Is(err, note.ErrEmptyTitle),
		errors.Is(err, note.ErrTitleTooLong),
		errors.Is(err, note.ErrInvalidID):
		writeError(w, http.StatusUnprocessableEntity, err.Error())
	default:
		// Error inesperado: no exponemos detalles internos al cliente.
		writeError(w, http.StatusInternalServerError, "internal server error")
	}
}

Tabla de mapeo Error → HTTP (la lógica de handleDomainError):

Error de dominio	Status HTTP	Semántica
ErrNotFound	404	El recurso no existe
ErrEmptyTitle, ErrTitleTooLong	422	Entidad procesable pero inválida
ErrInvalidID	422	Validación de negocio falló
JSON malformado	400	Sintaxis de petición inválida
Error técnico (DB)	500	Fallo interno, no exponer detalles

Paso 7.3 — El Router (internal/infrastructure/http/router.go)

package http

import "net/http"

// NewRouter configura las rutas usando el enhanced routing de Go 1.22.
// El patrón "METHOD /path/{param}" es nativo: sin gorilla/mux ni chi.
func NewRouter(h *NoteHandler) http.Handler {
	mux := http.NewServeMux()

	// El router de stdlib distingue por método HTTP desde 1.22.
	mux.HandleFunc("POST /notes", h.Create)
	mux.HandleFunc("GET /notes", h.List)
	mux.HandleFunc("GET /notes/{id}", h.Get)
	mux.HandleFunc("PUT /notes/{id}", h.Update)
	mux.HandleFunc("DELETE /notes/{id}", h.Delete)

	// Health check para readiness/liveness probes (Azure, Kubernetes).
	mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
		writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
	})

	// Aplicamos middleware en cadena (logging). Composición de funciones.
	return loggingMiddleware(mux)
}

// loggingMiddleware envuelve el handler para registrar cada request.
// Patrón decorator: una función que toma y devuelve http.Handler.
func loggingMiddleware(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// Aquí podrías inyectar request-id, medir latencia, etc.
		next.ServeHTTP(w, r)
	})
}

Paso 7.4 — Commit

git add internal/infrastructure/http
git commit -m "feat(infra): add HTTP handlers, router and JSON helpers"

---

Fase 8: Configuración

Paso 8.1 — Config (internal/config/config.go)

package config

import "os"

// Config centraliza la configuración leída del entorno.
// Patrón 12-factor: la config vive en variables de entorno, no en código.
type Config struct {
	Port        string
	DatabaseDSN string
}

// Load lee la configuración con valores por defecto sensatos.
func Load() Config {
	return Config{
		Port:        getEnv("PORT", "8080"),
		DatabaseDSN: getEnv("DATABASE_DSN", "notes.db"),
	}
}

func getEnv(key, fallback string) string {
	if v, ok := os.LookupEnv(key); ok && v != "" {
		return v
	}
	return fallback
}

---

Fase 9: Composition Root — El Ensamblaje

Concepto: El main.go es el único lugar donde las capas se conocen entre sí. Aquí inyectamos las dependencias concretas. Es el “Big Bang” del sistema: el punto donde toda la materia (componentes) se ensambla.

Paso 9.1 — cmd/api/main.go

package main

import (
	"context"
	"errors"
	"log/slog"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"

	"github.com/tu-usuario/notes-api/internal/application"
	"github.com/tu-usuario/notes-api/internal/config"
	httpadapter "github.com/tu-usuario/notes-api/internal/infrastructure/http"
	"github.com/tu-usuario/notes-api/internal/infrastructure/persistence/sqlite"
)

func main() {
	// Logger estructurado de la stdlib (Go 1.21+). Sin logrus/zap.
	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
	slog.SetDefault(logger)

	if err := run(); err != nil {
		slog.Error("fatal error", "error", err)
		os.Exit(1)
	}
}

// run separa la lógica de main para poder retornar errores limpiamente.
// Patrón idiomático Go: main solo loguea y sale; run hace el trabajo.
func run() error {
	cfg := config.Load()

	// Contexto raíz que se cancela ante señales del SO (SIGINT/SIGTERM).
	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer stop()

	// --- WIRING: ensamblaje de dependencias de adentro hacia afuera ---

	// 1. Infraestructura: conexión a la DB (driven adapter)
	db, err := sqlite.NewConnection(ctx, cfg.DatabaseDSN)
	if err != nil {
		return err
	}
	defer db.Close()

	// 2. Repository concreto implementando el puerto del dominio
	repo := sqlite.NewNoteRepository(db)

	// 3. Application: caso de uso, recibe el puerto (interface)
	service := application.NewNoteService(repo)

	// 4. Driving adapter: handler HTTP, recibe el service
	handler := httpadapter.NewNoteHandler(service)

	// 5. Router que cablea rutas a handlers
	router := httpadapter.NewRouter(handler)

	// --- Servidor HTTP con timeouts (defensa contra slowloris) ---
	srv := &http.Server{
		Addr:              ":" + cfg.Port,
		Handler:           router,
		ReadHeaderTimeout: 5 * time.Second, // Mitiga ataques de headers lentos
		ReadTimeout:       10 * time.Second,
		WriteTimeout:      10 * time.Second,
		IdleTimeout:       60 * time.Second,
	}

	// Lanzamos el servidor en una goroutine para no bloquear el graceful shutdown.
	serverErr := make(chan error, 1)
	go func() {
		slog.Info("server starting", "port", cfg.Port)
		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
			serverErr <- err
		}
	}()

	// --- GRACEFUL SHUTDOWN ---
	// Esperamos: o un error del servidor, o una señal de terminación.
	select {
	case err := <-serverErr:
		return err
	case <-ctx.Done():
		slog.Info("shutdown signal received")
	}

	// Damos 10s para que las requests en vuelo terminen antes de morir.
	// Es la "muerte digna" del proceso: no cortamos conexiones abruptamente.
	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	if err := srv.Shutdown(shutdownCtx); err != nil {
		return err
	}

	slog.Info("server stopped gracefully")
	return nil
}

Graceful Shutdown — Filosofía Estoica: “Acepta el fin con dignidad.” Cuando llega SIGTERM (ej. Azure reiniciando el contenedor), no abandonamos a los clientes a mitad de petición. Drenamos las conexiones activas durante 10 segundos, luego morimos limpiamente.

---

Fase 10: Compilar, Ejecutar y Probar

Paso 10.1 — Verificar que todo compila

go build ./...

Paso 10.2 — Limpiar dependencias

go mod tidy

Paso 10.3 — Ejecutar

go run ./cmd/api
# O con config custom:
PORT=9000 DATABASE_DSN=mynotes.db go run ./cmd/api

Paso 10.4 — Probar con curl (cada endpoint del CRUD)

# CREATE
curl -X POST http://localhost:8080/notes \
  -H "Content-Type: application/json" \
  -d '{"title":"Mi primera nota","content":"Contenido de prueba"}'

# LIST
curl http://localhost:8080/notes

# GET (reemplaza {id} con el ID retornado al crear)
curl http://localhost:8080/notes/{id}

# UPDATE
curl -X PUT http://localhost:8080/notes/{id} \
  -H "Content-Type: application/json" \
  -d '{"title":"Título editado","content":"Nuevo contenido"}'

# DELETE
curl -X DELETE http://localhost:8080/notes/{id}

# Probar validación (debe dar 422)
curl -X POST http://localhost:8080/notes \
  -H "Content-Type: application/json" \
  -d '{"title":"","content":"sin título"}'

Paso 10.5 — Commit final

git add .
git commit -m "feat: wire composition root with graceful shutdown"

---

Apéndice: El Flujo de una Petición (Diagrama Mental)

Cliente (curl)
   │  POST /notes {"title":"X"}
   ▼
[Router]  ──── match "POST /notes" ────► NoteHandler.Create
   │
   ▼
[Handler]  decode JSON → CreateNoteInput
   │  llama service.Create(ctx, input)
   ▼
[Service]  generateID() → note.New() ◄── DOMINIO valida invariantes
   │  llama repo.Save(ctx, note)
   ▼
[Repository SQLite]  traduce Note → INSERT SQL
   │  ejecuta en DB
   ▼
[Vuelta]  Note → NoteOutput (DTO) → JSON → HTTP 201 Created
   │
   ▼
Cliente recibe respuesta

El flujo de control es unidireccional hacia el dominio y vuelve. Las dependencias apuntan hacia adentro (regla de dependencia de Clean Architecture). El dominio es el centro inmóvil; todo gira a su alrededor.

---

Tabla Resumen: Orden de Construcción Ideal

#	Capa	Por qué este orden
1	Domain (entity, errors, port)	Es el núcleo; nada depende de afuera. Empieza por la verdad del negocio.
2	Application (service, DTOs)	Orquesta el dominio; depende solo de puertos.
3	Infrastructure persistence	Implementa el puerto definido en el dominio.
4	Infrastructure HTTP	Expone los casos de uso al mundo.
5	Config	Parametriza sin tocar lógica.
6	Composition Root (main)	Ensambla todo. Lo último, porque conoce todo.

Principio de cierre (Bushido): “Construye de adentro hacia afuera. El corazón primero, la armadura al final.” El dominio se diseña en aislamiento puro; la infraestructura es intercambiable. Mañana cambias SQLite por PostgreSQL tocando solo un adaptador — el dominio ni se entera.

---

¿Quieres que profundice en testing (unit tests del dominio sin mocks + integration tests del repo con SQLite en memoria), o en cómo migrar este mismo diseño a gRPC manteniendo el dominio intacto?