Go Conventions

Go Conventions Skill

Overview

This skill provides guidelines for writing idiomatic, production-ready Go code following Go conventions, best practices, and patterns optimized for backend development with Gin and standard library.

Core Principles

1. Idiomatic Go

• Follow Go's philosophy: "Simple is better"
• Prefer composition over inheritance
• Use small interfaces
• Write self-documenting code with clear variable names
• Keep functions short and focused

2. Error Handling

// DO: Explicit error handling with context
result, err := processData(input)
if err != nil {
    return fmt.Errorf("failed to process data: %w", err)
}

// DON'T: Ignore errors
result, _ := processData(input) // Never do this

// DO: Wrap errors for context
return fmt.Errorf("database operation failed: %w", err)

// DO: Use custom error types for domain-specific errors
type ValidationError struct {
    Field   string
    Message string
}

func (e ValidationError) Error() string {
    return fmt.Sprintf("validation failed for %s: %s", e.Field, e.Message)
}

3. Concurrency Patterns

// DO: Use context for cancellation
func fetchData(ctx context.Context, url string) ([]byte, error) {
    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
    if err != nil {
        return nil, err
    }
    // ...
}

// DO: Use channels with select for timeouts
select {
case result := <-ch:
    return result, nil
case <-time.After(timeout):
    return nil, errors.New("timeout")
case <-ctx.Done():
    return nil, ctx.Err()
}

// DO: Use sync.WaitGroup for goroutine coordination
var wg sync.WaitGroup
for _, task := range tasks {
    wg.Add(1)
    go func(t Task) {
        defer wg.Done()
        process(t)
    }(task)
}
wg.Wait()

4. Struct and Interface Design

// DO: Small interfaces (Interface Segregation)
type Reader interface {
    Read(p []byte) (n int, err error)
}

type Writer interface {
    Write(p []byte) (n int, err error)
}

// DO: Constructor patterns for complex structs
func NewService(db *sql.DB, cache *redis.Client, logger *zap.Logger) *Service {
    return &Service{
        db:     db,
        cache:  cache,
        logger: logger,
    }
}

// DO: Method receivers - pointer vs value
func (s *Service) Update(data Data) error  // Pointer for mutation
func (c Config) Validate() error            // Value for read-only

5. Package Organization

myproject/
├── cmd/
│   └── api/              # Main application entry point
│       └── main.go
├── internal/
│   ├── domain/           # Business logic (entities, use cases)
│   ├── repository/       # Data access layer
│   ├── service/          # Business services
│   └── handler/          # HTTP handlers
├── pkg/
│   ├── middleware/       # Shared middleware
│   └── utils/           # Shared utilities
└── go.mod

Gin-Specific Patterns

1. Handler Structure

// DO: Use dependency injection
func (h *UserHandler) CreateUser(c *gin.Context) {
    var req CreateUserRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    
    user, err := h.service.CreateUser(c.Request.Context(), req)
    if err != nil {
        handleError(c, err)
        return
    }
    
    c.JSON(http.StatusCreated, user)
}

// DO: Centralized error handling
func handleError(c *gin.Context, err error) {
    switch e := err.(type) {
    case *ValidationError:
        c.JSON(http.StatusBadRequest, gin.H{"error": e.Error()})
    case *NotFoundError:
        c.JSON(http.StatusNotFound, gin.H{"error": e.Error()})
    default:
        c.JSON(http.StatusInternalServerError, gin.H{"error": "internal server error"})
    }
}

2. Middleware Patterns

// DO: Authentication middleware
func AuthMiddleware(secret string) gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing token"})
            return
        }
        
        claims, err := validateToken(token, secret)
        if err != nil {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid token"})
            return
        }
        
        c.Set("user", claims)
        c.Next()
    }
}

// DO: Logging middleware
func LoggerMiddleware(logger *zap.Logger) gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        path := c.Request.URL.Path
        
        c.Next()
        
        logger.Info("request",
            zap.String("method", c.Request.Method),
            zap.String("path", path),
            zap.Int("status", c.Writer.Status()),
            zap.Duration("duration", time.Since(start)),
        )
    }
}

Database Patterns (PostgreSQL)

// DO: Repository pattern
type UserRepository interface {
    Create(ctx context.Context, user *User) error
    GetByID(ctx context.Context, id int64) (*User, error)
    Update(ctx context.Context, user *User) error
    Delete(ctx context.Context, id int64) error
    List(ctx context.Context, opts ListOptions) ([]User, error)
}

// DO: Transaction handling
func (r *userRepo) CreateWithProfile(ctx context.Context, user *User, profile *Profile) error {
    tx, err := r.db.BeginTx(ctx, nil)
    if err != nil {
        return err
    }
    defer tx.Rollback()
    
    if err := r.createUserTx(ctx, tx, user); err != nil {
        return err
    }
    
    if err := r.createProfileTx(ctx, tx, profile); err != nil {
        return err
    }
    
    return tx.Commit()
}

Testing Patterns

// DO: Table-driven tests
func TestCalculateTotal(t *testing.T) {
    tests := []struct {
        name     string
        items    []Item
        expected float64
    }{
        {
            name:     "empty cart",
            items:    []Item{},
            expected: 0,
        },
        {
            name: "single item",
            items: []Item{{Price: 10, Quantity: 2}},
            expected: 20,
        },
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result := calculateTotal(tt.items)
            assert.Equal(t, tt.expected, result)
        })
    }
}

// DO: Mock interfaces for testing
type MockUserService struct {
    mock.Mock
}

func (m *MockUserService) GetUser(ctx context.Context, id int64) (*User, error) {
    args := m.Called(ctx, id)
    return args.Get(0).(*User), args.Error(1)
}

When to Use

Use this skill when:

• Writing or reviewing Go code
• Designing Go architecture
• Refactoring Go projects
• Implementing Go backend services with Gin
• Writing Go tests
• Setting up Go project structure

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Jonathan0823
• Source: Jonathan0823/opencode-config
• License: MIT

Install and usage instructions live in the source repository linked above.