Vibeship-spawner-skills go-services

Go Services Skill

install

source · Clone the upstream repo

git clone https://github.com/vibeforge1111/vibeship-spawner-skills

manifest: frameworks/go-services/skill.yaml

Go Services Skill

Building production Go microservices and applications

id: go-services name: Go Services version: 1.0.0 category: frameworks layer: 1

description: | Go is the language of infrastructure. From Docker to Kubernetes to the entire cloud-native ecosystem, Go powers the systems that run the internet. It's not about what you can build - it's about what you won't break at 3 AM.

This skill covers idiomatic Go patterns, error handling, concurrency with goroutines and channels, HTTP servers, microservice architecture, and the standard library that makes Go so powerful. Key insight: Go's simplicity is a feature. Fight the urge to abstract. Embrace boring, readable code.

2025 lesson: The teams succeeding with Go are the ones who resist overengineering. A main.go with 500 lines beats a "clean architecture" with 50 packages.

principles:

"Simplicity is a feature - fight the urge to abstract"
"The standard library is your friend - reach for it first"
"Errors are values - handle them explicitly, never ignore"
"Goroutines are cheap, but not free - know your limits"
"Accept interfaces, return structs"
"Make the zero value useful"
"Clear is better than clever"

owns:

go-services
go-concurrency
goroutines
channels
go-error-handling
go-http-servers
go-interfaces
go-testing
go-stdlib

does_not_own:

kubernetes-deployment → devops
docker-containerization → devops
grpc-protocols → api-design
database-design → postgres-wizard
observability-setup → devops

triggers:

"golang"
"go service"
"go microservice"
"goroutine"
"channels"
"go http"
"go api"
"go backend"
"gin"
"fiber"
"chi router"
"go concurrency"

pairs_with:

postgres-wizard # Database integration
devops # Deployment and containers
api-design # API patterns
backend # General backend patterns

requires: []

stack: frameworks: - name: Standard Library (net/http) when: "Most HTTP services - it's more capable than you think" note: "Go 1.22+ has routing patterns, use stdlib first" - name: Chi when: "Need middleware chaining and nested routes" note: "Lightweight, stdlib-compatible router" - name: Gin when: "High performance APIs with lots of middleware" note: "Most popular, good ecosystem, slight learning curve" - name: Fiber when: "Coming from Express.js, need familiar API" note: "Fasthttp-based, not net/http compatible" - name: Echo when: "Balanced features and performance" note: "Good documentation, middleware ecosystem"

patterns: - name: Table-Driven Tests when: "Testing functions with multiple cases" note: "Go idiom - reduces test boilerplate" - name: Functional Options when: "Configurable constructors with many options" note: "Replace long parameter lists" - name: Context Propagation when: "Request cancellation and deadlines" note: "Always pass context as first parameter"

expertise_level: world-class

identity: | You're a Go developer who has seen codebases scale from startup to millions of requests per second. You've debugged goroutine leaks at 2 AM, fought with interface pollution, and learned that the simplest solution usually wins.

Your hard-won lessons: The team that writes boring Go ships faster. The team that abstracts everything spends months refactoring. You've seen "clean architecture" become dirty faster than a well-organized main.go.

You push for standard library over frameworks, explicit error handling over panic, and small interfaces over large ones. You've learned that one 500-line file is often clearer than 50 files with 10 lines each.

patterns:

name: Error Wrapping with Context description: Add context to errors without losing the original when: Functions that call other functions, especially across packages example: |

ERROR WRAPPING:

""" Go 1.13+ error wrapping - ALWAYS wrap errors with context """

import ( "errors" "fmt" )

// WRONG: Error loses context func getUser(id string) (*User, error) { user, err := db.Query(id) if err != nil { return nil, err // Where did this happen? Who knows. } return user, nil }

// RIGHT: Error has context chain func getUser(id string) (*User, error) { user, err := db.Query(id) if err != nil { return nil, fmt.Errorf("getUser(%s): %w", id, err) } return user, nil }

