mostafavi | Blog

Author: Reza

  • golangci-lint: The Guide to Go Code Quality

    In the world of Go development, code quality isn’t just about making your code work—it’s about making it maintainable, efficient, and bug-free. Enter golangci-lint, the Swiss Army knife of Go linters that has become the industry standard for ensuring code quality across Go projects.

    Unlike running individual linters separately, golangci-lint aggregates dozens of linters into a single, blazingly fast tool. It runs linters in parallel, caches results, and provides a unified configuration system. Whether you’re working on a small microservice or a large-scale distributed system, golangci-lint is an essential tool in your development workflow.

    Why golangci-lint Matters

    Before golangci-lint, Go developers had to run multiple linting tools separately: go vet, errcheck, staticcheck, gosimple, and many others. This approach had several problems:

    • Slow execution: Running linters sequentially wasted valuable development time
    • Inconsistent configuration: Each linter had its own configuration format
    • CI/CD complexity: Setting up multiple tools in pipelines was tedious
    • Missed issues: Forgetting to run a particular linter meant missing potential bugs

    golangci-lint solves all these problems by providing a unified interface to 50+ linters, running them in parallel, and offering intelligent caching that can speed up subsequent runs by 5x or more.

    Installation

    Getting started with golangci-lint is straightforward. Choose the method that works best for your environment:

    Using Go Install (Recommended)

    go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

    Using Homebrew (macOS/Linux)

    brew install golangci-lint

    Basic Usage

    The simplest way to use golangci-lint is to run it in your project directory:

    golangci-lint run

    This command will:

    1. Discover all Go files in your project
    2. Run a set of default enabled linters
    3. Report any issues found

    Targeting Specific Paths

    You can lint specific packages or files:

    # Lint everything recursively
golangci-lint run ./...

# Lint a specific package
golangci-lint run ./pkg/api

# Lint specific files
golangci-lint run main.go handler.go

    Viewing Available Linters

    To see all available linters and their status:

    golangci-lint linters

    This command shows which linters are enabled by default and provides brief descriptions of what each linter does.

    Configuration: The .golangci.yml File

    The real power of golangci-lint comes from its configuration system. Create a .golangci.yml file in your project root to customize behavior:

    # .golangci.yml
run:
  # Timeout for analysis
  timeout: 5m
  
  # Include test files
  tests: true
  
  # Modules download mode
  modules-download-mode: readonly

linters:
  # Enable specific linters
  enable:
    - errcheck
    - gosimple
    - govet
    - ineffassign
    - staticcheck
    - unused
    - misspell
    - gocyclo
    - dupl
    - gocritic
    
  # Disable problematic linters
  disable:
    - typecheck  # Can conflict with generated code

# Configure individual linters
linters-settings:
  errcheck:
    # Check type assertions
    check-type-assertions: true
    # Check blank assignments
    check-blank: true
    
  gocyclo:
    # Maximum cyclomatic complexity
    min-complexity: 15
    
  dupl:
    # Minimum token sequence for duplication
    threshold: 100
    
  govet:
    # Enable shadow checking
    check-shadowing: true

