Go Hexagonal Architecture

Welcome to visit my blog post

Project Overview

This project is a Go microservice framework based on Hexagonal Architecture and Domain-Driven Design. It provides a clear project structure and design patterns to help developers build maintainable, testable, and scalable applications.

Hexagonal Architecture (also known as Ports and Adapters Architecture) divides the application into internal and external parts, implementing Separation of Concerns and Dependency Inversion Principle through well-defined interfaces (ports) and implementations (adapters). This architecture decouples business logic from technical implementation details, facilitating unit testing and feature extension.

Core Features

Architecture Design

• Domain-Driven Design (DDD) - Organize business logic through concepts like Aggregates, Entities, and Value Objects
• Hexagonal Architecture - Divide the application into domain, application, and adapter layers
• Dependency Injection - Use Wire for dependency injection, improving code testability and flexibility
• Repository Pattern - Abstract data access layer with transaction support
• Domain Events - Implement Event-Driven Architecture, supporting loosely coupled communication between system components
• CQRS Pattern - Command and Query Responsibility Segregation, optimizing read and write operations
• Interface-Driven Design - Use interfaces to define service contracts, implementing Dependency Inversion Principle

Technical Implementation

• RESTful API - Implement HTTP API using the Gin framework
• Database Support - Integrate GORM with support for MySQL, PostgreSQL, and other databases
• Cache Support - Integrate Redis caching with comprehensive error handling, local error definitions for cache misses, and health check implementation for monitoring cache availability
• Enhanced Cache - Advanced cache features including negative caching to prevent cache penetration, distributed locking for cache consistency, and key tracking for improved hit rates
• MongoDB Support - Integration with MongoDB for document storage
• Logging System - Use Zap for high-performance logging with structured context support for tracing and debugging
• Configuration Management - Use Viper for flexible configuration management
• Graceful Shutdown - Support graceful service startup and shutdown
• Unit Testing - Use go-sqlmock, redismock, and testify/mock for comprehensive test coverage with enhanced HTTP testing utilities and improved DTO handling
• Transaction Support - Provide no-operation transaction implementation, simplifying service layer interaction with repository layer, complete with mock transaction implementation and lifecycle hooks (Begin, Commit, and Rollback) for testing
• Asynchronous Event Processing - Support for asynchronous event handling with worker pools, event persistence, and replay capabilities

Development Toolchain

• Code Quality - Integrate Golangci-lint for code quality checks
• Commit Standards - Use Commitlint to ensure Git commit messages follow conventions
• Pre-commit Hooks - Use Pre-commit for code checking and formatting
• CI/CD - Integrate GitHub Actions for continuous integration and deployment

Recent Enhancements

Unified Error Handling

• Extended error handling with consistent error types and error wrapping functions
• Support for structured error details and HTTP status code mapping
• Error comparison capabilities for more robust error checking

Enhanced Structured Logging

• Context-aware logging with support for request IDs, user IDs, and trace IDs
• Consistent log formatting and level management
• Improved debugging capabilities with contextual information

Asynchronous Event System

• Worker pool-based event processing for improved throughput
• Event persistence and replay capabilities for reliability
• Graceful shutdown support for event processing

Advanced Caching Features

• Negative caching to protect against cache penetration
• Distributed locking to prevent cache stampede
• Key tracking for improved cache hit rates
• Cache consistency mechanisms for data integrity

Project Structure

.
├── adapter/                # Adapter Layer - External system interactions
│   ├── amqp/               # Message queue adapters
│   ├── dependency/         # Dependency injection configuration
│   │   └── wire.go         # Wire DI setup with interface bindings
│   ├── job/                # Scheduled task adapters
│   └── repository/         # Data repository adapters
│       ├── mysql/          # MySQL implementation
│       │   └── entity/     # Database entities and repo implementations
│       ├── postgre/        # PostgreSQL implementation
│       ├── mongo/          # MongoDB implementation
│       └── redis/          # Redis implementation
│           └── enhanced_cache.go  # Enhanced cache with advanced features
├── api/                    # API Layer - HTTP requests and responses
│   ├── dto/                # Data Transfer Objects for API
│   ├── error_code/         # Error code definitions
│   ├── grpc/               # gRPC API handlers
│   └── http/               # HTTP API handlers
│       ├── handle/         # Request handlers using domain interfaces
│       ├── middleware/     # HTTP middleware
│       ├── paginate/       # Pagination handling
│       └── validator/      # Request validation
├── application/            # Application Layer - Use cases coordinating domain objects
│   ├── core/               # Core interfaces and base implementations
│   │   └── interfaces.go   # UseCase and UseCaseHandler interfaces
│   └── example/            # Example use case implementations
│       ├── create_example.go     # Create example use case
│       ├── delete_example.go     # Delete example use case
│       ├── get_example.go        # Get example use case
│       ├── update_example.go     # Update example use case
│       └── find_example_by_name.go # Find example by name use case
├── cmd/                    # Command-line entry points
│   └── main.go             # Main application entry point
├── config/                 # Configuration management
│   ├── config.go           # Configuration structure and loading
│   └── config.yaml         # Configuration file
├── domain/                 # Domain Layer - Core business logic
│   ├── aggregate/          # Domain aggregates
│   ├── dto/                # Domain Data Transfer Objects
│   ├── event/              # Domain events
│   ├── model/              # Domain models
│   ├── repo/               # Repository interfaces
│   ├── service/            # Domain services
│   └── vo/                 # Value Objects
└── tests/                  # Test utilities and examples
    ├── migrations/         # Database migrations for testing
    ├── mysql.go            # MySQL test utilities
    ├── postgresql.go       # PostgreSQL test utilities
    └── redis.go            # Redis test utilities