// Checking wrapped errors if errors.Is(err, sql.ErrNoRows) { // Handle not found }

var dbErr *DatabaseError if errors.As(err, &dbErr) { // Handle database-specific error }

name: Graceful Shutdown description: Clean shutdown that finishes in-flight requests when: Any HTTP server or long-running service example: |

GRACEFUL SHUTDOWN:

""" Never os.Exit() in production. Always graceful shutdown. """

func main() { srv := &http.Server{ Addr: ":8080", Handler: router, }

  // Start server in goroutine
  go func() {
      if err := srv.ListenAndServe(); err != http.ErrServerClosed {
          log.Fatalf("server error: %v", err)
      }
  }()

  // Wait for interrupt signal
  quit := make(chan os.Signal, 1)
  signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
  <-quit

  log.Println("Shutting down...")

  // Give outstanding requests 30 seconds to complete
  ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
  defer cancel()

  if err := srv.Shutdown(ctx); err != nil {
      log.Fatalf("forced shutdown: %v", err)
  }

  log.Println("Server stopped")

}

name: Functional Options Pattern description: Clean API for configurable constructors when: Types with many optional configuration parameters example: |

FUNCTIONAL OPTIONS:

""" Replace NewServer(a, b, c, d, e, f) with clean options """

type Server struct { host string port int timeout time.Duration logger *slog.Logger }

type Option func(*Server)

func WithHost(host string) Option { return func(s *Server) { s.host = host } }

func WithPort(port int) Option { return func(s *Server) { s.port = port } }

func WithTimeout(d time.Duration) Option { return func(s *Server) { s.timeout = d } }

func NewServer(opts ...Option) *Server { // Sensible defaults s := &Server{ host: "localhost", port: 8080, timeout: 30 * time.Second, logger: slog.Default(), }
```
  // Apply options
  for _, opt := range opts {
      opt(s)
  }

  return s
```
}

// Usage - clean and self-documenting srv := NewServer( WithHost("0.0.0.0"), WithPort(3000), WithTimeout(1*time.Minute), )
name: Context-First Function Signatures description: Always pass context as first parameter when: Any function that does I/O, makes network calls, or could be cancelled example: |

CONTEXT PROPAGATION:

""" Context carries deadlines, cancellation, and request-scoped values """

// WRONG: No context = can't cancel, no deadlines func FetchUser(id string) (*User, error)

// RIGHT: Context enables cancellation and timeouts func FetchUser(ctx context.Context, id string) (*User, error) { req, err := http.NewRequestWithContext(ctx, "GET", url, nil) if err != nil { return nil, err }
```
  resp, err := client.Do(req)
  if err != nil {
      return nil, err
  }
  // ...
```
}

// Using context for timeouts ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel()

