go-cloud

module
v0.0.0-...-b25cd16 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 24, 2024 License: MIT

README 

                                           ,--,
                                         ,--.'|                               ,---,
                ,---.      ,---,.        |  | :     ,---.           ,--,    ,---.'|
    ,----._,.  '   ,'\   ,'  .' |        :  : '    '   ,'\        ,'_ /|    |   | :
   /   /  ' / /   /   |,---.'   , ,---.  |  ' |   /   /   |  .--. |  | :    |   | |
  |   :     |.   ; ,. :|   |    |/     \ '  | |  .   ; ,. :,'_ /| :  . |  ,--.__| |
  |   | .\  .'   | |: ::   :  .'/    / ' |  | :  '   | |: :|  ' | |  . . /   ,'   |
  .   ; ';  |'   | .; ::   |.' .    ' /  '  : |__'   | .; :|  | ' |  | |.   '  /  |
  '   .   . ||   :    |'---'   '   ; :__ |  | '.'|   :    |:  | : ;  ; |'   ; |:  |
   '---'-'| | \   \  /         '   | '.'|;  :    ;\   \  / '  :  '--'   \   | '/  '
   .'__/\_: |  '----'          |   :    :|  ,   /  '----'  :  ,      .-./   :    :|
   |   :    :                   \   \  /  ---'-'            '--'----'    \   \  /
    \   \  /                     '----'                                   '----'
     '--'-'

go-cloud is is an open-source CLI tool designed to streamline the development of cloud-native Go backend services. It enables developers and teams to generate boilerplate code for microservices rapidly, ensuring consistency, scalability, and maintainability across projects.

By leveraging go-cloud, you can focus on implementing business logic rather than worrying about repetitive setup tasks. It supports interactive configuration through a user-friendly TUI (Text User Interface) and allows for customization via YAML configuration files that act as blueprints for your microservices.

Table of Contents

Motivation

In the fast-paced world of software development, especially in organizations that embrace microservices architecture, maintaining consistency and adhering to best practices can be challenging. Teams often face irregularities and misunderstandings when implementing complex architectural patterns like Clean Architecture in Go microservices.

go-cloud was developed to address these challenges and provide substantial benefits to an organization’s tech team. The tool serves as a bridge between the conceptual architectural design and the actual code implementation, ensuring that everyone—from team leaders to developers—is aligned.

Benefits to the Tech Team

  • Alignment Across Teams: go-cloud empowers team leaders, product managers, product owners, and developers to collaboratively plan and configure microservices. The YAML configuration files act as blueprints, making it easier for all stakeholders to understand the architecture and expected functionalities.
  • Standardization of Architecture: Enforces a consistent project structure that adheres to Clean Architecture principles. This reduces confusion and discrepancies in how different teams implement microservices, leading to a more cohesive codebase.
  • Enhanced Productivity: Automates the generation of boilerplate code, allowing developers to focus on business logic rather than repetitive setup tasks. This accelerates development cycles and reduces time-to-market for new features.
  • Improved Maintainability: Generates modular and clean code, which is easier to maintain and extend. This is crucial for long-term project health and scalability.
  • Facilitates Onboarding: New team members can get up to speed faster by working with familiar project structures and standardized codebases.
  • Transparent Planning: Helps product managers and owners visualize the technical aspects of planned features. The configuration files serve as a communication tool, bridging the gap between technical and non-technical team members.
  • Flexibility and Customization: While enforcing best practices, go-cloud allows for customization through templates and configuration files. Teams can adapt the generated code to fit specific project needs.
  • Risk Mitigation: By standardizing the code generation process, the tool minimizes the risk of errors that can occur during manual setup, improving overall code quality.

By emphasizing the blueprint concept, go-cloud acts as a template generator, translating your defined architecture into ready-to-use code. This approach not only saves time but also ensures that the generated code adheres to best practices and architectural standards.

Features

  • Rapid Project Scaffolding: Generate a fully-functional Go backend project with a single command.
  • Interactive Configuration: Use the TUI to create or edit project configurations without manually editing YAML files.
  • Blueprint-Based Generation: Configuration files serve as blueprints, defining the architecture and serving as templates for code generation.
  • Clean Architecture Implementation: Enforces separation of concerns and modular design.
  • Protocol Support: Currently supports REST protocol with plans to extend to other communication protocols.
  • Dependency Injection: Integrates with Uber’s Dig for efficient dependency management.
  • Customizable Templates: Templates can be customized to fit your project’s specific needs (need to rebuilt go-cloud sources)

Clean Architecture

Clean Architecture is a software design philosophy that emphasizes the separation of concerns, making your codebase more maintainable, testable, and scalable. It allows you to build systems that are independent of frameworks, databases, and user interfaces.

Core Principles

  • Separation of Concerns:
    • Divide the application into layers, each with distinct responsibilities.
    • Prevents changes in one layer from affecting others unnecessarily.
  • Dependency Rule:
    • Inner layers should not depend on outer layers.
    • Code dependencies point inwards, towards high-level policies.
  • Layered Architecture:
    • Entities (Domain Models): Core business logic and data structures.
    • Use Cases (Interactors): Application-specific business rules.
    • Interface Adapters: Convert data from the use cases to a format suitable for frameworks or external agencies like databases and UI.
    • Frameworks & Drivers (External Interfaces): Databases, UI, web frameworks, and other I/O mechanisms.
  • Independence:
    • Framework Independent: Business logic is not tied to any specific framework.
    • UI Independent: The UI can change without changing the rest of the system.
    • Database Independent: Business rules are not bound to a specific database.

Benefits of Clean Architecture

  • Maintainability: Easier to update and modify the system without breaking other parts.
  • Testability: Business logic can be tested independently of external factors.
  • Flexibility: Swap out databases, frameworks, and UI components with minimal impact.
  • Scalability: Modular design allows the system to grow and adapt to new requirements.

Bridging Clean Architecture and go-cloud

Imagine you’re building a city. In this city, you have different layers:

  • Blueprints (Architecture Plans): The detailed designs that outline how the city should be built—like where the roads go, where the buildings stand, and how utilities are connected.
  • Construction Teams (Developers): They use these blueprints to construct the city, following the designs carefully to ensure everything works together.
  • City Officials (CTO, Product Managers): They plan the city’s expansion, ensuring it meets the needs of the residents and complies with regulations.

Now, think of go-cloud as a powerful tool that helps everyone involved:

  • For City Officials (CTO, Product Managers, Lead Developers):
    • go-cloud allows them to define the blueprints of the city (your backend services) in a clear and structured way using YAML configuration files.
    • They can outline what services are needed, how they should interact, and what data models they use, without getting bogged down in technical details.
    • This ensures that the vision for the city is accurately translated into the construction plans.
  • For Construction Teams (Lead Developers, Developers):
    • go-cloud takes these blueprints and automatically builds the foundation of the city.
    • It sets up the roads (service routes), constructs the buildings (services and models), and lays down the utilities (repositories and handlers).
    • Developers can then focus on adding the unique features to each building, customizing and extending the generated code to meet specific needs.
  • For Residents (Users and Stakeholders):
    • The city is built efficiently and reliably, providing them with the services they need without unnecessary delays.
    • Because the city is well-planned and structured, it’s easier to maintain and expand in the future.

Clean Architecture in this analogy ensures that:

  • Buildings (Services) are well-organized: Each building has a specific purpose and is constructed following best practices.
  • Roads and Utilities (Communication and Data Flow) are standardized: Making it easy to navigate the city and ensure consistent delivery of services.
  • Future Expansion is Simplified: Adding new buildings or modifying existing ones doesn’t disrupt the entire city.

go-cloud empowers teams to collaboratively design their “city” from the ground up:

  • CTO and Product Owners can work together to outline the requirements and services needed.
  • Lead Developers can use go-cloud to generate the initial codebase, ensuring adherence to Clean Architecture principles.
  • Developers can extend and customize the code, adding business logic and features.
  • DevOps and Infrastructure Teams benefit from the standardized structure, making deployment and scaling more manageable.

Example Scenario:

A CTO, Product Manager, and Lead Developer are planning a new microservice for handling user authentication and profile management.

  1. Defining the Blueprint: They use go-cloud’s YAML configuration to define the services (AuthService), models (User, Profile), and repositories (UserRepository).
  2. Collaborative Planning:
    • The Product Manager outlines the required features: user registration, login, profile updates.
    • The Lead Developer specifies the technical details: data models, methods, and routes.
  3. Generating the Foundation:
    • They run go-cloud generate with the configuration file.
    • go-cloud generates the project structure, adhering to Clean Architecture.
  4. Extending and Customizing:
    • Developers add business logic to the generated methods.
    • They implement security measures, validation, and integrate external services as needed.
  5. Deployment and Scaling:
    • DevOps teams benefits the standardized structure for setting up CI/CD pipelines.
    • The modular design makes scaling specific services straightforward.

Outcome:

  • The team efficiently develops a robust, maintainable microservice.
  • The standardized architecture simplifies onboarding new developers and facilitates future enhancements.
  • Stakeholders have a clear understanding of the system’s structure and capabilities.

By bridging Clean Architecture and go-cloud through this collaborative and structured approach, organizations can ensure that their backend systems are built on solid foundations, ready to adapt and grow with their needs.

