Working with Multiple Services in Goa

Design and implement scalable microservice architectures with Goa

In real-world applications, it’s common to have multiple services that work together to form a complete system. Goa makes it easy to design and implement multiple services within a single project. This guide will walk you through the process of creating and managing multiple services effectively.

See also how to build an Elegant Monolith with Goa.

Understanding Multiple Services

A service in Goa represents a logical grouping of related endpoints that provide specific functionality. While simple applications might only need one service, larger applications often benefit from splitting functionality across multiple services. This approach enables better organization of API endpoints, clearer separation of concerns, easier maintenance and testing, independent deployment capabilities, and granular security controls.

Service Architecture Patterns

When designing a multi-service system, services typically fall into two categories: front services which are exposed to the outside world and back services which are used by front services. Understanding these patterns helps in designing a scalable and maintainable architecture.

Service Organization

Goa offers flexibility in how you organize your services’ designs and generated code. Let’s explore the two main approaches: independent and unified designs.

Independent Design Approach

The independent approach treats each service as a standalone unit, in this case goa gen is invoked for each service separately and they each contain their own gen/ directory. This makes it possible to easily move services to separate repositories and to version them independently.

Unified Design Approach

The unified approach defines a top-level design file that imports all the services design package and defines a common API:

// design/design.go - Top-level design file package design  import (  _ "myapi/services/users/design" // Each service has its own design which gets imported into the top-level design  _ "myapi/services/products/design"  . "goa.design/goa/v3/dsl" )  var _ = API("myapi", func() {  Title("My API")  Description("Multi-service API example") })

This approach centralizes code generation and type sharing:

  • Generated code lives in the root gen/ directory
  • A single goa gen command generates all service code
  • Shared types defined using the Meta struct:pkg:path key are automatically available across services
  • The system maintains a unified OpenAPI specification

The unified approach is well-suited for grouping related services and sharing common types. It ensures that all the related services are versioned together and makes it easier to manage dependencies and updates.

Transport Considerations

Your choice of transport protocol significantly impacts how services interact. Let’s examine the benefits of each approach:

HTTP Services

HTTP is an excellent choice for external-facing services. It offers universal client compatibility, a rich ecosystem of tools and middleware, and familiar REST patterns. HTTP is also easy to debug and test, and it’s a natural fit for web applications.

The flexibility of HTTP comes with a cost though: servers potentially need to deal with different types of encoding, they also need to choose a specific style for the their API. Arguably the main drawback is typically poor encoding performance as compared to a binary protocol like protobuf.

gRPC Services

gRPC is particularly well-suited for internal service communication due to its high performance, low latency, and built-in streaming support. gRPC also provides built-in service discovery when reflection is enabled. Additionally, gRPC enables efficient multiplexing of requests and responses over a single connection, which can lead to significant performance gains when communicating between services.

The main drawback of gRPC is that it is not as well-suited for external-facing services since it requires a client library to encode and decode the binary messages. Additionally, gRPC is not as widely adopted as HTTP so it may not be as suitable for services that expect a wide range of clients.

TL;DR

When building a system composed of multiple services, a good approach is to use HTTP for services that need to be exposed to the outside world and gRPC for services that only need to communicate with other internal services.

Repository Structure

A well-organized repository helps teams navigate and maintain the codebase effectively. A unified structure also makes it easier for developers to move between systems and services. Here’s a recommended structure:

myapi/ ├── README.md # System overview and setup guide ├── design/ # Shared design elements │ ├── design.go # Top-level design for unified approach │ └── types/ # Shared type definitions defined with Meta("struct:pkg:path") ├── gen/ # Generated code (unified design approach) │ ├── http/ # HTTP transport layer code │ ├── grpc/ # gRPC transport layer code │ └── types/ # Generated shared types ├── scripts/ # Development and deployment scripts └── services/ # Service implementations ├── users/ # Example: User service │ ├── cmd/ # Service executables │ ├── design/ # Service-specific design │ ├── gen/ # Generated code (independent design approach) │ ├── users.go # Business logic │ └── README.md # Service documentation └── products/ # Example: Product service └── ...

The directory structure follows a clean separation of concerns and modular organization:

  • README.md: Contains the overall system documentation, setup instructions, and architectural overview.

  • design/: Houses the shared design elements across services

    • design.go: Defines the top-level API design using Goa’s DSL for a unified approach
    • types/: Contains shared type definitions used across multiple services

  • gen/: Contains the code generated by Goa from the unified design approach

  • services/: Individual service implementations

    • Each service (e.g., orders/, products/) follows a consistent structure:
      • cmd/: Service entry points and executables
      • design/: Service-specific API designs
      • gen/: Service-specific generated code
      • users.go: Business logic implementation
      • README.md: Service-specific documentation

This structure supports both monolithic and microservice deployments, allowing for:

  • Clear separation between services
  • Shared types and design elements
  • Independent service evolution
  • Easy service discovery and navigation

Service Communication Patterns

When designing service interactions, consider these common patterns:

Front and Back Services

Services typically fall into two categories:

  1. Front Services: Public-facing services that:

    • Use HTTP as transport for broad client compatibility
    • Focus on orchestrating requests to back services
    • Handle authentication and authorization of external requests
    • Initiate observability contexts (traces, metrics)
    • Define broad APIs with shallow implementations

  2. Back Services: Internal services that:

    • Often use gRPC for performance benefits
    • Implement core business logic
    • May use private identity mechanisms (e.g., spiffe)
    • Contribute to existing observability contexts
    • Define focused APIs with deep implementations

A common architecture pattern is to have a few front services (sometimes just one) that expose your platform’s capabilities to external clients, with multiple back services handling the actual business logic.

Scripts and Automation

