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 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 things than need attention.
Web UI example (React)
This boilerplate includes simple Web UI to demonstrate example interaction with API. Once deployed and hosts are set please visit https://api.go-api-learning.local to access UI.
Key concepts:
- Rest API
- Docker
- Kubernetes
- Helm chart
- Terraform
- 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
Edit /etc/hosts to add localhost alias
β go-api-learning git:(master) cat /etc/hosts
##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting. Do not change this entry.
##
127.0.0.1 go-api-learning.local api.go-api-learning.local maildev.go-api-learning.local mysql.go-api-learning.local
Build release
Local image
make docker-build BIN=auth
make docker-build BIN=migrate
make docker-build BIN=user
make docker-build BIN=web
GitHub Package Registry
Creating tag with metadata will trigger github workflow and publish docker image to GitHub Package Registry.
Tag v1.0.0+user will trigger build for user service releasing 1.0.0 docker image tag.
you can create release for all services in cmd directory.
v1.0.0+auth
v1.0.0+user
v1.0.0+web
v1.0.0+migrate
Replace image details in main.yaml
image:
- repository: go-api-learning-user
+ repository: docker.pkg.github.com/bradishungry/go-api-learning/go-api-learning-user
- tag: latest
+ tag: 1.0.0
pullPolicy: IfNotPresent
repeat for all services and migrate init containers.
Private Registry
docker login
Copy docker config
cp ~/.docker/config.json ./k8s/.docker/config.json
Verify config.json
Deploy release
make terraform-install
Destroy
make terraform-destroy
If persistent volume is stack in terminating, this happens when persistent volume is protected. You should be able to cross verify this:
kubectl describe pvc PVC_NAME --namespace=go-api-learning | grep Finalizers
Output:
Finalizers: [kubernetes.io/pvc-protection]
You can fix this by setting finalizers to null using kubectl patch:
kubectl patch pvc PVC_NAME --namespace=go-api-learning -p '{"metadata":{"finalizers": []}}' --type=merge
Build tags
Build flags are used for different persistence layers. Please see services.go file for details. Provided layers are mysql, mongo and memory.
If desired in similar way new layer can be easily added, following given patter.
go build -tags=persistence_mysql
Available build tags
- persistence_mysql (mysql service container)
- persistence_mongodb (mongodb service container)
Important persistence layer defaults to memory if no flag is provided (Docker image sets persistence_mysql flag), see each service Dockerfile for details.
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-learning.local/users/v1/dispatch/user/user-register-with-email --insecure
View
Public routes
Get user details https://api.go-api-learning.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-learning.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-learning.local/users/v1/me.
{"code": "401","message": "Unauthorized"}
Request access token for user
curl -d '{"email":"test@test.com"}' -H "Content-Type: application/json" -X POST https://api.go-api-learning.local/users/v1/dispatch/user/user-request-access-token --insecure
Get your access token from mail catcher https://maildev.go-api-learning.local.
Access protected route using auth token https://api.go-api-learning.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 |
|
auth/internal/domain/token
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 |
|
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 |
|
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 auth grpc server
|
Package grpc provides auth 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 |
|
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/memory
Package memory holds view model repositories
|
Package memory holds view model repositories |
|
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
|
|
|
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/sqllite
Package eventstore provides sqllite implementation of domain event store
|
Package eventstore provides sqllite 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/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 |
|
http/response/json
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 |