Getting started guidelines in writing maintainable code using Hexagonal Architecture.

# Hex Monscape [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

[![Go Reference](https://pkg.go.dev/badge/github.com/Haraj-backend/hex-monscape.svg)](https://pkg.go.dev/github.com/Haraj-backend/hex-monscape)
[![Go Report Card](https://goreportcard.com/badge/github.com/Haraj-backend/hex-monscape)](https://goreportcard.com/report/github.com/Haraj-backend/hex-monscape)
[![Coverage Status](https://coveralls.io/repos/github/Haraj-backend/hex-monscape/badge.svg?branch=master&refresh_token=4fff75f6-460c-48d9-b532-896e2aadbc5a)](https://coveralls.io/github/Haraj-backend/hex-monscape?branch=master)


![hex_monscape_preview](./docs/images/readme-preview-cc14f47c-8a2a-41ce-b442-bdd99b4807ca.png)

`Hex Monscape` is a simple turn-based game to make Haraj Solutions Team onboarding more fun.

In the game code, you can find the team's secret technique in writing production code for [Haraj](https://haraj.com.sa) services that help serve millions of people daily in Saudi Arabia despite only having a handful of team members. 🥷🏻💥

The secret technique actually lies in the architecture we choose for these services: [Hexagonal Architecture](./docs/reference/hex-architecture.md).

By using this remarkable architecture, not only can we speed up the development process of these services but also make them **maintainable by the whole team**. This is why even though our team is small, we can still do our job properly without losing good sleep at night. 🤣

The game was created using [Golang](https://go.dev/) & [Vue 3](https://vuejs.org/). To learn how we apply [Hexagonal Architecture](./docs/reference/hex-architecture.md) to the game, please refer to [this doc](./docs/reference/hex-architecture.md).

To start playing the game, please refer to [How to Run The Game](#how-to-run-the-game) section.

> **Note:**
>
> Many people got interested in software engineering because of games. So using them to exchange knowledge within our team seems like a fun idea. This is why we created this project. 😃
>
> Even though we are using Golang to implement [Hexagonal Architecture](./docs/reference/hex-architecture.md) in this repo, the architecture itself is language agnostic. So we can also apply it to other languages such as PHP, Typescript, & Python.

## Background Story

One of the most significant engineering issues in [Haraj](https://haraj.com.sa) is code maintainability.

What is code maintainability? Essentially it is the ability of a codebase to be easily maintained by others. So when a developer can no longer maintain the codebase, other developers could easily take over the code they left behind.

As you may already know, Haraj engineering team is small. So in our early days, we gave project ownership to the developer who started the project. This developer will be responsible for every aspect of the project development: writing the code, deploying it to production, & maintaining it.

At that time, we did not set common standards for writing code for those projects. So every developer writes code based on their style & preferences with almost no consideration for other developers.

This situation created a lot of frustration in the team. Since the project authors were the only ones who understood the code they wrote, they were also the only ones who could maintain it. So when they were on vacation or sick, the project they owned would be stuck until they came back because no one else dared to touch it. 😢

On the other hand, our developers will stay long before they leave (`~5 years`). So when a developer leaves the team, they usually own several valuable projects for the Haraj business. The problem is that since the projects were written in the developer's style, no team member could easily take over those projects. 😅


 <img width=512 src="./docs/reference/assets/memes/code-maintainability-this-is-fine.jpg" alt="Code Maintainability? This is fine.">


This is why code maintainability grows into such a big issue in Haraj, and the solution to prevent more of this is to set up common standards on how to write code in Haraj projects. This is where [Hexagonal Architecture](./docs/reference/hex-architecture.md) comes into play.

## Game Design

In the game you will play as a `10 years` old monster hunter that dreams to become the very best. In order to reach that, you need to make journey together with your monster partner to seek `3` strong wild monsters and kick them in the butt. 💥💪🏻

The game scenario is pretty simple, player just need to choose monster partner then won battle for `3` times to beat the game. After that player may choose to end the game or continue playing.

Here is the flowchart for the game scenario:


 <img src="./docs/reference/assets/game-flow.drawio.svg" alt="Game Flow" height="400" />


Here is the flowchart for each battle in the game:


 <img src="./docs/reference/assets/battle-flow.drawio.svg" alt="Battle Flow" height="400" />


To see the REST API specification for this game, please see [this doc](./docs/api/rest-api.md).

## How to Run The Game

You can try out this game online by visiting this URL: https://hex-monscape.haraj.app.

If you want to run the game locally, make sure following applications already installed in your machine:

- [Docker](https://docs.docker.com/get-docker/) `v20.10.23` or above => this will also install Docker Compose `v2.15.1`
- [make](https://linuxhint.com/make-command-linux/) => to execute the scripts for running the project defined in [Makefile](./Makefile)

After that use this command to run the game:

```bash
> make run
```

Wait for a moment until you see message like this:

```bash
rest-memory-client-1 | yarn run v1.22.19
rest-memory-client-1 | $ vite --host --port 8161
rest-memory-client-1 |
rest-memory-client-1 | vite v2.8.4 dev server running at:
rest-memory-client-1 |
rest-memory-client-1 | > Local: http://localhost:8161/
rest-memory-client-1 | > Network: http://172.31.0.3:8161/
rest-memory-client-1 |
rest-memory-client-1 | ready in 151ms.
```

After that you could access the game by visiting this URL: http://localhost:8161.

## Multiple Server Variants

Actually there are `3` variants of game server in this project:

- Server using In-Memory storage => run command: `make run-rest-memory`
- Server using DynamoDB storage => run command: `make run-rest-dynamodb`
- Server using MySQL storage => run command: `make run-rest-mysql`

All of them serve the same game, the only difference is the place where they store the game data.

For details on these commands, please refer to [this Makefile](./Makefile).

> **Note:**
>
> When we use [Hexagonal Architecture](./docs/reference/hex-architecture.md) to build an application, it is quite easy to swap its infrastructure code with another technologies.
>
> So for example, if initially we used in-memory storage to store our data, we could easily swap it with MySQL storage or something else. This is why in this project we provide `3` variants of game server for you, this is to demonstrate exactly this point.

## Attribution

The monster characters used in this project is designed by [Freepik](http://www.freepik.com). To be exact we are using [this asset](https://www.freepik.com/free-vector/set-funny-monsters-hand-drawn-style_1933029.htm).

The memes used in this project is generated using [this meme generator](https://imgflip.com/memegenerator).

The project layout used in this project is inspired by [this repo](https://github.com/golang-standards/project-layout).

The font used in the words `"Hex Monscape"` on the Hex Monscape logo is [Lexend Deca](https://fonts.google.com/specimen/Lexend+Deca?preview.text=HEX%20MONSCAPE&preview.text_type=custom&category=Sans+Serif,Display) from Google Fonts.

## Contributing

Got more idea on how to make this learning project more fun? Or maybe you found something that can be improved from this project?

Feel free to contribute to this repo by opening issue or creating a pull request! 😃

## Core Maintainers

Got any questions related to this project? Feel free to contact us:

- [Riandy Rahman Nugraha (@riandyrn)](https://github.com/riandyrn)
- [Muhammad Iskandar Dzulqornain (@isdzulqor)](https://github.com/isdzulqor)
- [Muhammad Izzuddin al Fikri (@knightazura)](https://github.com/knightazura)
- [Alfat Saputra Harun (@harunalfat)](https://github.com/harunalfat)
- [Ilham Syahid Syamsudin (@ilhamsyahids)](https://github.com/ilhamsyahids)

We will be very happy to help you! 🚀

## License

MIT

Hex Monscape

Curated list of awesome remote jobs. A lot of them are looking for Go hackers.

Awesome Remote Job

awesome-awesomeness

Parse awesome-go README file and generate a new README file with repo info.

awesome-go-extra

A curated list of awesome golang workshops.

# Awesome Golang Workshops [![Awesome](https://awesome.re/badge.svg)](https://awesome.re)
A curated list of awesome golang workshops. 

As opossed to tutorials or blog posts, workshops cover a topic thoroughly with great depth and are usually hosted in Github.  

### Contributing
Any comments, suggestions? [Let us know!](https://github.com/amit-davidson/awesome-golang-workshops/issues)  If you see something missing, please open a PR. Workshops should be a source to learn a new topic in depth so keep that in mind when opening a PR.


## Contents
* [Performance](#performance)
* [Learning Go](#learning-go)
* [Versioning](#versioning)
* [Web](#web)
* [Best Practices](#best-practices)
* [Design Patterns](#design-patterns)
* [Go Internals](#go-internals)
* [gRPC](#grpc)
* [ML](#ml)
* [Tooling](#tooling)

---

### Performance
* [High Performance Go Workshop](https://github.com/davecheney/high-performance-go-workshop) - Covers the tools to diagnose performance problems
* [Go Perfbook](https://github.com/dgryski/go-perfbook/) - Outlines best practices for writing high-performance Go code
* [Golang Benchmarks](https://github.com/jeromefroe/golang_benchmarks) - Comparison of different benchmarks with explanations for the results 
* [Compiler Optimizations](https://github.com/golang/go/wiki/CompilerOptimizations) - Optimizations done by the Go compiler

### Learning Go
* [Learn Go With Tests](https://github.com/quii/learn-go-with-tests) - Learn Go with test-driven development 
* [Gopher Labs](https://github.com/sangam14/GopherLabs) - A workshop with a track on how to be a Go developer
* [The Beginner's Guide to Go](https://tutorialedge.net/courses/go-beginners-guide/) - A workshop that walks you through everything you need in order to learn Go from the ground up.


### Versioning
* [vgo](https://research.swtch.com/vgo) - A collection of posts by Russ Cox about versioning in Go

### Web
* [Go Web Workshop](https://github.com/campoy/go-web-workshop) - How to build a web application with Go

### Best Practices
* [Uber Styling guide](https://github.com/uber-go/guide) - Documents style patterns and conventions used in Go use at Uber 
* [Clean Go Article](https://github.com/Pungyeon/clean-go-article) - Covers writing clean code and discusses concrete refactoring examples specific to Go

### Data Structures
* [Go Data Structures Course](https://tutorialedge.net/courses/go-data-structures-course/) - A course covering how you can build all the standard CS data structures using Go

### Design Patterns
* [Go Patterns](https://github.com/tmrts/go-patterns) - Curated list of Go design patterns, recipes and idioms

### Go Internals
* [Go Internals](https://github.com/teh-cmc/go-internals) - About the internals of Go
* [Static Analysis Workshop](https://github.com/amit-davidson/GopherCon2021IsraelStaticAnalysisWorkshop) - Dicusses about writing static code analyzers (linters) in Go for Go programs
* [Go 101](https://github.com/go101/go101) - focusing on Go syntax/semantics and all kinds of runtime related things

### gRPC
* [gRPC Workshop](https://github.com/mresti/grpc-workshop) - How to build a gRPC server, a gRPC client and how to deploy a gRPC server using docker
* [Go gRPC Crash Course](https://github.com/preslavmihaylov/go-grpc-crash-course) - A crash course on using gRPC with Go
* [Building gRPC Microservices in Go](https://tutorialedge.net/courses/go-grpc-services-course/) - A course that walks you through setting up, and implementing a gRPC microservice in Go

### ML
* [Machine Learning With Go](https://github.com/ardanlabs/training-ai/tree/master/machine-learning-with-go) - Provides a view on training, utilizing, evaluating, and deploying machine learning models using Go

### Tooling
* [Go Tooling Workshop](https://github.com/campoy/go-tooling-workshop) - Covers all the tools gophers use in their day to day life


Awesome Golang Workshops

A little e-book on Ethereum Development with Go.

<a href="https://goethereumbook.org"><img src="https://github.com/miguelmota/ethereum-development-with-go-book/raw/master/assets/cover.jpg" width="320" alt="Book cover" /></a>

 

# Ethereum Development with Go

> A little guide book on [Ethereum](https://www.ethereum.org/) Development with [Go](https://golang.org/) (golang)

[![License](http://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/miguelmota/merkletreejs/master/LICENSE)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)

## Online

[https://goethereumbook.org](https://goethereumbook.org/)

## E-book

The e-book is avaiable in different formats.

- [PDF](https://goethereumbook.org/ethereum-development-with-go.pdf)
- [EPUB](https://goethereumbook.org/ethereum-development-with-go.epub)
- [MOBI](https://goethereumbook.org/ethereum-development-with-go.mobi)

## Languages

* [English](en/)
* [Chinese中文](zh/)

## Contents

* [Introduction](en/README.md)
* [Client](en/client/README.md)
 * [Setting up the Client](en/client-setup/README.md)
* [Accounts](en/accounts/README.md)
 * [Account Balances](en/account-balance/README.md)
 * [Account Token Balances](en/account-balance-token/README.md)
 * [Generating New Wallets](en/wallet-generate/README.md)
 * [Keystores](en/keystore/README.md)
 * [HD Wallets](en/hd-wallet/README.md)
 * [Address Check](en/address-check/README.md)
* [Transactions](en/transactions/README.md)
 * [Querying Blocks](en/block-query/README.md)
 * [Querying Transactions](en/transaction-query/README.md)
 * [Transferring ETH](en/transfer-eth/README.md)
 * [Transferring Tokens](en/transfer-tokens/README.md)
 * [Subscribing to New Blocks](en/block-subscribe/README.md)
 * [Create Raw Transaction](en/transaction-raw-create/README.md)
 * [Send Raw Transaction](en/transaction-raw-send/README.md)
* [Smart Contracts](en/smart-contracts/README.md)
 * [Smart Contract Compilation & ABI](en/smart-contract-compile/README.md)
 * [Deploying a Smart Contract](en/smart-contract-deploy/README.md)
 * [Loading a Smart Contract](en/smart-contract-load/README.md)
 * [Querying a Smart Contract](en/smart-contract-read/README.md)
 * [Writing to a Smart Contract](en/smart-contract-write/README.md)
 * [Reading Smart Contract Bytecode](en/smart-contract-bytecode/README.md)
 * [Querying an ERC20 Token Smart Contract](en/smart-contract-read-erc20/README.md)
* [Event Logs](en/events/README.md)
 * [Subscribing to Event Logs](en/event-subscribe/README.md)
 * [Reading Event Logs](en/event-read/README.md)
 * [Reading ERC-20 Token Event Logs](en/event-read-erc20/README.md)
 * [Reading 0x Protocol Event Logs](en/event-read-0xprotocol/README.md)
* [Signatures](en/signatures/README.md)
 * [Generating Signatures](en/signature-generate/README.md)
 * [Verifying Signatures](en/signature-verify/README.md)
* [Testing](en/test/README.md)
 * [Faucets](en/faucets/README.md)
 * [Using a Simulated Client](en/client-simulated/README.md)
* [Swarm](en/swarm/README.md)
 * [Setting Up Swarm](en/swarm-setup/README.md)
 * [Uploading Files to Swarm](en/swarm-upload/README.md)
 * [Download Files From Swarm](en/swarm-download/README.md)
* [Whisper](en/whisper/README.md)
 * [Connecting Whisper Client](en/whisper-client/README.md)
 * [Generating Whisper Key Pair](en/whisper-keys/README.md)
 * [Sending Messages on Whisper](en/whisper-send/README.md)
 * [Subscribing to Whisper Messages](en/whisper-subscribe/README.md)
* [Utilities](en/util/README.md)
 * [Collection of Utility Functions](en/util-go/README.md)
* [Glossary](en/GLOSSARY.md)
* [Resources](en/resources/README.md)

## Help & Support

- Join the [#ethereum](https://gophers.slack.com/messages/C9HP1S9V2/) channel on the [gophers slack](https://invite.slack.golangbridge.org/) for Go (golang) help

- The [Ethereum StackExchange](https://ethereum.stackexchange.com/) is a great place to ask general Ethereum question and Go specific questions

## Development

Install dependencies:

```bash
make install
```

Run gitbook server:

```bash
make serve
```

Generating e-book in pdf, mobi, and epub format:

```bash
make ebooks
```

Visit [http://localhost:4000](http://localhost:4000)

## Contributing

Pull requests are welcome!

If making general content fixes:

- please double check for typos and cite any relevant sources in the comments.

If updating code examples:

- make sure to update both the code in the markdown files as well as the code in the [code](code/) folder.

If wanting to add a new translation, follow these instructions:

1. Set up [development environment](#development)

2. Add language to `LANGS.md`

3. Copy the the `en` directory and rename it with the 2 letter language code of the language you're translating to (e.g. `zh`)

4. Translate content

5. Set `"root"` to `"./"` in `book.json` if not already set

## Thanks

Thanks to [@qbig](https://github.com/qbig) and [@gzuhlwang](https://github.com/gzuhlwang) for the Chinese translation.

And thanks to all the [contributors](https://github.com/miguelmota/ethereum-development-with-go-book/graphs/contributors) who have contributed to this guide book.

## License

Released under the [CC0-1.0](./LICENSE) license.

© [Miguel Mota](https://github.com/miguelmota)

Ethereum Development with Go

Learn everything about Go in 7 days (from a Nodejs developer).

![banner](./assets/banner.png)

*the artwork created by [Wonkeen](https://github.com/QualitechOU/wonkeenGophers).*

## 🗺 roadmap

![roadmap](./assets/roadmap.png)

*[PDF file](./assets/roadmap.pdf)*

## 📝 documents

- [Golang tutorial series](https://golangbot.com/learn-golang-series/)
- [Go Language Advanced Programming](https://zalopay-oss.github.io/go-advanced/)
- [Let's Go: Learn Go in 30 days](https://dev.to/canro91/let-s-go-learn-go-in-30-days-3dg9)
- [Go tutorials by flaviocopes.com](https://flaviocopes.com/tags/go/)
- [Clean Go Code](https://github.com/Pungyeon/clean-go-article)
- [How To Code in Go](https://www.digitalocean.com/community/tutorial_series/how-to-code-in-go)
- [Go cheatsheet](https://devhints.io/go)
- [gophercises - FREE coding exercises for budding gophers](https://gophercises.com/)
- [exercism.io - go](https://exercism.io/tracks/go)
- [Awesome Go](https://github.com/avelino/awesome-go)
- [Eli Bendersky's website](https://eli.thegreenplace.net/)

## 🦄 license

MIT © [Cuong Tran](https://github.com/103cuong)


Go in 7 days

Clean Architecture template for Golang services.

![Go Clean Template](docs/img/logo.svg)

# Go Clean template
[🇨🇳中文](README_CN.md)

Clean Architecture template for Golang services

[![Go Report Card](https://goreportcard.com/badge/github.com/evrone/go-clean-template)](https://goreportcard.com/report/github.com/evrone/go-clean-template)
[![License](https://img.shields.io/github/license/evrone/go-clean-template.svg)](https://github.com/evrone/go-clean-template/blob/master/LICENSE)
[![Release](https://img.shields.io/github/v/release/evrone/go-clean-template.svg)](https://github.com/evrone/go-clean-template/releases/)
[![codecov](https://codecov.io/gh/evrone/go-clean-template/branch/master/graph/badge.svg?token=XE3E0X3EVQ)](https://codecov.io/gh/evrone/go-clean-template)

## Overview
The purpose of the template is to show:
- how to organize a project and prevent it from turning into spaghetti code
- where to store business logic so that it remains independent, clean, and extensible
- how not to lose control when a microservice grows

Using the principles of Robert Martin (aka Uncle Bob).

[Go-clean-template](https://evrone.com/go-clean-template?utm_source=github&utm_campaign=go-clean-template) is created & supported by [Evrone](https://evrone.com/?utm_source=github&utm_campaign=go-clean-template).

## Content
- [Quick start](#quick-start)
- [Project structure](#project-structure)
- [Dependency Injection](#dependency-injection)
- [Clean Architecture](#clean-architecture)

## Quick start
Local development:
```sh
# Postgres, RabbitMQ
$ make compose-up
# Run app with migrations
$ make run
```

Integration tests (can be run in CI):
```sh
# DB, app + migrations, integration tests
$ make compose-up-integration-test
```

## Project structure
### `cmd/app/main.go`
Configuration and logger initialization. Then the main function "continues" in
`internal/app/app.go`.

### `config`
Configuration. First, `config.yml` is read, then environment variables overwrite the yaml config if they match.
The config structure is in the `config.go`.
The `env-required: true` tag obliges you to specify a value (either in yaml, or in environment variables).

For configuration, we chose the [cleanenv](https://github.com/ilyakaznacheev/cleanenv) library.
It does not have many stars on GitHub, but is simple and meets all the requirements.

Reading the config from yaml contradicts the ideology of 12 factors, but in practice, it is more convenient than
reading the entire config from ENV.
It is assumed that default values are in yaml, and security-sensitive variables are defined in ENV.

### `docs`
Swagger documentation. Auto-generated by [swag](https://github.com/swaggo/swag) library.
You don't need to correct anything by yourself.

### `integration-test`
Integration tests.
They are launched as a separate container, next to the application container.
It is convenient to test the Rest API using [go-hit](https://github.com/Eun/go-hit).

### `internal/app`
There is always one _Run_ function in the `app.go` file, which "continues" the _main_ function.

This is where all the main objects are created.
Dependency injection occurs through the "New ..." constructors (see Dependency Injection).
This technique allows us to layer the application using the [Dependency Injection](#dependency-injection) principle.
This makes the business logic independent from other layers.

Next, we start the server and wait for signals in _select_ for graceful completion.
If `app.go` starts to grow, you can split it into multiple files.

For a large number of injections, [wire](https://github.com/google/wire) can be used.

The `migrate.go` file is used for database auto migrations.
It is included if an argument with the _migrate_ tag is specified.
For example:

```sh
$ go run -tags migrate ./cmd/app
```

### `internal/controller`
Server handler layer (MVC controllers). The template shows 2 servers:
- RPC (RabbitMQ as transport)
- REST http (Gin framework)

Server routers are written in the same style:
- Handlers are grouped by area of application (by a common basis)
- For each group, its own router structure is created, the methods of which process paths
- The structure of the business logic is injected into the router structure, which will be called by the handlers

#### `internal/controller/http`
Simple REST versioning.
For v2, we will need to add the `http/v2` folder with the same content.
And in the file `internal/app` add the line:
```go
handler := gin.New()
v1.NewRouter(handler, t)
v2.NewRouter(handler, t)
```

Instead of Gin, you can use any other http framework or even the standard `net/http` library.

In `v1/router.go` and above the handler methods, there are comments for generating swagger documentation using [swag](https://github.com/swaggo/swag).

### `internal/entity`
Entities of business logic (models) can be used in any layer.
There can also be methods, for example, for validation.

### `internal/usecase`
Business logic.
- Methods are grouped by area of application (on a common basis)
- Each group has its own structure
- One file - one structure

Repositories, webapi, rpc, and other business logic structures are injected into business logic structures
(see [Dependency Injection](#dependency-injection)).

#### `internal/usecase/repo`
A repository is an abstract storage (database) that business logic works with.

#### `internal/usecase/webapi`
It is an abstract web API that business logic works with.
For example, it could be another microservice that business logic accesses via the REST API.
The package name changes depending on the purpose.

### `pkg/rabbitmq`
RabbitMQ RPC pattern:
- There is no routing inside RabbitMQ
- Exchange fanout is used, to which 1 exclusive queue is bound, this is the most productive config
- Reconnect on the loss of connection

## Dependency Injection
In order to remove the dependence of business logic on external packages, dependency injection is used.

For example, through the New constructor, we inject the dependency into the structure of the business logic.
This makes the business logic independent (and portable).
We can override the implementation of the interface without making changes to the `usecase` package.

```go
package usecase

import (
 // Nothing!
)

type Repository interface {
 Get()
}

type UseCase struct {
 repo Repository
}

func New(r Repository) *UseCase{
 return &UseCase{
 repo: r,
 }
}

func (uc *UseCase) Do() {
 uc.repo.Get()
}
```

It will also allow us to do auto-generation of mocks (for example with [mockery](https://github.com/vektra/mockery)) and easily write unit tests.

> We are not tied to specific implementations in order to always be able to change one component to another.
> If the new component implements the interface, nothing needs to be changed in the business logic.

## Clean Architecture
### Key idea
Programmers realize the optimal architecture for an application after most of the code has been written.

> A good architecture allows decisions to be delayed to as late as possible.

### The main principle
Dependency Inversion (the same one from SOLID) is the principle of dependency inversion.
The direction of dependencies goes from the outer layer to the inner layer.
Due to this, business logic and entities remain independent from other parts of the system.

So, the application is divided into 2 layers, internal and external:
1. **Business logic** (Go standard library).
2. **Tools** (databases, servers, message brokers, any other packages and frameworks).

![Clean Architecture](docs/img/layers-1.png)

**The inner layer** with business logic should be clean. It should:
- Not have package imports from the outer layer.
- Use only the capabilities of the standard library.
- Make calls to the outer layer through the interface (!).

The business logic doesn't know anything about Postgres or a specific web API.
Business logic has an interface for working with an _abstract_ database or _abstract_ web API.

**The outer layer** has other limitations:
- All components of this layer are unaware of each other's existence. How to call another from one tool? Not directly, only through the inner layer of business logic.
- All calls to the inner layer are made through the interface (!).
- Data is transferred in a format that is convenient for business logic (`internal/entity`).

For example, you need to access the database from HTTP (controller).
Both HTTP and database are in the outer layer, which means they know nothing about each other.
The communication between them is carried out through `usecase` (business logic):

```
 HTTP > usecase
 usecase > repository (Postgres)
 usecase < repository (Postgres)
 HTTP < usecase
```
The symbols > and < show the intersection of layer boundaries through Interfaces.
The same is shown in the picture:

![Example](docs/img/example-http-db.png)

Or more complex business logic:
```
 HTTP > usecase
 usecase > repository
 usecase < repository
 usecase > webapi
 usecase < webapi
 usecase > RPC
 usecase < RPC
 usecase > repository
 usecase < repository
 HTTP < usecase
```

### Layers
![Example](docs/img/layers-2.png)

### Clean Architecture Terminology
- **Entities** are structures that business logic operates on.
 They are located in the `internal/entity` folder.
 In MVC terms, entities are models.
 
- **Use Cases** is business logic located in `internal/usecase`.

The layer with which business logic directly interacts is usually called the _infrastructure_ layer.
These can be repositories `internal/usecase/repo`, external webapi `internal/usecase/webapi`, any pkg, and other microservices.
In the template, the _infrastructure_ packages are located inside `internal/usecase`.

You can choose how to call the entry points as you wish. The options are:
- controller (in our case)
- delivery
- transport
- gateways
- entrypoints
- primary
- input

### Additional layers
The classic version of [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) was designed for building large monolithic applications and has 4 layers.

In the original version, the outer layer is divided into two more, which also have an inversion of dependencies
to each other (directed inward) and communicate through interfaces.

The inner layer is also divided into two (with separation of interfaces), in the case of complex logic.

_______________________________

Complex tools can be divided into additional layers.
However, you should add layers only if really necessary.

### Alternative approaches
In addition to Clean architecture, _Onion architecture_ and _Hexagonal_ (_Ports and adapters_) are similar to it.
Both are based on the principle of Dependency Inversion.
_Ports and adapters_ are very close to _Clean Architecture_, the differences are mainly in terminology.


## Similar projects
- [https://github.com/bxcodec/go-clean-arch](https://github.com/bxcodec/go-clean-arch)
- [https://github.com/zhashkevych/courses-backend](https://github.com/zhashkevych/courses-backend)

## Useful links
- [The Clean Architecture article](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
- [Twelve factors](https://12factor.net/ru/)

go-clean-template

Curated list of Go design patterns, recipes and idioms.

go-patterns

Collection of Go projects that needs help. Good place to start your open-source way in Go.

# gocryforhelp
List of opensource projects looking for help

![](https://raw.githubusercontent.com/ninedraft/gocryforhelp/master/GCFH.png)

# Contents
  - [CMS, blog engines, etc](#cms)
  - [GUI && Widgets packages and toolchains](#gui-widgets)
  - [Telegram bots && API](#telegram-bots)
  - [Web frameworks](#web-frameworks)
  - [Programming languages](#programming-languages)


### CMS

* [blackbox](https://github.com/ninedraft/blackbox) - a KISSed blog engine
* [go-starter-kit](https://github.com/olebedev/go-starter-kit) - Golang isomorphic react/hot reloadable/redux/css-modules starter kit


### GUI, Widgets

* [go-wde](https://github.com/kirillDanshin/go-wde) - (W)indows, (d)rawing and (e)vents for Go. Fork of [go.wde](https://github.com/skelterjohn/go.wde)
* [go.uik](https://github.com/kirillDanshin/go.uik) - A concurrent UI kit written in pure go. Fork of [go.uik](https://github.com/skelterjohn/go.uik)

### Telegram bots
* [nagtlg](https://github.com/diphost/nagtlg/) - Telegram bot for Nagios and Livestatus 
* [bot-api/telegram](https://github.com/bot-api/telegram/) - Implementation of the telegram bot API with net/context and middlewares
* [HentaiDB](https://github.com/HentaiDB/) - Telegram bot for searching content in popular repositories and tools for his work

### Web frameworks
* [gramework](https://github.com/gramework/gramework) - One of the fastest framework written in Go, while respecting the licenses. Bringing convenient, useful high performance battle-tested solutions to opensource. ([telegram chat](https://t.me/gramework))

### Programming languages
* [Goodlang](https://github.com/goodlang/good) - Golang fork ([telegram chat](https://telegram.me/goodlang))


gocryforhelp

Collection of Go images, graphics, and art.

golang-graphics
================

A community repository for Go language vector (and bitmap) graphics. It includes the official graphics that ship with Go as well as 3rd-party contributions.

This is an *unofficial* repository.

The goal of this repository is to encourage creativity and innovation (as well as fair use) in the Go community. Having access to high-quality vector graphics and 3D models makes it possible to produce beautiful, creative works that feel familiar and recognizable.



## How to Contribute

Just submit a pull request with your creation or derivative work. Vector formats are preferred.

**Here's some tips for submitting a PR:**

- Files are organized into folders by type. If a folder for your file type doesn't already exist, you may create it.
- Each folder should have a plain-text file called `README`. It credits each file in alphabetical order in this kind of format (flexible depending on the contribution):
```
file-name.ext
	Contributed by Your Name
	If released under a different license, specify it here
	Adaptation of original-file.png (Original Creator)
	Any other source or historical information of interest
```
- If possible, please try to keep file names lowercase with hyphens between words (no spaces or other punctuation).



## Check the license!

[![CC-BY-4.0](http://i.creativecommons.org/l/by/4.0/88x31.png)](http://creativecommons.org/licenses/by/4.0)

By default, contributions fall under [Creative Commons Attribution 4.0 International](http://creativecommons.org/licenses/by/4.0). However, licenses vary among different files, so pay attention before you use.


#### Is a license specified for that file in the README?

Each folder has a file called `README` that contains information about its contents. If a certain file has an exceptional license, it will be specified in the `README`.



#### Is there a LICENSE file in the folder?

If a folder has a `LICENSE` file, that license applies, by default, to all files in that folder and all sub-folders. It may be overridden by subsequent `LICENSE` files or on a per-file basis in a `README`.





## Hotlinking

We advise against linking directly to these images. GitHub is not a CDN; if the paths ever change, your links will break.



## Original credit

The original Go gopher was created by [Renée French](http://reneefrench.blogspot.com) and is released under [Creative Commons Attribution 3.0 USA license](http://creativecommons.org/licenses/by/3.0/us). Thus all derivatives must provide attribution.

More information about the gopher can be found [on the Go blog](http://blog.golang.org/gopher).


golang-graphics

Golang ebook intro how to build a web app with golang.

# Multiple Language Versions

* [(HTML - PDF) on GitBook](https://astaxie.gitbooks.io/build-web-application-with-golang)
* [Deutsch](de/preface.md)
* [English](en/preface.md)
* [Español](es/preface.md)
* [Français](fr/preface.md)
* [Português - Brasil](pt-br/preface.md)
* [Русский](ru/preface.md)
* [Türkçe](tr/preface.md)
* [বাংলা](bn/preface.md)
* [日本語](ja/preface.md)
* [简体中文](zh/preface.md)
* [正體中文](zh-tw/preface.md)
* [پارسی](fa/preface.md)
* [ภาษาไทย](th/preface.md)

# Donate

AliPay: <img src="zh/images/alipay.png" alt="alipay" width="100" height="100">

English Donate:[donate](http://beego.me/donate)

## Community
QQ群：148647580

BBS：[http://gocn.io/](http://gocn.io/)

## Contributors

- See [contributors page](https://github.com/astaxie/build-web-application-with-golang/graphs/contributors) for full list of contributors.

## Acknowledgments

 - [四月份平民](https://plus.google.com/110445767383269817959) (review代码)
 - [Hong Ruiqi](https://github.com/hongruiqi) (review代码)
 - [BianJiang](https://github.com/border) (编写go开发工具Vim和Emacs的设置)
 - [Oling Cat](https://github.com/OlingCat)(review代码)
 - [Wenlei Wu](mailto:spadesacn@gmail.com)(提供一些图片展示)
 - [polaris](https://github.com/polaris1119)(review书)
 - [雨痕](https://github.com/qyuhen)(review第二章)

## License
Book License: [CC BY-SA 3.0 License](http://creativecommons.org/licenses/by-sa/3.0/)

Code License: [BSD 3-Clause License](<https://github.com/astaxie/build-web-application-with-golang/blob/master/LICENSE.md>)

Build web application with Golang

Collection of programming design patterns implemented in Go.

# Design Patterns 🚀🧩

[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go)

Design Patterns are ways of solving different problems we face while designing software solutions. Having too many if/else conditions? Need to implement multiple ways of initializing objects? Writing too many parsers? There's probably a design pattern to help you structure your code elegantly!

An important thing to note though, is that design patterns are but a set of blueprints/recommendations. They are not exact solutions to problems. Rather, they are a concepts/conventions to follow in your code.

In this repository, I have curated a list of design patterns that may help you in your projects!

> These patterns are implemented in go. However, with each pattern, I have included a readme file containing the detailed description of the pattern. Hence, you should comfortably be able to implement this in any coding language 🤘🏽

### Contents

1. [Factory pattern](./1-factory)
2. [Abstract Factory pattern](./2-abstract-factory)
3. [Builder Pattern](./3-builder)
4. [Adapter Pattern](./4-adapter)
5. [Bridge Pattern](./5-bridge)
6. [Decorator Pattern](./6-decorator)
7. [Facade Pattern](./7-facade)
8. [Flyweight Pattern](./8-flyweight)
9. [Chain of responsibility](./9-chain-of-responsibility)

wip


Design Patterns in Go

# Go Cheat Sheet

# Index
1. [Basic Syntax](#basic-syntax)
2. [Operators](#operators)
 * [Arithmetic](#arithmetic)
 * [Comparison](#comparison)
 * [Logical](#logical)
 * [Other](#other)
3. [Declarations](#declarations)
4. [Functions](#functions)
 * [Functions as values and closures](#functions-as-values-and-closures)
 * [Variadic Functions](#variadic-functions)
5. [Built-in Types](#built-in-types)
6. [Type Conversions](#type-conversions)
7. [Packages](#packages)
8. [Control structures](#control-structures)
 * [If](#if)
 * [Loops](#loops)
 * [Switch](#switch)
9. [Arrays, Slices, Ranges](#arrays-slices-ranges)
 * [Arrays](#arrays)
 * [Slices](#slices)
 * [Operations on Arrays and Slices](#operations-on-arrays-and-slices)
10. [Maps](#maps)
11. [Structs](#structs)
12. [Pointers](#pointers)
13. [Interfaces](#interfaces)
14. [Embedding](#embedding)
15. [Errors](#errors)
16. [Concurrency](#concurrency)
 * [Goroutines](#goroutines)
 * [Channels](#channels)
 * [Channel Axioms](#channel-axioms)
17. [Printing](#printing)
18. [Reflection](#reflection)
 * [Type Switch](#type-switch)
 * [Examples](https://github.com/a8m/reflect-examples)
19. [Snippets](#snippets)
 * [Files Embedding](#files-embedding)
 * [HTTP Server](#http-server)

## Credits

Most example code taken from [A Tour of Go](http://tour.golang.org/), which is an excellent introduction to Go.
If you're new to Go, do that tour. Seriously.

## Go in a Nutshell

* Imperative language
* Statically typed
* Syntax tokens similar to C (but less parentheses and no semicolons) and the structure to Oberon-2
* Compiles to native code (no JVM)
* No classes, but structs with methods
* Interfaces
* No implementation inheritance. There's [type embedding](http://golang.org/doc/effective%5Fgo.html#embedding), though.
* Functions are first class citizens
* Functions can return multiple values
* Has closures
* Pointers, but not pointer arithmetic
* Built-in concurrency primitives: Goroutines and Channels

# Basic Syntax

## Hello World
File `hello.go`:
```go
package main

import "fmt"

func main() {
 fmt.Println("Hello Go")
}
```
`$ go run hello.go`

## Operators
### Arithmetic
|Operator|Description|
|--------|-----------|
|`+`|addition|
|`-`|subtraction|
|`*`|multiplication|
|`/`|quotient|
|`%`|remainder|
|`&`|bitwise and|
|`\|`|bitwise or|
|`^`|bitwise xor|
|`&^`|bit clear (and not)|
|`<<`|left shift|
|`>>`|right shift|

### Comparison
|Operator|Description|
|--------|-----------|
|`==`|equal|
|`!=`|not equal|
|`<`|less than|
|`<=`|less than or equal|
|`>`|greater than|
|`>=`|greater than or equal|

### Logical
|Operator|Description|
|--------|-----------|
|`&&`|logical and|
|`\|\|`|logical or|
|`!`|logical not|

### Other
|Operator|Description|
|--------|-----------|
|`&`|address of / create pointer|
|`*`|dereference pointer|
|`<-`|send / receive operator (see 'Channels' below)|

## Declarations
Type goes after identifier!
```go
var foo int // declaration without initialization
var foo int = 42 // declaration with initialization
var foo, bar int = 42, 1302 // declare and init multiple vars at once
var foo = 42 // type omitted, will be inferred
foo := 42 // shorthand, only in func bodies, omit var keyword, type is always implicit
const constant = "This is a constant"

// iota can be used for incrementing numbers, starting from 0
const (
 _ = iota
 a
 b
 c = 1 << iota
 d
)
 fmt.Println(a, b) // 1 2 (0 is skipped)
 fmt.Println(c, d) // 8 16 (2^3, 2^4)
```

## Functions
```go
// a simple function
func functionName() {}

// function with parameters (again, types go after identifiers)
func functionName(param1 string, param2 int) {}

// multiple parameters of the same type
func functionName(param1, param2 int) {}

// return type declaration
func functionName() int {
 return 42
}

// Can return multiple values at once
func returnMulti() (int, string) {
 return 42, "foobar"
}
var x, str = returnMulti()

// Return multiple named results simply by return
func returnMulti2() (n int, s string) {
 n = 42
 s = "foobar"
 // n and s will be returned
 return
}
var x, str = returnMulti2()

```

### Functions As Values And Closures
```go
func main() {
 // assign a function to a name
 add := func(a, b int) int {
 return a + b
 }
 // use the name to call the function
 fmt.Println(add(3, 4))
}

// Closures, lexically scoped: Functions can access values that were
// in scope when defining the function
func scope() func() int{
 outer_var := 2
 foo := func() int { return outer_var}
 return foo
}

func another_scope() func() int{
 // won't compile because outer_var and foo not defined in this scope
 outer_var = 444
 return foo
}


// Closures
func outer() (func() int, int) {
 outer_var := 2
 inner := func() int {
 outer_var += 99 // outer_var from outer scope is mutated.
 return outer_var
 }
 inner()
 return inner, outer_var // return inner func and mutated outer_var 101
}
```

### Variadic Functions
```go
func main() {
	fmt.Println(adder(1, 2, 3)) 	// 6
	fmt.Println(adder(9, 9))	// 18

	nums := []int{10, 20, 30}
	fmt.Println(adder(nums...))	// 60
}

// By using ... before the type name of the last parameter you can indicate that it takes zero or more of those parameters.
// The function is invoked like any other function except we can pass as many arguments as we want.
func adder(args ...int) int {
	total := 0
	for _, v := range args { // Iterates over the arguments whatever the number.
		total += v
	}
	return total
}
```

## Built-in Types
```go
bool

string

int int8 int16 int32 int64
uint uint8 uint16 uint32 uint64 uintptr

byte // alias for uint8

rune // alias for int32 ~= a character (Unicode code point) - very Viking

float32 float64

complex64 complex128
```

All Go's predeclared identifiers are defined in the [builtin](https://golang.org/pkg/builtin/) package. 

## Type Conversions
```go
var i int = 42
var f float64 = float64(i)
var u uint = uint(f)

// alternative syntax
i := 42
f := float64(i)
u := uint(f)
```

## Packages
* Package declaration at top of every source file
* Executables are in package `main`
* Convention: package name == last name of import path (import path `math/rand` => package `rand`)
* Upper case identifier: exported (visible from other packages)
* Lower case identifier: private (not visible from other packages)

## Control structures

### If
```go
func main() {
	// Basic one
	if x > 10 {
		return x
	} else if x == 10 {
		return 10
	} else {
		return -x
	}

	// You can put one statement before the condition
	if a := b + c; a < 42 {
		return a
	} else {
		return a - 42
	}

	// Type assertion inside if
	var val interface{} = "foo"
	if str, ok := val.(string); ok {
		fmt.Println(str)
	}
}
```

### Loops
```go
 // There's only `for`, no `while`, no `until`
 for i := 1; i < 10; i++ {
 }
 for ; i < 10; { // while - loop
 }
 for i < 10 { // you can omit semicolons if there is only a condition
 }
 for { // you can omit the condition ~ while (true)
 }
 
 // use break/continue on current loop
 // use break/continue with label on outer loop
here:
 for i := 0; i < 2; i++ {
 for j := i + 1; j < 3; j++ {
 if i == 0 {
 continue here
 }
 fmt.Println(j)
 if j == 2 {
 break
 }
 }
 }

there:
 for i := 0; i < 2; i++ {
 for j := i + 1; j < 3; j++ {
 if j == 1 {
 continue
 }
 fmt.Println(j)
 if j == 2 {
 break there
 }
 }
 }
```

### Switch
```go
 // switch statement
 switch operatingSystem {
 case "darwin":
 fmt.Println("Mac OS Hipster")
 // cases break automatically, no fallthrough by default
 case "linux":
 fmt.Println("Linux Geek")
 default:
 // Windows, BSD, ...
 fmt.Println("Other")
 }

 // as with for and if, you can have an assignment statement before the switch value
 switch os := runtime.GOOS; os {
 case "darwin": ...
 }

 // you can also make comparisons in switch cases
 number := 42
 switch {
 case number < 42:
 fmt.Println("Smaller")
 case number == 42:
 fmt.Println("Equal")
 case number > 42:
 fmt.Println("Greater")
 }

 // cases can be presented in comma-separated lists
 var char byte = '?'
 switch char {
 case ' ', '?', '&', '=', '#', '+', '%':
 fmt.Println("Should escape")
 }
```

## Arrays, Slices, Ranges

### Arrays
```go
var a [10]int // declare an int array with length 10. Array length is part of the type!
a[3] = 42 // set elements
i := a[3] // read elements

// declare and initialize
var a = [2]int{1, 2}
a := [2]int{1, 2} //shorthand
a := [...]int{1, 2} // elipsis -> Compiler figures out array length
```

### Slices
```go
var a []int // declare a slice - similar to an array, but length is unspecified
var a = []int {1, 2, 3, 4} // declare and initialize a slice (backed by the array given implicitly)
a := []int{1, 2, 3, 4} // shorthand
chars := []string{0:"a", 2:"c", 1: "b"} // ["a", "b", "c"]

var b = a[lo:hi]	// creates a slice (view of the array) from index lo to hi-1
var b = a[1:4]		// slice from index 1 to 3
var b = a[:3]		// missing low index implies 0
var b = a[3:]		// missing high index implies len(a)
a = append(a,17,3)	// append items to slice a
c := append(a,b...)	// concatenate slices a and b

// create a slice with make
a = make([]byte, 5, 5)	// first arg length, second capacity
a = make([]byte, 5)	// capacity is optional

// create a slice from an array
x := [3]string{"Лайка", "Белка", "Стрелка"}
s := x[:] // a slice referencing the storage of x
```

### Operations on Arrays and Slices
`len(a)` gives you the length of an array/a slice. It's a built-in function, not a attribute/method on the array.

```go
// loop over an array/a slice
for i, e := range a {
 // i is the index, e the element
}

// if you only need e:
for _, e := range a {
 // e is the element
}

// ...and if you only need the index
for i := range a {
}

// In Go pre-1.4, you'll get a compiler error if you're not using i and e.
// Go 1.4 introduced a variable-free form, so that you can do this
for range time.Tick(time.Second) {
 // do it once a sec
}

```

## Maps

```go
m := make(map[string]int)
m["key"] = 42
fmt.Println(m["key"])

delete(m, "key")

elem, ok := m["key"] // test if key "key" is present and retrieve it, if so

// map literal
var m = map[string]Vertex{
 "Bell Labs": {40.68433, -74.39967},
 "Google": {37.42202, -122.08408},
}

// iterate over map content
for key, value := range m {
}

```

## Structs

There are no classes, only structs. Structs can have methods.
```go
// A struct is a type. It's also a collection of fields

// Declaration
type Vertex struct {
 X, Y float64
}

// Creating
var v = Vertex{1, 2}
var v = Vertex{X: 1, Y: 2} // Creates a struct by defining values with keys
var v = []Vertex{{1,2},{5,2},{5,5}} // Initialize a slice of structs

// Accessing members
v.X = 4

// You can declare methods on structs. The struct you want to declare the
// method on (the receiving type) comes between the the func keyword and
// the method name. The struct is copied on each method call(!)
func (v Vertex) Abs() float64 {
 return math.Sqrt(v.X*v.X + v.Y*v.Y)
}

// Call method
v.Abs()

// For mutating methods, you need to use a pointer (see below) to the Struct
// as the type. With this, the struct value is not copied for the method call.
func (v *Vertex) add(n float64) {
 v.X += n
 v.Y += n
}

```
**Anonymous structs:**
Cheaper and safer than using `map[string]interface{}`.
```go
point := struct {
	X, Y int
}{1, 2}
```

## Pointers
```go
p := Vertex{1, 2} // p is a Vertex
q := &p // q is a pointer to a Vertex
r := &Vertex{1, 2} // r is also a pointer to a Vertex

// The type of a pointer to a Vertex is *Vertex

var s *Vertex = new(Vertex) // new creates a pointer to a new struct instance
```

## Interfaces
```go
// interface declaration
type Awesomizer interface {
 Awesomize() string
}

// types do *not* declare to implement interfaces
type Foo struct {}

// instead, types implicitly satisfy an interface if they implement all required methods
func (foo Foo) Awesomize() string {
 return "Awesome!"
}
```

## Embedding

There is no subclassing in Go. Instead, there is interface and struct embedding.

```go
// ReadWriter implementations must satisfy both Reader and Writer
type ReadWriter interface {
 Reader
 Writer
}

// Server exposes all the methods that Logger has
type Server struct {
 Host string
 Port int
 *log.Logger
}

// initialize the embedded type the usual way
server := &Server{"localhost", 80, log.New(...)}

// methods implemented on the embedded struct are passed through
server.Log(...) // calls server.Logger.Log(...)

// the field name of the embedded type is its type name (in this case Logger)
var logger *log.Logger = server.Logger
```

## Errors

There is no exception handling. Instead, functions that might produce an error just declare an additional return value of type [`error`](https://golang.org/pkg/builtin/#error). This is the `error` interface:

```go
// The error built-in interface type is the conventional interface for representing an error condition,
// with the nil value representing no error.
type error interface {
 Error() string
}
```

Here's an example:
```go
func sqrt(x float64) (float64, error) {
	if x < 0 {
		return 0, errors.New("negative value")
	}
	return math.Sqrt(x), nil
}

func main() {
	val, err := sqrt(-1)
	if err != nil {
		// handle error
		fmt.Println(err) // negative value
		return
	}
	// All is good, use `val`.
	fmt.Println(val)
}
```

# Concurrency

## Goroutines
Goroutines are lightweight threads (managed by Go, not OS threads). `go f(a, b)` starts a new goroutine which runs `f` (given `f` is a function).

```go
// just a function (which can be later started as a goroutine)
func doStuff(s string) {
}

func main() {
 // using a named function in a goroutine
 go doStuff("foobar")

 // using an anonymous inner function in a goroutine
 go func (x int) {
 // function body goes here
 }(42)
}
```

## Channels
```go
ch := make(chan int) // create a channel of type int
ch <- 42 // Send a value to the channel ch.
v := <-ch // Receive a value from ch

// Non-buffered channels block. Read blocks when no value is available, write blocks until there is a read.

// Create a buffered channel. Writing to a buffered channels does not block if less than <buffer size> unread values have been written.
ch := make(chan int, 100)

close(ch) // closes the channel (only sender should close)

// read from channel and test if it has been closed
v, ok := <-ch

// if ok is false, channel has been closed

// Read from channel until it is closed
for i := range ch {
 fmt.Println(i)
}

// select blocks on multiple channel operations, if one unblocks, the corresponding case is executed
func doStuff(channelOut, channelIn chan int) {
 select {
 case channelOut <- 42:
 fmt.Println("We could write to channelOut!")
 case x := <- channelIn:
 fmt.Println("We could read from channelIn")
 case <-time.After(time.Second * 1):
 fmt.Println("timeout")
 }
}
```

### Channel Axioms
- A send to a nil channel blocks forever

 ```go
 var c chan string
 c <- "Hello, World!"
 // fatal error: all goroutines are asleep - deadlock!
 ```
- A receive from a nil channel blocks forever

 ```go
 var c chan string
 fmt.Println(<-c)
 // fatal error: all goroutines are asleep - deadlock!
 ```
- A send to a closed channel panics

 ```go
 var c = make(chan string, 1)
 c <- "Hello, World!"
 close(c)
 c <- "Hello, Panic!"
 // panic: send on closed channel
 ```
- A receive from a closed channel returns the zero value immediately

 ```go
 var c = make(chan int, 2)
 c <- 1
 c <- 2
 close(c)
 for i := 0; i < 3; i++ {
 fmt.Printf("%d ", <-c)
 }
 // 1 2 0
 ```

## Printing

```go
fmt.Println("Hello, 你好, नमस्ते, Привет, ᎣᏏᏲ") // basic print, plus newline
p := struct { X, Y int }{ 17, 2 }
fmt.Println( "My point:", p, "x coord=", p.X ) // print structs, ints, etc
s := fmt.Sprintln( "My point:", p, "x coord=", p.X ) // print to string variable

fmt.Printf("%d hex:%x bin:%b fp:%f sci:%e",17,17,17,17.0,17.0) // c-ish format
s2 := fmt.Sprintf( "%d %f", 17, 17.0 ) // formatted print to string variable

hellomsg := `
 "Hello" in Chinese is 你好 ('Ni Hao')
 "Hello" in Hindi is नमस्ते ('Namaste')
` // multi-line string literal, using back-tick at beginning and end
```

## Reflection
### Type Switch
A type switch is like a regular switch statement, but the cases in a type switch specify types (not values) which are compared against the type of the value held by the given interface value.
```go
func do(i interface{}) {
	switch v := i.(type) {
	case int:
		fmt.Printf("Twice %v is %v\n", v, v*2)
	case string:
		fmt.Printf("%q is %v bytes long\n", v, len(v))
	default:
		fmt.Printf("I don't know about type %T!\n", v)
	}
}

func main() {
	do(21)
	do("hello")
	do(true)
}
```

# Snippets

## Files Embedding

Go programs can embed static files using the `"embed"` package as follows:

```go
package main

import (
	"embed"
	"log"
	"net/http"
)

// content holds the static content (2 files) for the web server.
//go:embed a.txt b.txt
var content embed.FS

func main() {
	http.Handle("/", http.FileServer(http.FS(content)))
	log.Fatal(http.ListenAndServe(":8080", nil))
}
```

[Full Playground Example](https://play.golang.org/p/pwWxdrQSrYv)

## HTTP Server
```go
package main

import (
 "fmt"
 "net/http"
)

// define a type for the response
type Hello struct{}

// let that type implement the ServeHTTP method (defined in interface http.Handler)
func (h Hello) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 fmt.Fprint(w, "Hello!")
}

func main() {
 var h Hello
 http.ListenAndServe("localhost:4000", h)
}

// Here's the method signature of http.ServeHTTP:
// type Handler interface {
// ServeHTTP(w http.ResponseWriter, r *http.Request)
// }
```

Go Cheat Sheet

An opinionated guideline to structure & develop a Go web application/service.

goapp

Examples of Golang compared to Node.js for learning.

Golang for Node.js Developers

# Go Examples

[![DOI](https://zenodo.org/badge/9459712.svg)](https://zenodo.org/badge/latestdoi/9459712) 
[![Go Report Card](https://goreportcard.com/badge/github.com/simonwaldherr/golang-examples)](https://goreportcard.com/report/github.com/simonwaldherr/golang-examples) 
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)  

Use the [online live editor with Golang support](https://simonwaldherr.github.io/golang-examples/). Edit and run the examples directly in your browser:
[![SimonWaldherr/golang-benchmarks Online Editor](https://simonwaldherr.github.io/golang-examples/golang-examples.png)](https://simonwaldherr.github.io/golang-examples/)  



If you liked this project, you may also like  
my [golang-benchmarks](https://github.com/SimonWaldherr/golang-benchmarks) repository:  
[![SimonWaldherr/golang-benchmarks - GitHub](https://gh-card.dev/repos/SimonWaldherr/golang-benchmarks.svg?fullname)](https://github.com/SimonWaldherr/golang-benchmarks)  
my [gotools](https://github.com/SimonWaldherr/gotools) repository:  
[![SimonWaldherr/gotools - GitHub](https://gh-card.dev/repos/SimonWaldherr/gotools.svg?fullname)](https://github.com/SimonWaldherr/gotools)  
my [sql-examples](https://github.com/SimonWaldherr/sql-examples) repository:  
[![SimonWaldherr/sql-examples - GitHub](https://gh-card.dev/repos/SimonWaldherr/sql-examples.svg?fullname)](https://github.com/SimonWaldherr/sql-examples)  
my [rp2040-examples](https://github.com/SimonWaldherr/rp2040-examples) repository:  
[![SimonWaldherr/rp2040-examples - GitHub](https://gh-card.dev/repos/SimonWaldherr/rp2040-examples.svg?fullname)](https://github.com/SimonWaldherr/rp2040-examples)  
or my [rpi-examples](https://github.com/SimonWaldherr/rpi-examples) repository:  
[![SimonWaldherr/rpi-examples - GitHub](https://gh-card.dev/repos/SimonWaldherr/rpi-examples.svg?fullname)](https://github.com/SimonWaldherr/rpi-examples)

## About

These examples explain the basics of Golang. There will be more examples from time to time.

if you like, feel free to add more Golang examples. Many thanks to all [contributors](https://github.com/SimonWaldherr/golang-examples/graphs/contributors).

## Install go(lang)

with [homebrew](http://mxcl.github.io/homebrew/):

```Shell
sudo brew install go
```

with [apt](http://packages.qa.debian.org/a/apt.html)-get:

```Shell
sudo apt-get install golang
```

[install Golang manually](https://golang.org/doc/install)
or
[compile it yourself](https://golang.org/doc/install/source)

## Examples

The examples are divided into three levels of difficulty. The [Beginner](https://github.com/SimonWaldherr/golang-examples#beginner) section contains very easy examples, starting with **Hello World** but also containing a few easy algorithms. The [Advanced](https://github.com/SimonWaldherr/golang-examples#advanced) section uses more complicated features of Golang. Finally, the [Expert](https://github.com/SimonWaldherr/golang-examples#expert) section contains applications like telnet-clients or http-server (even with SSL).
If you want even more Golang examples, you can take a look at my other go repositories at GitHub:

* [golang-benchmarks](https://github.com/SimonWaldherr/golang-benchmarks) shows how to benchmark the execution time of Golang functions
* [GolangSortingVisualization](https://github.com/SimonWaldherr/GolangSortingVisualization) visualizes various sorting algorithms on the terminal or as gif
* [golang-minigames](https://github.com/SimonWaldherr/golang-minigames) currently only contains a snake clone
* [bbmandelbrot.go](https://github.com/SimonWaldherr/bbmandelbrot.go) calculates a [Mandelbrot Fractal](https://en.wikipedia.org/wiki/Mandelbrot_set) and saves it as PNG
* [golibs](https://github.com/SimonWaldherr/golibs) contains various Go packages (e.g. math, converter, stack, cli, ...)
* [fsagent](https://github.com/SimonWaldherr/fsagent) watch a folder for new or modified files and do something
* [cgol.go](https://github.com/SimonWaldherr/cgol.go) is [Conway's](https://en.wikipedia.org/wiki/John_Horton_Conway) [Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life) in [Golang](https://en.wikipedia.org/wiki/Go_(programming_language))
* [micromarkdownGo](https://github.com/SimonWaldherr/micromarkdownGo) converts markdown to html (via regular expression)
* [wikiGo](https://github.com/SimonWaldherr/wikiGo) is a wiki software in Go
* [WorkingTimeMeasurementSystem](https://github.com/SimonWaldherr/WorkingTimeMeasurementSystem) demonstrates how to create a simple time tracking system using Golang and SQLite
* [zplgfa](https://github.com/SimonWaldherr/zplgfa) is an image converter to print pictures on zpl compatible labels
* [...](https://github.com/search?utf8=✓&q=user%3Asimonwaldherr&type=Repositories&ref=advsearch&l=Go)

All of them are published as free and open source software.

If all of this is even not enough for you, you can take a look at the following websites:

* [tour.golang.org](https://tour.golang.org/)
* [Go by example](https://gobyexample.com/)
* [Golang Book](http://www.golang-book.com/)
* [Go-Learn](https://github.com/skippednote/Go-Learn)

### Beginner

To execute a **Golang** program, write ```go run``` at the cli followed by the name of the file.  
You also can convert the file to a binary executable program by the command ```go build```.  
If you know ```#!```, also known as [Shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)), there is an equivalent for go: ```//usr/bin/env go run $0 $@ ; exit```  

Print Hello World with comments ([Golang Playground](https://play.golang.org/p/PiUVBrRB9AR))

```Shell
go run HelloWorld.go
```

Print Hello World with comments (shebang version)

```Shell
./HelloWorldShebang.go
```

Declare variables and print them ([Golang Playground](https://play.golang.org/p/O3_FWH2IQ75))

```Shell
go run var.go
```

Various ways (and styles) to print variables ([Golang Playground](https://play.golang.org/p/QH05DN_CeJU))

```Shell
go run printf.go
```

If statement in Golang ([Golang Playground](https://play.golang.org/p/rIpps0zUl1N))

```Shell
go run if.go Hello
```

Declare array and print its items ([Golang Playground](https://play.golang.org/p/jqseOd76Dqk))

```Shell
go run array.go
```

Declare your own functions ([Golang Playground](https://play.golang.org/p/9L0-F76gK0D))

```Shell
go run function.go
```

Do something multiple times ([Golang Playground](https://play.golang.org/p/5G3Ek89eKCH))

```Shell
go run for.go
```

Read via cli provided input data ([Golang Playground](https://play.golang.org/p/oUZ97D0Kg-_O))

```Shell
go run args.go string string2
```

Read via cli provided input data ([Golang Playground](https://play.golang.org/p/4IjMGLZBmue))

```Shell
go run input.go
```

Or scan for it ([Golang Playground](https://play.golang.org/p/rZ6clB9Z9Zu))

```Shell
go run scan.go
```

Read named argument input data ([Golang Playground](https://play.golang.org/p/i7BXecoK_wZ))

```Shell
go run flag.go
```

Return the *working directory* ([Golang Playground](https://play.golang.org/p/Ijx04bm8r8s))

```Shell
go run dir.go
```

Return the current time/date in various formats ([Golang Playground](https://play.golang.org/p/tPbn_CbHYYw))

```Shell
go run time.go
```

Return pseudo random integer values ([Golang Playground](https://play.golang.org/p/PapALcxQkpN))

```Shell
go run random.go
```

Concat strings in two different ways ([Golang Playground](https://play.golang.org/p/sBD_-peBzm5))

```Shell
go run cat.go
```

Modulo operation finds the remainder of division ([Golang Playground](https://play.golang.org/p/mYcueUHX1XL))

```Shell
go run modulo.go
```

Split a string by another string and make an array from the result ([Golang Playground](https://play.golang.org/p/VYP9tVMcbPW))

```Shell
go run split.go
```

An example implementation of the Ackermann function ([Golang Playground](https://play.golang.org/p/OjNgscvZhZT))

```Shell
go run ackermann.go
```

An example implementation of the Euclidean algorithm ([Golang Playground](https://play.golang.org/p/b1HWeUyk4Uf))

```Shell
go run euklid.go
```

Submit a function as argument ([Golang Playground](https://play.golang.org/p/fy0_S3J29_2))

```Shell
go run functioncallback.go
```

A function returned by a function ([Golang Playground](https://play.golang.org/p/earjKURMsPp))

```Shell
go run functionclosure.go
```

A function with an unknown amount of inputs (variadic function) ([Golang Playground](https://play.golang.org/p/s4Fvj8voh3Y))

```Shell
go run functionvariadic.go
```

Empty interface as argument (You Don't Know Type) ([Golang Playground](https://play.golang.org/p/D7OPshRATt_e))

```Shell
go run interface.go
```

Execute Shell/Bash commands and print its output values ([Golang Playground](https://play.golang.org/p/4Z-wLSkPJll))

```Shell
go run shell.go
```

Make structs (objects) which have functions ([Golang Playground](https://play.golang.org/p/t-082xlTu2t))

```Shell
go run oop.go
```

Dependency injection for easier testing

```Shell
cd beginner/di
go test
```

Hashing (md5, sha) in go ([Golang Playground](https://play.golang.org/p/fB2Y2MV7zt3))

```Shell
go run hashing.go
```

### Advanced

Benchmarking example (using JSON marshal and unmarshal for the sample) ([Golang Playground](https://play.golang.org/p/80Tcnkb301J)) 
From the root directory (`$GOPATH/github.com/SimonWaldherr/golang-examples`), run this command:

```Shell
go test -bench=. -benchmem advanced/json_bench/main_test.go
```

Make pipe-able unix applications with os.Stdin ([Golang Playground](https://play.golang.org/p/NqrUOfBmJtt))

```Shell
go run pipe.go
```

AES-GCM encryption example ([Golang Playground](https://play.golang.org/p/ujfs6s5JZ-P))

```Shell
go run aesgcm.go
```

Bcrypt hashing example ([Golang Playground](https://play.golang.org/p/9R7oS56Od6H)) 
Please install package golang.org/x/crypto/bcrypt before run this file by running `go get golang.org/x/crypto/bcrypt`

```Shell
go run bcrypt.go
```

Search element is exist in arrays or not ([Golang Playground](https://play.golang.org/p/1gVa9Jgk6vg))

```Shell
go run in_array.go
```

Calculate triangles ([Golang Playground](https://play.golang.org/p/l8ehuAWZitv))

```Shell
go run pythagoras.go (float|?) (float|?) (float|?)
```

Read from stdin (but don't wait for the enter key)

```Shell
go run getchar.go
```

Wait and sleep ([Golang Playground](https://play.golang.org/p/qGec1g7rTHC))

```Shell
go run wait.go
```

Last in - first out - example (Pop and push in Golang) ([Golang Playground](https://play.golang.org/p/TekltztwUfE))

```Shell
go run lifo.go
```

Split a string via regular expression and make an array from the result ([Golang Playground](https://play.golang.org/p/sWFDPMyF-wD))

```Shell
go run regex.go
```

More advanced regex (with time and dates) ([Golang Playground](https://play.golang.org/p/u1SdhFEwRch))

```Shell
go run regex2.go
```

Use my [golibs regex package](https://github.com/SimonWaldherr/golibs#regex-----) and have fun ([Golang Playground](https://play.golang.org/p/1RxtOxL0nQo))

```Shell
go run regex3.go
```

Calculate and print the fibonacci numbers ([Golang Playground](https://play.golang.org/p/BbjQ_ohw0m1))

```Shell
go run fibonacci.go
```

Calculate and print the requested (32th) prime number ([Golang Playground](https://play.golang.org/p/fB25PQlVWu4))

```Shell
go run prime.go 32
```

Do things with numbers, strings and switch-cases ([Golang Playground](https://play.golang.org/p/MvKDvR_wzlQ))

```Shell
go run numbers.go
```

Use a template to create and fill documents (this example uses [LaTeX](https://www.latex-project.org)) ([Golang Playground](https://play.golang.org/p/riy6SU21alH))

```Shell
go run template.go
pdflatex -interaction=nonstopmode template_latex.tex
```

Start a ticker (do things periodically) 

```Shell
go run ticker.go
```

Do something in case of a timeout ([Golang Playground](https://play.golang.org/p/Qtu62LaC3-q))

```Shell
go run timeout.go
```

Convert go object to json string ([Golang Playground](https://play.golang.org/p/s1onU7jpP91))

```Shell
go run json.go
```

Run unix/shell commands in go apps

```Shell
go run exec.go
```

Compress by pipe

```Shell
go run compress.go
```

Compress by file

```Shell
go run compress2.go
```

Parse CSV ([Golang Playground](https://play.golang.org/p/plVmXW8TB32))

```Shell
go run csv.go
```

Convert CSV to a Markdown table ([Golang Playground](https://play.golang.org/p/HTobb_U9JQt))

```Shell
go run csv2md.go
```

Parse a XML string into a Struct with undefined Fields ([Golang Playground](https://play.golang.org/p/6LuNPcaeagS))

```Shell
go run xml.go
```

Run a self killing app

```Shell
go run suicide.go
```

GoCV : hello video

```Shell
go run hello_video.go
```

GoCV : face detection

```Shell
go run face_detect.go 0 model/haarcascade_frontalface_default.xml
```

Run the example for generic ([Golang Playground](https://go.dev/play/p/586EEI0ZAEe))

```Shell
go run generic.go
```

### Expert

Calculate π with go (leibniz, euler and prime are running until you stop it via CTRL+C)

```Shell
go run pi2go.go leibniz
go run pi2go.go euler
go run pi2go.go prime
```

Calculate π with go - same as above - but with live output (based on [gcurses](https://godoc.org/github.com/SimonWaldherr/golibs/gcurses))

```Shell
go run pi2go-live.go leibniz
go run pi2go-live.go euler
go run pi2go-live.go prime
```


List files in working directory

```Shell
go run explorer.go
```

run assembly code from golang

```Shell
go run assembly.go
```

run C code from golang 

```Shell
go run cgo.go
```

generate Go code with golang templates

```Shell
go run codegen.go
```

Convert from rgb to hsl ([Golang Playground](https://play.golang.org/p/UuX27PhA0Zx))

```Shell
go run color.go
```

Telnet with Golang

```Shell
go run telnet.go
```

The smallest Golang http server

```Shell
go run httpd.go
```

Secure Golang http server

```Shell
go run httpsd.go
```

The smallest Golang http proxy

```Shell
go run proxy.go
```

Read and write cookies

```Shell
go run cookies.go
```

Demonstrate the power of multithreading / parallel computing
you have to set GOMAXPROCS to something greater than 1 to see any effect

```Shell
export GOMAXPROCS=8
time go run parallel.go true
time go run parallel.go false
```

A dynamic amount of channels

```go
time go run dynparallel.go 8
```

Run the compiler and comment each line which contains an error

```Shell
go build gocomment.go
./gocomment go-app.go
```

Convert a image to a grayscale and to a color inverted image

```Shell
go run image.go
```

Generate an image with three colored circles (with intersection)

```Shell
go run image2.go
```

Generate an image representing the Mandelbrot fractal

```Shell
go run image3.go
```

Sql (sqlite) Golang example  
maybe you also wanna take a look at my [sql-examples](https://github.com/SimonWaldherr/sql-examples)-project

```Shell
go run sqlite.go insert test
go run sqlite.go select
```

Public-key/asymmetric cryptography signing and validating

```Shell
go run ppk-crypto.go
```

Command Line Arguments Golang Example
We can get argument values though command line by specifying the operator '-' with the name of the argument and the value to be set. E.g. -env=qa

```Shell
go run command_line_arguments.go
go run command_line_arguments.go -env=qa -consumer=true
```

Cron Golang Example
We can trigger a function at a particular time through cron 

```Shell
go run cron.go
```

Map Golang Example
Hash Map standard functions in golang 

```Shell
go run map.go
```

### TinyGo

You can even use Go on microcontrollers, the keyword here is [TinyGo](https://tinygo.org/), a go compiler specially developed for SBCs and MCUs.  
If you want to blink the LED of your Raspberry Pi Pico, try this: 

```Shell
tinygo build -o firmware.uf2 -target=pico ./tinygo/blink.go
```

and then upload it to the pico.

## Compile

One great aspect of Golang is, that you can start go applications via ```go run name.go```, but also compile it to an executable with ```go build name.go```. After that you can start the compiled version which starts much faster.
If you start fibonacci.go and the compiled version you will notice, that the last line which contains the execution time doesn't differ much, but if you start it with ```time ./fibonacci 32``` and ```time go run ./fibonacci.go 32``` you will see the difference.

## License

Copyright © 2024 Simon Waldherr
Dual-licensed. See the [LICENSE](https://github.com/SimonWaldherr/golang-examples/blob/master/LICENSE) file for details.


golang-examples

Learn Go with thousands of examples, exercises, and quizzes.

# Get my book!

Go by Example: Programmer's guide to idiomatic and testable code.

👉 https://github.com/inancgumus/gobyexample

_This book is what you need once you wrap up the exercises in this repository._

[![gobyexamplecover](https://github.com/inancgumus/learngo/assets/621232/14dd4bff-f6e1-489f-9aa5-1452b8219a11)](https://github.com/inancgumus/gobyexample)

---

# A Huge Number of Go Examples, Exercises and Quizzes

Best way of learning is doing. Inside this repository, you will find thousands of Go examples, exercises and quizzes. I initially created this repository for my **[Go: Bootcamp Course](https://www.udemy.com/course/learn-go-the-complete-bootcamp-course-golang/?referralCode=5CE6EB34E2B1EF4A7D37)**. Later on, I added a lot of exercises, and I wanted every programmer who is not yet enrolled in the course to learn for free as well. So here it is. Enjoy.

**Available in the following languages:**
* **[English](https://github.com/inancgumus/learngo)**
* **[Spanish](translation/spanish)** _(WIP: Please Contribute)_
* **[Chinese](translation/chinese)** _(WIP: Please Contribute)_

## ❤️ Help other fellow developers

Sharing is free but caring is priceless. [So, now please click here](https://twitter.com/intent/tweet?text=I%27m%20learning%20%23golang%20with%201000%2B%20hand-crafted%20examples%2C%20exercises%2C%20and%20quizzes.&url=https://github.com/inancgumus/learngo&via=inancgumus) and share this repository on Twitter.

## Stay in touch

* **[Follow me on Twitter](https://twitter.com/inancgumus)**

 _I usually tweet Go tips and tricks._

 [![@inancgumus](https://img.shields.io/twitter/follow/inancgumus.svg?style=social&label=@inancgumus)](https://twitter.com/inancgumus)

* **[Subscribe to my newsletter](https://eepurl.com/c4DMNX)**

 _Get updates from me._

* **[Read my blog](https://blog.learngoprogramming.com)**

 _Followed by 5K+ developers, and contains dozens of illustrated articles about Go._

* **[Watch my Youtube channel](https://www.youtube.com/channel/UCYxepZhtnFIVRh8t5H_QAdg?view_as=subscriber)**

---

## License
Whole materials are licensed under the <a rel="license" href="https://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>. 
<a rel="license" href="https://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png"/></a>

Learn Go with 1000+ Exercises

# Learn Go with Tests


 <img src="red-green-blue-gophers-smaller.png" />


[Art by Denise](https://twitter.com/deniseyu21)

[![Go Report Card](https://goreportcard.com/badge/github.com/quii/learn-go-with-tests)](https://goreportcard.com/report/github.com/quii/learn-go-with-tests)

## Formats

- [Gitbook](https://quii.gitbook.io/learn-go-with-tests)
- [EPUB or PDF](https://github.com/quii/learn-go-with-tests/releases)

## Translations

- [中文](https://studygolang.gitbook.io/learn-go-with-tests)
- [Português](https://larien.gitbook.io/aprenda-go-com-testes/)
- [日本語](https://andmorefine.gitbook.io/learn-go-with-tests/)
- [한국어](https://miryang.gitbook.io/learn-go-with-tests/)
- [Türkçe](https://halilkocaoz.gitbook.io/go-programlama-dilini-ogren/)
- [فارسی](https://go-yaad-begir.gitbook.io/go-ba-test/)

## Support me

I am proud to offer this resource for free, but if you wish to give some appreciation:

- [Tweet me @quii](https://twitter.com/quii)
- <a rel="me" href="https://mastodon.cloud/@quii">Mastodon</a>
- [Buy me a coffee :coffee:](https://www.buymeacoffee.com/quii)
- [Sponsor me on GitHub](https://github.com/sponsors/quii)

## Why

* Explore the Go language by writing tests
* **Get a grounding with TDD**. Go is a good language for learning TDD because it is a simple language to learn and testing is built-in
* Be confident that you'll be able to start writing robust, well-tested systems in Go
* [Watch a video, or read about why unit testing and TDD is important](why.md)

## Table of contents

### Go fundamentals

1. [Install Go](install-go.md) - Set up environment for productivity.
2. [Hello, world](hello-world.md) - Declaring variables, constants, if/else statements, switch, write your first go program and write your first test. Sub-test syntax and closures.
3. [Integers](integers.md) - Further Explore function declaration syntax and learn new ways to improve the documentation of your code.
4. [Iteration](iteration.md) - Learn about `for` and benchmarking.
5. [Arrays and slices](arrays-and-slices.md) - Learn about arrays, slices, `len`, varargs, `range` and test coverage.
6. [Structs, methods & interfaces](structs-methods-and-interfaces.md) - Learn about `struct`, methods, `interface` and table driven tests.
7. [Pointers & errors](pointers-and-errors.md) - Learn about pointers and errors.
8. [Maps](maps.md) - Learn about storing values in the map data structure.
9. [Dependency Injection](dependency-injection.md) - Learn about dependency injection, how it relates to using interfaces and a primer on io.
10. [Mocking](mocking.md) - Take some existing untested code and use DI with mocking to test it.
11. [Concurrency](concurrency.md) - Learn how to write concurrent code to make your software faster.
12. [Select](select.md) - Learn how to synchronise asynchronous processes elegantly.
13. [Reflection](reflection.md) - Learn about reflection
14. [Sync](sync.md) - Learn some functionality from the sync package including `WaitGroup` and `Mutex`
15. [Context](context.md) - Use the context package to manage and cancel long-running processes
16. [Intro to property based tests](roman-numerals.md) - Practice some TDD with the Roman Numerals kata and get a brief intro to property based tests
17. [Maths](math.md) - Use the `math` package to draw an SVG clock
18. [Reading files](reading-files.md) - Read files and process them
19. [Templating](html-templates.md) - Use Go's html/template package to render html from data, and also learn about approval testing
20. [Generics](generics.md) - Learn how to write functions that take generic arguments and make your own generic data-structure
21. [Revisiting arrays and slices with generics](revisiting-arrays-and-slices-with-generics.md) - Generics are very useful when working with collections. Learn how to write your own `Reduce` function and tidy up some common patterns.

### Build an application

Now that you have hopefully digested the _Go Fundamentals_ section you have a solid grounding of a majority of Go's language features and how to do TDD.

This next section will involve building an application.

Each chapter will iterate on the previous one, expanding the application's functionality as our product owner dictates.

New concepts will be introduced to help facilitate writing great code but most of the new material will be learning what can be accomplished from Go's standard library.

By the end of this, you should have a strong grasp as to how to iteratively write an application in Go, backed by tests.

* [HTTP server](http-server.md) - We will create an application which listens to HTTP requests and responds to them.
* [JSON, routing and embedding](json.md) - We will make our endpoints return JSON and explore how to do routing.
* [IO and sorting](io.md) - We will persist and read our data from disk and we'll cover sorting data.
* [Command line & project structure](command-line.md) - Support multiple applications from one code base and read input from command line.
* [Time](time.md) - using the `time` package to schedule activities.
* [WebSockets](websockets.md) - learn how to write and test a server that uses WebSockets.

### Testing fundamentals

Covering other subjects around testing.

* [Introduction to acceptance tests](intro-to-acceptance-tests.md) - Learn how to write acceptance tests for your code, with a real-world example for gracefully shutting down a HTTP server
* [Scaling acceptance tests](scaling-acceptance-tests.md) - Learn techniques to manage the complexity of writing acceptance tests for non-trivial systems.
* [Working without mocks, stubs and spies](working-without-mocks.md) - Learn about how to use fakes and contracts to create more realistic and maintainable tests.
* [Refactoring Checklist](refactoring-checklist.md) - Some discussion on what refactoring is, and some basic tips on how to do it.

### Questions and answers

I often run in to questions on the internets like

> How do I test my amazing function that does x, y and z

If you have such a question raise it as an issue on github and I'll try and find time to write a short chapter to tackle the issue. I feel like content like this is valuable as it is tackling people's _real_ questions around testing.

* [OS exec](os-exec.md) - An example of how we can reach out to the OS to execute commands to fetch data and keep our business logic testable/
* [Error types](error-types.md) - Example of creating your own error types to improve your tests and make your code easier to work with.
* [Context-aware Reader](context-aware-reader.md) - Learn how to TDD augmenting `io.Reader` with cancellation. Based on [Context-aware io.Reader for Go](https://pace.dev/blog/2020/02/03/context-aware-ioreader-for-golang-by-mat-ryer)
* [Revisiting HTTP Handlers](http-handlers-revisited.md) - Testing HTTP handlers seems to be the bane of many a developer's existence. This chapter explores the issues around designing handlers correctly.

### Meta / Discussion

* [Why unit tests and how to make them work for you](why.md) - Watch a video, or read about why unit testing and TDD is important
* [Anti-patterns](anti-patterns.md) - A short chapter on TDD and unit testing anti-patterns

## Contributing

* _This project is work in progress_ If you would like to contribute, please do get in touch.
* Read [contributing.md](https://github.com/quii/learn-go-with-tests/tree/842f4f24d1f1c20ba3bb23cbc376c7ca6f7ca79a/contributing.md) for guidelines
* Any ideas? Create an issue

## Background

I have some experience introducing Go to development teams and have tried different approaches as to how to grow a team from some people curious about Go into highly effective writers of Go systems.

### What didn't work

#### Read _the_ book

An approach we tried was to take [the blue book](https://www.amazon.co.uk/Programming-Language-Addison-Wesley-Professional-Computing/dp/0134190440) and every week discuss the next chapter along with the exercises.

I love this book but it requires a high level of commitment. The book is very detailed in explaining concepts, which is obviously great but it means that the progress is slow and steady - this is not for everyone.

I found that whilst a small number of people would read chapter X and do the exercises, many people didn't.

#### Solve some problems

Katas are fun but they are usually limited in their scope for learning a language; you're unlikely to use goroutines to solve a kata.

Another problem is when you have varying levels of enthusiasm. Some people just learn way more of the language than others and when demonstrating what they have done end up confusing people with features the others are not familiar with.

This ends up making the learning feel quite _unstructured_ and _ad hoc_.

### What did work

By far the most effective way was by slowly introducing the fundamentals of the language by reading through [go by example](https://gobyexample.com/), exploring them with examples and discussing them as a group. This was a more interactive approach than "read chapter x for homework".

Over time the team gained a solid foundation of the _grammar_ of the language so we could then start to build systems.

This to me seems analogous to practicing scales when trying to learn guitar.

It doesn't matter how artistic you think you are, you are unlikely to write good music without understanding the fundamentals and practicing the mechanics.

### What works for me

When _I_ learn a new programming language I usually start by messing around in a REPL but eventually, I need more structure.

What I like to do is explore concepts and then solidify the ideas with tests. Tests verify the code I write is correct and documents the feature I have learned.

Taking my experience of learning with a group and my own personal way I am going to try and create something that hopefully proves useful to other teams. Learning the fundamentals by writing small tests so that you can then take your existing software design skills and ship some great systems.

## Who this is for

* People who are interested in picking up Go.
* People who already know some Go, but want to explore testing with TDD.

## What you'll need

* A computer!
* [Installed Go](https://golang.org/)
* A text editor
* Some experience with programming. Understanding of concepts like `if`, variables, functions etc.
* Comfortable using the terminal

## Feedback

* Add issues/submit PRs [here](https://github.com/quii/learn-go-with-tests) or [tweet me @quii](https://twitter.com/quii)

[MIT license](LICENSE.md)

[Logo is by egonelbre](https://github.com/egonelbre) What a star!

Learn Go with TDD

# Working with Go

## View online at: https://mkaz.blog/working-with-go/

Working with Go is a set of examples for Go (golang) to help an experienced programmer become familiar with the Go language. Go is often referred to as golang to help searches.


## Resources

This set of examples assumes a base level of programming experience and is intended for someone learning the Go language from another language; not necessarily someone new to programming altogether.

If you are starting out and want to learn how to program and choose Go as your first language, check out [Learn Programming in Go](http://www.golang-book.com/)

The official site has a [Tour of Go](http://tour.golang.org/) which is an interactive walk through, another good introduction to the language.

I'm also a big fan of [Go by Example](https://gobyexample.com/) which is quite similar.


## Contribute

The site is sourced from markdown files in the `pages` directory. Any additions, corrections, suggestions or any contributions are appreciated.

To submit a pull request, make your edit to the file in `pages` directory.

Working with Go was started by Marcus Kazmierczak. Thanks to <a href="https://github.com/mkaz/working-with-go/graphs/contributors">all the contributors</a> who have helped make it even better.


## License

Working with Go is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.

The Best Go Libraries For Websites - Other (20)