go-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Go Best Practices

Go语言最佳实践

Type-First Development

类型优先开发

Types define the contract before implementation. Follow this workflow:

Define data structures - structs and interfaces first
Define function signatures - parameters, return types, and error conditions
Implement to satisfy types - let the compiler guide completeness
Validate at boundaries - check inputs where data enters the system

类型定义先于实现的契约。遵循以下工作流程：

定义数据结构 - 优先定义结构体和接口
定义函数签名 - 参数、返回类型和错误条件
按类型实现 - 让编译器引导实现完整性
在边界处验证 - 在数据进入系统的位置检查输入

Make Illegal States Unrepresentable

让非法状态无法被表示

Use Go's type system to prevent invalid states at compile time.

Structs for domain models:

// Define the data model first
type User struct {
    ID        UserID
    Email     string
    Name      string
    CreatedAt time.Time
}

type CreateUserRequest struct {
    Email string
    Name  string
}

// Functions follow from the types
func CreateUser(req CreateUserRequest) (*User, error) {
    // implementation
}

Custom types for domain primitives:

// Distinct types prevent mixing up IDs
type UserID string
type OrderID string

func GetUser(id UserID) (*User, error) {
    // Compiler prevents passing OrderID here
}

func NewUserID(raw string) UserID {
    return UserID(raw)
}

// Methods attach behavior to the type
func (id UserID) String() string {
    return string(id)
}

Interfaces for behavior contracts:

// Define what you need, not what you have
type Reader interface {
    Read(p []byte) (n int, err error)
}

type UserRepository interface {
    GetByID(ctx context.Context, id UserID) (*User, error)
    Save(ctx context.Context, user *User) error
}

// Accept interfaces, return structs
func ProcessInput(r Reader) ([]byte, error) {
    return io.ReadAll(r)
}

Enums with iota:

type Status int

const (
    StatusActive Status = iota + 1
    StatusInactive
    StatusPending
)

func (s Status) String() string {
    switch s {
    case StatusActive:
        return "active"
    case StatusInactive:
        return "inactive"
    case StatusPending:
        return "pending"
    default:
        return fmt.Sprintf("Status(%d)", s)
    }
}

// Exhaustive handling in switch
func ProcessStatus(s Status) (string, error) {
    switch s {
    case StatusActive:
        return "processing", nil
    case StatusInactive:
        return "skipped", nil
    case StatusPending:
        return "waiting", nil
    default:
        return "", fmt.Errorf("unhandled status: %v", s)
    }
}

Functional options for flexible construction:

type ServerOption func(*Server)

func WithPort(port int) ServerOption {
    return func(s *Server) {
        s.port = port
    }
}

func WithTimeout(d time.Duration) ServerOption {
    return func(s *Server) {
        s.timeout = d
    }
}

func NewServer(opts ...ServerOption) *Server {
    s := &Server{
        port:    8080,    // sensible defaults
        timeout: 30 * time.Second,
    }
    for _, opt := range opts {
        opt(s)
    }
    return s
}

// Usage: NewServer(WithPort(3000), WithTimeout(time.Minute))

Embed for composition:

type Timestamps struct {
    CreatedAt time.Time
    UpdatedAt time.Time
}

type User struct {
    Timestamps  // embedded - User has CreatedAt, UpdatedAt
    ID    UserID
    Email string
}

利用Go的类型系统在编译时防止无效状态。

领域模型结构体：

// Define the data model first
type User struct {
    ID        UserID
    Email     string
    Name      string
    CreatedAt time.Time
}

type CreateUserRequest struct {
    Email string
    Name  string
}

// Functions follow from the types
func CreateUser(req CreateUserRequest) (*User, error) {
    // implementation
}

领域原语的自定义类型：

// Distinct types prevent mixing up IDs
type UserID string
type OrderID string

func GetUser(id UserID) (*User, error) {
    // Compiler prevents passing OrderID here
}

func NewUserID(raw string) UserID {
    return UserID(raw)
}

// Methods attach behavior to the type
func (id UserID) String() string {
    return string(id)
}

行为契约的接口：

// Define what you need, not what you have
type Reader interface {
    Read(p []byte) (n int, err error)
}

