Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/amitshekhariitbhu/go-backend-clean-architecture

A Go (Golang) Backend Clean Architecture project with Gin, MongoDB, JWT Authentication Middleware, Test, and Docker.
https://github.com/amitshekhariitbhu/go-backend-clean-architecture

api architecture backend clean-architecture docker gin go golang jwt-authentication project project-template test

Last synced: 26 days ago
JSON representation

A Go (Golang) Backend Clean Architecture project with Gin, MongoDB, JWT Authentication Middleware, Test, and Docker.

Lists

README 

        
# Go Backend Clean Architecture



A Go (Golang) Backend Clean Architecture project with Gin, MongoDB, JWT Authentication Middleware, Test, and Docker.



![Go Backend Clean Architecture](https://github.com/amitshekhariitbhu/go-backend-clean-architecture/blob/main/assets/go-backend-clean-architecture.png?raw=true)



**You can use this project as a template to build your Backend project in the Go language on top of this project.**



Before creating this project, I have gone through more than 20 projects related to the Go(Golang) Clean Architecture on GitHub.



Thanks to all those projects, I learned a lot from all of those. As I keep saying:



> The best way to learn to code is to code. But, to write good code, you will also have to read good code. Make a habit of reading good code. You can find many open-source projects on GitHub and start reading.



Then for the implementation part, I combined all of my ideas, experiences, and learnings from those projects to create this project.



And as always I would love to get feedback on my project. This helps everyone and most importantly me.



Learn about this project architecture in detail from the blogs mentioned below:



- [Go Backend Clean Architecture](https://amitshekhar.me/blog/go-backend-clean-architecture)

- [Go JWT Authentication Middleware](https://amitshekhar.me/blog/go-jwt-authentication-middleware)

- [Configuration with Viper in Go](https://amitshekhar.me/blog/configuration-with-viper-in-go)

- [Test with Testify and Mockery in Go](https://amitshekhar.me/blog/test-with-testify-and-mockery-in-go)



## Architecture Layers of the project



- Router

- Controller

- Usecase

- Repository

- Domain



![Go Backend Clean Architecture Diagram](https://github.com/amitshekhariitbhu/go-backend-clean-architecture/blob/main/assets/go-backend-arch-diagram.png?raw=true)



## About me



Hi, I am [**Amit Shekhar**](https://amitshekhar.me), I have mentored many developers, and their efforts landed them high-paying tech jobs, helped many tech companies in solving their unique problems, and created many open-source libraries being used by top companies. I am passionate about sharing knowledge through open-source, blogs, and videos.



You can connect with me on:



- [Twitter](https://twitter.com/amitiitbhu)

- [YouTube](https://www.youtube.com/@amitshekhar)

- [LinkedIn](https://www.linkedin.com/in/amit-shekhar-iitbhu)

- [GitHub](https://github.com/amitshekhariitbhu)



## System Design Playlist on YouTube



- [What is System Design?](https://www.youtube.com/watch?v=i4YWRY3hsdA)

- [Twitter Timeline Design with Fanout Approach - System Design](https://www.youtube.com/watch?v=_7qHGfwgPz0)

- [HTTP Request vs HTTP Long-Polling vs WebSocket vs Server-Sent Events](https://www.youtube.com/watch?v=8ksWRX4xV-s)

- [YouTube Video Upload Service - System Design](https://www.youtube.com/watch?v=N0vvJTkokZc)

- [What is Consistent Hashing?](https://www.youtube.com/watch?v=dV5cIm9T3ss)

- [Capacity Estimation: Back-of-the-envelope calculation - Twitter](https://www.youtube.com/watch?v=yrbKxzXm6_Q)



## Major Packages used in this project



- **gin**: Gin is an HTTP web framework written in Go (Golang). It features a Martini-like API with much better performance -- up to 40 times faster. If you need a smashing performance, get yourself some Gin.

- **mongo go driver**: The Official Golang driver for MongoDB.

- **jwt**: JSON Web Tokens are an open, industry-standard RFC 7519 method for representing claims securely between two parties. Used for Access Token and Refresh Token.

- **viper**: For loading configuration from the `.env` file. Go configuration with fangs. Find, load, and unmarshal a configuration file in JSON, TOML, YAML, HCL, INI, envfile, or Java properties formats.

- **bcrypt**: Package bcrypt implements Provos and Mazières's bcrypt adaptive hashing algorithm.

- **testify**: A toolkit with common assertions and mocks that plays nicely with the standard library.

- **mockery**: A mock code autogenerator for Golang used in testing.

- Check more packages in `go.mod`.



### Public API Request Flow without JWT Authentication Middleware



![Public API Request Flow](https://github.com/amitshekhariitbhu/go-backend-clean-architecture/blob/main/assets/go-arch-public-api-request-flow.png?raw=true)



### Private API Request Flow with JWT Authentication Middleware



> JWT Authentication Middleware for Access Token Validation.



![Private API Request Flow](https://github.com/amitshekhariitbhu/go-backend-clean-architecture/blob/main/assets/go-arch-private-api-request-flow.png?raw=true)



### How to run this project?



We can run this Go Backend Clean Architecture project with or without Docker. Here, I am providing both ways to run this project.



- Clone this project



```bash

# Move to your workspace

cd your-workspace



# Clone this project into your workspace

git clone https://github.com/amitshekhariitbhu/go-backend-clean-architecture.git



# Move to the project root directory

cd go-backend-clean-architecture

```



#### Run without Docker



- Create a file `.env` similar to `.env.example` at the root directory with your configuration.

- Install `go` if not installed on your machine.

- Install `MongoDB` if not installed on your machine.

- Important: Change the `DB_HOST` to `localhost` (`DB_HOST=localhost`) in `.env` configuration file. `DB_HOST=mongodb` is needed only when you run with Docker.

- Run `go run cmd/main.go`.

- Access API using `http://localhost:8080`



#### Run with Docker



- Create a file `.env` similar to `.env.example` at the root directory with your configuration.

- Install Docker and Docker Compose.

- Run `docker-compose up -d`.

- Access API using `http://localhost:8080`



### How to run the test?



```bash

# Run all tests

go test ./...

```



### How to generate the mock code?



In this project, to test, we need to generate mock code for the use-case, repository, and database.



```bash

# Generate mock code for the usecase and repository

mockery --dir=domain --output=domain/mocks --outpkg=mocks --all



# Generate mock code for the database

mockery --dir=mongo --output=mongo/mocks --outpkg=mocks --all

```



Whenever you make changes in the interfaces of these use-cases, repositories, or databases, you need to run the corresponding command to regenerate the mock code for testing.



### The Complete Project Folder Structure



```

.

├── Dockerfile

├── api

│   ├── controller

│   │   ├── login_controller.go

│   │   ├── profile_controller.go

│   │   ├── profile_controller_test.go

│   │   ├── refresh_token_controller.go

│   │   ├── signup_controller.go

│   │   └── task_controller.go

│   ├── middleware

│   │   └── jwt_auth_middleware.go

│   └── route

│       ├── login_route.go

│       ├── profile_route.go

│       ├── refresh_token_route.go

│       ├── route.go

│       ├── signup_route.go

│       └── task_route.go

├── bootstrap

│   ├── app.go

│   ├── database.go

│   └── env.go

├── cmd

│   └── main.go

├── docker-compose.yaml

├── domain

│   ├── error_response.go

│   ├── jwt_custom.go

│   ├── login.go

│   ├── profile.go

│   ├── refresh_token.go

│   ├── signup.go

│   ├── success_response.go

│   ├── task.go

│   └── user.go

├── go.mod

├── go.sum

├── internal

│   └── tokenutil

│       └── tokenutil.go

├── mongo

│   └── mongo.go

├── repository

│   ├── task_repository.go

│   ├── user_repository.go

│   └── user_repository_test.go

└── usecase

    ├── login_usecase.go

    ├── profile_usecase.go

    ├── refresh_token_usecase.go

    ├── signup_usecase.go

    ├── task_usecase.go

    └── task_usecase_test.go

```



### API documentation of Go Backend Clean Architecture





    View API Doc Button




### Example API Request and Response



- signup



  - Request



  ```

  curl --location --request POST 'http://localhost:8080/signup' \

  --data-urlencode '[email protected]' \

  --data-urlencode 'password=test' \

  --data-urlencode 'name=Test Name'

  ```



  - Response



  ```json

  {

    "accessToken": "access_token",

    "refreshToken": "refresh_token"

  }

  ```



- login



  - Request



  ```

  curl --location --request POST 'http://localhost:8080/login' \

  --data-urlencode '[email protected]' \

  --data-urlencode 'password=test'

  ```



  - Response



  ```json

  {

    "accessToken": "access_token",

    "refreshToken": "refresh_token"

  }

  ```



- profile



  - Request



  ```

  curl --location --request GET 'http://localhost:8080/profile' \

  --header 'Authorization: Bearer access_token'

  ```



  - Response



  ```json

  {

    "name": "Test Name",

    "email": "[email protected]"

  }

  ```



- task create



  - Request



  ```

  curl --location --request POST 'http://localhost:8080/task' \

  --header 'Authorization: Bearer access_token' \

  --header 'Content-Type: application/x-www-form-urlencoded' \

  --data-urlencode 'title=Test Task'

  ```



  - Response



  ```json

  {

    "message": "Task created successfully"

  }

  ```



- task fetch



  - Request



  ```

  curl --location --request GET 'http://localhost:8080/task' \

  --header 'Authorization: Bearer access_token'

  ```



  - Response



  ```json

  [

    {

      "title": "Test Task"

    },

    {

      "title": "Test Another Task"

    }

  ]

  ```



- refresh token



  - Request



  ```

  curl --location --request POST 'http://localhost:8080/refresh' \

  --header 'Content-Type: application/x-www-form-urlencoded' \

  --data-urlencode 'refreshToken=refresh_token'

  ```



  - Response



  ```json

  {

    "accessToken": "access_token",

    "refreshToken": "refresh_token"

  }

  ```



### TODO



- Improvement based on feedback.

- Add more test cases.

- Always try to update with the latest version of the packages used.



## If this project helps you in anyway, show your love ❤️ by putting a ⭐ on this project ✌️



### License



```

   Copyright (C) 2024 Amit Shekhar



   Licensed under the Apache License, Version 2.0 (the "License");

   you may not use this file except in compliance with the License.

   You may obtain a copy of the License at



       http://www.apache.org/licenses/LICENSE-2.0



   Unless required by applicable law or agreed to in writing, software

   distributed under the License is distributed on an "AS IS" BASIS,

   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

   See the License for the specific language governing permissions and

   limitations under the License.

```



### Contributing to Go Backend Clean Architecture



All pull requests are welcome.