Go Fast, Small, and Productive With GolangSpell

Introduction to GoSpell

MonolithicService

In the picture MonolithicService can be observed an example of Monolithic architecture, in which all of the application logic is coded, built and deployed as an unit. After refactoring this Monolith into Microservices, the result could be similar to the components presented in the picture Microservices.

Microservices

Golang

As in any other technology, there is always place for some valuable improvements. It can be noticed checking out some Golang applications, that there are not many similarities on how the code is organized. Basically each application is structured in a way that make sense for the application creators but hardly can be correlated with different applications, even inside the same team. While it can slightly reduce the design effort if we look to a single project, it certainly is not scalable in the long run. Inside a fast paced environment in which engineers come and go and the show must go on, having totally different structures all the time means that onboarding a new colleague can represent a huge effort. Building tools to make the life easier can be difficult as well, because it is totally unpredictable how the different applications will look like. Ruby on Rails, as a known very productive environment, took advantage of a more strict code structure to make it possible to deliver tools to deliver faster code following the same structure.

Golang Spell

Golang Spell is a productivity platform for building Microservices using Golang.

Golang Spell makes it possible to build lightning fast Microservices written Go in an easy and productive way. It is possible to generate the boilerplate code using Golang Spell, following a standard structure which can be shared between projects.

• REST — Echo ()
• Configuration — Viper ()
• Logging — Zap ()
• Building new Spells (Platform Plugins) — Cobra ()

It is an extendable platform. That means it is possible to create, publish and integrate new features as Spells, without the need of following any process from the Golangspell team to integrate it. The platform provides the features needed for extending it with new Spells;It provides a common platform where the community can build and share new Spells with the ability to create code to solve many different common problems;Speeds up dramatically the time to market generating the boilerplate code in an elegant fashion;It is Open Source and free for personal and commercial use;

How it works

The Golang Spell platform components starts with two core components, the golangspell tool and the golangspell-core Spell. The platform is totally based in plugins, called Spells in the platform context. The first Spell (golangspell-core), is automatically downloaded and installed when the golangspell tool is executed for the first time. It contains the core features of the platform. These features are responsible for initializing new Microservices, for creating new Spells, for adding new commands to Spells. It is important to understand the platform proposal while joining the community. The idea of the platform is not to add new features to the golangspell tool and the golangspell-core Spell. Instead of that, new specialized Spells should be created when needed. For example, for creating code related to MongoDB, there is another Spell, created using the Golangspell platform, which is responsible for delivering the MongoDB specific features, the golangspell-mongodb, which will be used on this article to create an example Microservice. The new Spells created by the community can be shared with the hole community in a public git repository or can be private, and not even be known by the Golangspell team. It is possible to directly integrate it locally using a private git repository.

Installation

Pre-reqs

Recommended Tool

Installing Golang Spell:

go install github.com/golangspell/golangspell@latest

Checking Golang Spell version

Let’s check if the Golangspell tool was properly installed using the command:

golangspell version

The current version at the article writing time is v0.4.3

Add binaries to Path

[YOUR GOPATH]/bin

[YOUR USER DIRECTORY/go]

/Users/danilo/go/bin

After adding the path, the golangspell command will be available when you create a new terminal

Checking Golang Spell — Core Spell version

The Golang Spell automatically installs the Core Spell. The Spells are plugins which extend the tool capabilities with new features. The Golang Spell — Core Spell is a default Spell from the platform.

golangspell version [Spell name])

To discover the current installed version of the golangspell-core spell the following command can be used:

golangspell version golangspell-core

The current version at the article writing time is v0.5.1

The help command shows the commands available in the golangspell tool.

golangspell help

golangspell [command]

golangspell help [command]

Build the first Microservice

The best way to learn how software works is using it. In this tutorial, you will learn how to build your first Go Microservice using Golang Spell.

User Story

Concepts

The Microservice created to manage the projects will be called project-api.

In the picture Components, can be found the components recommended to deliver the new features. For this tutorial, the cloud infrastructure and the frontend components are out of scope, the focus will be on the backend solution.

Components

Open API Specification

With the API specification defined, the next step is to define the Architectural Model and to create the Microservice.

Architectural Model