Architecture Design Principles

Layer Separation

1. Domain Layer (domain/)
2. Contains core business logic and rules
3. Defines domain models, aggregates, and value objects
4. Declares repository interfaces and domain services

5. Independent of external concerns

6. Application Layer (application/)

7. Implements use cases and orchestrates domain objects
8. Handles transaction boundaries
9. Coordinates between domain objects and external systems

10. Contains no business rules

11. Adapter Layer (adapter/)

12. Implements interfaces defined by domain and application layers
13. Handles external concerns (databases, HTTP, messaging)
14. Provides concrete implementations of ports

15. Contains technical details and frameworks

16. API Layer (api/)

17. Handles HTTP/gRPC requests and responses
18. Manages data transformation between DTOs and domain objects
19. Implements API-specific validation and error handling
20. Provides API documentation and versioning

Key Architectural Elements

This structure enforces the Hexagonal Architecture principles:

1. Interface-Implementation Separation:
2. Domain layer defines interfaces (ports)
3. Adapter layer provides implementations (adapters)

4. Dependency flows inward, with outer layers depending on inner layers

5. Dependency Inversion:

6. High-level modules (domain/application) depend on abstractions
7. Low-level modules (adapters) implement these abstractions

8. All dependencies are injected through interfaces

9. Domain-Centric Design:

10. Domain models are pure business entities without technical concerns
11. Repository interfaces declare what the domain needs

12. Service interfaces define business operations

13. Clean Boundaries:

14. Each layer has clear responsibilities and dependencies
15. Data transformation occurs at layer boundaries
16. No leakage of implementation details between layers

Design Patterns and Principles

1. Dependency Inversion
2. High-level modules define interfaces
3. Low-level modules implement interfaces

4. Dependencies point inward toward the domain

5. Interface Segregation

6. Interfaces are specific to use cases
7. Clients only depend on methods they use

8. Prevents interface pollution

9. Single Responsibility

10. Each component has one reason to change
11. Clear separation of concerns

12. Focused and maintainable code

13. Open/Closed

14. Open for extension
15. Closed for modification
16. New features through new implementations

Architecture Layers

Domain Layer

The domain layer is the core of the application, containing business logic and rules. It is independent of other layers and does not depend on any external components.

• Models: Domain entities and value objects

• Example: Example entity, containing basic properties like ID, name, alias, etc.

• Repository Interfaces: Define data access interfaces

• IExampleRepo: Example repository interface, defining operations like create, read, update, delete, etc.
• IExampleCacheRepo: Example cache interface, defining health check methods

• Transaction: Transaction interface, supporting transaction begin, commit, and rollback

• Domain Services: Handle business logic across entities

• IExampleService: Service interface defining contracts for example-related operations

• ExampleService: Implementation of the example service interface, handling business logic for example entities

• Domain Events: Define events within the domain

• ExampleCreatedEvent: Example creation event
• ExampleUpdatedEvent: Example update event
• ExampleDeletedEvent: Example deletion event
• AsyncEventBus: Asynchronous event processing with persistence

Application Layer

The application layer coordinates domain objects to complete specific application tasks. It depends on domain interfaces but not on concrete implementations, following the Dependency Inversion Principle.

• Use Cases: Define application functionality
• CreateExampleUseCase: Create example use case
• GetExampleUseCase: Get example use case
• UpdateExampleUseCase: Update example use case
• DeleteExampleUseCase: Delete example use case

• FindExampleByNameUseCase: Find example by name use case

• Commands and Queries: Implement CQRS pattern

• Each use case defines Input and Output structures, representing command/query inputs and results

• Event Handlers: Process domain events

• LoggingEventHandler: Logging event handler, recording all events
• ExampleEventHandler: Example event handler, processing events related to examples

Adapter Layer

The adapter layer implements interaction with external systems, such as databases and message queues.

• Repository Implementation: Implement data access interfaces
• EntityExample: MySQL implementation of example repository
• NoopTransaction: No-operation transaction implementation, simplifying testing
• MySQL: MySQL connection and transaction management -