backend-go-code-style（后端 Go 代码风格）

Community default. A company skill that explicitly supersedes jimmy-skills@backend-go-code-style skill takes precedence.

Go Code Style

Style rules that require human judgment. Linters handle mechanical enforcement; this skill handles clarity, locality, and readable package boundaries. For naming see jimmy-skills@backend-go-naming skill; for design patterns see jimmy-skills@backend-go-design-patterns skill; for struct/interface design see jimmy-skills@backend-go-structs-interfaces skill.

"Clear is better than clever." — Go Proverbs

When ignoring a rule, add a comment to the code.

Line Length & Breaking

No rigid line limit, but lines beyond ~120 characters MUST be broken. Break at semantic boundaries, not arbitrary column counts. Function calls with 4+ arguments MUST use one argument per line — even when the prompt asks for single-line code:

// Good — each argument on its own line, closing paren separate
mux.HandleFunc("/api/users", func(w http.ResponseWriter, r *http.Request) {
    handleUsers(
        w,
        r,
        serviceName,
        cfg,
        logger,
        authMiddleware,
    )
})

When a function signature is too long, the real fix is often fewer parameters (use an options struct) rather than better line wrapping. For multi-line signatures, put each parameter on its own line.

Variable Declarations

SHOULD use := for non-zero values, var for zero-value initialization. The form signals intent: var means "this starts at zero."

var count int              // zero value, set later
name := "default"          // non-zero, := is appropriate
var buf bytes.Buffer       // zero value is ready to use

Slice & Map Initialization

Slices and maps MUST be initialized explicitly, never nil. Nil maps panic on write; nil slices serialize to null in JSON (vs [] for empty slices), surprising API consumers.

users := []User{}                       // always initialized
m := map[string]int{}                   // always initialized
users := make([]User, 0, len(ids))      // preallocate when capacity is known
m := make(map[string]int, len(items))   // preallocate when size is known

Do not preallocate speculatively — make([]T, 0, 1000) wastes memory when the common case is 10 items.

Composite Literals

Composite literals MUST use field names — positional fields break when the type adds or reorders fields:

srv := &http.Server{
    Addr:         ":8080",
    ReadTimeout:  5 * time.Second,
    WriteTimeout: 10 * time.Second,
}

Control Flow

Reduce Nesting

Errors and edge cases MUST be handled first (early return). Keep the happy path at minimal indentation:

func process(data []byte) (*Result, error) {
    if len(data) == 0 {
        return nil, errors.New("empty data")
    }

    parsed, err := parse(data)
    if err != nil {
        return nil, fmt.Errorf("parsing: %w", err)
    }

    return transform(parsed), nil
}

Eliminate Unnecessary else

When the if body ends with return/break/continue, the else MUST be dropped. Use default-then-override for simple assignments — assign a default, then override with independent conditions or a switch:

// Good — default-then-override with switch (cleanest for mutually exclusive overrides)
level := zap.InfoLevel
switch {
case debug:
    level = zap.DebugLevel
case verbose:
    level = zap.WarnLevel
}

// Bad — else-if chain hides that there's a default
if debug {
    level = zap.DebugLevel
} else if verbose {
    level = zap.WarnLevel
} else {
    level = zap.InfoLevel
}

Complex Conditions & Init Scope

When an if condition has 3+ operands, MUST extract into named booleans — a wall of || is unreadable and hides business logic. Keep expensive checks inline for short-circuit benefit. Details

// Good — named booleans make intent clear
isAdmin := user.Role == RoleAdmin
isOwner := resource.OwnerID == user.ID
isPublicVerified := resource.IsPublic && user.IsVerified
if isAdmin || isOwner || isPublicVerified || permissions.Contains(PermOverride) {
    allow()
}

Scope variables to if blocks when only needed for the check:

if err := validate(input); err != nil {
    return err
}

Switch Over If-Else Chains

When comparing the same variable multiple times, prefer switch:

switch status {
case StatusActive:
    activate()
case StatusInactive:
    deactivate()
default:
    panic(fmt.Sprintf("unexpected status: %d", status))
}

Function Design

• Functions SHOULD be short and focused — one function, one job.
• Functions SHOULD have ≤4 parameters. Beyond that, use an options struct (see jimmy-skills@backend-go-design-patterns skill).
• Parameter order: context.Context first, then inputs, then output destinations.
• Naked returns help in very short functions (1-3 lines) where return values are obvious, but become confusing when readers must scroll to find what's returned — name returns explicitly in longer functions.

