golang

提供地道的Go编程专业知识和最佳实践。确保遵循官方Go约定的干净、高效和可维护的代码。专门研究并发编程模式、接口设计、错误处理策略和性能优化。精通标准库使用和生态系统集成。使用场景:编写Go代码(.go文件)、设计和结构体类型、实现并发模式(goroutines/channels)、地道地处理错误、编写表驱动测试、创建Go模块、优化性能关键代码、使用go.mod管理依赖、实现HTTP服务器和客户端、处理上下文传播或设计公共库的包API。

📖 中文导读:提供地道的Go编程专业知识和最佳实践。确保遵循官方Go约定的干净、高效和可维护的代码。专门研究并发编程模式、接口设计、错误处理策略和性能优化。精通标准库使用和生态系统集成。使用场景:编写Go代码(.go文件)、设计和结构体类型、实现并发模式(goroutines/channels)、地道地处理错误、编写表驱动测试、创建Go模块、优化性能关键代码、使用go.mod管理依赖、实现HTTP服务器和客户端、处理上下文传播或设计公共库的包API。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: golang description: | Provides idiomatic Go programming expertise and best practices. Ensures clean, efficient, and maintainable code following official Go conventions. Specializes in concurrent programming patterns, interface design, error handling strategies, and performance optimization. Masters standard library usage and ecosystem integration. Use when: writing Go code (.go files), designing interfaces and struct types, implementing concurrent patterns (goroutines/channels), handling errors idiomatically, writing table-driven tests, creating Go modules, optimizing performance-critical code, managing dependencies with go.mod, implementing HTTP servers and clients, working with context propagation, or designing package APIs for public libraries.

Go Coding Standards

Basic Principles

One Function, One Responsibility

  • If function name connects with "and" or "or", it's a signal to split
  • If test cases are needed for each if branch, it's a signal to split

Conditional and Loop Depth Limited to 2 Levels

  • Minimize depth using early return whenever possible
  • If still heavy, extract into separate functions

Make Function Side Effects Explicit

  • Example: If getUser also runs updateLastAccess(), specify it in the function name

Convert Magic Numbers/Strings to Constants When Possible

  • Declare at the top of the file where used
  • Consider separating into a constants file if there are many

Function Order by Call Order

  • Follow Go's clear conventions if they exist
  • Otherwise, order top-to-bottom for easy reading by call order

Review External Libraries for Complex Implementations

  • When logic is complex and tests become bloated
  • If industry-standard libraries exist, use them
  • When security, accuracy, or performance optimization is critical
  • When platform compatibility or edge cases are numerous

Modularization (Prevent Code Duplication and Pattern Repetition)

  • Absolutely forbid code repetition
  • Modularize similar patterns into reusable forms
  • Allow pre-modularization if reuse is confirmed
  • Avoid excessive abstraction
  • Modularization levels:
    • Same file: Extract into separate function
    • Multiple files: Separate into different package
    • Multiple projects/domains: Separate into different module

Variable and Function Names

  • Clear purpose while being concise
  • Forbid abbreviations outside industry standards (id, api, db, err, etc.)
  • Don't repeat context from the parent scope
  • Boolean variables use is, has, should prefixes
  • Function names are verbs or verb+noun forms
  • Plural rules:
    • Pure arrays/slices: "s" suffix (users)
    • Wrapped struct: "list" suffix (userList)
    • Specific data structure: Explicit (userSet, userMap)
    • Already plural words: Use as-is

Field Order

  • Alphabetically ascending by default
  • Maintain consistency in usage

Error Handling

  • Error handling level: Handle where meaningful response is possible
  • Error messages: Technical details for logs, actionable guidance for users
  • Error classification: Distinguish between expected and unexpected errors
  • Error propagation: Add context when propagating up the call stack
  • Recovery vs. fast fail: Recover from expected errors with fallback
  • Use %w for error chains, %v for simple logging
  • Wrap internal errors not to be exposed with %v
  • Never ignore return errors from functions; handle them explicitly
  • Sentinel errors: For expected conditions that callers must handle, use var ErrNotFound = errors.New("not found")

File Structure

Element Order in File

  1. package declaration
  2. import statements (grouped)
  3. Constant definitions (const)
  4. Variable definitions (var)
  5. Type/Interface/Struct definitions
  6. Constructor functions (New*)
  7. Methods (grouped by receiver type, alphabetically ordered)
  8. Helper functions (alphabetically ordered)

Interfaces and Structs

Interface Definition Location

  • Define interfaces in the package that uses them (Accept interfaces, return structs)
  • Only separate shared interfaces used by multiple packages

Pointer Receiver Rules

  • Use pointer receivers for state modification, large structs (3+ fields), or when consistency is needed
  • Use value receivers otherwise

Context Usage

Context Parameter

  • Always pass as the first parameter
  • Use context.Background() only in main and tests

Testing

Testing Libraries

  • Prefer standard library's if + t.Errorf over assertion libraries like testify
  • Prefer manual mocking over gomock

Forbidden Practices

init() Functions

  • Generally forbidden. Prefer explicit initialization functions

Package Structure

internal Package

  • Actively use for libraries, use only when necessary for applications
  • Web: Fiber
  • DB: Bun, SQLBoiler (when managing migrations externally)
  • Logging: slog
  • CLI: cobra
  • Utilities: samber/lo, golang.org/x/sync
  • Configuration: koanf (viper if cobra integration needed)
  • Validation: go-playground/validator/v10
  • Scheduling: github.com/go-co-op/gocron
  • Image processing: github.com/h2non/bimg