type UserRepository interface {
    GetByID(ctx context.Context, id UserID) (*User, error)
    Save(ctx context.Context, user *User) error
}

// Accept interfaces, return structs
func ProcessInput(r Reader) ([]byte, error) {
    return io.ReadAll(r)
}

使用iota实现枚举：

type Status int

const (
    StatusActive Status = iota + 1
    StatusInactive
    StatusPending
)

func (s Status) String() string {
    switch s {
    case StatusActive:
        return "active"
    case StatusInactive:
        return "inactive"
    case StatusPending:
        return "pending"
    default:
        return fmt.Sprintf("Status(%d)", s)
    }
}

// Exhaustive handling in switch
func ProcessStatus(s Status) (string, error) {
    switch s {
    case StatusActive:
        return "processing", nil
    case StatusInactive:
        return "skipped", nil
    case StatusPending:
        return "waiting", nil
    default:
        return "", fmt.Errorf("unhandled status: %v", s)
    }
}

灵活构造的函数选项：

type ServerOption func(*Server)

func WithPort(port int) ServerOption {
    return func(s *Server) {
        s.port = port
    }
}

func WithTimeout(d time.Duration) ServerOption {
    return func(s *Server) {
        s.timeout = d
    }
}

func NewServer(opts ...ServerOption) *Server {
    s := &Server{
        port:    8080,    // sensible defaults
        timeout: 30 * time.Second,
    }
    for _, opt := range opts {
        opt(s)
    }
    return s
}

// Usage: NewServer(WithPort(3000), WithTimeout(time.Minute))

组合式嵌入：

type Timestamps struct {
    CreatedAt time.Time
    UpdatedAt time.Time
}

type User struct {
    Timestamps  // embedded - User has CreatedAt, UpdatedAt
    ID    UserID
    Email string
}

Module Structure

模块结构

Prefer smaller files within packages: one type or concern per file. Split when a file handles multiple unrelated types or exceeds ~300 lines. Keep tests in

_test.go

files alongside implementation. Package boundaries define the API; internal organization is flexible.

推荐包内使用较小的文件：每个文件对应一个类型或关注点。当一个文件处理多个不相关类型或超过约300行时进行拆分。将测试放在实现文件旁的

_test.go

文件中。包边界定义API；内部组织可灵活调整。

Functional Patterns

函数式模式

Use value receivers when methods don't mutate state; reserve pointer receivers for mutation.
Avoid package-level mutable variables; pass dependencies explicitly via function parameters.
Return new structs/slices rather than mutating inputs; makes data flow explicit.
Use closures and higher-order functions where they simplify code (e.g.,
```
sort.Slice
```
, iterators).

当方法不修改状态时使用值接收器；仅在修改状态时使用指针接收器。
避免包级可变变量；通过函数参数显式传递依赖。
返回新的结构体/切片而非修改输入；让数据流更清晰。
在简化代码的场景下使用闭包和高阶函数（例如
```
sort.Slice
```
、迭代器）。

Instructions

注意事项

Return errors with context using
```
fmt.Errorf
```
and
```
%w
```
for wrapping. This preserves the error chain for debugging.
Every function returns a value or an error; unimplemented paths return descriptive errors. Explicit failures are debuggable.
Handle all branches in
```
switch
```
statements; include a
```
default
```
case that returns an error. Exhaustive handling prevents silent bugs.
Pass
```
context.Context
```
to external calls with explicit timeouts. Runaway requests cause cascading failures.
Reserve
```
panic
```
for truly unrecoverable situations; prefer returning errors. Panics crash the program.
Add or update table-driven tests for new logic; cover edge cases (empty input, nil, boundaries).

使用
```
fmt.Errorf
```
和
```
%w
```
包装错误并附带上下文。这会保留错误链以便调试。
每个函数都返回值或错误；未实现的路径返回描述性错误。显式的错误更易于调试。
处理
```
switch
```
语句中的所有分支；包含返回错误的
```
default
```
分支。全面处理可防止隐性bug。
为外部调用传递带显式超时的
```
context.Context
```
。失控的请求会导致级联故障。
仅在真正不可恢复的情况下使用
```
panic
```
；优先返回错误。Panic会导致程序崩溃。
为新逻辑添加或更新表驱动测试；覆盖边缘情况（空输入、nil、边界值）。

