go-practices

Files (1)

• SKILL.md

SKILL.md (first lines)

# Go Practices

These are Go-specific conventions that implement the architectural principles from the `design-principles` skill with concrete Go patterns. When this skill conflicts with a plugin skill, this skill wins — it reflects the project's actual conventions.

<!-- CUSTOMIZE: Add your specific Go version, module path, project layout, and any additional conventions below -->

## Dependency Inversion in Go

Go's implicit interface satisfaction makes dependency inversion natural — but only if you follow the pattern consistently.

### The Core Pattern

**Interfaces are defined where they are consumed, not where they are implemented.**

```go
// internal/user/service/user_service.go — the CONSUMER defines what it needs

type UserRepository interface {
    FindByID(ctx context.Context, id string) (*model.User, error)
    Save(ctx context.Context, user *model.User) error
}

type UserService struct {
    repo   UserRepository   // interface, not *repository.userRepository
    email  EmailSender      // interface, not *smtp.Client
    logger Logger           // interface, not *zap.Logger
}

func NewUserService(repo UserRepository, email EmailSender, logger Logger) *UserService {
    return &UserService{repo: repo, email: email, logger: logger}
}
```

### Unexported Struct, Exported Constructor, Interface Return

The implementation struct is **unexported** (lowercase). The constructor is exported and returns the **consumer's interface type**, not the concrete type. This gives two guarantees:

1. No one outside the package can depend on the concrete type
2. The compiler validates the interface contract at the implementation site — missing methods are caught here, not at the injection point

```go
// internal/user/repository/postgres_user.go — the IMPLEMENTATION

import (
    "myapp/internal/user/model"
    "myapp/internal/user/service"
)

// unexported struct — no one outside this package can name it
type userRepository struct {
    db *sql.DB
}

// exported constructor returns the consumer's interface
func NewUserRepository(db *sql.DB) service.UserRepository {
    return &userRepository{db: db}
}

func (r *userRepository) FindByID(ctx context.Context, id string) (*model.User, error) {
    // implementation
}

func (r *userRepository) Save(ctx context.Context, user *model.User) error {
    // implementation
}
```

**Why this matters:** If `userRepository` is missing a method that `service.UserRepository` requires, the compiler error appears in `NewUserRepository` — right where you're building the implementation. You don't discover it later in `main.go` or when a test fails.

### Multi-Consumer Interfaces

When the same implementation satisfies interfaces from different consumers, the constructor returns a composite interface:

```go
// Two different consumers need different views of the same repository
// package service:   type UserRepository interface { FindByID(...); Save(...) }
// package reporting: type UserQuery interface { FindByID(...); ListActive(...) }

// The constructor returns both
func NewUserRepository(db *sql.DB) interface {
    service.UserRepository
    reporting.UserQuery
} {
    return &userRepository{db: db}
}
```

Each consumer still receives only the interface it declared — the composite is only visible at the wiring site. This keeps each consumer's dependency minimal.

### Wiring — Module Factory Pattern

Each module exports a **factory function** at the module root package (`internal/user/`) that wires its own internals and returns a struct of ready-to-use components. This keeps the composition root clean — `main.go` only knows about modules, not their internal layers.

```go
// internal/user/module.go — the module's public factory
package user

import (
    "database/sql"

    "myapp/internal/user/handler"
    "myapp/internal/user/repository"
    "myapp/internal/user/service"
)

// Services exposes what this module provides to the outside world
type Services struct {
    Handler     *handler.UserHandler
    UserService service.UserService      // exposed as interface for cross-module use
}

// New wires the module's internal dependency graph and returns ready-to-use components
func New(db *sql.DB, emailSender service.EmailSender, logger service.Logger) *Services {
    repo := repository.NewUserRepository(db)               // returns service.UserRepository
    svc := service.NewUserService(repo, emailSender, logger)
    h := handler.NewUserHandler(svc)

    return &Services{
        Handler:     h,

From ovargas/virtual-team, MIT.

More from ovargas/virtual-team