Example Structure Generated by go-cloud:

your_project/
├── cmd/
│   └── main.go           // Entry point of the application
├── internal/
│   ├── handlers/         // Interface Adapters layer
│   ├── repositories/     // Data access layer
│   ├── services/         // Use Cases layer
│   └── models/           // Entities layer
├── go.mod                // Go module file
└── go.sum                // Go dependencies

Installation

To install go-cloud, ensure you have Go installed (version 1.18 or higher), and then run:

go install github.com/Systenix/go-cloud@latest

This command will download and install the go-cloud binary into your $GOPATH/bin directory.

Getting Started

Creating a New Project

  1. Prepare a Configuration File: Define your project structure in a YAML configuration file. See Configuration File Structure for details.

  2. Generate the Project: Run the create command with the path to your configuration file.

    go-cloud generate --config path/to/your_config.yaml

  3. Build and Run: Navigate to the generated project directory, tidy up dependencies, and run your application.

    cd generated/github.com/YourUsername/your_project_name
go mod tidy
go run cmd/main.go

Editing a Project Configuration

  1. Start the Config TUI: Use the config command to create or edit a project configuration interactively.

    go-cloud config --output path/to/your_config.yaml       # Create a new configuration file to the specified path
go-cloud config                                         # Create a new configuration file in the current directory

    • To edit an existing configuration:

      go-cloud config --config path/to/your_config.yaml --output path/to/updated_config.yaml

  2. Follow the Prompts: The TUI will guide you through setting up your project name, module path, and adding services, models, repositories, handlers, and methods.

  3. Save and Generate: Once you’re satisfied with the configuration, save it, and use the create command to generate the project.

Commands

go-cloud generate

Generates a new Go backend project based on the provided configuration file.

Usage:

go-cloud generate --config path/to/your_config.yaml

For a detailed walkthrough, refer to the Comprehensive Guide.

Flags:

  • -c, --config: Path to the configuration file (YAML). (Required)
  • -h, --help: Display help information.

go-cloud config

Launches an interactive TUI to create or edit a project configuration file.

Usage:

go-cloud config [flags]

Flags:

  • -c, --config: Path to an existing configuration file to edit.
  • -o, --output: Path to save the new or updated configuration file. Defaults to project_config.yaml.
  • -h, --help: Display help information.

Configuration File Structure

The configuration file is a YAML file that defines the structure of your project. It acts as a blueprint, outlining the architecture and components of your microservice.

Understanding the Blueprint

The blueprint configuration file allows you to define:

  • Project Information:
    • project_name: Name of your project.
    • module_path: Go module path (e.g., github.com/YourUsername/your_project).
  • Services: Define one or more services, specifying their types (e.g., rest).
  • Models: Define data models with fields, types, and JSON mappings.
  • Repositories: Specify repositories for data access, linked to models.
  • Handlers: Define HTTP handlers or controllers that manage incoming requests.
  • Methods: Outline the business logic methods within services.

Configuration Sections

Below is an expanded example configuration file with explanations for each section:

# Root-level project information
project_name: "YourProjectName"
module_path: "github.com/YourUsername/your_project"

# Services section
services:
  - name: "GameService"          # Name of the service
    type: "rest"                 # Type of service (rest)
    models:
      - name: "Player"           # Models used by this service
      - name: "Game"
    repositories:
      - name: "GameRepository"   # Repositories associated with this service
        model: "Game"
    handlers:
      - name: "GameHandler"      # HTTP handler for the service
        service: "GameService"
        routes:
          - path: "/search-game"     # Endpoint path
            method: "POST"           # HTTP method
            function: "SearchGame"   # Function name in the handler
            service_method: "SearchGame"  # Corresponding service method
            request_model: "Player"       # Model for request payload
            response_model: "Game"        # Model for response payload
          - path: "/start-solo-game"
            method: "POST"
            function: "StartSoloGame"
            service_method: "StartSoloGame"
            request_model: "Player"
            response_model: "Game"
    methods:
      - name: "SearchGame"        # Business logic method in the service
        params:
          - name: "ctx"           # Parameter name
            type: "context.Context"  # Parameter type
          - name: "player"
            type: "*models.Player"
        returns:
          - name: "game"
            type: "*models.Game"
          - name: "err"
            type: "error"
      - name: "StartSoloGame"
        params:
          - name: "ctx"
            type: "context.Context"
          - name: "player"
            type: "*models.Player"
        returns:
          - name: "game"
            type: "*models.Game"
          - name: "err"
            type: "error"

# Models section
models:
  - name: "Player"               # Model name
    fields:
      - name: "Username"         # Field name
        type: "string"           # Field type
        json_name: "username"    # JSON key in serialized output
  - name: "Game"
    fields:
      - name: "GameID"
        type: "string"
        json_name: "game_id"
      - name: "Players"
        type: "[]Player"         # Nested model (array of Player)
        json_name: "players"