Examples

示例

Explicit failure for unimplemented logic:

func buildWidget(widgetType string) (*Widget, error) {
    return nil, fmt.Errorf("buildWidget not implemented for type: %s", widgetType)
}

Wrap errors with context to preserve the chain:

out, err := client.Do(ctx, req)
if err != nil {
    return nil, fmt.Errorf("fetch widget failed: %w", err)
}
return out, nil

Exhaustive switch with default error:

func processStatus(status string) (string, error) {
    switch status {
    case "active":
        return "processing", nil
    case "inactive":
        return "skipped", nil
    default:
        return "", fmt.Errorf("unhandled status: %s", status)
    }
}

Structured logging with slog:

import "log/slog"

var log = slog.With("component", "widgets")

func createWidget(name string) (*Widget, error) {
    log.Debug("creating widget", "name", name)
    widget := &Widget{Name: name}
    log.Debug("created widget", "id", widget.ID)
    return widget, nil
}

未实现逻辑的显式错误返回：

func buildWidget(widgetType string) (*Widget, error) {
    return nil, fmt.Errorf("buildWidget not implemented for type: %s", widgetType)
}

附带上下文包装错误以保留错误链：

out, err := client.Do(ctx, req)
if err != nil {
    return nil, fmt.Errorf("fetch widget failed: %w", err)
}
return out, nil

带默认错误的全面switch处理：

func processStatus(status string) (string, error) {
    switch status {
    case "active":
        return "processing", nil
    case "inactive":
        return "skipped", nil
    default:
        return "", fmt.Errorf("unhandled status: %s", status)
    }
}

使用slog的结构化日志：

import "log/slog"

var log = slog.With("component", "widgets")

func createWidget(name string) (*Widget, error) {
    log.Debug("creating widget", "name", name)
    widget := &Widget{Name: name}
    log.Debug("created widget", "id", widget.ID)
    return widget, nil
}

Configuration

配置

Load config from environment variables at startup; validate required values before use. Missing config should cause immediate exit.
Define a Config struct as single source of truth; avoid
```
os.Getenv
```
scattered throughout code.
Use sensible defaults for development; require explicit values for production secrets.

在启动时从环境变量加载配置；使用前验证必填值。缺失配置应导致程序立即退出。
定义Config结构体作为单一可信源；避免在代码中分散使用
```
os.Getenv
```
。
为开发环境使用合理默认值；生产环境的密钥需要显式配置。

Examples

示例

Typed config struct:

type Config struct {
    Port        int
    DatabaseURL string
    APIKey      string
    Env         string
}

func LoadConfig() (*Config, error) {
    dbURL := os.Getenv("DATABASE_URL")
    if dbURL == "" {
        return nil, fmt.Errorf("DATABASE_URL is required")
    }
    apiKey := os.Getenv("API_KEY")
    if apiKey == "" {
        return nil, fmt.Errorf("API_KEY is required")
    }
    port := 3000
    if p := os.Getenv("PORT"); p != "" {
        var err error
        port, err = strconv.Atoi(p)
        if err != nil {
            return nil, fmt.Errorf("invalid PORT: %w", err)
        }
    }
    return &Config{
        Port:        port,
        DatabaseURL: dbURL,
        APIKey:      apiKey,
        Env:         getEnvOrDefault("ENV", "development"),
    }, nil
}

类型化配置结构体：

type Config struct {
    Port        int
    DatabaseURL string
    APIKey      string
    Env         string
}

func LoadConfig() (*Config, error) {
    dbURL := os.Getenv("DATABASE_URL")
    if dbURL == "" {
        return nil, fmt.Errorf("DATABASE_URL is required")
    }
    apiKey := os.Getenv("API_KEY")
    if apiKey == "" {
        return nil, fmt.Errorf("API_KEY is required")
    }
    port := 3000
    if p := os.Getenv("PORT"); p != "" {
        var err error
        port, err = strconv.Atoi(p)
        if err != nil {
            return nil, fmt.Errorf("invalid PORT: %w", err)
        }
    }
    return &Config{
        Port:        port,
        DatabaseURL: dbURL,
        APIKey:      apiKey,
        Env:         getEnvOrDefault("ENV", "development"),
    }, nil
}