theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/patrones-go/SKILL.md

@@ -0,0 +1,674 @@
+---
+name: patrones-go
+description: Patrones idiomáticos de Go, buenas prácticas y convenciones para construir aplicaciones robustas, eficientes y mantenibles.
+---
+
+# Patrones de desarrollo en Go
+
+Patrones idiomáticos de Go y buenas prácticas para construir aplicaciones robustas, eficientes y mantenibles.
+
+## Cuándo activar esta skill
+
+- Al escribir código Go nuevo
+- Al revisar código Go
+- Al refactorizar código Go existente
+- Al diseñar paquetes/módulos de Go
+
+## Principios fundamentales
+
+### 1. Simplicidad y claridad
+
+Go prefiere la simplicidad sobre la astucia. El código debe ser obvio y fácil de leer.
+
+```go
+// Bien: claro y directo
+func GetUser(id string) (*User, error) {
+    user, err := db.FindUser(id)
+    if err != nil {
+        return nil, fmt.Errorf("get user %s: %w", id, err)
+    }
+    return user, nil
+}
+
+// Mal: excesivamente rebuscado
+func GetUser(id string) (*User, error) {
+    return func() (*User, error) {
+        if u, e := db.FindUser(id); e == nil {
+            return u, nil
+        } else {
+            return nil, e
+        }
+    }()
+}
+```
+
+### 2. Haz útil el valor cero
+
+Diseña los tipos de forma que su valor cero sea usable de inmediato sin inicialización.
+
+```go
+// Bien: el valor cero es útil
+type Counter struct {
+    mu    sync.Mutex
+    count int // el valor cero es 0, listo para usar
+}
+
+func (c *Counter) Inc() {
+    c.mu.Lock()
+    c.count++
+    c.mu.Unlock()
+}
+
+// Bien: bytes.Buffer funciona con su valor cero
+var buf bytes.Buffer
+buf.WriteString("hello")
+
+// Mal: requiere inicialización
+type BadCounter struct {
+    counts map[string]int // un map nil provocará panic
+}
+```
+
+### 3. Acepta interfaces, devuelve structs
+
+Las funciones deben aceptar parámetros de tipo interface y devolver tipos concretos.
+
+```go
+// Bien: acepta una interface, devuelve un tipo concreto
+func ProcessData(r io.Reader) (*Result, error) {
+    data, err := io.ReadAll(r)
+    if err != nil {
+        return nil, err
+    }
+    return &Result{Data: data}, nil
+}
+
+// Mal: devuelve una interface (oculta innecesariamente los detalles de implementación)
+func ProcessData(r io.Reader) (io.Reader, error) {
+    // ...
+}
+```
+
+## Patrones de manejo de errores
+
+### Envolver errores con contexto
+
+```go
+// Bien: envolver los errores con contexto
+func LoadConfig(path string) (*Config, error) {
+    data, err := os.ReadFile(path)
+    if err != nil {
+        return nil, fmt.Errorf("load config %s: %w", path, err)
+    }
+
+    var cfg Config
+    if err := json.Unmarshal(data, &cfg); err != nil {
+        return nil, fmt.Errorf("parse config %s: %w", path, err)
+    }
+
+    return &cfg, nil
+}
+```
+
+### Tipos de error personalizados
+
+```go
+// Definir errores específicos del dominio
+type ValidationError struct {
+    Field   string
+    Message string
+}
+
+func (e *ValidationError) Error() string {
+    return fmt.Sprintf("validation failed on %s: %s", e.Field, e.Message)
+}
+
+// Errores centinela para casos comunes
+var (
+    ErrNotFound     = errors.New("resource not found")
+    ErrUnauthorized = errors.New("unauthorized")
+    ErrInvalidInput = errors.New("invalid input")
+)
+```
+
+### Comprobación de errores con errors.Is y errors.As
+
+```go
+func HandleError(err error) {
+    // Comprobar un error específico
+    if errors.Is(err, sql.ErrNoRows) {
+        log.Println("No se encontraron registros")
+        return
+    }
+
+    // Comprobar el tipo de error
+    var validationErr *ValidationError
+    if errors.As(err, &validationErr) {
+        log.Printf("Error de validación en el campo %s: %s",
+            validationErr.Field, validationErr.Message)
+        return
+    }
+
+    // Error desconocido
+    log.Printf("Error inesperado: %v", err)
+}
+```
+
+### Nunca ignores los errores
+
+```go
+// Mal: ignorar el error con el identificador en blanco
+result, _ := doSomething()
+
+// Bien: manejarlo o documentar explícitamente por qué es seguro ignorarlo
+result, err := doSomething()
+if err != nil {
+    return err
+}
+
+// Aceptable: cuando el error realmente no importa (raro)
+_ = writer.Close() // Limpieza de mejor esfuerzo; el error se registra en otro lugar
+```
+
+## Patrones de concurrencia
+
+### Worker pool
+
+```go
+func WorkerPool(jobs <-chan Job, results chan<- Result, numWorkers int) {
+    var wg sync.WaitGroup
+
+    for i := 0; i < numWorkers; i++ {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            for job := range jobs {
+                results <- process(job)
+            }
+        }()
+    }
+
+    wg.Wait()
+    close(results)
+}
+```
+
+### Context para cancelación y timeouts
+
+```go
+func FetchWithTimeout(ctx context.Context, url string) ([]byte, error) {
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+    defer cancel()
+
+    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+    if err != nil {
+        return nil, fmt.Errorf("create request: %w", err)
+    }
+
+    resp, err := http.DefaultClient.Do(req)
+    if err != nil {
+        return nil, fmt.Errorf("fetch %s: %w", url, err)
+    }
+    defer resp.Body.Close()
+
+    return io.ReadAll(resp.Body)
+}
+```
+
+### Apagado ordenado (graceful shutdown)
+
+```go
+func GracefulShutdown(server *http.Server) {
+    quit := make(chan os.Signal, 1)
+    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+
+    <-quit
+    log.Println("Apagando el servidor...")
+
+    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+    defer cancel()
+
+    if err := server.Shutdown(ctx); err != nil {
+        log.Fatalf("El servidor se vio forzado a apagarse: %v", err)
+    }
+
+    log.Println("Servidor detenido")
+}
+```
+
+### errgroup para goroutines coordinadas
+
+```go
+import "golang.org/x/sync/errgroup"
+
+func FetchAll(ctx context.Context, urls []string) ([][]byte, error) {
+    g, ctx := errgroup.WithContext(ctx)
+    results := make([][]byte, len(urls))
+
+    for i, url := range urls {
+        i, url := i, url // Capturar las variables del bucle
+        g.Go(func() error {
+            data, err := FetchWithTimeout(ctx, url)
+            if err != nil {
+                return err
+            }
+            results[i] = data
+            return nil
+        })
+    }
+
+    if err := g.Wait(); err != nil {
+        return nil, err
+    }
+    return results, nil
+}
+```
+
+### Evitar fugas de goroutines
+
+```go
+// Mal: fuga de goroutine si el contexto se cancela
+func leakyFetch(ctx context.Context, url string) <-chan []byte {
+    ch := make(chan []byte)
+    go func() {
+        data, _ := fetch(url)
+        ch <- data // Se bloquea para siempre si no hay receptor
+    }()
+    return ch
+}
+
+// Bien: maneja correctamente la cancelación
+func safeFetch(ctx context.Context, url string) <-chan []byte {
+    ch := make(chan []byte, 1) // Canal con buffer
+    go func() {
+        data, err := fetch(url)
+        if err != nil {
+            return
+        }
+        select {
+        case ch <- data:
+        case <-ctx.Done():
+        }
+    }()
+    return ch
+}
+```
+
+## Diseño de interfaces
+
+### Interfaces pequeñas y enfocadas
+
+```go
+// Bien: interfaces de un solo método
+type Reader interface {
+    Read(p []byte) (n int, err error)
+}
+
+type Writer interface {
+    Write(p []byte) (n int, err error)
+}
+
+type Closer interface {
+    Close() error
+}
+
+// Componer interfaces según se necesite
+type ReadWriteCloser interface {
+    Reader
+    Writer
+    Closer
+}
+```
+
+### Define las interfaces donde se usan
+
+```go
+// En el paquete consumidor, no en el proveedor
+package service
+
+// UserStore define lo que este servicio necesita
+type UserStore interface {
+    GetUser(id string) (*User, error)
+    SaveUser(user *User) error
+}
+
+type Service struct {
+    store UserStore
+}
+
+// La implementación concreta puede estar en otro paquete
+// No necesita conocer esta interface
+```
+
+### Comportamiento opcional con aserciones de tipo
+
+```go
+type Flusher interface {
+    Flush() error
+}
+
+func WriteAndFlush(w io.Writer, data []byte) error {
+    if _, err := w.Write(data); err != nil {
+        return err
+    }
+
+    // Hacer flush si está soportado
+    if f, ok := w.(Flusher); ok {
+        return f.Flush()
+    }
+    return nil
+}
+```
+
+## Organización de paquetes
+
+### Estructura estándar de proyecto
+
+```text
+myproject/
+├── cmd/
+│   └── myapp/
+│       └── main.go           # Punto de entrada
+├── internal/
+│   ├── handler/              # Handlers HTTP
+│   ├── service/              # Lógica de negocio
+│   ├── repository/           # Acceso a datos
+│   └── config/               # Configuración
+├── pkg/
+│   └── client/               # Cliente de API público
+├── api/
+│   └── v1/                   # Definiciones de API (proto, OpenAPI)
+├── testdata/                 # Fixtures de test
+├── go.mod
+├── go.sum
+└── Makefile
+```
+
+### Nombres de paquetes
+
+```go
+// Bien: cortos, en minúsculas, sin guiones bajos
+package http
+package json
+package user
+
+// Mal: verbosos, con mayúsculas mezcladas o redundantes
+package httpHandler
+package json_parser
+package userService // Sufijo 'Service' redundante
+```
+
+### Evita el estado a nivel de paquete
+
+```go
+// Mal: estado global mutable
+var db *sql.DB
+
+func init() {
+    db, _ = sql.Open("postgres", os.Getenv("DATABASE_URL"))
+}
+
+// Bien: inyección de dependencias
+type Server struct {
+    db *sql.DB
+}
+
+func NewServer(db *sql.DB) *Server {
+    return &Server{db: db}
+}
+```
+
+## Diseño de structs
+
+### Patrón de opciones funcionales
+
+```go
+type Server struct {
+    addr    string
+    timeout time.Duration
+    logger  *log.Logger
+}
+
+type Option func(*Server)
+
+func WithTimeout(d time.Duration) Option {
+    return func(s *Server) {
+        s.timeout = d
+    }
+}
+
+func WithLogger(l *log.Logger) Option {
+    return func(s *Server) {
+        s.logger = l
+    }
+}
+
+func NewServer(addr string, opts ...Option) *Server {
+    s := &Server{
+        addr:    addr,
+        timeout: 30 * time.Second, // valor por defecto
+        logger:  log.Default(),    // valor por defecto
+    }
+    for _, opt := range opts {
+        opt(s)
+    }
+    return s
+}
+
+// Uso
+server := NewServer(":8080",
+    WithTimeout(60*time.Second),
+    WithLogger(customLogger),
+)
+```
+
+### Embedding para composición
+
+```go
+type Logger struct {
+    prefix string
+}
+
+func (l *Logger) Log(msg string) {
+    fmt.Printf("[%s] %s\n", l.prefix, msg)
+}
+
+type Server struct {
+    *Logger // Embedding: Server obtiene el método Log
+    addr    string
+}
+
+func NewServer(addr string) *Server {
+    return &Server{
+        Logger: &Logger{prefix: "SERVER"},
+        addr:   addr,
+    }
+}
+
+// Uso
+s := NewServer(":8080")
+s.Log("Iniciando...") // Llama al Log del Logger embebido
+```
+
+## Memoria y rendimiento
+
+### Prealoca slices cuando el tamaño es conocido
+
+```go
+// Mal: el slice crece varias veces
+func processItems(items []Item) []Result {
+    var results []Result
+    for _, item := range items {
+        results = append(results, process(item))
+    }
+    return results
+}
+
+// Bien: una sola asignación
+func processItems(items []Item) []Result {
+    results := make([]Result, 0, len(items))
+    for _, item := range items {
+        results = append(results, process(item))
+    }
+    return results
+}
+```
+
+### Usa sync.Pool para asignaciones frecuentes
+
+```go
+var bufferPool = sync.Pool{
+    New: func() interface{} {
+        return new(bytes.Buffer)
+    },
+}
+
+func ProcessRequest(data []byte) []byte {
+    buf := bufferPool.Get().(*bytes.Buffer)
+    defer func() {
+        buf.Reset()
+        bufferPool.Put(buf)
+    }()
+
+    buf.Write(data)
+    // Procesar...
+    return buf.Bytes()
+}
+```
+
+### Evita la concatenación de strings en bucles
+
+```go
+// Mal: crea muchas asignaciones de strings
+func join(parts []string) string {
+    var result string
+    for _, p := range parts {
+        result += p + ","
+    }
+    return result
+}
+
+// Bien: una sola asignación con strings.Builder
+func join(parts []string) string {
+    var sb strings.Builder
+    for i, p := range parts {
+        if i > 0 {
+            sb.WriteString(",")
+        }
+        sb.WriteString(p)
+    }
+    return sb.String()
+}
+
+// Mejor aún: usar la biblioteca estándar
+func join(parts []string) string {
+    return strings.Join(parts, ",")
+}
+```
+
+## Integración con las herramientas de Go
+
+### Comandos esenciales
+
+```bash
+# Compilar y ejecutar
+go build ./...
+go run ./cmd/myapp
+
+# Testing
+go test ./...
+go test -race ./...
+go test -cover ./...
+
+# Análisis estático
+go vet ./...
+staticcheck ./...
+golangci-lint run
+
+# Gestión de módulos
+go mod tidy
+go mod verify
+
+# Formateo
+gofmt -w .
+goimports -w .
+```
+
+### Configuración de linter recomendada (.golangci.yml)
+
+```yaml
+linters:
+  enable:
+    - errcheck
+    - gosimple
+    - govet
+    - ineffassign
+    - staticcheck
+    - unused
+    - gofmt
+    - goimports
+    - misspell
+    - unconvert
+    - unparam
+
+linters-settings:
+  errcheck:
+    check-type-assertions: true
+  govet:
+    enable:
+      - shadow
+
+issues:
+  exclude-use-default: false
+```
+
+## Referencia rápida: modismos de Go
+
+| Modismo | Descripción |
+|---------|-------------|
+| Acepta interfaces, devuelve structs | Las funciones aceptan parámetros de interface y devuelven tipos concretos |
+| Los errores son valores | Trata los errores como valores de primera clase, no como excepciones |
+| No te comuniques compartiendo memoria | Usa canales para coordinar goroutines |
+| Haz útil el valor cero | Los tipos deben funcionar sin inicialización explícita |
+| Un poco de copia es mejor que un poco de dependencia | Evita dependencias externas innecesarias |
+| Claro es mejor que ingenioso | Prioriza la legibilidad sobre la astucia |
+| gofmt no es el favorito de nadie pero es amigo de todos | Formatea siempre con gofmt/goimports |
+| Retorna temprano | Maneja los errores primero, mantén el camino feliz sin indentar |
+
+## Antipatrones a evitar
+
+```go
+// Mal: naked returns en funciones largas
+func process() (result int, err error) {
+    // ... 50 líneas ...
+    return // ¿Qué se está devolviendo?
+}
+
+// Mal: usar panic como control de flujo
+func GetUser(id string) *User {
+    user, err := db.Find(id)
+    if err != nil {
+        panic(err) // No hagas esto
+    }
+    return user
+}
+
+// Mal: pasar el contexto dentro de un struct
+type Request struct {
+    ctx context.Context // El contexto debe ser el primer parámetro
+    ID  string
+}
+
+// Bien: contexto como primer parámetro
+func ProcessRequest(ctx context.Context, id string) error {
+    // ...
+}
+
+// Mal: mezclar receptores por valor y por puntero
+type Counter struct{ n int }
+func (c Counter) Value() int { return c.n }    // Receptor por valor
+func (c *Counter) Increment() { c.n++ }        // Receptor por puntero
+// Elige un estilo y sé consistente
+```
+
+**Recuerda**: el código Go debe ser aburrido en el mejor sentido: predecible, consistente y fácil de entender. Ante la duda, mantenlo simple.