https://github.com/sebajax/go-vertical-slice-architecture

go-vertical-slice-architecture
https://github.com/sebajax/go-vertical-slice-architecture

Last synced: 3 months ago
JSON representation

go-vertical-slice-architecture

• Host: GitHub
• URL: https://github.com/sebajax/go-vertical-slice-architecture
• Owner: sebajax
• License: gpl-3.0
• Created: 2024-01-26T21:34:30.000Z (10 months ago)
• Default Branch: master
• Last Pushed: 2024-02-25T02:43:19.000Z (9 months ago)
• Last Synced: 2024-06-21T14:20:10.491Z (5 months ago)
• Language: Go
• Homepage:
• Size: 606 KB
• Stars: 15
• Watchers: 1
• Forks: 3
• Open Issues: 8
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-fiber - sebajax/go-vertical-slice-architecture - Vertical Slice Architecture code archetype using Fiber and Uber dig. A maintainable, and scalable code organization. (🚧 Boilerplates / 🌱 Third Party)

README

        




    ⚡ go-vertical-slice-architecture



This structure, created following the development guide's for vertical slice architecture, will help to isolate the dependencies, make development easier and have a cleaner and testable code in every package.

## 👩‍💻 Authors

#### Sebastián Ituarte

- [@sebajax](https://www.github.com/sebajax)

#### Luis Fernando Miranda

- [@Abraxas-365](https://www.github.com/Abraxas-365)

## 🖍 Vertical slice architecture

Vertical slice architecture is an approach to software development where code and functionality are organized around individual features or user stories, encompassing all layers of the application from user interface to data access, promoting autonomy, reduced dependencies, and iterative development.

![alt text](./image/vertical-slice-architecture.png)

## 📚 Code Structure

![alt text](./image/go-vertical-slice-architecture.png)

A brief description of the layout:

- `.github` has two template files for creating PR and issue. Please see the files for more details.

- `.gitignore` varies per project, but all projects need to ignore `bin` directory.

- `.golangci.yml` is the golangci-lint config file.

- `Makefile` is used to build the project. **You need to tweak the variables based on your project**.

- `CHANGELOG.md` contains auto-generated changelog information.

- `OWNERS` contains owners of the project.

- `README.md` is a detailed description of the project.

- `cmd` contains the main.go file that is our starting point to execute

- `pkg` places most of project business logic.

- `migrations` contains all vendored code.

- `internal` contains all the api logic.

## 🚀 Stack

#### Programming language [Go](https://go.dev/)

#### Framework [Fiber](https://docs.gofiber.io/)

#### Dependency injection [Uber dig](https://github.com/uber-go/dig)

#### Database [Postgre SQL](https://www.postgresql.org/)

#### Container [Docker](https://www.docker.com/)

#### Live reload [Air](https://github.com/cosmtrek/air)

## 🧐 This app uses conventional commits

[Conventional commits url](https://www.conventionalcommits.org/en/v1.0.0/)

## 🤜 How to create a new use case (Example)

```http

  POST /api/product

```

| Parameter  | Type     | Description                              |

| :--------- | :------- | :--------------------------------------- |

| `name`     | `string` | **Required**. Product Name               |

| `sku`      | `string` | **Required**. Product Sku must be Unique |

| `category` | `string` | **Required**. Product Category           |

| `price`    | `float`  | **Required**. Product Price              |

### Internal folder structure for a new domain all folders and files go in internal/product/

```tree

├───internal

│   ├───product

│   │   │   port.go

│   │   │   product.go

│   │   │

│   │   ├───handler

│   │   │       createProduct.go

│   │   │       handler.go

│   │   │

│   │   ├───infrastructure

│   │   │       productRepository.go

│   │   │

│   │   ├───mock

│   │   │       mockProductRepository.go

│   │   │

│   │   └───service

│   │           createProduct.go

│   │           service.go

```

#### 1 - Create product.go (domain)

https://github.com/sebajax/go-vertical-slice-architecture/blob/d4501917930ef2263551bee3ee529de49b6d6fc5/internal/product/product.go#L1-L58

#### 2 - Create infrastructure/productRepository.go (DB query)

https://github.com/sebajax/go-vertical-slice-architecture/blob/872df7def565c7e0a95216b0b93d8166c3912ef5/internal/product/infrastructure/productRepository.go#L1-L61

```tree

├───internal

│   ├───product

│   │   ├───infrastructure

│   │   │       productRepository.go

```

#### 3 - Create port.go (dp injection for the service)

https://github.com/sebajax/go-vertical-slice-architecture/blob/872df7def565c7e0a95216b0b93d8166c3912ef5/internal/product/port.go#L1-L7

#### 4 - Create service/createProduct.go (create a new product use case implementation)

```tree

├───internal

│   ├───product

│   │   └───service

│   │           createProduct.go

│   │           service.go

```

https://github.com/sebajax/go-vertical-slice-architecture/blob/872df7def565c7e0a95216b0b93d8166c3912ef5/internal/product/service/createProduct.go#L1-L51

#### 5 - Create service/service.go (dependency injection service using uber dig)

```tree

├───internal

│   ├───product

│   │   └───service

│   │           createProduct.go

│   │           service.go

```

https://github.com/sebajax/go-vertical-slice-architecture/blob/872df7def565c7e0a95216b0b93d8166c3912ef5/internal/product/service/service.go#L1-L42

#### 6 - Create handler/createProduct.go (create a new hanlder presenter to call the use case)

```tree

├───internal

│   ├───product

│   │   ├───handler

│   │   │       createProduct.go

│   │   │       handler.go

```

https://github.com/sebajax/go-vertical-slice-architecture/blob/872df7def565c7e0a95216b0b93d8166c3912ef5/internal/product/handler/createProduct.go#L1-L60

#### 7 - Create handler/handler.go (handles all the routes for all the presenters)

```tree

├───internal

│   ├───product

│   │   ├───handler

│   │   │       createProduct.go

│   │   │       handler.go

```

https://github.com/sebajax/go-vertical-slice-architecture/blob/872df7def565c7e0a95216b0b93d8166c3912ef5/internal/product/handler/handler.go#L1-L11

#### 8 - Create mock/ProductRepository.go (mocks the user repository implementation for unit testing)

```tree

├───internal

│   ├───product

│   │   ├───mock

│   │   │       mockProductRepository.go

```

```bash

    # It uses mockery Run

        mockery

```

#### 9 - Create service/createProduct_test.go (create a unit test for the service)

```tree

├───internal

│   ├───product

│   │   └───service

│   │           createProduct.go

│   │           service.go

```

https://github.com/sebajax/go-vertical-slice-architecture/blob/9ff7ae658ee5bada18b88ec4a03994a105ccbe02/internal/product/service/createProduct_test.go#L1-L97

#### 10 - Add dependency injection service using uber dig

```tree

├───pkg

│   ├───injection

```

https://github.com/sebajax/go-vertical-slice-architecture/blob/eb79ccae805d23b6f77385a5f7ebfc81bb6174e0/pkg/injection/injection.go#L1-L73

## ⚙️ Usage without Make

### Docker usage

```bash

    # Build server

        docker-compose -p go-vertical-slice-architecture build

    # Start server

        docker-compose up -d

    # Stop server

        docker-compose down

```

### Standalone usage

```bash

    # Live reload

        air

```

### Testing

```bash

    # To run unit testing

        go test ./...

    # To run unit testing coverage

        go test -cover ./...

```

### Formatting, Linting and Vetting

```bash

    # Clean dependencies

        go mod tidy

    # Run formating

        go fmt ./...

    # Remove unused imports

        goimports -l -w .

    # Run linting

        golangci-lint run ./...

    # Run vetting

        go vet ./...

    # Run shadow to check shadowed variables

        # Install shadow

        go install golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow@latest

        # Run shadow

        shadow ./...

```

### Database migration script

```bash

    # Create the script

        migrate create -ext sql -dir /migrations -seq [script_name]

    # Run the script

        migrate -database ${POSTGRESQL_URL} -path /migrations up

    # It will run automatically when the database initializes

```

## ⚙️ Usage with Make

### Docker usage

```bash

    # Build server

        make build-server

    # Start server

        make start-server

    # Stop server

        make stop-server

```

### Standalone usage

```bash

    # Live reload

        make live-reload

```

### Testing

```bash

    # To run unit testing

        make test

    # To run unit testing coverage

        make test-coverage

```

### Formatting, Linting and Vetting

```bash

    # Clean dependencies

        make clean-deps

    # Run formating

        make format

    # Remove unused imports

        make clean-imports

    # Run linting

        make lint

    # Run vetting

        make vet

    # Run shadow to check shadowed variables

        # Install shadow

        go install golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow@latest

        # Run shadow

        make check-shadow

    # Run vetting to lint, format and vet your once

        make lint-format

```

### Database migration script

```bash

    # Create the script (replace your_script_name with the actual name)

        make migrate-create name=your_script_name

    # Run the script

        make migrate-up

    # It will run automatically when the database initializes

```

## 💻 Environment variables

To modify/add configuration via environment variables, use the `.env` file, which contains basic app configuration.