The Golang Spell platform is based in the Go ecosystem and it wouldn’t be reasonable to introduce complexity while trying to make things more standardized. This is why the chosen Architectural Model to be applied in the generated code is simple and effective by design, the Clean Architecture.

The Clean Architecture can be considered as an Architecture Guide, built up by Robert Martin

The model proposed in Clean Architecture promotes the application structuring by separating the business logic similarly to the way it is done when the engineering teams are understanding a new feature, in terms of use cases, domain entities and the related artifacts. By following correctly this architecture model it’s possible to achieve a clear responsibility division between the application’s layers.

Clean Architecture

In the next sections will be presented how the Clean Architecture was used as basis to structure the projects created with the Golang Spell platform.

The Golangspell applications are designed to be compliant with this Architectural Model, providing the organization and necessary features, like components injection, out-of-the-box.

Create application

Finally everything is set to build our first Microservice using Golang. This section will guide you through the steps needed to accomplish that task.

mkdir project-api

md project-api

cd project-api

golangspell init github.com/[your-git-user]/project-api project-api

Loading Spells …
Spells loaded!
Rendering template: .gitignore
Rendering template: Dockerfile
Rendering template: README.md
Rendering template: context.got
Rendering template: context_test.got
Rendering template: environment.got
Rendering template: logger.got
Rendering template: version.got
Rendering template: health_controller.got
Rendering template: health_controller_test.got
Rendering template: info_controller.got
Rendering template: info_controller_test.got
Rendering template: router.got
Rendering template: router_test.got
Rendering template: model_health.got
Rendering template: model_info.got
Rendering template: logger.got
Rendering template: main.got
Rendering template: .gitkeep
go: creating new go.mod: module github.com/[your-git-user]/project-api
Application created!
— — — — — — — — — — — — — — — — — — — — — — — — — — — — -
To run your application, first build it with the command:
go build
— — — — — — — — — — — — — — — — — — — — — — — — — — — — -
Then execute the application with the command (Unix based systems):
./project-api
Then execute the application with the command (Windows based systems):
project-api
— — — — — — — — — — — — — — — — — — — — — — — — — — — — -
Available endpoints:
//localhost:8080/project-api/v1/info
//localhost:8080/project-api/v1/health
— — — — — — — — — — — — — — — — — — — — — — — — — — — — -
Find more details on README.md file

go build

./project-api

project-api

This two endpoints provides respectively the health check result and the current version of the application (the version is configured in the generated file config/version.go).

The application now can be stopped in the terminal using the key combination Ctrl + C;Let’s open the application folder using Visual Studio Code (or your preferred editor) to discover and understand the generated code. To do that, open the Visual Studio Code, click in File -> Open and select the directory created for your application. The application will be shown:

Project view

In the README.md file can be found some hints on how to build, run the tests and the lint for the new project.

Tip: Make sure that the Go Extension is installed in the Visual Studio Code to make your life easier, like suggested in the Installation Process - Recommended Tool. 

Packages

Package appcontext

Using the ApplicationContext is possible to inject dependencies using interfaces, keeping the design consistent with the Clean Architecture. The dependency injection is important to make it easier to test the application components (this way mocking becomes trivial).

File context.go

File context_test.go

Package config

File environment.go

File logger.go

As you can guess, this file contains the Logger definitions. It provides the Logger interface, which defines the Logger capabilities, and the utility function GetLogger(), which gets the current Logger instance.

File version.go

Package controller

File router.go

Files with the suffix _controller.go

Package domain

Files with prefix model_

Package gateway

Package customlog

File logger.go

Package usecase

Files in the root directory

Dockerfile

go.mod

main.go

CRUD for the domain entity Project

Now is time to add to the application the CRUD (Create, Read, Update and Delete) features.

Using a Nosql database is a good choice for having scalability and a flexible schema in a single shot, powered by a cloud managed service.

docker run -d -p 27017:27017 mongo

export DB_CONNECTION_STRING=”mongodb://localhost:27017/project”

set DB_CONNECTION_STRING=”mongodb://localhost:27017/project”

golangspell addspell github.com/golangspell/golangspell-mongodb golangspell-mongodb

golangspell help

golangspell help mongodbinit