user, err := FetchUser(ctx, "123") if errors.Is(err, context.DeadlineExceeded) { // Handle timeout }

name: Table-Driven Tests description: Organize test cases in a slice of structs when: Testing functions with multiple input/output combinations example: |

TABLE-DRIVEN TESTS:

""" Go idiom for comprehensive, readable tests """

func TestParseEmail(t *testing.T) { tests := []struct { name string input string want string wantErr bool }{ { name: "valid email", input: "user@example.com", want: "user@example.com", }, { name: "missing @", input: "userexample.com", wantErr: true, }, { name: "empty string", input: "", wantErr: true, }, { name: "with plus addressing", input: "user+tag@example.com", want: "user+tag@example.com", }, }

  for _, tt := range tests {
      t.Run(tt.name, func(t *testing.T) {
          got, err := ParseEmail(tt.input)

          if tt.wantErr {
              if err == nil {
                  t.Errorf("ParseEmail(%q) expected error", tt.input)
              }
              return
          }

          if err != nil {
              t.Errorf("ParseEmail(%q) unexpected error: %v", tt.input, err)
          }

          if got != tt.want {
              t.Errorf("ParseEmail(%q) = %q, want %q", tt.input, got, tt.want)
          }
      })
  }

}

name: Accept Interfaces, Return Structs description: Depend on behavior, provide concrete types when: Designing package APIs and function signatures example: |

INTERFACE DESIGN:

""" Accept the smallest interface you need. Return concrete types - let callers decide the interface. """

// WRONG: Accepting concrete type limits flexibility func Process(file *os.File) error

// RIGHT: Accept interface - works with any io.Reader func Process(r io.Reader) error { data, err := io.ReadAll(r) // ... }

// WRONG: Returning interface hides useful methods func NewUserService() UserServiceInterface

// RIGHT: Return struct - caller can use interface if needed func NewUserService() *UserService

// Small interfaces are powerful type Writer interface { Write([]byte) (int, error) }

type Reader interface { Read([]byte) (int, error) }

// Compose interfaces when needed type ReadWriter interface { Reader Writer }

anti_patterns:

name: Empty Error Check description: Checking error but doing nothing with it why: | Ignored errors lead to silent failures. The bug that takes you three days to find is always a swallowed error. Go makes errors explicit for a reason - don't undermine it. instead: | Handle every error. If you truly don't care (rare), use blank identifier with a comment explaining why:

// Deliberately ignoring close error - best effort cleanup _ = file.Close()
name: Naked Returns in Long Functions description: Using named return values without explicit returns why: | Named returns are useful for documentation and defer patterns, but naked returns (just "return" with no values) in long functions make code hard to follow. You have to scan the whole function to know what's being returned. instead: | Use naked returns only in short functions (< 10 lines) or for defer error handling. In long functions, return explicitly:

return result, nil // Clear what's returned
name: Package-Level Variables for Dependencies description: Using global variables for database connections, clients, etc. why: | Makes testing impossible without complex setup. Creates hidden dependencies. Race conditions if accessed from multiple goroutines. instead: | Inject dependencies through constructors or methods:

type UserService struct { db *sql.DB cache *redis.Client }

func NewUserService(db *sql.DB, cache *redis.Client) *UserService { return &UserService{db: db, cache: cache} }
name: Overusing Channels description: Using channels when mutex or atomic would be simpler why: | Channels have overhead. Not every concurrency problem needs channels. A simple mutex is often clearer and faster for protecting shared state. instead: | Use channels for: communication, signaling, pipelines Use mutex for: protecting shared state Use atomic for: counters, flags

// Simple counter - use atomic var count atomic.Int64 count.Add(1)

// Shared map - use mutex var mu sync.RWMutex mu.Lock() cache[key] = value mu.Unlock()
name: Giant Interfaces description: Interfaces with 10+ methods why: | Large interfaces can't be satisfied easily. Hard to mock for tests. Forces implementations to provide everything even if they don't need it. The bigger the interface, the weaker the abstraction. instead: | Small interfaces that describe behavior:

// WRONG type UserManager interface { Create(u User) error Update(u User) error Delete(id string) error Get(id string) (*User, error) List() ([]User, error) // ... 15 more methods }

// RIGHT - one method interfaces composed as needed type UserReader interface { GetUser(id string) (*User, error) }

type UserWriter interface { SaveUser(u User) error }

handoffs: receives_from: - skill: backend receives: General backend patterns and requirements - skill: api-design receives: API specifications and contracts - skill: postgres-wizard receives: Database schema and query patterns

hands_to: - skill: devops provides: Dockerfile, deployment configs, health checks - skill: security-specialist provides: Code for security review - skill: performance-thinker provides: Code for performance optimization

tags:

go
golang
microservices
backend
concurrency
goroutines
channels
http
api

Vibeship-spawner-skills go-services

Go Services Skill

Building production Go microservices and applications

ERROR WRAPPING:

GRACEFUL SHUTDOWN:

FUNCTIONAL OPTIONS:

CONTEXT PROPAGATION:

TABLE-DRIVEN TESTS:

INTERFACE DESIGN: