Go Best Practices & Architecture

Comprehensive guide for developing high-quality Go applications following industry best practices.

What This Skill Does

Provides expert guidance on Go development covering:

Project structure and code organization

Design patterns and anti-patterns

Performance optimization techniques

Security best practices

Testing strategies

Error handling patterns

Memory management

Concurrency patterns

Instructions

1. Code Organization and Structure

**Directory Structure:**

```

project-name/

├── cmd/ # Application entry points

│ └── project-name/

│ └── main.go

├── internal/ # Private application code

│ ├── app/ # Business logic

│ ├── domain/ # Core domain types

│ └── pkg/ # Internal utilities

├── pkg/ # Public libraries

├── api/ # API definitions

├── web/ # Web assets

├── scripts/ # Build/deployment scripts

├── configs/ # Configuration files

├── go.mod

└── README.md

```

**Key Principles:**

Use `internal/` for private code that shouldn't be imported by other projects

Use `pkg/` for reusable libraries meant to be shared

Follow snake_case for file names (e.g., `user_service.go`)

Use `_test.go` suffix for test files

**Module Organization:**

Initialize modules with `go mod init <module-name>`

Follow semantic versioning (SemVer)

Use Git tags for releases (e.g., `v1.0.0`)

Consider vendoring with `go mod vendor` for reproducible builds

2. Architecture Patterns

**Layered Architecture:**

Separate presentation, service, repository, and data access layers

Promote separation of concerns and testability

**Dependency Injection:**

```go

type Server struct {

Addr string

Port int

Protocol string

Timeout time.Duration

}

type Option func(*Server)

func WithAddress(addr string) Option {

return func(s *Server) {

s.Addr = addr

}

func NewServer(options ...Option) *Server {

srv := &Server{

Addr: "localhost",

Port: 8080,

Protocol: "tcp",

Timeout: 30 * time.Second,

}

for _, option := range options {

option(srv)

}

return srv

}

```

**Context Pattern:**

```go

func handleRequest(ctx context.Context, req *http.Request) {

select {

case <-ctx.Done():

// Operation cancelled

return

default:

// Process the request

}

```

**Middleware Pattern:**

```go

func loggingMiddleware(next http.Handler) http.Handler {

return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

log.Printf("Request: %s %s", r.Method, r.URL.Path)

next.ServeHTTP(w, r)

})

}

```

3. Error Handling

**Always Handle Errors:**

```go

// Bad

_, _ = fmt.Println("Hello, world!")

// Good

_, err := fmt.Println("Hello, world!")

if err != nil {

log.Println("Error printing: ", err)

}

```

**Error Wrapping:**

```go

func readFile(filename string) ([]byte, error) {

data, err := ioutil.ReadFile(filename)

if err != nil {

return nil, fmt.Errorf("failed to read file %s: %w", filename, err)

}

return data, nil

}

```

**Custom Error Types:**

```go

type NotFoundError struct {

Resource string

}

func (e *NotFoundError) Error() string {

return fmt.Sprintf("%s not found", e.Resource)

}

```

**Sentinel Errors:**

```go

var ErrNotFound = errors.New("not found")

func getUser(id int) (*User, error) {

if id == 0 {

return nil, ErrNotFound

}

// ...

}

```

4. Performance Optimization

**Profiling:**

```bash

go tool pprof http://localhost:6060/debug/pprof/profile # CPU

go tool pprof http://localhost:6060/debug/pprof/heap # Memory

```

**Benchmarking:**

```go

func BenchmarkFunction(b *testing.B) {

for i := 0; i < b.N; i++ {

// Code to benchmark

}

```

**String Concatenation:**

```go

var sb strings.Builder

for i := 0; i < 1000; i++ {

sb.WriteString("hello")

}

result := sb.String()

```

**State Management with Mutex:**

```go

var mu sync.Mutex

var counter int

func incrementCounter() {

mu.Lock()

defer mu.Unlock()

counter++

}

```

5. Anti-patterns to Avoid

**Never ignore errors** - Always handle explicitly

**Avoid panic for normal errors** - Use only for exceptional situations

**Minimize global variables** - Pass state explicitly

**Don't shadow variables** - Prevent confusion

**Be careful with unbuffered channels** - Can cause deadlocks

**Don't overuse goroutines** - Consider worker pools

**Avoid mutable global state** - Prevents race conditions

**Use constants instead of magic numbers/strings**

**Keep functions short and focused**

**Avoid deeply nested code** - Use early returns

6. Common Tasks

**Configuration Management:**

Use `spf13/viper` or `joho/godotenv`

**Logging:**

Use `sirupsen/logrus` or `uber-go/zap` for structured logging

**Database Access:**

Use `database/sql` with appropriate drivers

Use prepared statements to prevent SQL injection

Consider `gorm.io/gorm` for complex interactions

**HTTP Handling:**

Use `net/http` or frameworks like `gin-gonic/gin`, `go-chi/chi`

Always set appropriate timeouts

**Input Validation:**

Use `go-playground/validator`

Always sanitize user input

**Resource Cleanup:**

```go

func processFile(filename string) error {

file, err := os.Open(filename)

if err != nil {

return err

}

defer file.Close() // Ensure cleanup

// ...

}

```

Usage Examples

**Creating a new Go service with proper structure:**

1. Initialize module: `go mod init github.com/username/project`

2. Create directory structure following the layout above

3. Implement layered architecture with dependency injection

4. Add comprehensive error handling with wrapped errors

5. Include benchmarks and profiling for critical paths

6. Use context for cancellation and timeouts

7. Implement middleware for cross-cutting concerns

**Refactoring existing code:**

1. Profile to identify bottlenecks

2. Apply optimization techniques (string builders, object pooling)

3. Add proper error wrapping and custom error types

4. Implement synchronization primitives for concurrent access

5. Add comprehensive tests and benchmarks

Constraints

Follow Go's philosophy of simplicity and explicitness

Prefer standard library over third-party dependencies when possible

Write idiomatic Go code following community conventions

Prioritize readability and maintainability over premature optimization

Always handle errors explicitly - never ignore them

Use interfaces for abstraction but don't over-engineer

Document exported functions, types, and packages

Go Best Practices & Architecture

Go Best Practices & Architecture

What This Skill Does

Instructions

1. Code Organization and Structure

2. Architecture Patterns

3. Error Handling

4. Performance Optimization

5. Anti-patterns to Avoid

6. Common Tasks

Usage Examples

Constraints

Reviews (0)