The scripts/ directory provides automation for common development and deployment tasks. These scripts adapt to both unified and independent approaches, making it easy to manage your services regardless of the chosen architecture.

Development Scripts

The core development scripts handle code generation, building, and testing:

# scripts/gen.sh - Code generation script #!/bin/bash if [ "$1" == "" ]; then  # Unified approach: generate all services  goa gen myapi/design else  # Independent approach: generate specific service  cd services/$1 && goa gen myapi/services/$1/design fi  # scripts/build.sh - Build script #!/bin/bash if [ "$1" == "" ]; then  # Build all services  for service in services/*/; do  service=${service%*/}  echo "Building ${service##*/}..."  go build -o bin/${service##*/} ./$service/cmd/${service##*/}  done else  # Build specific service  go build -o bin/$1 ./services/$1/cmd/$1 fi  # scripts/test.sh - Test runner #!/bin/bash if [ "$1" == "" ]; then  # Test all services and shared code  go test ./... -v else  # Test specific service  go test ./services/$1/... -v fi

Deployment Scripts

The deployment scripts handle service execution and container deployment:

# scripts/run.sh - Local service runner #!/bin/bash if [ "$1" != "" ]; then  # Run specific service  ./bin/$1 else  # List available services  echo "Available services:"  ls bin/ fi  # scripts/deploy.sh - Kubernetes deployment #!/bin/bash if [ "$1" != "" ]; then  deploy_service() {  echo "Deploying $1..."  docker build -t myapi/$1 ./services/$1  docker push myapi/$1  kubectl apply -f ./services/$1/k8s/  }  deploy_service $1 else  # Deploy all services  for service in services/*/; do  service=${service%*/}  deploy_service ${service##*/}  done fi

These scripts support both development workflows:

Unified Design Approach:

  • Single command generates all service code
  • Centralized testing across services
  • Coordinated builds and deployments
  • Shared dependency management

Independent Design Approach:

  • Per-service code generation
  • Isolated testing environments
  • Independent build processes
  • Service-specific deployments

Service Implementation

Each service runs as a separate executable, promoting isolation and independent scaling. Here’s an example service implementation:

// services/users/cmd/users/main.go - Service entry point package main  import (  "context"  "flag"  "fmt"  "net/http"  "os"  "os/signal"  "strings"  "sync"  "syscall"  "time"   "goa.design/clue/log"  goahttp "goa.design/goa/v3/http"   genusersserver "myapi/services/users/gen/http/users/server"  genusers "myapi/services/users/gen/users"  "myapi/services/users" )  func main() {  // Parse command line flags  var (  httpAddr = flag.String("http-addr", ":8080", "HTTP listen address")  debug = flag.Bool("debug", false, "Enable debug mode")  )  flag.Parse()   // Initialize context with logger  format := log.FormatJSON  if log.IsTerminal() {  format = log.FormatTerminal  }  ctx := log.Context(context.Background(), log.WithFormat(format))  if *debug {  ctx = log.Context(ctx, log.WithDebug())  log.Debugf(ctx, "debug mode enabled")  }   // Create service and endpoints  svc := users.NewUsers()  endpoints := genusers.NewEndpoints(svc)   // Create transport handlers  mux := goahttp.NewMuxer()  server := genusersserver.New(endpoints, mux, goahttp.RequestDecoder, goahttp.ResponseEncoder, nil, nil)  server.Mount(mux)   // Log mounted endpoints  for _, m := range server.Mounts {  log.Printf(ctx, "mounted %s %s", m.Method, m.Pattern)  }   // Create HTTP server  mux.Use(log.HTTP(ctx)) // Add logger to request context  httpServer := &http.Server{  Addr: *httpAddr,  Handler: mux,  }   // Handle shutdown gracefully  errc := make(chan error)  go func() {  c := make(chan os.Signal, 1)  signal.Notify(c, syscall.SIGINT, syscall.SIGTERM)  errc <- fmt.Errorf("signal: %s", <-c)  }()   ctx, cancel := context.WithCancel(ctx)  var wg sync.WaitGroup  wg.Add(1)   go func() {  defer wg.Done()   // Start HTTP server  go func() {  log.Printf(ctx, "HTTP server listening on %s", *httpAddr)  errc <- httpServer.ListenAndServe()  }()   <-ctx.Done()  log.Print(ctx, "shutting down HTTP server")   // Shutdown gracefully with a 30s timeout  ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)  defer cancel()   if err := httpServer.Shutdown(ctx); err != nil {  log.Errorf(ctx, err, "failed to shutdown HTTP server")  }  }()   // Wait for shutdown  if err := <-errc; err != nil && !strings.HasPrefix(err.Error(), "signal:") {  log.Errorf(ctx, err, "server error")  }  cancel()  wg.Wait()  log.Print(ctx, "server exited") }

The service implementation contains the business logic:

// services/users/users.go - Service implementation package users  import (  "context"   "goa.design/clue/log"  "myapi/services/users/gen/users" )  // Users implements the user service interface type Users struct {}  // NewUsers creates a new user service instance func NewUsers() *Users {  return &Users{} }  // List retrieves all users func (s *Users) List(ctx context.Context, p *users.ListPayload) (*users.UserCollection, error) {  log.Printf(ctx, "listing users with filter: %v", p.Filter)  // Implementation details...  return nil, nil }

Best Practices

When building multi-service systems with Goa, follow these guidelines:

  1. Choose Appropriate Transport Use gRPC for internal services and HTTP for external APIs.

  2. Plan for Evolution Version your services and plan for backward compatibility.

  3. Implement Robust Error Handling Define clear error types and handle cross-service failures gracefully.

  4. Document Service Interactions Maintain clear documentation of service APIs and dependencies.

Next Steps

To deepen your understanding of multi-service systems: