Your first microservice in Golang

So, let’s start developing microservices using the Pip.Services toolkit. As a simple example, we will make a Hello World microservice, which will greet you in response to your request. The communication protocol will be HTTP REST.

The microservice is structurally made up of these components:

  • The controller, which generates responses to requests
  • A REST service for the transmission of responses and requests
  • The component factory for the dynamic creation of components
  • A container process, which will be filled with the necessary components, based on yml configuration.

Step 1. Project setup

Create a folder for the project and run the following command in the command line:

go mod init quickstart

Update the generated /go.mod file to add there dependencies to Pip.Services toolkit.

/go.mod

module quickstart
go 1.13
require (
	github.com/pip-services3-go/pip-services3-commons-go v1.0.0
	github.com/pip-services3-go/pip-services3-components-go v1.0.2
	github.com/pip-services3-go/pip-services3-container-go v1.0.0
	github.com/pip-services3-go/pip-services3-rpc-go v1.0.0
)

In the command line execute the following command to install the dependencies:

go get -u

Step 2. Controller

The controller will be a simple class that implements a single business method, which receives a name and generates a greeting. In general, business methods can call other built-in services or work with a database.

func (c *HelloWorldController) Greeting(name string) (result string, err error) {
    if name == "" { 
        name = c.defaultName
    }
    return "Hello, " + name + "!", nil
}

To demonstrate the dynamic configuration of a component, the recipient name will be specified by the parameter “default_name”. To get the configuration, the component must implement the interface “IConfigurable” with the method “configure”.

func (c *HelloWorldController) Configure(config *cconf.ConfigParams) {	
    c.defaultName = config.GetAsStringWithDefault("default_name", c.defaultName)
}

Parameters will be read by the microservice from the configuration file and passed to the “configure” method of the corresponding component. Here’s an example of the configuration:

# Controller
- descriptor: "hello-world:controller:default:default:1.0"
  default_name: "World"

More details on this mechanism can be found in The Configuration recipe.

This is all the code of the controller in the file:

/HelloWorldController.go

package quickstart

import ( 
    cconf "github.com/pip-services3-go/pip-services3-commons-go/config"
)

type HelloWorldController struct { 
    defaultName string
}
func NewHelloWorldController() *HelloWorldController {
    c := HelloWorldController{}
    c.defaultName = "Pip User"
    return &c
}

func (c *HelloWorldController) Configure(config *cconf.ConfigParams) {
    c.defaultName = config.GetAsStringWithDefault("default_name", c.defaultName)
}

func (c *HelloWorldController) Greeting(name string) (result string, err error) {
    if name == "" {
        name = c.defaultName
    }
    return "Hello, " + name + "!", nil
}

Step 3. REST service

One of the most popular ways of transferring data between microservices is using the synchronous HTTP REST protocol. The HelloWorldRestService will be used to implement an external REST interface. This component extends the abstract RestService of the Pip.Services toolkit, which implements all the necessary functionality for processing REST HTTP requests.

type HelloWorldRestService struct {
    *rpc.RestService
    controller *HelloWorldController
}

Next, we’ll need to register the REST operations that we’ll be using in the class’s Register method. In this microservice, we’ll only be needing to implement a single GET command: “/greeting”. This command receives a “name” parameter, calls the controller’s “greeting” method, and returns the generated result to the client.

func (c *HelloWorldRestService) greeting(res http.ResponseWriter, req *http.Request) {
    name := req.URL.Query().Get("name")
    result, err := c.controller.Greeting(name)
    c.SendResult(res, req, result, err)
}

func (c *HelloWorldRestService) Register() {
    c.RegisterRoute("get", "/greeting", nil, c.greeting)
}

To get a reference to the controller, add its handle to the DependencyResolver under the name “controller”. And for the registration mechanism to work correctly, you must pass a pointer to RestService on the component that implements the IRegistrable interface. Let’s do it in the component constructing method:

func NewHelloWorldRestService() *HelloWorldRestService {
    c := HelloWorldRestService{}
    c.RestService = rpc.NewRestService()
    c.RestService.IRegisterable = &c
    c.BaseRoute = "/hello_world"
    c.DependencyResolver.Put("controller", crefer.NewDescriptor("hello-world", "controller", "*", "*", "1.0"))
    return &c
}

Using this descriptor, the base class will be able to find a reference to the controller during component linking. Check out The Locator Pattern for more on how this mechanism works.

We also need to set a base route in the service’s constructor using the _baseRoute property. As a result, the microservice’s full REST request will look something like:

GET /hello_world/greeting?name=John

Full listing for the REST service found in the file:

/HelloWorldRestService.go

package quickstart

import (
    "net/http"
    crefer "github.com/pip-services3-go/pip-services3-commons-go/refer"
    rpc "github.com/pip-services3-go/pip-services3-rpc-go/services"
)

type HelloWorldRestService struct {
    *rpc.RestService
    controller *HelloWorldController
}

func NewHelloWorldRestService() *HelloWorldRestService {
    c := HelloWorldRestService{}
    c.RestService = rpc.NewRestService()
    c.RestService.IRegisterable = &c
    c.BaseRoute = "/hello_world"
    c.DependencyResolver.Put("controller", crefer.NewDescriptor("hello-world", "controller", "*", "*", "1.0"))
    return &c
}

func (c *HelloWorldRestService) SetReferences(references crefer.IReferences) { 
    c.RestService.SetReferences(references)
    depRes, depErr := c.DependencyResolver.GetOneRequired("controller")
    if depErr == nil && depRes != nil {
        c.controller = depRes.(*HelloWorldController)
    }
}

func (c *HelloWorldRestService) greeting(res http.ResponseWriter, req *http.Request) {
    name := req.URL.Query().Get("name")
    result, err := c.controller.Greeting(name)
    c.SendResult(res, req, result, err)
}

func (c *HelloWorldRestService) Register() {
    c.RegisterRoute("get", "/greeting", nil, c.greeting)
}

Step 4. Сomponent factory

When a microservice is being populated by components based on the configuration being used, it requires a special factory to create components in accordance with their descriptors. To do this, use the HelloWorldServiceFactory structure into which the Factory from the Pip.Services toolkit will be embedded.

type HelloWorldServiceFactory struct {
    cbuild.Factory
}

Next, in the factory’s constructor, we’ll be registering descriptors and their corresponding component types.

func NewHelloWorldServiceFactory() *HelloWorldServiceFactory {
    c := HelloWorldServiceFactory{}
    c.Factory = *cbuild.NewFactory()
    c.RegisterType(
        cref.NewDescriptor("hello-world", "controller", "default", "*", "1.0"),
        NewHelloWorldController,
    )
    c.RegisterType(
        cref.NewDescriptor("hello-world", "service", "http", "*", "1.0"),
        NewHelloWorldRestService,
    )
    return &c
}

For more info on how this works, be sure to check out The Container recipe.

Full listing of the factory’s code found in the file:

‍/HelloWorldServiceFactory.go

package quickstart

import (
    cref "github.com/pip-services3-go/pip-services3-commons-go/refer"
    cbuild "github.com/pip-services3-go/pip-services3-components-go/build"
)

type HelloWorldServiceFactory struct {
    cbuild.Factory
} 
func NewHelloWorldServiceFactory() *HelloWorldServiceFactory {
    c := HelloWorldServiceFactory{}
    c.Factory = *cbuild.NewFactory()
    c.RegisterType(
        cref.NewDescriptor("hello-world", "controller", "default", "*", "1.0"),
        NewHelloWorldController,
    )
    c.RegisterType(
        cref.NewDescriptor("hello-world", "service", "http", "*", "1.0"),
        NewHelloWorldRestService,
    )
    return &c
}

Step 5. Container

Last but not least, our microservice needs a container component. This component creates all of the other components, links them with one another, and controls their life cycle. Although there exist many different ways of running a microservice in a container (regular classes, serverless functions, serlets, etc), we’ll be running our example microservice as a system process. To do this, integrate the ProcessContainer from the Pip.Services toolkit into the HelloWorldProcess structure.

Although containers can be populated by components manually, we’ll be using dynamic configuration to do this. By default, ProcessContainer reads the configuration from an external config.yml file. All we have left to do is register the factory for creating components from their descriptors.

Full listing of the container’s code found in the file:

‍/HelloWorldProcess.go

package quickstart

import (
    cproc "github.com/pip-services3-go/pip-services3-container-go/container"
    rpcbuild "github.com/pip-services3-go/pip-services3-rpc-go/build"
)

type HelloWorldProcess struct {
    cproc.ProcessContainer
}

func NewHelloWorldProcess() *HelloWorldProcess {
    c := HelloWorldProcess{}
    c.ProcessContainer = *cproc.NewProcessContainer("hello-world", "HelloWorld microservice")
    c.SetConfigPath("./config.yml")
    c.AddFactory(NewHelloWorldServiceFactory())
    c.AddFactory(rpcbuild.NewDefaultRpcFactory())
    return &c
}

The dynamic configuration is defined in the file:

‍/config.yml

---
# Container context
- descriptor: "pip-services:context-info:default:default:1.0" 
  name: "hello-world" 
  description: "HelloWorld microservice" 

# Console logger
- descriptor: "pip-services:logger:console:default:1.0" 
  level: "trace" 

# Performance counter that post values to log
- descriptor: "pip-services:counters:log:default:1.0" 
# Controller
- descriptor: "hello-world:controller:default:default:1.0" 
  default_name: "World" 
# Shared HTTP Endpoint
- descriptor: "pip-services:endpoint:http:default:1.0" 
  connection: 
    protocol: http 
    host: 0.0.0.0 
    port: 8080 

# HTTP Service V1
- descriptor: "hello-world:service:http:default:1.0" 

# Heartbeat service
- descriptor: "pip-services:heartbeat-service:http:default:1.0" 

# Status service
- descriptor: "pip-services:status-service:http:default:1.0"

Looking at the configuration file, we can conclude that the following components will be created in the microservice:

  • ContextInfo - standard Pip.Services component for determining the name and description of a microservice.
  • ConsoleLogger - standard Pip.Services component for writing logs to stdout,
  • LogCounters - standard Pip.Services component for logging performance counters.
  • HelloWorldController - the controller of our microservice, implemented in step 2. Make note of the controller’s descriptor, as it will be used to link the controller class to the REST service.
  • HttpEndpoint - standard Pip.Services component that allows multiple services to use a single HTTP port simultaneously.
  • HelloWorldRestServices - the REST service we implemented on step 3.
  • HeartbeatHttpService - standard Pip.Services component that is used to check whether or not a microservice is still up and running by calling GET /heartbeat.
  • StatusHttpService - standard Pip.Services component for getting the status of a microservice by calling GET /status.

As you may have noticed, more than half of the components are being taken from Pip.Services and used “right out of the box”. This significantly expands our microservice’s capabilities, with minimal effort on our part.

Step 6. Run and test the microservice

In Golang, we’ll need a special file to run the microservice. All this file does is creates a container instance and runs it with the parameters provided from the command line. Let’s place it separately from the rest in the folder bin.

/bin/run.go

package main

import (
    "os"
    "quickstart"
)

func main() {
    proc := quickstart.NewHelloWorldProcess()
    proc.Run(os.Args)
}

When a microservice starts up, the following sequence of events takes place:

  1. A container is created and started;

  2. The container reads the configuration found in config.yml;

  3. Using the factory, the container creates the necessary components in accordance with their descriptors (see The Container recipe);

  4. The components are configured. During this step, all components that implement the IConfigurable interface have their configure methods called with the configuration defined in config.yml passed as a parameter (see The Configuration recipe);

  5. Components are linked. All components that implement the IReferenceable interface get their setReferences methods called with a list of components available in the container. With the help of descriptors, objects can find all necessary dependencies (see [The References recipe]);

  6. Components with active processes are run. A component is considered to contain active processes if it implements the IOpenable interface and has an open method defined (see The Component Lifecycle recipe).

When the microservice receives a signal to stop the process, the reverse sequence takes place:

  1. Components with active processes are closed - classes implementing the IClosable interface get their close methods called; Components are unlinked. All components that implement the IUnreferenceable interface have their unsetReferences methods called;
  2. The components previously created in the container are destroyed;
  3. The container is stopped.

To start the microservice, run the following command from a terminal:

go run ./bin/run.go

If the microservice started up successfully, you should see the following result in the terminal:

[echo:INFO:2018-09-25T15:15:30.284Z] Press Control-C to stop the microservice...
[echo:DEBUG:2018-09-25T15:15:30.542Z] Opened REST service at http://0.0.0.0:8080
[echo:INFO:2018-09-25T15:15:30.542Z] Container hello-world started.

Test the microservice by requesting the following URL in a browser:

http://localhost:8080/hello_world/greeting?name=John

If all’s well, you should get the following string as a result:

Hello, John!

All source codes are available on GitHub.

To learn even more about Pip.Services, consider creating a Data Microservice as your next step!