Let’s create a new Mongodb persistence infra, including a new database called project (the database name is the last word in the command). In order to accomplish that, the following command must be used:

golangspell mongodbinit project

Project with the MongoDB infrastructure

Firstly, a new package was created, called mongodb, inside the gateway package.

On this package was created a new file, called db_client.go. This file contains a client component to communicate with the mongodb database called project.

The second change can be noticed in the config package. The file environment.go now have a backup file, with the same name and a suffix _backup_<timestamp>. The backup is done automatically when an application file is changed by a Spell command.

Comparing the backup file and the current environment.go file, can be noticed that two new environment variables were added to connect to the mongodb database, DB_CONNECTION_STRING and DB_CONNECTION_CERTIFICATE_FILE_NAME. This variables can be accessed in the application code through the variables config.Values.DBConnectionString and config.Values.DBConnectionCertificateFileName respectively. The first one defines the connection string and the second one defines the certificate file name if the connection is using TLS.

The third change is in the package appcontext. The file context.go was changed and backed up as well, because a new constant was introduced to define the new component added to the application context, DBClient.

Looking at the file db_client.go, there is an example of how to register a component in the application context. It is done in the application lifecycle during the initialization process, this is why the command appcontext.Current.Add(appcontext.DBClient, buildMongoClient) is implemented in the init() function.

appcontext.DBClient: the constant defined to identify the new component buildMongoClient: the method which will be used to lazy load the component in the first time it is used.

golangspell mongodbaddcrud Project

As can be seen with the help of the golangspell help mongodbaddcrud command, the unique expected parameter is the domain entity name, in camel case. In our example the business entity which will be represented is the Project, so that the provided name will be Project.

Application with the base CRUD code

A new backup was created to the file appcontext/context.go. That means some changes were made to the file. Some constants were added, referring to the new components created in the application. These components are:

ProjectRepository: The Repository created to handle the persistence features for the new domain. The implementation of the component can be found in the new file gateway/mongodb/project_repository.go;

ProjectDeleteUsecase: The use case created for the feature Project — Delete. The implementation of the component can be found in the new file usecase/project_delete_usecase.go;

ProjectUpdateUsecase: The use case created for the feature Project — Update. The implementation of the component can be found in the new file usecase/project_update_usecase.go;

ProjectGetByIDUsecase: The use case created for the feature Project — Get By Id. The implementation of the component can be found in the new file usecase/project_get_by_id_usecase.go;

ProjectGetAllUsecase: The use case created for the feature Project — Get All. The implementation of the component can be found in the new file usecase/project_get_all_usecase.go;

ProjectCreateUsecase: The use case created for the feature Project — Create. The implementation of the component can be found in the new file usecase/project_create_usecase.go;

The backup of the file controller/router.go indicates that something was changed there. Looking to the new state of the file it is possible to notice that new HTTP routes were added. These new routes exposes the Project management endpoints.

A new file called controller/project_controller.go was created as well with the logic to handle the Project endpoints requests.

The business domain entity can be found in the new file domain/model_project.go.

ID — Instance Identifier;

DateCreated — timestamp which holds the creation date;

DateUpdated: timestamp representing the last update date;The interface which specifies the Repository capabilities;

The interfaces which represents the Use Cases related to the business entity;

The convenience functions to retrieve the current implementation of the related components, loaded in the application context during the initialization phase.

The component abstraction using interfaces and the application context makes it easier to build tests with mocked components using tools like Mockery ().

The Rhymond/go-money () library will be used in this article for managing the monetary amounts. This way we will have a better monetary amounts precision. In order to accomplish this, it is necessary to create a wrapper struct to persist the monetary data in the database. Let’s create a new file called model_money.go inside the package domain and paste the following code:

Some additional attributes must be added to the file domain/model_project.go to represent properly the model defined in the Open API Specification.

Name string `bson:”name” json:”name”`
UnitPrice Money `bson:”unitPrice” json:”unitPrice”`
TimeUnit string `bson:”timeUnit” json:”timeUnit”`

