Skip to content

v1.0.0: refactor: code improve

Latest
Latest
Compare
Choose a tag to compare
@RanchoCooper RanchoCooper released this 24 Mar 00:51
v1.0.0
0f754bd

Go Hexagonal - v1.0.0

Overview

Go Hexagonal Architecture is a production-ready microservice framework implementing Hexagonal Architecture (Ports and Adapters) and Domain-Driven Design principles. This framework provides a clear and maintainable project structure, along with a comprehensive set of design patterns to help developers build scalable, testable, and maintainable applications.

Core Architecture

The framework implements Hexagonal Architecture, which divides the application into internal (domain) and external layers, enforcing a clean separation of concerns through well-defined interfaces (ports) and implementations (adapters). This approach decouples business logic from technical implementation details, enabling:

  • Clear boundaries between domain logic and infrastructure
  • Enhanced testability through dependency inversion
  • Independent evolution of business and technical components
  • Flexibility in adapting to changing infrastructure requirements

Key Features

Architecture Design

  • Domain-Driven Design (DDD) - Organize business logic using aggregates, entities, and value objects
  • Hexagonal Architecture - Clean separation between domain, application, and adapter layers
  • Interface-Driven Design - Define clear service contracts implementing the Dependency Inversion Principle
  • CQRS Pattern - Command and Query Responsibility Segregation for optimized read/write operations
  • Domain Events - Event-driven architecture support for loosely coupled communication
  • Repository Pattern - Abstract data access layer with transaction support
  • Dependency Injection - Uses Google Wire for explicit, compile-time dependency injection

Technical Implementation

  • Database Support - Integration with MySQL and PostgreSQL via GORM
  • Cache Support - Redis integration for high-performance caching
  • RESTful API - HTTP API implementation using the Gin framework
  • Logging System - High-performance structured logging with Uber's Zap
  • Configuration Management - Flexible configuration via Viper with environment variable support
  • Graceful Shutdown - Controlled service startup and shutdown procedures
  • NoopTransaction - No-operation transaction implementation to simplify testing and development

Testing Strategy

  • Comprehensive Test Coverage - Unit and integration test support
  • Mock Implementations - Interface-based testing with testify/mock
  • Database Mocking - go-sqlmock and redismock for database and cache testing

Development Toolchain

  • Code Quality - Golangci-lint integration for code quality checks
  • Commit Standards - Conventional commits enforcement via Commitlint
  • Pre-commit Hooks - Automated code checking and formatting
  • CI/CD - GitHub Actions integration for continuous integration and deployment

Project Structure

The project follows a clean, layered structure:

├── domain/          # Core business logic and domain models
├── application/     # Use cases coordinating domain objects
├── adapter/         # External system implementations
├── api/             # HTTP/gRPC API handlers
├── cmd/             # Application entry points
├── config/          # Configuration management
├── tests/           # Integration testing
└── util/            # Utility functions

Technical Design Principles

  1. Interface-Implementation Separation

    • Domain layer defines interfaces (ports)
    • Adapter layer provides implementations (adapters)
    • Dependency flows inward, following clean architecture principles

  2. Dependency Inversion

    • High-level modules depend on abstractions
    • Low-level modules implement these abstractions
    • All dependencies are injected through interfaces

  3. Domain-Centric Design

    • Domain models are pure business entities
    • Repository interfaces declare domain-focused capabilities
    • Service interfaces define clean business operations

  4. Data Mapping and Transformation

    • Clear separation of layer-specific data models
    • Efficient object mapping using jinzhu/copier
    • Standardized approach to entity-model-DTO conversions

Recent Improvements

  • Environment Variable Support - Flexible configuration for containerized deployments
  • Unified Error Handling - Consistent application-level error type system
  • Request Logging Middleware - Comprehensive request/response tracking
  • Request ID Tracking - Distributed tracing capabilities
  • Internationalization - Multi-language validation error messages
  • CORS Support - Configurable cross-origin request handling
  • Performance Diagnostics - Integrated pprof tools for production debugging

Getting Started

Prerequisites

  • Go 1.16+
  • Docker (for local development with MySQL/Redis)

Quick Start

# Clone the repository
git clone https://github.com/yourusername/go-hexagonal.git

# Start MySQL with Docker
docker run --name mysql-local \
  -e MYSQL_ROOT_PASSWORD=mysqlroot \
  -e MYSQL_DATABASE=go-hexagonal \
  -e MYSQL_USER=user \
  -e MYSQL_PASSWORD=mysqlroot \
  -p 3306:3306 \
  -d mysql:latest

# Install development tools
make init && make precommit.rehook

# Run the application
go run cmd/main.go

# Run tests
go test ./...

Future Plans

  • gRPC Support - Full gRPC service implementation
  • Monitoring Integration - Prometheus metrics collection
  • Extended Event Sourcing - Enhanced event persistence and replay

License

This project is licensed under the MIT License - see the LICENSE file for details.

For more information, visit project blog.

Assets 2
Loading