FTGOGO - event-driven architecture demonstration application using edat
ftgogo (food-to-gogo) is a Golang implementation of the FTGO application described in the book "Microservice Patterns" by Chris Richardson. A library edat was developed to provide for Golang many of the solutions that Eventuate, the framework used by FTGO, provides for Java.
This repository exists to demonstrate the patterns and processes involved when constructing a distributed application using event-driven architecture.
This repository started as a Golang clone of the FTGO demonstration application but as time goes on it will grow to demonstrate additional microservice patterns and techniques.
Docker - Everything is built and run from a docker compose environment.
Open a command prompt and then execute the following docker command
NOTE: The first time you bring everything up the init script for Postgres will run automatically. The services will crash-loop for a bit because of that. Eventually things will stabilize.
docker-compose up
Use Ctrl-C
to stop all services.
Not recommended but each service can be run using go run .
. You'll need to use an .env
file or set some environment
variables to properly run the service.
Use
go run . --help
to see all the flags and environment variables that can be set.
The colors used for each component in the above diagram align with the ring colors used in clean architecture diagram.
In this implementation of clean architecture I am working mainly with Hexagonal Architecture or Ports & Adapters terms from those methodologies.
/internal/handlers
/internal/application/service.go
/internal/adapters
/internal/application/ports
Bringing the interfaces and implementations together looks about the same for all services. Below is an example from the Consumer Service.
package main
import (
"github.com/stackus/ftgogo/consumer/internal/adapters"
"github.com/stackus/ftgogo/consumer/internal/application"
"github.com/stackus/ftgogo/consumer/internal/domain"
"github.com/stackus/ftgogo/consumer/internal/handlers"
"github.com/stackus/ftgogo/serviceapis"
"shared-go/applications"
)
func main() {
svc := applications.NewService(initService)
if err := svc.Execute(); err != nil {
panic(err)
}
}
func initService(svc *applications.Service) error {
serviceapis.RegisterTypes()
domain.RegisterTypes()
// Driven
consumerRepo := adapters.NewConsumerRepositoryPublisherMiddleware(
adapters.NewConsumerAggregateRepository(svc.AggregateStore),
adapters.NewConsumerEntityEventPublisher(svc.Publisher),
)
app := application.NewServiceApplication(consumerRepo)
// Drivers
handlers.NewCommandHandlers(app).Mount(svc.Subscriber, svc.Publisher)
handlers.NewRpcHandlers(app).Mount(svc.RpcServer)
return nil
}
/"domain" - A capability or domain that is a subdomain in the larger application domain
|-/cmd - Parent for servers, cli, and tools that are built using the code in this domain
| |-/cdc - CDC (Change Data Capture) server. If the service publishes messages it will also have this
| |-/service - Primary service for this capability
|-/internal - Use the special treatment of "internal" to sequester our code from the other services
|-/adapters - Driven Adapter implementations.
|-/application - Application core folder. Processes under this will implement business rules and logic
| |-/commands - CQRS commands. Processes that apply some change to the subdomain
| |-/ports - Application interfaces that the Driven Adapters implement.
| |-/queries - CQRS queries. Processes that request information from the subdomain
| |-service.go - Application interface and implementation that is used by the handlers, the Driver Adapters.
|-/domain - The definitions and the domain rules and logic
|-/handlers - Driver Adapter implementations
This layout is an example of organizing code to achieve clean architecture. You do not need to use this layout to have implemented clean architecture with Go. I've made and am likely to make more minor adjustments to this layout and do not consider it perfect or the "one".
Accounting Service
Consumer Service
Delivery Service
Kitchen Service
Order Service
Order History Service
Restaurant Service
Accounting CDC Service
Consumer CDC Service
Kitchen CDC Service
Order CDC Service
Restaurant CDC Service
Customer Web Gateway Service
Store Web Gateway Service
Asynchronous messaging handles all inter-service communication. The exception is the communication from the BFF/UI layer to the downstream services.
The same three sagas found in FTGO have been implemented here in the order-service.
An implementation of the outbox pattern can be used to ensure all messages arrive at their destinations. It provides the solution to the dual write problem. Any service that publishes messages is actually publishing the message into the database. A CDC sibling service then processes the messages from the database and publishes the message into NATS Streaming. This process provides at-least-once delivery.
TODO
This will be a new feature added to the edat library.
Each service divides the requests it receives into commands and queries. Using a simple design described here by Three Dots Labs all of our handlers can be setup to use a command or query.
This is a very limited in scope implementation of CQRS. It is valid in that we have two things where before we had one. Command and query have been segregated to separate responsibilities.
The Order History Service provides an order by consumer read-model.
Several services use event sourcing and keep track of the changes to aggregates using commands and recorded events. Check out the Order aggregate for an example.
The project now demonstrates the backend-for-frontend pattern with the addition of a Customer-Web service. These types of services are purpose built API Gateways that serve a specific client experience.
The addition of these BFFs also provide a place to implement cross-cutting concerns such as authorization and authentication. I've tried to add demonstrations of the capabilities of what a BFF might do for a microservices application.
With the addition of the first BFF, GRPC is now used in place of HTTP by the handlers. GRPC is a subjectively better choice for communication between your applications Api Gateway or BFF than using HTTP with REST. The move to GRPC was done leaving the contracts previously used by HTTP endpoints unchanged as much as possible.
Executable specifications written in Gherkin have been added to most services. You can find these in the /features
directories.
These specifications can be executed using the godog Cucumber tool. The Makefile
target run-feature-tests
can be used to run all the specifications across all services. Below is an example output
from running the Consumer Registration specification.
Feature: Register Consumer
Scenario: Consumers can be registered # features\register_consumer.feature:4
When I register a consumer named "Able Anders" # register_consumer.go:15 -> *FeatureState
Then I expect the command to succeed # feature_state.go:72 -> *FeatureState
Scenario: Consumers must be registered with a name # features\register_consumer.feature:8
When I register a consumer named "" # register_consumer.go:15 -> *FeatureState
Then I expect the command to fail # feature_state.go:64 -> *FeatureState
And the returned error message is "cannot register a consumer without a name" # feature_state.go:80 -> *FeatureState
Scenario: Duplicate consumer names do not cause conflicts # features\register_consumer.feature:13
Given I register a consumer named "Able Anders" # register_consumer.go:15 -> *FeatureState
When I register another consumer named "Able Anders" # register_consumer.go:15 -> *FeatureState
Then I expect the command to succeed # feature_state.go:72 -> *FeatureState
TODO
TODO
New requests into the system will be given value that is put into three containers RequestID
, a CorrelationID
, and
a CausationID
.
At each request boundary, -> HTTP, or -> GRPC, or -> Message, a new RequestID
is generated, if a previous RequestID
exists in the current context it is moved into the CausationID
.
RequestID
is generatedCausationID
is set to the previous RequestID
CorrelationID
value remains the same into every new request that results from the original request.These three values can be used to build a map of a request through the system.
The tracking and management of these IDs is a feature of edat.
Prometheus metrics for each service are available at http://localhost:[port]/metrics
. The order-service has a few
additional counters. See the order-service code for more information.
This demonstration application is a mono-repository for the Golang services. I chose to use as few additional frameworks
as possible, so you'll find there is also quite a bit of shared code in packages under /shared-go
/shared-go
is named the way it is because I intended to build one of the services in another language. I didn't but
left the name the way it was.
This code exists simply to make it easier for me to build this demonstration. Applying DRY to microservices is a code-smell.
Still a work-in-progress.
Industry blogs , books, and talks typically all suggest applications start with a monolith, single deployable application, before developing an application using microservices. Whether you have a legacy monolith application or are starting a new application the last step before microservices is to refactor or design the monolith to be loosely-coupled.
The service capabilities can all be run together in a monolith to demonstrate what that might look like. It'll at beat represent the final form of a monolith that has been broken up by feature. This kind of monolith has several names. The "Majestic Monolith", the "Loosely-Coupled Monolith", or the "Modular Monolith".
Note: The monolith came into existence after the development of the microservices. It may not give the best example of what a monolith might look like just before switching to microservices.
Commands, Events, Snapshots, and other serializable entities get registered in groups in
each /"domain"/internal/domain/register_types.go
and in the child packages of serviceapis
. This type registration is
a feature of edat/core and is not unique to this application.
The purpose of doing this type registration is to avoid boilerplate marshalling and unmarshalling code for every struct.
I intend for this demonstration to exist as a faithful Golang recreation of the original. If a difference exists either because of opinion or is necessary due of the particulars of Go, I will try my best to include them all here.
/api
and use snake_case
instead of camelCase
for property names.OrderService->createOrder
method I felt was doing too much.
The command
implementation creates the order like before, but the published entity event that results from that command is now the
catalyst for starting the CreateOrderSaga.addressId
. Consumers will register one or
more addresses now. The customer-web service uses data
from another service to complete the modified CreateOrder command.Just like the original the following are outside the scope of the demonstration.
DEPRECATED
TODO: Rewrite. The instructions below no longer work with the changes made to the demo, primarily from the addition of the BFFs.
Postman can be used to load the api collection for an easy demo.
With the application running using one of the commands above you can make the following calls to see the processes, events, and entities involved.
Loading FTGOGO.postman_collection.json
into Postman will provide pre-built calls with semi-random data that can be
used to test the above.
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.
From time to time I expect to make improvements that may be breaking. I provide no expectation that local copies of this demonstration application won't be broken after fetching any new commit(s). If it does fail to run; simply remove the related docker volumes and re-run the demonstration.