README

🧰 Golang API Starter Kit

Build Status Go Report Card codecov license baker sponsor

logo

Go Server/API boilerplate using best practices, DDD, CQRS, ES, gRPC.

Table of Contents

πŸ“– ABOUT

The main purpose of this project is to provide boilerplate project setup using using best practices, DDD, CQRS, ES, gRPC. Featuring kubernetes for both development and production environments. Allowing to work with environment reflecting production one, allowing to reduce any misconfigurations.

This is mono-repository of many services such as authentication or user domain. Each service has it own code base with exception of shared packages to simplify things for this boilerplate. Services communicate witch each other using gRPC. Each service might expose HTTP API for external communication or/and gRPC.

This project setup should reduce the time spent on environment configuration for the whole kubernetes cluster and/or each of microservice. Extracting each of services to own repository or keeping it as mono-repo should be a matter of preference.

Please look for comments like @TODO and @FIXME to better understand thing than need attention.

Key concepts:

  1. Rest API
  2. Docker
  3. Kubernetes
  4. Helm chart
  5. gRPC
  6. Domain Driven Design (DDD)
  7. CQRS
  8. Event Sourcing
  9. Hexagonal, Onion, Clean Architecture
  10. oAuth2

Worth getting to know packages used in this boilerplate:

  1. gorouter
  2. message-bus
  3. gollback
  4. shutdown
  5. pubsub
  6. pushpull
  7. gocontainer
  8. ardanlabs/service

πŸ“š DOCUMENTATION

🏫 EXAMPLE

Quick start

localhost alias
Build release
make docker-build BIN=auth
make docker-build BIN=migrate
make docker-build BIN=user
Install Cert Manager
helm repo add jetstack https://charts.jetstack.io
helm repo update

make helm-dependencies
Deploy release
make helm-install

Dashboard

Domain

Dispatching command

Send example JSON via POST request

curl -d '{"email":"test@test.com"}' -H "Content-Type: application/json" -X POST https://api.go-api-boilerplate.local/users/v1/dispatch/register-user-with-email --insecure

View

Public routes

Get user details https://api.go-api-boilerplate.local/users/v1/34e7ed39-aa94-4ef2-9422-401bba9fc812

