README
ΒΆ
π§° Golang API Starter Kit
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:
- Rest API
- Docker
- Kubernetes
- Helm chart
- gRPC
- Domain Driven Design (DDD)
- CQRS
- Event Sourcing
- Hexagonal, Onion, Clean Architecture
- oAuth2
Worth getting to know packages used in this boilerplate:
π 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
Documentation
ΒΆ
Overview ΒΆ
Package goapiboilerplate provides Go Server/API boilerplate using best practices, DDD, CQRS, ES.
Source Files
Directories
ΒΆ
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
auth/internal/application
Package application is a layer responsible for driving the workflow of the application, matching the use cases at hand.
|
Package application is a layer responsible for driving the workflow of the application, matching the use cases at hand. |
|
auth/internal/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. |
|
auth/internal/domain/client
Package client holds client domain logic Package client holds client domain logic
|
Package client holds client domain logic Package client holds client domain logic |
|
auth/internal/domain/token
Package token holds token domain logic Package token holds token domain logic
|
Package token holds token domain logic Package token holds token domain logic |
|
auth/internal/infrastructure
Package infrastructure is a layer that holds everything that interacts with other systems - Secondary/Driven Adapters.
|
Package infrastructure is a layer that holds everything that interacts with other systems - Secondary/Driven Adapters. |
|
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
|
Package persistence holds view models and repository interfaces Package persistence holds view models and repository interfaces Package persistence holds view models and repository interfaces |
|
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
|
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 |
|
auth/internal/infrastructure/repository
Package repository holds event sourced repositories Package repository holds event sourced repositories
|
Package repository holds event sourced repositories Package repository holds event sourced repositories |
|
auth/internal/interfaces
Package interfaces is a layer that holds everything that other systems interacts with - Primary/Driving Adapters.
|
Package interfaces is a layer that holds everything that other systems interacts with - Primary/Driving Adapters. |
|
auth/internal/interfaces/grpc
Package grpc provides user grpc server
|
Package grpc provides user grpc server |
|
auth/internal/interfaces/http
Package http provides routes for http router
|
Package http provides routes for http router |
|
auth/internal/interfaces/http/handlers
Package handlers provides http handlers
|
Package handlers provides http handlers |
|
user/internal/application
Package application is a layer responsible for driving the workflow of the application, matching the use cases at hand.
|
Package application is a layer responsible for driving the workflow of the application, matching the use cases at hand. |
|
user/internal/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. |
|
user/internal/domain/user
Package user holds user domain logic Package user holds user domain logic
|
Package user holds user domain logic Package user holds user domain logic |
|
user/internal/infrastructure
Package infrastructure is a layer that holds everything that interacts with other systems - Secondary/Driven Adapters.
|
Package infrastructure is a layer that holds everything that interacts with other systems - Secondary/Driven Adapters. |
|
user/internal/infrastructure/persistence
Package persistence holds view models and repository interfaces
|
Package persistence holds view models and repository interfaces |
|
user/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 |
|
user/internal/infrastructure/repository
Package repository holds event sourced repositories
|
Package repository holds event sourced repositories |
|
user/internal/interfaces
Package interfaces is a layer that holds everything that other systems interacts with - Primary/Driving Adapters.
|
Package interfaces is a layer that holds everything that other systems interacts with - Primary/Driving Adapters. |
|
user/internal/interfaces/grpc
Package grpc provides user grpc server
|
Package grpc provides user grpc server |
|
user/internal/interfaces/http
Package http provides routes for http router
|
Package http provides routes for http router |
|
user/internal/interfaces/http/handlers
Package handlers provides http handlers
|
Package handlers provides http handlers |
|
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 |