# Additional configurations (optional)

Key Components:

  • Services:
    • name: Identifier for the service.
    • type: Communication protocol (rest).
    • models: List of models the service uses.
    • repositories: Data access layers linked to models.
    • handlers: Define how the service handles incoming requests.
    • methods: Business logic functions within the service.
  • Models:
    • name: Name of the data model.
    • fields: Properties of the model.
      • name: Field name.
      • type: Data type (supports basic types and custom models).
      • json_name: Key name when serialized to JSON.
  • Repositories:
    • name: Name of the repository.
    • model: The model the repository interacts with.
  • Handlers:
    • name: Name of the handler.
    • service: The service it belongs to.
    • routes: HTTP routes managed by the handler.
  • Methods:
    • name: Function name.
    • params: Function parameters.
    • returns: Return values.

Example Explanation:

  • GameService:
    • A RESTful service that uses Player and Game models.
    • Has a GameRepository for data access related to Game models.
    • Includes a GameHandler that handles routes for searching and starting games.
    • Defines methods SearchGame and StartSoloGame for business logic.
  • Models:
    • Player:
      • Represents a player with a Username field.
    • Game:
      • Represents a game with a GameID and a list of Players.
      • The Players field demonstrates nesting by using an array of Player models.

By defining your project’s architecture in this configuration file, go-cloud can generate code that adheres to Clean Architecture principles, ensuring a well-organized and maintainable codebase.

Examples

Generating a Service

  1. Create a Configuration File: Save the above configuration as config/service_config.yaml.

  2. Generate the Project:

    go-cloud generate --config config/service_config.yaml

  3. Run the Application:

    cd generated/github.com/YourUsername/service
go mod tidy
go run cmd/main.go

  4. Test the Endpoints:

    • Search Game:

      curl -X POST http://localhost:8080/search-game -d '{"username":"player1"}' -H "Content-Type: application/json"

    • Start Solo Game:

      curl -X POST http://localhost:8080/start-solo-game -d '{"username":"player1"}' -H "Content-Type: application/json"

Editing an Existing Configuration

  1. Edit the Configuration:

    go-cloud config --config tetris_config.yaml --output updated_tetris_config.yaml

  2. Follow the TUI Prompts: Add new services, models, or modify existing ones.

  3. Generate the Updated Project:

    go-cloud generate --config updated_tetris_config.yaml

Project Status and Roadmap

Current Status

go-cloud is in its early stages of development, and while it’s functional, I'm continuously working to enhance its capabilities and reduces bugs (especially in the TUI). As this project is developed and maintained by a single developer, I'm looking for contributors to help me improve and expand the tool.

Planned Features and Improvements

  • Refactoring the TUI Codebase: I'm planning a significant refactoring of the TUI (Text/Terminal User Interface) codebase to improve usability, maintainability, and extendability.
  • Enhancing the Project Generator: Refactoring the project generator to support more complex configurations and customizations.
  • Support for Additional Protocols: Implementing support for gRPC, GraphQL, and other communication protocols.
  • Dockerfile and Docker Compose Generation: Automatically generate Dockerfiles and docker-compose configurations for containerization.
  • Improved Documentation and Tutorials: Expanding guides, examples, and tutorials to help users make the most of go-cloud.

Source Code Overview

For an in-depth look at the source code and architecture, refer to the Source Code Overview.

Contributing

Contributions are welcome! If you’d like to contribute to go-cloud, please follow these steps:

  1. Fork the Repository: Click the “Fork” button at the top right of this page.

  2. Clone Your Fork:

    git clone https://github.com/YourUsername/go-cloud.git

  3. Create a Branch:

    git checkout -b feature/your-feature-name

  4. Make Your Changes: Implement your feature or fix the bug.

  5. Commit Your Changes:

    git commit -am 'Add new feature'

  6. Push to the Branch:

    git push origin feature/your-feature-name

  7. Create a Pull Request: Go to the original repository and click “New Pull Request”.

Please ensure that your code follows the Go's coding standards and includes tests where appropriate.

License

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

Author

[LAHMAR Kamel (Systenix)]

As a software engineer with a focus for cloud computing, microservices, clean architecture and related stuff, I developed go-cloud to address common challenges in microservices development, contribute to the open-source community and sharpen my knowledge in Go.

Feel free to reach out for collaborations or discussions!

Contact

For any questions or suggestions, please open an issue on GitHub or contact me:

Thank you for using go-cloud! I hope it helps you in your development.

Directories

Path Synopsis
cmd
cli
tui
configure_command
generate_command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.