{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812","email":"test@test.com"}

Get list of users https://api.go-api-boilerplate.local/users/v1?page=1&limit=10

{"page":1,"limit":20,"total":1,"users":[{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812","email":"test@test.com"}]}
Protected routes

Access protected route using auth token https://api.go-api-boilerplate.local/users/v1/me.

{"code": "401","message": "Unauthorized"}

Request access token for user

curl -d '{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812"}' -H "Content-Type: application/json" -X POST https://api.go-api-boilerplate.local/users/v1/dispatch/request-user-access-token --insecure

Get your access token from mail catcher https://maildev.go-api-boilerplate.local.

Access protected route using auth token https://api.go-api-boilerplate.local/users/v1/me?authToken=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJyXHUwMDE277-977-977-977-9IiwiZXhwIjoxNTU5NjEwOTc2LCJzdWIiOiIzNGU3ZWQzOS1hYTk0LTRlZjItOTQyMi00MDFiYmE5ZmM4MTIifQ.pEkgtDAvNh2D3Dtgfpu4tt-Atn1h6QwMkDhz4KpgFxNX8jE7fQH00J6K5V7CV063pigxWhOMMTRLmQdhzhajzQ

{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812","email":"test@test.com"}

πŸ’² Sponsoring

πŸš€ Contributing

Want to contribute ? Feel free to send pull requests!

Have problems, bugs, feature ideas? We are using the github issue tracker to manage them.

πŸ‘¨πŸ»β€πŸ’»πŸ‘©πŸΎβ€πŸ’» Core Team:


RafaΕ‚ Lorenz
Marin Kirkov

πŸ‘₯ Backers

Support us with a monthly donation and help us continue our activities.

πŸ₯‡ Sponsors

Proudly sponsored by Open Collective sponsors.

πŸ“œ License

Expand β–Ύ Collapse β–΄

Documentation

Overview ΒΆ

Package goapiboilerplate provides Go Server/API boilerplate using best practices, DDD, CQRS, ES.

Source Files

View all

Directories

Path Synopsis
cmd/auth
cmd/auth/internal/application Package application is a layer responsible for driving the workflow of the application, matching the use cases at hand.
cmd/auth/internal/application/config
cmd/auth/internal/application/eventhandler
cmd/auth/internal/application/oauth2
cmd/auth/internal/domain Package domain is the heart layer of the software, and this is where the interesting stuff happens.
cmd/auth/internal/domain/client Package client holds client domain logic Package client holds client domain logic
cmd/auth/internal/domain/token Package token holds token domain logic Package token holds token domain logic
cmd/auth/internal/infrastructure Package infrastructure is a layer that holds everything that interacts with other systems - Secondary/Driven Adapters.
cmd/auth/internal/infrastructure/persistence Package persistence holds view models and repository interfaces Package persistence holds view models and repository interfaces Package persistence holds view models and repository interfaces
cmd/auth/internal/infrastructure/persistence/mysql Package mysql holds view model repositories Package mysql holds view model repositories Package mysql holds view model repositories Package mysql holds view model repositories Package mysql holds view model repositories Package mysql holds view model repositories
cmd/auth/internal/infrastructure/repository Package repository holds event sourced repositories Package repository holds event sourced repositories
cmd/auth/internal/interfaces Package interfaces is a layer that holds everything that other systems interacts with - Primary/Driving Adapters.
cmd/auth/internal/interfaces/grpc Package grpc provides user grpc server
cmd/auth/internal/interfaces/http Package http provides routes for http router
cmd/auth/internal/interfaces/http/handlers Package handlers provides http handlers
cmd/auth/proto
cmd/user
cmd/user/internal/application Package application is a layer responsible for driving the workflow of the application, matching the use cases at hand.
cmd/user/internal/application/config
cmd/user/internal/application/email
cmd/user/internal/application/eventhandler
cmd/user/internal/application/mailer
cmd/user/internal/application/oauth2
cmd/user/internal/domain Package domain is the heart layer of the software, and this is where the interesting stuff happens.
cmd/user/internal/domain/user Package user holds user domain logic Package user holds user domain logic
cmd/user/internal/infrastructure Package infrastructure is a layer that holds everything that interacts with other systems - Secondary/Driven Adapters.
cmd/user/internal/infrastructure/persistence Package persistence holds view models and repository interfaces
cmd/user/internal/infrastructure/persistence/mysql Package mysql holds view model repositories Package mysql holds view model repositories
cmd/user/internal/infrastructure/repository Package repository holds event sourced repositories
cmd/user/internal/interfaces Package interfaces is a layer that holds everything that other systems interacts with - Primary/Driving Adapters.
cmd/user/internal/interfaces/grpc Package grpc provides user grpc server
cmd/user/internal/interfaces/http Package http provides routes for http router
cmd/user/internal/interfaces/http/handlers Package handlers provides http handlers
cmd/user/proto
pkg/application Package errors implements functions to manipulate errors.
pkg/auth
pkg/auth/oauth2
pkg/buildinfo
pkg/commandbus Package commandbus provides interfaces along with helper functions
pkg/commandbus/memory
pkg/container
pkg/domain Package domain is the heart layer of the software, and this is where the interesting stuff happens.
pkg/errors Package errors implements functions to manipulate errors.
pkg/eventbus Package eventbus provides interfaces along with helper functions
pkg/eventbus/memory
pkg/eventbus/pubsub
pkg/eventbus/pushpull
pkg/eventstore Package eventstore provides interfaces along with helper functions
pkg/eventstore/dynamodb Package memory provides dynamodb implementation of domain event store
pkg/eventstore/memory Package memory provides memory implementation of domain event store
pkg/executioncontext Package executioncontext provides context helper function so set and get execution flags
pkg/grpc
pkg/grpc/middleware
pkg/grpc/middleware/firewall
pkg/http/errors
pkg/http/firewall Package firewall allow to guard handlers
pkg/http/middleware Package middleware provides http middleware
pkg/http/middleware/authenticator Package authenticator provides allows to authorize request
pkg/http/request
pkg/http/response Package response provides helpers and utils for working with HTTP response Package response provides helpers and utils for working with HTTP response Package response provides helpers and utils for working with HTTP response
pkg/identity Package identity provides type that allows to authorize request
pkg/log Package log provides Logger
pkg/metadata
pkg/mysql