func FetchUser(ctx context.Context, id string) (*User, error)
func SendEmail(ctx context.Context, msg EmailMessage) error  // grouped into struct

Prefer range for Iteration

SHOULD use range over index-based loops. Use range n (Go 1.22+) for simple counting.

for _, user := range users {
    process(user)
}

Value vs Pointer Arguments

Pass small types (string, int, bool, time.Time) by value. Use pointers when mutating, for large structs (~128+ bytes), or when nil is meaningful. Details

Code Organization Within Files

• Group related declarations: type, constructor, methods together
• Order: package doc, imports, constants, types, constructors, methods, helpers
• One primary type per file when it has significant methods
• Blank imports (_ "pkg") register side effects (init functions). Restricting them to main and test packages makes side effects visible at the application root, not hidden in library code
• Dot imports pollute the namespace and make it impossible to tell where a name comes from — never use in library code
• Unexport aggressively — you can always export later; unexporting is a breaking change

Package Boundaries & Locality

For APIs and services, prioritize feature-first packages over technical-layer packages. A business capability should mostly live in one package or one directory tree, not be split across handlers/, services/, repository/, and models/ buckets.

• Prefer internal/users/, internal/invoices/, internal/posts/ over internal/handlers/, internal/services/, internal/repository/
• Keep handler, service, repository, routes, and feature-local types near each other when they belong to one feature
• Start with fewer packages than you think you need; split only when the package has multiple unrelated reasons to change
• If changing one feature forces edits across many packages, the boundaries are probably wrong

This is a readability concern, not just an architecture concern: locality is one of the fastest ways to reduce maintenance cost.

Naming Noise

• File names SHOULD NOT repeat the package name unless needed for clarity
• Type names SHOULD NOT repeat the package name
• Method names SHOULD NOT repeat the receiver type name

// Good
package users

type Service struct{}

func (s *Service) Create(ctx context.Context, in CreateInput) error { ... }

// Bad
package users

type UserService struct{}

func (s *UserService) CreateUser(ctx context.Context, in UserCreateInput) error { ... }

Keep names short once package and type context already tell the story.

Keep Types Near Usage

Do not create giant models.go buckets by default. Keep types close to the feature and use case they serve.

• Request/response DTOs stay near the handler or transport boundary that owns them
• Persistence-only structs stay near the repository that uses them
• Domain types shared by multiple files in the same feature can stay in types.go
• Extract a shared package only when the type is truly shared across multiple features

Avoid Circular Dependencies

Package imports must stay one-way. If two packages start depending on each other:

1. Move behavior to the package that truly owns the concern
2. Merge the packages if they are really one concept
3. Define a small interface at the consumer side and inject the concrete implementation from wiring code

Do not let users import billing while billing imports users. That is almost always a sign that the package split is wrong.

String Handling

Use strconv for simple conversions (faster), fmt.Sprintf for complex formatting. Use %q in error messages to make string boundaries visible. Use strings.Builder for loops, + for simple concatenation.

Type Conversions

Prefer explicit, narrow conversions. Use generics over any when a concrete type will do:

func Contains[T comparable](slice []T, target T) bool  // not []any

Philosophy

• "A little copying is better than a little dependency"
• Use slices and maps standard packages; for filter/group-by/chunk, prefer plain loops or small local helpers before adding a dependency
• "Reflection is never clear" — avoid reflect unless necessary
• Don't abstract prematurely — extract when the pattern is stable
• Minimize public surface — every exported name is a commitment

Parallelizing Code Style Reviews

When reviewing code style across a large codebase, use up to 5 parallel sub-agents (via the Agent tool), each targeting an independent style concern (e.g. control flow, function design, variable declarations, string handling, code organization).

Enforce with Linters

Many rules are enforced automatically: gofmt, gofumpt, goimports, gocritic, revive, wsl_v5. → See the jimmy-skills@backend-go-linter skill.

Cross-References

• → See the jimmy-skills@backend-go-naming skill for identifier naming conventions
• → See the jimmy-skills@backend-go-structs-interfaces skill for pointer vs value receivers, interface design
• → See the jimmy-skills@backend-go-design-patterns skill for functional options, builders, constructors
• → See the jimmy-skills@backend-go-linter skill for automated formatting enforcement
• → See the jimmy-skills@backend-go-project-layout skill for feature-first package trees and circular dependency prevention