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 ΒΆ

    Directories ΒΆ

    Path Synopsis
    cmd
    pkg
    application
    Package errors implements functions to manipulate errors.
    Package errors implements functions to manipulate errors.
    commandbus
    Package commandbus provides interfaces along with helper functions
    Package commandbus provides interfaces along with helper functions
    domain
    Package domain is the heart layer of the software, and this is where the interesting stuff happens.
    Package domain is the heart layer of the software, and this is where the interesting stuff happens.
    errors
    Package errors implements functions to manipulate errors.
    Package errors implements functions to manipulate errors.
    eventbus
    Package eventbus provides interfaces along with helper functions
    Package eventbus provides interfaces along with helper functions
    eventstore
    Package eventstore provides interfaces along with helper functions
    Package eventstore provides interfaces along with helper functions
    eventstore/dynamodb
    Package memory provides dynamodb implementation of domain event store
    Package memory provides dynamodb implementation of domain event store
    eventstore/memory
    Package memory provides memory implementation of domain event store
    Package memory provides memory implementation of domain event store
    executioncontext
    Package executioncontext provides context helper function so set and get execution flags
    Package executioncontext provides context helper function so set and get execution flags
    http/firewall
    Package firewall allow to guard handlers
    Package firewall allow to guard handlers
    http/middleware
    Package middleware provides http middleware
    Package middleware provides http middleware
    http/middleware/authenticator
    Package authenticator provides allows to authorize request
    Package authenticator provides allows to authorize request
    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
    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
    identity
    Package identity provides type that allows to authorize request
    Package identity provides type that allows to authorize request
    log
    Package log provides Logger
    Package log provides Logger