# Issue filtering
issues:
  # Maximum issues to report (0 = unlimited)
  max-issues-per-linter: 0
  max-same-issues: 0
  
  # Exclude specific rules
  exclude-rules:
    # Exclude some linters from running on tests
    - path: _test\.go
      linters:
        - errcheck
        - dupl
        - gosec

    Conclusion

    golangci-lint is an indispensable tool for Go developers who care about code quality. By aggregating dozens of linters into a single, fast tool with a unified configuration, it makes maintaining high code standards effortless.

    Start simple with the default configuration, then gradually enable more linters as your team becomes comfortable with the tool. Integrate it into your editor, pre-commit hooks, and CI/CD pipeline to catch issues early.

    Remember that linters are tools to help you write better code—not rigid rules to be followed blindly. Use your judgment to configure golangci-lint appropriately for your project’s needs, and don’t hesitate to exclude false positives or disable linters that don’t add value to your specific context.

    The time invested in properly configuring golangci-lint will pay dividends in fewer bugs, more maintainable code, and a smoother development experience for your entire team.

    Additional Resources

  • Escape Analysis in Go: How the Compiler Decides Where Your Variables Live

    When Go developers talk about performance, conversations often turn to allocation and garbage collection. But underneath those topics lies a subtle, powerful compiler optimization that determines how efficiently your program runs: escape analysis.

    It’s the mechanism that decides whether your variables are stored on the stack — fast, cheap, and automatically reclaimed — or on the heap, where they incur the cost of garbage collection. Understanding escape analysis helps you write Go code that’s both clear and efficient, without micro-optimizing blindly.

    What Is Escape Analysis?

    In simple terms, escape analysis is a process the Go compiler uses to determine the lifetime and visibility of variables.

    If the compiler can prove that a variable never escapes the function where it’s defined — meaning no other part of the program can access it after the function returns — it can safely allocate that variable on the stack.

    If not, the variable “escapes” to the heap, ensuring it lives long enough to be used elsewhere but at a higher performance cost.

    A Simple Example

    Let’s look at how Go decides where to place a variable.

    func a() *Resp {
    s := Resp{Status: "OK"}
    return &s
}

    At first glance, s looks like a local variable. But since its address is returned, s must survive after a() returns. The compiler detects that and allocates it on the heap.

    We can verify this using the compiler flag:

    go build -gcflags="-m" main.go

    Output:

    ./main.go:3:6: moved to heap: Resp

    Now consider a variant:

    func b() {
    s := Resp{Status: "OK"}
    fmt.Println(s.Status)
}

    Here, s doesn’t escape — it’s only used within the function. The compiler can safely put it on the stack:

    ./main.go:3:6: s does not escape

    Why Escape Analysis Matters for Performance

    Escape analysis directly affects allocation patterns, garbage collector load, and ultimately, latency.

    1. Fewer Heap Allocations

    Fewer escapes mean fewer heap allocations — less GC work, smaller memory footprint, and reduced pauses.

    2. Predictable Performance

    Stack allocation is deterministic. Heap allocation involves runtime bookkeeping and garbage collection cycles.

    3. Inlining and Optimizations

    Escape analysis interacts closely with other compiler optimizations like function inlining. Sometimes, inlining can expose more information to the compiler, allowing it to keep variables on the stack.

  • How Radix Trees Power High-Performance Web Server Routers

    When we think of web performance, our minds often jump to caching layers, CDNs, or optimized databases. Yet, one of the most overlooked contributors to web speed lies at the heart of every web framework — the router.

    Each time a request arrives, the router decides which piece of code should handle it. This decision must be made fast, thousands of times per second, often across hundreds or thousands of possible routes. To meet this demand, high-performance web servers increasingly rely on a clever data structure: the radix tree.

    What Is a Radix Tree?

    A radix tree, also known as a Patricia trie or compact prefix tree, is a space-optimized structure designed for prefix matching. It’s a close cousin of the traditional trie, but instead of storing one character per edge, a radix tree compresses chains of single-child nodes into multi-character strings.

    This makes it particularly well-suited for hierarchical data such as URL paths, file systems, and IP addresses, all of which share common prefixes.

    Example: Routes in a Web Server

    Consider the following web routes:

    /users
/users/:id
/users/:id/settings
/articles
/articles/:year/:month

    A radix tree representation would look like this:

    (root)
 ├── "users"
 │     ├── ""
 │     └── "/:id"
 │          └── "/settings"
 └── "articles"
       └── "/:year"
             └── "/:month"

    Instead of scanning all routes linearly, the tree enables the router to walk through matching prefixes (/users → /:id → /settings) in O(k) time, where k is the length of the path.

    How Radix Trees Are Used in Web Routers

    In a modern web server, the router’s job is to map URL patterns to handler functions. When a request arrives, the router must find the correct handler as quickly as possible.

    Using a radix tree, the router:

    1. Stores routes as compressed prefixes, minimizing redundancy.
    2. Matches requests by walking the tree from root to leaf, comparing chunks of the path.
    3. Supports dynamic parameters (like :id or :slug) by treating them as special wildcard edges.
    4. Selects the best matching route (the longest prefix match).

    This structure is particularly efficient because most routes share prefixes — for example, /api/users and /api/posts both begin with /api.