Backend Go Conventions

This skill provides specific conventions for Go backend development.

When to Use

• Use this skill when working on Go projects
• Use this skill when creating new handlers, services, or repositories
• This skill builds upon project-standards skill

Instructions

1. Project Layout (Standard Go Layout)

project/
├── cmd/
│   └── api/
│       └── main.go           # Entry point
├── internal/
│   ├── handler/              # HTTP handlers (Controllers)
│   ├── service/              # Business logic
│   ├── repository/           # Database access
│   ├── model/                # Domain models
│   └── dto/                  # Request/Response objects
├── pkg/                      # Shared libraries
├── api/                      # OpenAPI/Swagger specs
├── config/                   # Configuration
└── go.mod

2. Architecture (Clean/Hexagonal)

• Handler (Controller): Receives requests, validates, calls Service.
• Service (Usecase): Contains Business Logic.
• Repository: Interacts with the Database.

Important: Interfaces should be defined where they are USED (Consumer), not where they are provided (Producer).

// In service package (consumer defines interface)
type UserRepository interface {
    FindByID(ctx context.Context, id string) (*model.User, error)
    Create(ctx context.Context, user *model.User) error
}

type UserService struct {
    repo UserRepository
}

func NewUserService(repo UserRepository) *UserService {
    return &UserService{repo: repo}
}

3. Error Handling

No Panic

Only panic during app setup failure (e.g., db disconnect).

// Bad - panicking in business logic
func GetUser(id string) User {
    user, err := repo.Find(id)
    if err != nil {
        panic(err) // Never do this!
    }
    return user
}

// Good - return errors
func GetUser(id string) (User, error) {
    user, err := repo.Find(id)
    if err != nil {
        return User{}, fmt.Errorf("get user %s: %w", id, err)
    }
    return user, nil
}

Wrap Errors

Use fmt.Errorf with %w to preserve context.

if err != nil {
    return fmt.Errorf("create user failed: %w", err)
}

4. Naming Convention

• Package: Short, lowercase, no underscores (e.g., user, auth).
• Interface: Ends with er (e.g., Reader, Writer, UserRepository).
• Variable: camelCase, acronyms all uppercase (userID, httpClient).
• Exported: PascalCase for exported, camelCase for unexported.

// Good
package user

type Repository interface {
    FindByID(ctx context.Context, id string) (*User, error)
}

var defaultTimeout = 30 * time.Second // unexported
var DefaultClient = &http.Client{}     // exported

5. Context Handling

Always pass context as the first parameter.

func (s *UserService) GetUser(ctx context.Context, id string) (*User, error) {
    // Check context cancellation
    select {
    case <-ctx.Done():
        return nil, ctx.Err()
    default:
    }
    
    return s.repo.FindByID(ctx, id)
}

6. HTTP Handler Example

func (h *UserHandler) GetUser(w http.ResponseWriter, r *http.Request) {
    id := chi.URLParam(r, "id")
    
    user, err := h.service.GetUser(r.Context(), id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            h.respondError(w, http.StatusNotFound, "user not found")
            return
        }
        h.respondError(w, http.StatusInternalServerError, "internal error")
        return
    }
    
    h.respondJSON(w, http.StatusOK, Response{
        Success: true,
        Data:    user,
    })
}

7. Testing

Use table-driven tests.

func TestUserService_GetUser(t *testing.T) {
    tests := []struct {
        name    string
        id      string
        want    *User
        wantErr bool
    }{
        {
            name: "valid user",
            id:   "123",
            want: &User{ID: "123", Email: "test@example.com"},
        },
        {
            name:    "not found",
            id:      "999",
            wantErr: true,
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // Test implementation
        })
    }
}

8. Dependencies

• Framework: Gin or Echo
• ORM: GORM or SQLC
• Config: Viper
• Logger: Zap or Zerolog