if project == nil {
return false, ConstraintViolation(“The Project is not instantiated”)
}
if strings.TrimSpace(project.Name) == “” {
return false, ConstraintViolation(“The Project is invalid. The required attribute ‘Name’ is missing”)
}
if project.UnitPrice.IsZero() || project.UnitPrice.IsNegative() || strings.TrimSpace(project.UnitPrice.Currency) == “” {
return false, ConstraintViolation(“The Project is invalid. The ‘Unit Price’ must be in a valid Currency and must be greater than zero”)
}
if project.TimeUnit != “Hour” &&
project.TimeUnit != “Day” &&
project.TimeUnit != “Week” &&
project.TimeUnit != “Month” {
return false, ConstraintViolation(“The Project is invalid. The ‘TimeUnit’ must be any of [Hour, Day, Week, Month]”)
}
return true, nil

After this changes, the code in the file domain/model_project.go will look like this:

The following flow will be executed when the application receives a request pointing to the Create Project endpoint:

Request processing sequence

go build

./project-api

(or simply project-api on Windows)

curl -X POST “//localhost:8080/project-api/v1/project" -H “accept: application/json” -H “Content-Type: application/json” -d “{\”name\”:\”My Customer Project\”,\”unitPrice\”:{\”currency\”:\”EUR\”,\”amount\”:70000},\”timeUnit\”:\”Day\”}”

The command will create a new Project document in the database. The expected results are the contents of the created document:

{“id”:”5f175f8780254962243c9362",”name”:”My Customer Project”,”unitPrice”:{“amount”:70000,”currency”:”EUR”},”timeUnit”:”Day”,”dateCreated”:”2020–07–21T23:35:03.104716+02:00",”dateUpdated”:”0001–01–01T00:00:00Z”}

In my response, for example, a new document was created with the id 5f175f8780254962243c9362. This Id will be used in the next commands to refer to this document. Change this to the one returned for you in the next commands.

Following with the usage example, lets get all the documents in the collection with the command:

curl -X GET “//localhost:8080/project-api/v1/project" -H “accept: application/json”

The command returns an array of Projects. For getting only an specific document, by Id:

curl -X GET “//localhost:8080/project-api/v1/project/5f175f8780254962243c9362" -H “accept: application/json”

Now, let’s update the document increasing the price from 700 Euros to 850 Euros (the amount notation is made by the value multiplied by 100, to include the cents in an int value):

curl -X PUT “//localhost:8080/project-api/v1/project/5f175f8780254962243c9362" -H “accept: application/json” -H “Content-Type: application/json” -d “{\”id\”:\”5f175f8780254962243c9362\”,\”name\”:\”My Customer Project\”,\”unitPrice\”:{\”currency\”:\”EUR\”,\”amount\”:85000},\”timeUnit\”:\”Day\”}”

Now the last test will be to delete the document from the database with the command:

curl -X DELETE “//localhost:8080/project-api/v1/project/5f175f8780254962243c9362" -H “accept: application/json”

Executing again the get all command nothing will be returned:

curl -X GET “//localhost:8080/project-api/v1/project" -H “accept: application/json”

The get all command is ready for pagination as well. It accepts the query parameters pageSize (int) and lastProjectId (ObjectId, 5f175f8780254962243c9362 for example). If these parameters are defined like this:

curl -X GET “//localhost:8080/project-api/v1/project?pageSize=10&lastProjectId=5f175f8780254962243c9362" -H “accept: application/json”

… will be returned the next 10 documents with id greater than 5f175f8780254962243c9362. The id based pagination delivers a very good performance in Mongodb.

Now you can play around with your first Microservice built with Golangspell, using the examples as a reference.

In normal situations the files with extensions like “go_backup_[timestamp]” should be deleted instead of added to the code repository. They are in the repository only for showing the intermediate steps of the project code.

Conclusion

• Microservices development context;
• Golangspell platform fundamentals;
• Steps needed to install the Golangspell platform and the golangspell-mongodb spell;
• Steps needed to create the first full featured Microservice using the Golangspell platform.

The outcome of these steps is a structured application following the Clean Architecture principles and ready for being extended using other Golangspell features. The generated code is organized into logic layers in an intuitive, maintainable and extendable fashion.

Now having a very good productivity is one go get away from you with the Golangspell platform, enjoy!

Project Wiki

Project Group

Also published at