"ToDo API" Microservice Example

Introduction

Welcome! 👋

This is an educational repository that includes a microservice written in Go. It is used as the principal example of my video series: Building Microservices in Go.

This repository is not a template nor a framework, it's a collection of patterns and guidelines I've successfully used to deliver enterprise microservices when using Go, and just like with everything in Software Development some trade-offs were made.

My end goal with this project is to help you learn another way to structure your Go project with 3 final goals:

1. It is enterprise, meant to last for years,
2. It allows a team to collaborate efficiently with little friction, and
3. It is as idiomatic as possible.

Join the fun at https://youtube.com/MarioCarrion.

Domain Driven Design

This project uses a lot of the ideas introduced by Eric Evans in his book Domain Driven Design, I do encourage reading that book but before I think reading Domain-Driven Design Distilled makes more sense, also there's a free to download DDD Reference available as well.

On YouTube I created a playlist that includes some of my favorite talks and webinars, feel free to explore that as well.

Project Structure

Talking specifically about microservices only, the structure I like to recommend is the following, everything using < and > depends on the domain being implemented and the bounded context being defined.

• [X] dockerfiles/: defines all the Dockerfiles used by the different applications used in the project.
• [ ] cmd/
• [ ] <primary-server>/: uses primary database.
• [ ] <replica-server>/: uses readonly databases.
• [ ] <binaryN>/
• [X] db/
• [X] migrations/: contains database migrations.
• [ ] seeds/: contains file meant to populate basic database values.
• [X] internal/: defines the core domain.
• [X] <datastoreN>/: a concrete repository used by the domain, for example postgresql
• [X] rest/: defines HTTP Handlers.
• [X] service/: orchestrates use cases and manages transactions.

There are cases where requiring a new bounded context is needed, in those cases the recommendation would be to define a package like internal/<bounded-context> that then should follow the same structure, for example:

• internal/<bounded-context>/
• internal/<bounded-context>/<datastoreN>
• internal/<bounded-context>/http
• internal/<bounded-context>/service

Tools

Please refer to the documentation in internal/tools/.

Features

Icons meaning:

• means a link to Youtube video.
• means a link to Blog post.

In no particular order:

• [X] Project Layout
• [X] Dependency Injection
• [X] Secure Configuration
• [X] Using Hashicorp Vault
• [X] Using AWS SSM
• [ ] Infrastructure as code
• [X] Metrics, Traces and Logging using OpenTelemetry
• [ ] Caching
• [X] Memcached
• [ ] Redis
• [X] Persistent Storage
• [X] Repository Pattern
• [X] Database migrations
• [ ] MySQL
• [X] PostgreSQL
  • jmoiron/sqlx, jackc/pgx and database/sql
  • go-gorm/gorm and volatiletech/sqlboiler
  • Masterminds/squirrel and kyleconroy/sqlc
• [ ] REST APIs
• [X] HTTP Handlers
• [X] Custom JSON Types
• [ ] Versioning
• [X] Error Handling
• [X] OpenAPI 3 and Swagger-UI
• [ ] Authorization
• [ ] Events and Messaging
• [ ] Apache Kafka
• [ ] RabbitMQ
• [ ] Redis
• [ ] Testing
• [X] Type-safe mocks with maxbrunsfeld/counterfeiter
• [X] Equality with google/go-cmp
• [X] Integration tests for Datastores with ory/dockertest
• [X] REST APIs
• [X] Containerization using Docker
• [ ] Graceful Shutdown
• [ ] Search Engine using ElasticSearch
• [ ] Documentation
• C4 Model
• [ ] Cloud Design Patterns
• Reliability
  • [ ] Circuit Breaker
• [ ] Tools as Dependencies
• [ ] Whatever else I forgot to include

More ideas

• 2016: Peter Bourgon's: Repository structure
• 2016: Ben Johnson's: Standard Package Layout
• 2017: William Kennedy's: Design Philosophy On Packaging
• 2017: Jaana Dogan's: Style guideline for Go packages
• 2018: Kat Zien - How Do You Structure Your Go Apps

Running project locally using Docker Compose

Originally added