AgentSkillsCN

golang

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

SKILL.md
--- frontmatter
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

Recommended Libraries

  • •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