Allows users to spin up a quick Go project using a popular framework

![logo](./public/logo.png)

<div style="text-align: center;">
  <h1>
    Introducing the Ultimate Golang Blueprint Library
  </h1>
</div>

Go Blueprint is a CLI tool that allows users to spin up a Go project with the corresponding structure seamlessly. It also
gives the option to integrate with one of the more popular Go frameworks (and the list is growing with new features)!

### Why Would I use this?

- Easy to set up and install
- Have the entire Go structure already established
- Setting up a Go HTTP server (or Fasthttp with Fiber)
- Integrate with a popular frameworks
- Focus on the actual code of your application

## Table of Contents

- [Install](#install)
- [Frameworks Supported](#frameworks-supported)
- [Database Support](#database-support)
- [Advanced Features](#advanced-features)
- [Blueprint UI](#blueprint-ui)
- [Usage Example](#usage-example)
- [GitHub Stats](#github-stats)
- [License](#license)

<a id="install"></a>

<h2>
  <picture>
    <img src="./public/install.gif?raw=true" width="60px" style="margin-right: 1px;">
  </picture>
  Install
</h2>

### Go Install
```bash
go install github.com/melkeydev/go-blueprint@latest
```

This installs a go binary that will automatically bind to your $GOPATH

> if you’re using Zsh, you’ll need to add it manually to `~/.zshrc`.

```bash
GOPATH=$HOME/go  PATH=$PATH:/usr/local/go/bin:$GOPATH/bin
```

don't forget to update

```bash
source ~/.zshrc
```

### NPM Install
```bash
npm install -g @melkeydev/go-blueprint
```

### Homebrew Install
```bash
brew install go-blueprint
```

Then in a new terminal run:

```bash
go-blueprint create
```

You can also use the provided flags to set up a project without interacting with the UI.

```bash
go-blueprint create --name my-project --framework gin --driver postgres --git commit
```

See `go-blueprint create -h` for all the options and shorthands.

<a id="frameworks-supported"></a>

<h2>
  <picture>
    <img src="./public/frameworks.gif?raw=true" width="60px" style="margin-right: 1px;">
  </picture>
  Frameworks Supported
</h2>

- [Chi](https://github.com/go-chi/chi)
- [Gin](https://github.com/gin-gonic/gin)
- [Fiber](https://github.com/gofiber/fiber)
- [HttpRouter](https://github.com/julienschmidt/httprouter)
- [Gorilla/mux](https://github.com/gorilla/mux)
- [Echo](https://github.com/labstack/echo)

<a id="database-support"></a>

<h2>
  <picture>
    <img src="./public/database.gif?raw=true" width="45px" style="margin-right: 15px;">
  </picture>
  Database Support
</h2>

Go Blueprint now offers enhanced database support, allowing you to choose your preferred database driver during project setup. Use the `--driver` or `-d` flag to specify the database driver you want to integrate into your project.

### Supported Database Drivers

Choose from a variety of supported database drivers:

- [Mysql](https://github.com/go-sql-driver/mysql)
- [Postgres](https://github.com/jackc/pgx/)
- [Sqlite](https://github.com/mattn/go-sqlite3)
- [Mongo](https://go.mongodb.org/mongo-driver)
- [Redis](https://github.com/redis/go-redis)
- [ScyllaDB GoCQL](https://github.com/scylladb/gocql)

<a id="advanced-features"></a>

<h2>
  <picture>
    <img src="./public/advanced.gif?raw=true" width="70px" style="margin-right: 1px;">
  </picture>
  Advanced Features
</h2>

Blueprint is focused on being as minimalistic as possible. That being said, we wanted to offer the ability to add other features people may want without bloating the overall experience.

You can now use the `--advanced` flag when running the `create` command to get access to the following features. This is a multi-option prompt; one or more features can be used at the same time:

- [HTMX](https://htmx.org/) support using [Templ](https://templ.guide/)
- CI/CD workflow setup using [Github Actions](https://docs.github.com/en/actions)
- [Websocket](https://pkg.go.dev/github.com/coder/websocket) sets up a websocket endpoint
- [Tailwind](https://tailwindcss.com/) css framework
- Docker configuration for go project
- [React](https://react.dev/) frontend written in TypeScript, including an example fetch request to the backend

Note: Selecting Tailwind option will automatically select HTMX unless React is explicitly selected

<a id="blueprint-ui"></a>

<h2>
  <picture>
    <img src="./public/ui.gif?raw=true" width="100px" style="margin-right: 1px;">
  </picture>
  Blueprint UI
</h2>

Blueprint UI is a web application that allows you to create commands for the CLI and preview the structure of your project. You will be able to see directories and files that will be created upon command execution. Check it out at [go-blueprint.dev](https://go-blueprint.dev)

<a id="usage-example"></a>

<h2>
  <picture>
    <img src="./public/example.gif?raw=true" width="60px" style="margin-right: 1px;">
  </picture>
  Usage Example
</h2>

Here's an example of setting up a project with a specific database driver:

```bash
go-blueprint create --name my-project --framework gin --driver postgres --git commit
```

<p align="center">
  <img src="./public/blueprint_1.png" alt="Starter Image" width="800"/>
</p>

Advanced features are accessible with the --advanced flag

```bash
go-blueprint create --advanced
```

Advanced features can be enabled using the `--feature` flag along with the `--advanced` flag.

HTMX:

```bash
go-blueprint create --advanced --feature htmx
```

CI/CD workflow:

```bash
go-blueprint create --advanced --feature githubaction
```

Websocket:

```bash
go-blueprint create --advanced --feature websocket
```

Tailwind:

```bash
go-blueprint create --advanced --feature tailwind
```

Docker:

```bash
go-blueprint create --advanced --feature docker
```

React:

```bash
go-blueprint create --advanced --feature react
```

Or all features at once:

```bash
go-blueprint create --name my-project --framework chi --driver mysql --advanced --feature htmx --feature githubaction --feature websocket --feature tailwind --feature docker --git commit --feature react
```

<p align="center">
  <img src="./public/blueprint_advanced.png" alt="Advanced Options" width="800"/>
</p>

**Visit [documentation](https://docs.go-blueprint.dev) to learn more about blueprint and its features.**

<a id="github-stats"></a>

<h2>
  <picture>
    <img src="./public/stats.gif?raw=true" width="45px" style="margin-right: 10px;">
  </picture>
  GitHub Stats
</h2>

<p align="center">
  <img alt="Alt" src="https://repobeats.axiom.co/api/embed/7c4be18864d441f961be61186ce49b5471a9e7bf.svg" title="Repobeats analytics image"/>
</p>

<a id="license"></a>

<h2>
  <picture>
    <img src="./public/license.gif?raw=true" width="50px" style="margin-right: 1px;">
  </picture>
  License
</h2>

Licensed under [MIT License](./LICENSE)


go-blueprint

Template for a typical module written on Go

[![Go Module][social.preview]][preview.config]

[![Coverage][coverage.icon]][coverage.page]
[![Quality][quality.icon]][quality.page]
[![Documentation][docs.icon]][docs.page]
[![CI/CD][build.icon]][build.page]
[![Promo][site.icon]][site.page]
[![Mirror][mirror.icon]][mirror.page]
[![Template][template.icon]][template.page]

# 🧩 Module [![awesome.icon]][awesome.page]

Template for a typical module written on Go.

## 🛫 Quick start

<details>
  <summary>Work with Makefile</summary>

```bash
$ make setup
$ make help

$ make find-todos
$ make test lint
$ TIMEOUT=5s make test-with-coverage
```

For more details please visit [the page](https://makefiles.octolab.org/).

</details>
<details>
  <summary>Work with Taskfile</summary>

```bash
$ alias run=./Taskfile
$ run refresh
$ run help

$ run docs # === `run docs install -- build -- start`
$ run docs npm ci
$ run docs npm i nextra@latest

$ run tools go generate tools.go
$ run tools golangci-lint --version -- mockgen --version
$ run which goimports golangci-lint govulncheck mockgen
```

For more details please visit [the page](https://taskfiles.octolab.org/).

</details>
<details>
  <summary>Work with tools</summary>

```bash
$ make tools
$ source bin/activate

$ which goimports
$ goimports -local $(go list -m) -w ./...
```

For more details please visit [the page](https://egg.octolab.org/).

</details>
<details>
  <summary>Work with Docker</summary>

```bash
$ make go-1.11 # or go-1.12, etc.
/src# make go-env 2>/dev/null | grep GOVERSION
# GOVERSION:   1.11.13
/src# make test
```

</details>
<details>
  <summary>🚧 Work with documentation</summary>

- https://go-module.octolab.org/ - [GitHub Pages](https://pages.github.com/)
- https://go-module.pages.dev/ - [Cloudflare Pages](https://pages.cloudflare.com/)

</details>

## 💡 Idea

Define a powerful template that quickly creates a new Go module.
Not only does it provide a starting point for new projects,
but it comes equipped with pre-configured ci/cd and inventory.

## 🏆 Motivation

At [OctoLab][octolab.site], we want to start new projects faster using best practices
with a predefined structure and focusing on core ideas implementation
rather than wasting time on environment configuration and copying boilerplate code.

## 🤼‍ How to

### Build your own module

1. [Generate][action.generate] a new repository from the template.
2. Clone the repository locally.
3. Update the desired files as needed, e.g., `run init my.new/module`.
4. Write your code and tests.
5. 🚀

### Contribute to the template

1. Read the [contribution guidelines][docs.contrib].
2. [Fork][action.fork] the repository.
3. Make your changes.
4. Send a pull request.
5. 🤗

Before you start, please make sure your changes are in demand.
The best for that is to create [a new discussion][action.discuss],
or if you find an issue, [report it][action.issue] first.

[action.discuss]:   https://github.com/octomation/go-module/discussions/new/choose
[action.fork]:      https://github.com/octomation/go-module/fork
[action.generate]:  https://github.com/octomation/go-module/generate
[action.issue]:     https://github.com/octomation/go-module/issues/new/choose
[docs.contrib]:     https://github.com/octomation/.github/blob/main/.github/CONTRIBUTING.md
[octolab.site]:     https://github.com/octolab

## 🎛️ Configuration

### Pre-configured

1. [GitHub Actions](https://github.com/features/actions).
2. [GitHub Pages](https://pages.github.com).
3. [Dependabot](https://github.com/dependabot).

### Included

1. [Nextra](https://nextra.site/).
2. [Makefiles](https://makefiles.octolab.org/).
3. [Taskfiles](https://taskfiles.octolab.org/).
4. [Go tools][egg]: [mockgen][], [golangci-lint][],
[goimports][], [govulncheck][].

[egg]:              https://egg.octolab.org/
[mockgen]:          https://github.com/golang/mock
[govulncheck]:      https://github.com/golang/vuln
[goimports]:        https://goimports.octolab.org/
[golangci-lint]:    https://golangci-lint.octolab.org/

### Optional

1. [Bitbucket](https://bitbucket.org/)[^1].
2. [Cloudflare Pages](https://pages.cloudflare.com/)[^2].
3. [Codecov](https://about.codecov.io/).
4. [GitHub Socialify](https://socialify.git.ci/).
5. [Go Report Card](https://goreportcard.com/).
6. [Settings](https://github.com/apps/settings)[^3].
7. [Shields.io](https://shields.io/).
8. [Slack](https://github.com/marketplace/slack-github).
9. [Vanity URL](https://vanity.octolab.org/).

[^1]: An alternative for backup could be [GitLab](https://about.gitlab.com/),
[Gogs](https://gogs.io/), or [Gitea](https://gitea.io/).

[^2]: Useful for private repositories.

[^3]: It has been deprecated and will be replaced someday by
[GitHub Actions](https://github.com/octomation/go-module/issues/56).

### Coming soon

1. [CodeQL](https://codeql.github.com/) (code scanning).
2. [Graphite](https://graphite.dev/) (git workflow).
3. [Qodana](https://qodana.cloud/) (code quality).
4. [SonarCloud](https://sonarcloud.io/) (code quality).
5. [Vercel](https://vercel.com/) (docs preview).

## 🛬 Integration

The project uses [SemVer](https://semver.org/) for versioning, and it is not
[BC][wiki.compat]-safe through major releases.
Please use [Go Modules][wiki.gomod] to manage its version.

```bash
$ go get go.octolab.org@latest
```

[wiki.compat]:  https://en.wikipedia.org/wiki/Backward_compatibility
[wiki.gomod]:   https://github.com/golang/go/wiki/Modules

## 🏗️ Ecosystem

### Input

- https://github.com/kamilsk/retry
- https://github.com/kamilsk/semaphore
- https://github.com/kamilsk/tracer
- https://github.com/octolab/breaker

### Impact

- https://github.com/octomation/go-tool
- https://github.com/octomation/maintainer
- https://github.com/octomation/makefiles
- https://github.com/octomation/taskfiles
- https://github.com/octomation/vanity

### Output

- https://github.com/octolab/cli*
- https://github.com/octolab/config
- https://github.com/octolab/pkg*
- https://github.com/octolab/propaganda
- https://github.com/octolab/protocol*

<p align="right">made with ❤️ for everyone by <a href="https://www.octolab.org/">OctoLab</a></p>

[social.preview]:   https://cdn.octolab.org/repo/go-module.png
[preview.config]:   https://socialify.git.ci/octomation/go-module?description=1&font=Raleway&language=1&name=1&owner=1&pattern=Circuit%20Board&theme=Light
[preview.fallback]: https://socialify.git.ci/octomation/go-module/image?description=1&font=Raleway&language=1&name=1&owner=1&pattern=Circuit%20Board&theme=Light

[awesome.icon]:     https://awesome.re/mentioned-badge.svg
[awesome.page]:     https://awesome-go.com/project-layout/
[coverage.icon]:    https://codecov.io/gh/octomation/go-module/branch/main/graph/badge.svg
[coverage.page]:    https://codecov.io/gh/octomation/go-module
[quality.icon]:     https://goreportcard.com/badge/go.octolab.org/template/module
[quality.page]:     https://goreportcard.com/report/go.octolab.org/template/module
[docs.icon]:        https://pkg.go.dev/badge/go.octolab.org/template/module.svg
[docs.page]:        https://pkg.go.dev/go.octolab.org/template/module
[build.icon]:       https://img.shields.io/badge/ci%2Fcd-GitHub%20Actions-brightgreen
[build.page]:       https://github.com/octomation/go-module/actions
[site.icon]:        https://img.shields.io/badge/site-GitHub%20Pages-brightgreen
[site.page]:        https://go-module.octolab.org/
[mirror.icon]:      https://img.shields.io/badge/mirror-Bitbucket-blue
[mirror.page]:      https://bitbucket.org/kamilsk/go-module
[template.icon]:    https://img.shields.io/badge/template-go--module-blue
[template.page]:    https://github.com/octomation/go-module


go-module

An opinionated production-ready RESTful JSON backend template, highly integrated with VSCode DevContainers

# project-readme

This is the README for the project created based on the **go-starter**. For the README of the go-starter checkout [README-go-starter.md](README-go-starter.md)

go-starter

Go Todo Backend example using modular project layout for product microservice

# go-todo-backend

[![GoDoc](https://godoc.org/github.com/Fs02/go-todo-backend?status.svg)](https://godoc.org/github.com/Fs02/go-todo-backend)
[![Build Status](https://travis-ci.com/Fs02/go-todo-backend.svg?branch=master)](https://travis-ci.com/Fs02/go-todo-backend)
[![Go Report Card](https://goreportcard.com/badge/github.com/Fs02/go-todo-backend)](https://goreportcard.com/report/github.com/Fs02/go-todo-backend)
[![Maintainability](https://api.codeclimate.com/v1/badges/d506b5b2df687cbcd358/maintainability)](https://codeclimate.com/github/Fs02/go-todo-backend/maintainability)
[![Test Coverage](https://api.codeclimate.com/v1/badges/d506b5b2df687cbcd358/test_coverage)](https://codeclimate.com/github/Fs02/go-todo-backend/test_coverage)

Go Todo Backend Example Using Modular Project Layout for Product Microservice. It's suitable as starting point for a medium to larger project.

This example uses [Chi](https://github.com/go-chi/chi) for http router and [REL](https://github.com/go-rel/rel) for database access.

Feature:

- Modular Project Structure.
- Full example including tests.
- Docker deployment.
- Compatible with [todobackend](https://www.todobackend.com/specs/index.html).

## Installation

### Prerequisite

1. Install [mockery](https://github.com/vektra/mockery#installation) for interface mock generation.
2. Install [rel cli](https://go-rel.github.io/migration/#running-migration) for database migration.

### Running

1. Prepare `.env`.
    ```
    cp .env.sample .env
    ```
2. Start postgresql and create database.
    ```
    docker-compose up -d
    ```
2. Prepare database schema.
    ```
    rel migrate
    ```
3. Build and Running
    ```
    make
    ```

## Project Structure

```
.
├── api
│   ├── handler
│   │   ├── todos.go
│   │   └── [other handler].go
│   └── middleware
│       └── [other middleware].go
├── bin
│   ├── api
│   └── [other executable]
├── cmd
│   ├── api
│   │   └── main.go
│   └── [other cmd]
│       └── main.go
├── db
│   ├── schema.sql
│   └── migrations
│       └── [migration file]
├── todos
│   ├── todo.go
│   ├── create.go
│   ├── update.go
│   ├── delete.go
│   ├── service.go
│   └── todostest
│       ├── todo.go
│       └── service.go
├── [other domain]
│   ├── [entity a].go
│   ├── [business logic].go
│   ├── [other domain]test
│   │   └── service.go
│   └── service.go
└── [other client]
    ├── [entity b].go
    ├── client.go
    └── [other client]test
        └── client.go
```

This project structure is based on a modular project structure, with loosely coupled dependencies between domain, Think of making libraries under a single repo that only exports certain functionality that used by other service and http handler. One of domain that present in this example is todos.

Loosely coupled dependency between domain is enforced by avoiding the use of shared entity package, therefore any entity struct should be included inside it's own respective domain. This will prevent cyclic dependency between entity. This shouldn't be a problem in most cases, becasause if you encounter cyclic dependency, there's huge chance that the entity should belongs to the same domain.

For example, consider three structs: user, transaction and transaction items. transaction and its transaction items might need cyclic dependency and items doesn't works standalone (items without transaction should not exists), thus it should be on the same domain.
In the other hand, user and transaction shouldn't require cyclic dependency, transaction might have a user field in the struct, but user shouldn't have a slice of transaction field, therefore it should be on a separate domain.

### Domain vs Client

Domain and Client folder is very similar, the difference is client folder doesn't actually implement any business logic (service), but instead a client that calls any internal/external API to works with the domain entity.


go-todo-backend

Set of common historical and emerging project layout patterns in the Go ecosystem. Note: despite the org-name they do not represent official golang standards, see [this issue](https://github.com/golang-standards/project-layout/issues/117) for more information. Nonetheless, some may find the layout useful

# Standard Go Project Layout

Translations:

* [한국어 문서](README_ko.md)
* [简体中文](README_zh.md)
* [正體中文](README_zh-TW.md)
* [简体中文](README_zh-CN.md) - ???
* [Français](README_fr.md)
* [日本語](README_ja.md)
* [Português](README_ptBR.md)
* [Español](README_es.md)
* [Română](README_ro.md)
* [Русский](README_ru.md)
* [Türkçe](README_tr.md)
* [Italiano](README_it.md)
* [Tiếng Việt](README_vi.md)
* [Українська](README_ua.md)
* [Indonesian](README_id.md)
* [हिन्दी](README_hi.md)
* [فارسی](README_fa.md)
* [Беларуская](README_be.md)
* [বাংলা](README_bn.md)

## Overview

This is a basic layout for Go application projects. Note that it's basic in terms of content because it's focusing only on the general layout and not what you have inside. It's also basic because it's very high level and it doesn't go into great details in terms of how you can structure your project even further. For example, it doesn't try to cover the project structure you'd have with something like Clean Architecture.

This is **`NOT an official standard defined by the core Go dev team`**. This is a set of common historical and emerging project layout patterns in the Go ecosystem. Some of these patterns are more popular than others. It also has a number of small enhancements along with several supporting directories common to any large enough real world application. Note that the **core Go team provides a great set of general guidelines about structuring Go projects** and what it means for your project when it's imported and when it's installed. See the [`Organizing a Go module`](https://go.dev/doc/modules/layout) page in the official Go docs for more details. It includes the `internal` and `cmd` directory patterns (described below) and other useful information.

**`If you are trying to learn Go or if you are building a PoC or a simple project for yourself this project layout is an overkill. Start with something really simple instead (a single `main.go` file and `go.mod` is more than enough).`** As your project grows keep in mind that it'll be important to make sure your code is well structured otherwise you'll end up with a messy code with lots of hidden dependencies and global state. When you have more people working on the project you'll need even more structure. That's when it's important to introduce a common way to manage packages/libraries. When you have an open source project or when you know other projects import the code from your project repository that's when it's important to have private (aka `internal`) packages and code. Clone the repository, keep what you need and delete everything else! Just because it's there it doesn't mean you have to use it all. None of these patterns are used in every single project. Even the `vendor` pattern is not universal.

With Go 1.14 [`Go Modules`](https://go.dev/wiki/Modules) are finally ready for production. Use [`Go Modules`](https://blog.golang.org/using-go-modules) unless you have a specific reason not to use them and if you do then you don’t need to worry about $GOPATH and where you put your project. The basic `go.mod` file in the repo assumes your project is hosted on GitHub, but it's not a requirement. The module path can be anything though the first module path component should have a dot in its name (the current version of Go doesn't enforce it anymore, but if you are using slightly older versions don't be surprised if your builds fail without it). See Issues [`37554`](https://github.com/golang/go/issues/37554) and [`32819`](https://github.com/golang/go/issues/32819) if you want to know more about it.

This project layout is intentionally generic and it doesn't try to impose a specific Go package structure.

This is a community effort. Open an issue if you see a new pattern or if you think one of the existing patterns needs to be updated.

If you need help with naming, formatting and style start by running [`gofmt`](https://golang.org/cmd/gofmt/) and [`staticcheck`](https://github.com/dominikh/go-tools/tree/master/cmd/staticcheck). The previous standard linter, golint, is now deprecated and not maintained; use of a maintained linter such as staticcheck is recommended. Also make sure to read these Go code style guidelines and recommendations:
* https://talks.golang.org/2014/names.slide
* https://golang.org/doc/effective_go.html#names
* https://blog.golang.org/package-names
* https://go.dev/wiki/CodeReviewComments
* [Style guideline for Go packages](https://rakyll.org/style-packages) (rakyll/JBD)

See [`Go Project Layout`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) for additional background information.

More about naming and organizing packages as well as other code structure recommendations:
* [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg)
* [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0)
* [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8)
* [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0)

A Chinese post about Package-Oriented-Design guidelines and Architecture layer
* [面向包的设计和架构分层](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md)

## Go Directories

### `/cmd`

Main applications for this project.

The directory name for each application should match the name of the executable you want to have (e.g., `/cmd/myapp`).

Don't put a lot of code in the application directory. If you think the code can be imported and used in other projects, then it should live in the `/pkg` directory. If the code is not reusable or if you don't want others to reuse it, put that code in the `/internal` directory. You'll be surprised what others will do, so be explicit about your intentions!

It's common to have a small `main` function that imports and invokes the code from the `/internal` and `/pkg` directories and nothing else.

See the [`/cmd`](cmd/README.md) directory for examples.

### `/internal`

Private application and library code. This is the code you don't want others importing in their applications or libraries. Note that this layout pattern is enforced by the Go compiler itself. See the Go 1.4 [`release notes`](https://golang.org/doc/go1.4#internalpackages) for more details. Note that you are not limited to the top level `internal` directory. You can have more than one `internal` directory at any level of your project tree.

You can optionally add a bit of extra structure to your internal packages to separate your shared and non-shared internal code. It's not required (especially for smaller projects), but it's nice to have visual clues showing the intended package use. Your actual application code can go in the `/internal/app` directory (e.g., `/internal/app/myapp`) and the code shared by those apps in the `/internal/pkg` directory (e.g., `/internal/pkg/myprivlib`).

You use internal directories to make packages private. If you put a package inside an internal directory, then other packages can’t import it unless they share a common ancestor. And it’s the only directory named in Go’s documentation and has special compiler treatment.

### `/pkg`

Library code that's ok to use by external applications (e.g., `/pkg/mypubliclib`). Other projects will import these libraries expecting them to work, so think twice before you put something here :-) Note that the `internal` directory is a better way to ensure your private packages are not importable because it's enforced by Go. The `/pkg` directory is still a good way to explicitly communicate that the code in that directory is safe for use by others. The [`I'll take pkg over internal`](https://travisjeffery.com/ill-take-pkg-over-internal/) blog post by Travis Jeffery provides a good overview of the `pkg` and `internal` directories and when it might make sense to use them.

It's also a way to group Go code in one place when your root directory contains lots of non-Go components and directories making it easier to run various Go tools (as mentioned in these talks: [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg) from GopherCon EU 2018, [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) and [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)).

See the [`/pkg`](pkg/README.md) directory if you want to see which popular Go repos use this project layout pattern. This is a common layout pattern, but it's not universally accepted and some in the Go community don't recommend it.

It's ok not to use it if your app project is really small and where an extra level of nesting doesn't add much value (unless you really want to :-)). Think about it when it's getting big enough and your root directory gets pretty busy (especially if you have a lot of non-Go app components).

The `pkg` directory origins: The old Go source code used to use `pkg` for its packages and then various Go projects in the community started copying the pattern (see [`this`](https://twitter.com/bradfitz/status/1039512487538970624) Brad Fitzpatrick's tweet for more context).

### `/vendor`

Application dependencies (managed manually or by your favorite dependency management tool like the new built-in [`Go Modules`](https://go.dev/wiki/Modules) feature). The `go mod vendor` command will create the `/vendor` directory for you. Note that you might need to add the `-mod=vendor` flag to your `go build` command if you are not using Go 1.14 where it's on by default.

Don't commit your application dependencies if you are building a library.

Note that since [`1.13`](https://golang.org/doc/go1.13#modules) Go also enabled the module proxy feature (using [`https://proxy.golang.org`](https://proxy.golang.org) as their module proxy server by default). Read more about it [`here`](https://blog.golang.org/module-mirror-launch) to see if it fits all of your requirements and constraints. If it does, then you won't need the `vendor` directory at all.

## Service Application Directories

### `/api`

OpenAPI/Swagger specs, JSON schema files, protocol definition files.

See the [`/api`](api/README.md) directory for examples.

## Web Application Directories

### `/web`

Web application specific components: static web assets, server side templates and SPAs.

## Common Application Directories

### `/configs`

Configuration file templates or default configs.

Put your `confd` or `consul-template` template files here.

### `/init`

System init (systemd, upstart, sysv) and process manager/supervisor (runit, supervisord) configs.

### `/scripts`

Scripts to perform various build, install, analysis, etc operations.

These scripts keep the root level Makefile small and simple (e.g., [`https://github.com/hashicorp/terraform/blob/main/Makefile`](https://github.com/hashicorp/terraform/blob/main/Makefile)).

See the [`/scripts`](scripts/README.md) directory for examples.

### `/build`

Packaging and Continuous Integration.

Put your cloud (AMI), container (Docker), OS (deb, rpm, pkg) package configurations and scripts in the `/build/package` directory.

Put your CI (travis, circle, drone) configurations and scripts in the `/build/ci` directory. Note that some of the CI tools (e.g., Travis CI) are very picky about the location of their config files. Try putting the config files in the `/build/ci` directory linking them to the location where the CI tools expect them (when possible).

### `/deployments`

IaaS, PaaS, system and container orchestration deployment configurations and templates (docker-compose, kubernetes/helm, terraform). Note that in some repos (especially apps deployed with kubernetes) this directory is called `/deploy`.

### `/test`

Additional external test apps and test data. Feel free to structure the `/test` directory anyway you want. For bigger projects it makes sense to have a data subdirectory. For example, you can have `/test/data` or `/test/testdata` if you need Go to ignore what's in that directory. Note that Go will also ignore directories or files that begin with "." or "_", so you have more flexibility in terms of how you name your test data directory.

See the [`/test`](test/README.md) directory for examples.

## Other Directories

### `/docs`

Design and user documents (in addition to your godoc generated documentation).

See the [`/docs`](docs/README.md) directory for examples.

### `/tools`

Supporting tools for this project. Note that these tools can import code from the `/pkg` and `/internal` directories.

See the [`/tools`](tools/README.md) directory for examples.

### `/examples`

Examples for your applications and/or public libraries.

See the [`/examples`](examples/README.md) directory for examples.

### `/third_party`

External helper tools, forked code and other 3rd party utilities (e.g., Swagger UI).

### `/githooks`

Git hooks.

### `/assets`

Other assets to go along with your repository (images, logos, etc).

### `/website`

This is the place to put your project's website data if you are not using GitHub pages.

See the [`/website`](website/README.md) directory for examples.

## Directories You Shouldn't Have

### `/src`

Some Go projects do have a `src` folder, but it usually happens when the devs came from the Java world where it's a common pattern. If you can help yourself try not to adopt this Java pattern. You really don't want your Go code or Go projects to look like Java :-)

Don't confuse the project level `/src` directory with the `/src` directory Go uses for its workspaces as described in [`How to Write Go Code`](https://golang.org/doc/code.html). The `$GOPATH` environment variable points to your (current) workspace (by default it points to `$HOME/go` on non-windows systems). This workspace includes the top level `/pkg`, `/bin` and `/src` directories. Your actual project ends up being a sub-directory under `/src`, so if you have the `/src` directory in your project the project path will look like this: `/some/path/to/workspace/src/your_project/src/your_code.go`. Note that with Go 1.11 it's possible to have your project outside of your `GOPATH`, but it still doesn't mean it's a good idea to use this layout pattern.


## Badges

* [Go Report Card](https://goreportcard.com/) - It will scan your code with `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` and `misspell`. Replace `github.com/golang-standards/project-layout` with your project reference.

    [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout)

* ~~[GoDoc](http://godoc.org) - It will provide online version of your GoDoc generated documentation. Change the link to point to your project.~~

    [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout)

* [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev is a new destination for Go discovery & docs. You can create a badge using the [badge generation tool](https://pkg.go.dev/badge).

    [![PkgGoDev](https://pkg.go.dev/badge/github.com/golang-standards/project-layout)](https://pkg.go.dev/github.com/golang-standards/project-layout)

* Release - It will show the latest release number for your project. Change the github link to point to your project.

    [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest)

## Notes

A more opinionated project template with sample/reusable configs, scripts and code is a WIP.


golang-standards/project-layout

Go application GitHub repository template

# Go Repository Template

[![Keep a Changelog](https://img.shields.io/badge/changelog-Keep%20a%20Changelog-%23E05735)](CHANGELOG.md)
[![Go Reference](https://pkg.go.dev/badge/github.com/golang-templates/seed.svg)](https://pkg.go.dev/github.com/golang-templates/seed)
[![go.mod](https://img.shields.io/github/go-mod/go-version/golang-templates/seed)](go.mod)
[![LICENSE](https://img.shields.io/github/license/golang-templates/seed)](LICENSE)
[![Go Report Card](https://goreportcard.com/badge/github.com/golang-templates/seed)](https://goreportcard.com/report/github.com/golang-templates/seed)
[![Codecov](https://codecov.io/gh/golang-templates/seed/branch/main/graph/badge.svg)](https://codecov.io/gh/golang-templates/seed)

⭐ `Star` this repository if you find it valuable and worth maintaining.

👁 `Watch` this repository to get notified about new releases, issues, etc.

## Description

This is a GitHub repository template for a Go application.
You can use it:

- to create a new repository with automation and environment setup,
- as reference when improving automation for an existing repository.

It includes:

- continuous integration via [GitHub Actions](https://github.com/features/actions),
- build automation via [Make](https://www.gnu.org/software/make),
- dependency management using [Go Modules](https://github.com/golang/go/wiki/Modules),
- code formatting using [gofumpt](https://github.com/mvdan/gofumpt),
- linting with [golangci-lint](https://github.com/golangci/golangci-lint),
  [misspell](https://github.com/client9/misspell),
  and [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli),
- unit testing with
  [race detector](https://blog.golang.org/race-detector),
  code coverage [HTML report](https://blog.golang.org/cover)
  and [Codecov report](https://codecov.io/),
- releasing using [GoReleaser](https://github.com/goreleaser/goreleaser),
- dependencies scanning and updating thanks to [Renovate](https://github.com/renovatebot/renovate), configured via the [Renovate GitHub App](https://github.com/apps/renovate),
- security code analysis using [CodeQL Action](https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/about-code-scanning),
  and [govulncheck](https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck),
- [Visual Studio Code](https://code.visualstudio.com) configuration with [Go](https://code.visualstudio.com/docs/languages/go) support.

## Usage

1. Sign up on [Codecov](https://codecov.io/) and configure
   [Codecov GitHub Application](https://github.com/apps/codecov).
2. Click the `Use this template` button (alt. clone or download this repository).
3. Replace all occurrences of `golang-templates/seed` to `your_org/repo_name` in all files.
4. Replace all occurrences of `seed` to `repo_name` in [Dockerfile](Dockerfile).
5. Follow [these](https://docs.codecov.com/docs/adding-the-codecov-token#github-actions)
   instructions to add the `CODECOV_TOKEN` as a GitHub Actions secret.
6. Update the following files:
   - [CHANGELOG.md](CHANGELOG.md)
   - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
   - [LICENSE](LICENSE)
   - [README.md](README.md)

## Setup

Below you can find sample instructions on how to set up the development environment.
Of course, you can use other tools like [GoLand](https://www.jetbrains.com/go/),
[Vim](https://github.com/fatih/vim-go), [Emacs](https://github.com/dominikh/go-mode.el).
However, take notice that the Visual Studio Go extension is
[officially supported](https://blog.golang.org/vscode-go) by the Go team.

1. Install [Go](https://golang.org/doc/install).
2. Install [Visual Studio Code](https://code.visualstudio.com/).
3. Install [Go extension](https://code.visualstudio.com/docs/languages/go).
4. Clone and open this repository.
5. `F1` -> `Go: Install/Update Tools` -> (select all) -> OK.

## Build

### Terminal

- `make` - execute the build pipeline.
- `make help` - print help for the [Make targets](Makefile).

### Visual Studio Code

`F1` → `Tasks: Run Build Task (Ctrl+Shift+B or ⇧⌘B)` to execute the build pipeline.

## Release

The release workflow is triggered each time a tag with `v` prefix is pushed.

_CAUTION_: Make sure to understand the consequences before you bump the major version.
More info: [Go Wiki](https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher),
[Go Blog](https://blog.golang.org/v2-go-modules).

## Maintenance

Notable files:

- [.github/workflows](.github/workflows) - GitHub Actions workflows,
- [renovate.json](renovate.json) - Renovate configuration,
- [.vscode](.vscode) - Visual Studio Code configuration files,
- [.golangci.yml](.golangci.yml) - golangci-lint configuration,
- [.goreleaser.yml](.goreleaser.yml) - GoReleaser configuration,
- [Dockerfile](Dockerfile) - Dockerfile used by GoReleaser to create a container image,
- [Makefile](Makefile) - Make targets used for development, [CI build](.github/workflows) and [.vscode/tasks.json](.vscode/tasks.json),

## FAQ

### Why Visual Studio Code editor configuration

Developers that use Visual Studio Code can take advantage of the editor configuration.
While others do not have to care about it.
Setting configs for each repo is unnecessary time consuming.
VS Code is the most popular Go editor ([survey](https://blog.golang.org/survey2019-results))
and it is officially [supported by the Go team](https://blog.golang.org/vscode-go).

You can always remove the [.vscode](.vscode) directory if it really does not help you.

### Why GitHub Actions, not any other CI server

GitHub Actions is out-of-the-box if you are already using GitHub.
[GitHub Actions for Go guide](https://github.com/mvdan/github-actions-golang) explains how to use it for Go.

However, changing to any other CI server should be very simple,
because this repository has build logic and tooling installation in [Makefile](Makefile).

### How can I build on Windows

Install [tdm-gcc](https://jmeubank.github.io/tdm-gcc/)
and copy `C:\TDM-GCC-64\bin\mingw32-make.exe`
to `C:\TDM-GCC-64\bin\make.exe`.
Alternatively, you may install [mingw-w64](http://mingw-w64.org/doku.php)
and copy `mingw32-make.exe` accordingly.

Take a look at [this workaround](https://github.com/docker-archive/toolbox/issues/673#issuecomment-355275054),
if you have problems using Docker in Git Bash.

You can also use [WSL (Windows Subsystem for Linux)](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
or develop inside a [Remote Container](https://code.visualstudio.com/docs/remote/containers).
However, take into consideration that then you are not going to use "bare-metal" Windows.

Consider using [goyek](https://github.com/goyek/goyek)
for creating cross-platform build pipelines in Go.

### How can I customize the release

Take a look at GoReleaser [docs](https://goreleaser.com/customization/)
as well as [its repo](https://github.com/goreleaser/goreleaser/)
how it is dogfooding its functionality.
You can use it to add deb/rpm/snap packages, Homebrew Tap, Scoop App Manifest etc.

If you are developing a library and you like handcrafted changelog and release notes,
you are free to remove any usage of GoReleaser.

## Contributing

Feel free to create an issue or propose a pull request.

Follow the [Code of Conduct](CODE_OF_CONDUCT.md).


golang-templates/seed

Generate a modern Web project with Go and Angular, React, or Vue in seconds

goxygen

Go application boilerplate and example applying modern practices

# Modern Go Application

[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go#project-layout)
[![Go Report Card](https://goreportcard.com/badge/github.com/sagikazarmark/modern-go-application?style=flat-square)](https://goreportcard.com/report/github.com/sagikazarmark/modern-go-application)
[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/mod/github.com/sagikazarmark/modern-go-application)

![GitHub Workflow Status](https://img.shields.io/github/workflow/status/sagikazarmark/modern-go-application/CI?style=flat-square)
[![CircleCI](https://circleci.com/gh/sagikazarmark/modern-go-application.svg?style=svg)](https://circleci.com/gh/sagikazarmark/modern-go-application)
[![Gitlab](https://img.shields.io/badge/gitlab-sagikazarmark%2Fmodern--go--application-orange.svg?logo=gitlab&longCache=true&style=flat-square)](https://gitlab.com/sagikazarmark/modern-go-application)

**Go application boilerplate and example applying modern practices**

This repository tries to collect the best practices of application development using Go language.
In addition to the language specific details, it also implements various language independent practices.

Some of the areas Modern Go Application touches:

- architecture
- package structure
- building the application
- testing
- configuration
- running the application (eg. in Docker)
- developer environment/experience
- telemetry

To help adopting these practices, this repository also serves as a boilerplate for new applications.


## Features

- configuration (using [spf13/viper](https://github.com/spf13/viper))
- logging (using [logur.dev/logur](https://logur.dev/logur) and [sirupsen/logrus](https://github.com/sirupsen/logrus))
- error handling (using [emperror.dev/emperror](https://emperror.dev/emperror))
- metrics and tracing using [Prometheus](https://prometheus.io/) and [Jaeger](https://www.jaegertracing.io/) (via [OpenCensus](https://opencensus.io/))
- health checks (using [AppsFlyer/go-sundheit](https://github.com/AppsFlyer/go-sundheit))
- graceful restart (using [cloudflare/tableflip](https://github.com/cloudflare/tableflip)) and shutdown
- support for multiple server/daemon instances (using [oklog/run](https://github.com/oklog/run))
- messaging (using [ThreeDotsLabs/watermill](https://github.com/ThreeDotsLabs/watermill))
- MySQL database connection (using [go-sql-driver/mysql](https://github.com/go-sql-driver/mysql))
- ~~Redis connection (using [gomodule/redigo](https://github.com/gomodule/redigo))~~ removed due to lack of usage (see [#120](../../issues/120))


## First steps

To create a new application from the boilerplate clone this repository (if you haven't done already) into your GOPATH
then execute the following:

```bash
chmod +x init.sh && ./init.sh
? Package name (github.com/sagikazarmark/modern-go-application)
? Project name (modern-go-application)
? Binary name (modern-go-application)
? Service name (modern-go-application)
? Friendly service name (Modern Go Application)
? Update README (Y/n)
? Remove init script (y/N) y
```

It updates every import path and name in the repository to your project's values.
**Review** and commit the changes.


### Load generation

To test or demonstrate the application it comes with a simple load generation tool.
You can use it to test the example endpoints and generate some load (for example in order to fill dashboards with data).

Follow the instructions in [etc/loadgen](etc/loadgen).


## Inspiration

See [INSPIRATION.md](INSPIRATION.md) for links to articles, projects, code examples that somehow inspired
me while working on this project.


## License

The MIT License (MIT). Please see [License File](LICENSE) for more information.


modern-go-application

Set of practices and discussions on how to structure Go project layout

# Go Project Layout
This is my understanding of how to structure `Go` project layout. The most important part is how to organize your `Go` code into packages.          

## Motivation
A good project layout will make your source code **easy to understand, easy to test, and easy to maintain**.     
[Kat Zien](https://github.com/katzien/) has a very good summary([Slides](https://github.com/katzien/talks/tree/master/how-do-you-structure-your-apps/gopherconuk-2018-08-03)) for this, so I'd like to refer it directly as below:        

### Questions, decisions 

- Should I put everything in the main package?
- Should I start with one package and extract other packages over time? 
- How do I decide if something should be in its own package?
- Should I just use a framework?
- What's the programming paradigm for Go?
- Microservices or monolith?
- How much should be shared between packages?
       
### Why should we care?
**Because if Go is going to be a language that companies invest in for the long term, the maintenance of Go programs, the ease of which they can change, 
will be a key factor in their decision.** - Dave Cheney, Golang UK 2016 keynote

### Good structure goals
- Consistent.
- Easy to understand, navigate and reason about. ("makes sense") Easy to change, loosely-coupled.
- Easy to test.
- "As simple as possible, but no simpler."
- Design reflects exactly how the software works.
- Structure reflects the design exactly.     

## Demo

```bash
# shell 1
$ go version
go version go1.13.1 linux/amd64
$
$ cd $GOPATH
$ 
$ # app 1: reverse echo
$ go get -u github.com/wangyoucao577/go-project-layout/cmd/echor
$ ./bin/echor "hello world"
dlrow olleh
$
$ # app 2: a simple diagnosis service for server diagnosis. 
$ #    return `Hostname/IP/CPUs/RemoteAddr...` by `HTTP`. 
$ #    sample request: `http://localhost:8000/diagnosis?diagnosis=ping`
$ go get -u github.com/wangyoucao577/go-project-layout/cmd/diagnosis
$ ./bin/diagnosis -alsologtostderr
I1007 18:50:05.550952    3769 main.go:33] Listen on :8000

# shell 2
$ curl "http://localhost:8000/diagnosis?diagnosis=ping"
{
  "Hostname":"server",
  "IP Addresses":[
    "192.168.29.201/24",
    "fe80::1c20:479:9094:4327/64",
    "192.168.141.1/24",
    "fe80::8002:2d87:c4f3:4aab/64",
    "192.168.128.1/24",
    "fe80::eca9:cfa0:9443:b8ff/64",
    "192.168.44.209/28",
    "fe80::8551:306e:7e7:6faf/64"
  ],
  "CPUs":8,
  "Remote Endpoint":"127.0.0.1:64717"
}
```

## Note
This topic is kind of best practices. I'd like to discuss some of them and my opinion, then maybe deep into more best practices in the future.     


### Top dir `/cmd`
[**My opinion: Strongly recommended**]     
The `cmd` layout pattern is very useful when you need to have more than one application binary.      

- Each binary gets a subdirectory (e.g., `your_project/cmd/your_app`).   
  - The subdirectory is the `main` package for your application.     
  - Don't put a lot of code in the `main` package. Instead, it should only used to initialises and ties everything together.     
- This patterns also helps you keep your project/package **go gettable**. 
  - It means you can use the `go get` command to fetch (and install) your project, its applications and its libraries (e.g., `go get github.com/your_github_username/your_project/cmd/your_app`). 
- The [official Go tool](https://github.com/golang/tools/tree/master/cmd) is one example of the `cmd` layout patter. A number of other well known projects use the same pattern: [Kubernetes](https://github.com/kubernetes/kubernetes/tree/master/cmd), [Docker](https://github.com/moby/moby/tree/master/cmd), [Prometheus](https://github.com/prometheus/prometheus/tree/master/cmd), [Influxdb](https://github.com/influxdata/influxdb/tree/master/cmd).


### Top dir `/pkg`
[**My opinion: NOT good enough, use it if good for you**]    
- People also recommend to set up a `/pkg` top dir in `Go` project to put your public libraries.    
  - These libraries can be used internally by your application.     
  - They can also be used by external projects. It's an informal contract between you and other external users of your code. Other projects will import these libraries expecting them to work.        
- But I think it's NOT a good enough idea because
  - It brings confusion since `Go` workspaces have a directory with the same name and that directory has a different purpose(it’s used to store object files for the packages the `Go` compiler builds).     
  - The meaning of "public libraries" is not clear enough.    
    - Even many well known projects use this pattern ([Kubernetes](https://github.com/kubernetes/kubernetes/tree/master/pkg), [Docker](https://github.com/moby/moby/tree/master/pkg), [Grafana](https://github.com/grafana/grafana/tree/master/pkg), [Influxdb](https://github.com/influxdata/influxdb/tree/master/pkg), [Etcd](https://github.com/coreos/etcd/tree/master/pkg)), [Docker](https://github.com/moby/moby/tree/master/pkg) and [Etcd](https://github.com/coreos/etcd/tree/master/pkg) comment the meaning of "public libraries" again. Both of them limit it only as **utility packages**, and these **utility packages** possible to be moved out into its own repository in the future:          
      - [Docker](https://github.com/moby/moby/tree/master/pkg): `pkg/` is a collection of utility packages used by the [moby](https://github.com/moby/moby/) project without being specific to its internals.    
      - [Etcd](https://github.com/coreos/etcd/tree/master/pkg): `pkg/` is a collection of utility packages used by etcd without being specific to etcd itself. A package belongs here only if it could possibly be moved out into its own repository in the future.


### Group packages by dependency     
[**My opinion: Strongly recommended**]     
- Domain types
  - Domain Types are types that model your business functionality and objects.    
  - [Ben Johnson - Standard Package Layout](https://medium.com/@benbjohnson/standard-package-layout-7cdbc8391fc1) recommend to place your into root package. This package only contains simple data types, so it will be extremely simple.      
  - In my opinion, either place them into root package or place them into a individual subpackage are ok. The most important part here is this package should be extermely simple, and not depend on any other package in application!     
- Each package should only has a single purpose.    
- Packages names describe their purpose.    
- When necessary, use a descriptive parent package and several children implementing the functionality.     
  - like the [encoding package](https://github.com/golang/go/tree/master/src/encoding).    
- `main` package ties together dependencies

### More best practices

- Follow conventions
  - Be similar to the standard library and other popular packages 
  - Don't surprise people
  - Be obvious, not clever
- Use [Go modules](https://github.com/golang/go/wiki/Modules)
- Avoid global scope and `init()`

## References
- [GopherCon UK 2018: Kat Zien - How do you structure your Go apps?](https://www.youtube.com/watch?v=VQym87o91f8&t=3s)     
  - This's an amazing talk for the `Go` project layout I think.    
  - [Slides](https://github.com/katzien/talks/tree/master/how-do-you-structure-your-apps/gopherconuk-2018-08-03)    
  - Code: [katzien/go-structure-examples](https://github.com/katzien/go-structure-examples)    
- [Standard Go Project Layout](https://github.com/golang-standards/project-layout)    
  - [No, it's NOT a golang standard!!!](https://github.com/golang-standards/project-layout/issues/38) See more in [Delete this repo #36](https://github.com/golang-standards/project-layout/issues/36) and [This repository has multiple serious issues #41](https://github.com/golang-standards/project-layout/issues/41).     
  - It's just an organization name "golang-standards" used by some one to manage these repos. It's harmful if you really think it's a standard and try to always follow it.     
  - On the other hand, I think this repo still have some benifits: collects many resources for the "golang-project-layout" question, gives suggestion for how to do it, etc.     
  - Try to read it as a post, think about what's valueable for you.             
  - [More resources metioned in #36](https://github.com/golang-standards/project-layout/issues/36#issue-479438391)
- [Ben Johnson - Standard Package Layout](https://medium.com/@benbjohnson/standard-package-layout-7cdbc8391fc1)
- [Ben Johnson - Building WTF Dial](https://medium.com/wtf-dial/wtf-dial-domain-model-9655cd523182)
- [Kyle C. Quest - Go Project Layout](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2)
- [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices](https://www.youtube.com/watch?v=MzTcsI6tn-0)
  - [slides](https://www.brianketelsen.com/slides/gcru18-best/)
- [Golang UK Conference 2017 | Mat Ryer - Writing Beautiful Packages in Go](https://www.youtube.com/watch?v=cAWlv2SeQus)
- [CodeBear801 - Golang Package layout](https://github.com/CodeBear801/tech_summary/blob/master/tech-summary/language/go/go-package-layout.md)
- [golang/go](https://github.com/golang/go)
- [golang/tools](https://github.com/golang/tools)
- [moby/moby](https://github.com/moby/moby)
- [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes)
- [etcd-io/etcd](https://github.com/etcd-io/etcd)
- [influxdata/influxdb](https://github.com/influxdata/influxdb)
- [prometheus/prometheus](https://github.com/prometheus/prometheus)


wangyoucao577/go-project-layout

A [starter kit](https://github.com/ardanlabs/service/wiki) for building production grade scalable web service applications

# Ultimate Software Design with Kubernetes

[![CircleCI](https://circleci.com/gh/ardanlabs/service.svg?style=svg)](https://circleci.com/gh/ardanlabs/service)
[![Go Report Card](https://goreportcard.com/badge/github.com/ardanlabs/service)](https://goreportcard.com/report/github.com/ardanlabs/service)
[![go.mod Go version](https://img.shields.io/github/go-mod/go-version/ardanlabs/service)](https://github.com/ardanlabs/service)

Copyright 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025 Ardan Labs  
hello@ardanlabs.com

## My Information

```
Name:    Bill Kennedy
Company: Ardan Labs
Title:   Managing Partner
Email:   bill@ardanlabs.com
Twitter: goinggodotnet
```

## Description

_"As a program evolves and acquires more features, it becomes complicated, with subtle dependencies between components. Over time, complexity accumulates, and it becomes harder and harder for programmers to keep all the relevant factors in their minds as they modify the system. This slows down development and leads to bugs, which slow development even more and add to its cost. Complexity increases inevitably over the life of any program. The larger the program, and the more people that work on it, the more difficult it is to manage complexity."_ - John Ousterhout

_"A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over with a working simple system."_ - John Gall

The service starter kit is a starting point for building production grade scalable web service applications that leverage the power of a Domain Driven, Data Oriented Architecture that can run in Kubernetes. The goal of this project is to provide a proven starting point that reduces the repetitive tasks required for a new project to be launched into production. It uses minimal dependencies, implements idiomatic code and follows Go best practices. Collectively, the project lays out everything logically to minimize guess work and enable engineers to quickly maintain a mental model for the project.

The class behind this starter kit teaches how to build production-level software in Go leveraging the power of a Domain Driven, Data Oriented Architecture that can run in Kubernetes. From the beginning, you will pair program with the instructor walking through the design philosophies and guidelines for building software in Go. With each new feature that is added to the project, you will learn how to deploy to and manage the Kubernetes environment used to run the project. The core of this class is to teach you and your team how to handle and reduce the spread of complexity in the systems you are building.

Learn more about the project:

[Wiki](https://github.com/ardanlabs/service/wiki) | [Course Outline](https://github.com/ardanlabs/service/wiki/course-outline) | [Class Schedule](https://www.ardanlabs.com/events/)

## Licensing

```
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

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

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

## Learn More

**Reach out about corporate training events, open enrollment live training sessions, and on-demand learning options.**

Ardan Labs (www.ardanlabs.com)  
hello@ardanlabs.com

## Index

- [Installation](https://github.com/ardanlabs/service?tab=readme-ov-file#installation)
- [Create Your Own Version](https://github.com/ardanlabs/service?tab=readme-ov-file#create-your-own-version)
- [Running The Project](https://github.com/ardanlabs/service?tab=readme-ov-file#running-the-project)
- [Purchase Video](https://github.com/ardanlabs/service?tab=readme-ov-file#purchase-video)
- [Experience](https://github.com/ardanlabs/service?tab=readme-ov-file#our-experience)
- [Teacher](https://github.com/ardanlabs/service?tab=readme-ov-file#our-teacher)
- [More About Go](https://github.com/ardanlabs/service?tab=readme-ov-file#more-about-go)
- [Minimal Qualified Student](https://github.com/ardanlabs/service?tab=readme-ov-file#minimal-qualified-student)
- [Joining the Go Slack Community](https://github.com/ardanlabs/service?tab=readme-ov-file#joining-the-go-slack-community)

## Installation

To clone the project, create a folder and use the git clone command. Then please read the [makefile](makefile) file to learn how to install all the tooling and docker images.

```
$ cd $HOME
$ mkdir code
$ cd code
$ git clone https://github.com/ardanlabs/service or git@github.com:ardanlabs/service.git
$ cd service
```

## Create Your Own Version

If you want to create a version of the project for your own use, use the new gonew command.

```
$ go install golang.org/x/tools/cmd/gonew@latest

$ cd $HOME
$ mkdir code
$ cd code
$ gonew github.com/ardanlabs/service github.com/mydomain/myproject
$ cd myproject
$ go mod vendor
```

Now you have a copy with your own module name. Now all you need to do is initialize the project for git.

## Running The Project

To run the project use the following commands.

```
# Install Tooling
$ make dev-gotooling
$ make dev-brew
$ make dev-docker

# Run Tests
$ make test

# Shutdown Tests
$ make test-down

# Run Project
$ make dev-up
$ make dev-update-apply
$ make token
$ export TOKEN=<COPY TOKEN>
$ make users

# Run Load
$ make load

# Run Tooling
$ make grafana
$ make statsviz

# Shut Project
$ make dev-down
```

## Purchase Video

The entire training class has been recorded to be made available to those who can't have the class taught at their company or who can't attend a conference. This is the entire class material.

[ardanlabs.com/education](https://www.ardanlabs.com/education/)

## Our Experience

We have taught Go to thousands of developers all around the world since 2014. There is no other company that has been doing it longer and our material has proven to help jump-start developers 6 to 12 months ahead of their knowledge of Go. We know what knowledge developers need in order to be productive and efficient when writing software in Go.

Our classes are perfect for intermediate-level developers who have at least a few months to years of experience writing code in Go. Our classes provide a very deep knowledge of the programming langauge with a big push on language mechanics, design philosophies and guidelines. We focus on teaching how to write code with a priority on consistency, integrity, readability and simplicity. We cover a lot about “if performance matters” with a focus on mechanical sympathy, data oriented design, decoupling and writing/debugging production software.

## Our Teacher

### William Kennedy ([@goinggodotnet](https://twitter.com/goinggodotnet))

_William Kennedy is a managing partner at Ardan Labs in Miami, Florida. Ardan Labs is a high-performance development and training firm working with startups and fortune 500 companies. He is also a co-author of the book Go in Action, the author of the blog GoingGo.Net, and a founding member of GoBridge which is working to increase Go adoption through diversity._

_**Video Training**_  
[Ultimate Go Video](https://education.ardanlabs.com)  
[Ardan Labs YouTube Channel](http://youtube.ardanlabs.com/)

_**Blog**_  
[Going Go](https://www.ardanlabs.com/blog/)

_**Writing**_  
[Running MongoDB Queries Concurrently With Go](http://blog.mongodb.org/post/80579086742/running-mongodb-queries-concurrently-with-go)  
[Go In Action](https://www.manning.com/books/go-in-action)

_**Articles**_  
[IT World Canada](http://www.itworldcanada.com/article/nascent-google-development-language-shows-promise-for-more-productive-coding/387449)

_**Video**_  
[GopherCon USA (2025): Understanding Escape Analysis to Speed Up Your Code](https://www.youtube.com/watch?v=FUm0pfgWehI&list=PL2ntRZ1ySWBeBA1lEnmD3vUedkRDvgnmw)  
[GopherCon USA (2025): Go’s Trace Tooling and Concurrency](https://www.youtube.com/watch?v=Gqo0oCfZSjg&list=PL2ntRZ1ySWBeBA1lEnmD3vUedkRDvgnmw&index=5)  
[GopherCon UK (2025) - Building a coding agent from scratch](https://www.youtube.com/watch?v=ybBVOa572Tw&list=PLDWZ5uzn69ewrYyHTNrXlrWVDjLiOX0Yb&index=21)  
[GopherCon UK (2025) - K8s CPU Limits Deconstructed - Bill Kennedy](https://www.youtube.com/watch?v=jECXV2BdsI8&list=PLDWZ5uzn69ewrYyHTNrXlrWVDjLiOX0Yb&index=13)  
[Golang Charlotte (2024) - Domain Driven, Data Oriented Architecture](https://www.youtube.com/watch?v=bQgNYK1Z5ho)  
[GopherCon SG (2023) - K8s CPU Limits and Go](https://www.youtube.com/watch?v=Dm7yuoYTx54&list=PLq2Nv-Sh8Eba2gEaId35K2aAUFdpbKx9D&index=6)  
[P99 Talk (2022) - Evaluating Performance In Go](https://www.youtube.com/watch?v=PYMs-urosXs)  
[GopherCon Europe (2022) - Practical Memory Profiling](https://www.youtube.com/watch?v=6qAfkJGWsns)  
[Dgrpah Day (2021) - Getting Started With Dgraph and GraphQL](https://www.youtube.com/watch?v=5L4PUbDqSEo)  
[GDN Event #1 (2021) - GoBridge Needs Your Help](https://www.youtube.com/watch?v=Tst0oI97cvQ&t=2s)  
[Training Within The Go Community (2019)](https://www.youtube.com/watch?v=PSR1twjzzAM&feature=youtu.be)  
[GopherCon Australia (2019) - Modules](https://www.youtube.com/watch?v=MVxbVR_6Tac)  
[Golab (2019) - You Want To Build a Web Service?](https://www.youtube.com/watch?v=IV0wrVb31Pg)  
[GopherCon Singapore (2019) - Garbage Collection Semantics](https://www.youtube.com/watch?v=q4HoWwdZUHs)  
[GopherCon India (2019) - Channel Semantics](https://www.youtube.com/watch?v=AHAf1Xfr_HE)  
[GoWayFest Minsk (2018) - Profiling Web Apps](https://www.youtube.com/watch?v=-GBMFPegqgw)  
[GopherCon Singapore (2018) - Optimizing For Correctness](https://engineers.sg/video/optimize-for-correctness-gopherconsg-2018--2610)  
[GopherCon India (2018) - What is the Legacy You Are Leaving Behind](https://www.youtube.com/watch?v=j3zCUc06OXo&t=0s&index=11&list=PLhJxE57Cki63cElK2kmt3_vi8j2eIHTqZ)  
[Code::Dive (2017) - Optimizing For Correctness](https://www.youtube.com/watch?v=OTLjN8NQDyo)  
[Code::Dive (2017) - Go: Concurrency Design](https://www.youtube.com/watch?v=OrctYMf4btA)  
[dotGo (2017) - Behavior Of Channels](https://www.youtube.com/watch?v=zDCKZn4-dck)  
[GopherCon Singapore (2017) - Escape Analysis](https://engineers.sg/video/escape-analysis-and-memory-profiling-gophercon-sg-2017--1746)  
[Capital Go (2017) - Concurrency Design](https://www.youtube.com/watch?v=yGOOUCrrgrE&index=10&list=PLeGxIOPLk9EKdl-h_Y-sbLhLoP-ia7CJ5)  
[GopherCon India (2017) - Package Oriented Design](https://www.youtube.com/watch?v=spKM5CyBwJA#t=0m56s)  
[GopherCon India (2015) - Go In Action](https://www.youtube.com/watch?v=QkPw8-Pf0SM)  
[GolangUK (2016) - Dependency Management](https://youtu.be/CdhucJShJU8)  
[GothamGo (2015) - Error Handling in Go](https://vimeo.com/115782573)  
[GopherCon (2014) - Building an analytics engine](https://www.youtube.com/watch?v=EfJRQ1lGkUk)

[Golang Charlotte (2023) - Domain Driven, Data Oriented Architecture with Bill Kennedy](https://www.youtube.com/watch?v=bQgNYK1Z5ho)  
[Prague Meetup (2021) - Go Module Engineering Decisions](https://youtu.be/m8lgcXv2lhI)  
[Practical Understanding Of Scheduler Semantics (2021)](https://www.youtube.com/watch?v=p2Cjq3Dq2Q0)  
[Go Generics Draft Proposal (2020)](https://www.youtube.com/watch?v=gIEPspmbMHM&t=2069s)  
[Hack Potsdam (2017) - Tech Talk with William Kennedy](https://www.youtube.com/watch?v=sBzJ-sjhgs8)  
[Chicago Meetup (2016) - An Evening](https://vimeo.com/199832344)  
[Vancouver Meetup (2016) - Go Talk & Ask Me Anything With William Kennedy](https://www.youtube.com/watch?v=7YcLIbG1ekM&t=91s)  
[Vancouver Meetup (2015) - Compiler Optimizations in Go](https://www.youtube.com/watch?v=AQipeq39Aek)  
[Bangalore Meetup (2015) - OOP in Go](https://youtu.be/gRpUfjTwSOo)  
[GoSF Meetup - The Nature of Constants in Go](https://www.youtube.com/watch?v=ZUCHMAoOgUQ)  
[London Meetup - Mechanical Sympathy](https://skillsmatter.com/skillscasts/8353-london-go-usergroup)  
[Vancouver Meetup - Decoupling From Change](https://www.youtube.com/watch?v=7YcLIbG1ekM&feature=youtu.be)

_**Podcasts**_  
[Ardan Labs Podcast: On Going Series](https://ardanlabs.buzzsprout.com/)  
[Encore, domain design in Go with Bill Kennedy](https://gopodcast.dev/episodes/034-encore-domain-design-in-go-with-bill-kennedy)  
[Mangtas Nation: A Golang Deep Dive with Bill Kennedy](https://anchor.fm/mangtasnation/episodes/A-Golang-Deep-Dive-with-Bill-Kennedy--S2-EP3-e1ij9c3)  
[Coding with Holger: Go with Bill Kennedy](https://anchor.fm/coding-with-holger/episodes/Go-with-Bill-Kennedy-e1c9h2q)  
[Craft of Code: From Programming to Teaching Code with Bill Kennedy](https://podcasts.apple.com/us/podcast/from-programming-to-teaching-code-with-bill-kennedy/id1537136353?i=1000545230339)  
[GoTime: Design Philosophy](https://changelog.com/gotime/172)  
[GoTime: Learning and Teaching Go](https://changelog.com/gotime/72)  
[GoTime: Bill Kennedy on Mechanical Sympathy](https://changelog.com/gotime/6)  
[GoTime: Discussing Imposter Syndrome](https://changelog.com/gotime/30)  
[HelloTechPros: Your Tech Interviews are Scaring Away Brilliant People](http://hellotechpros.com/william-kennedy-people)  
[HelloTechPros: The 4 Cornerstones of Writing Software](http://hellotechpros.com/bill-kennedy-productivity)

## More About Go

Go is an open source programming language that makes it easy to build simple, reliable, and efficient software. Although it borrows ideas from existing languages, it has a unique and simple nature that make Go programs different in character from programs written in other languages. It balances the capabilities of a low-level systems language with some high-level features you see in modern languages today. This creates a programming environment that allows you to be incredibly productive, performant and fully in control; in Go, you can write less code and do so much more.

Go is the fusion of performance and productivity wrapped in a language that software developers can learn, use and understand. Go is not C, yet we have many of the benefits of C with the benefits of higher level programming languages.

[The Ecosystem of the Go Programming Language](https://henvic.dev/posts/go/) - Henrique Vicente  
[The Why of Go](https://www.infoq.com/presentations/go-concurrency-gc) - Carmen Andoh  
[Go Ten Years and Climbing](https://commandcenter.blogspot.com/2017/09/go-ten-years-and-climbing.html) - Rob Pike  
[The eigenvector of "Why we moved from language X to language Y"](https://erikbern.com/2017/03/15/the-eigenvector-of-why-we-moved-from-language-x-to-language-y.html) - Erik Bernhardsson  
[Learn More](https://talks.golang.org/2012/splash.article) - Go Team  
[Simplicity is Complicated](https://www.youtube.com/watch?v=rFejpH_tAHM) - Rob Pike  
[Getting Started In Go](http://aarti.github.io/2016/08/13/getting-started-in-go) - Aarti Parikh

## Minimal Qualified Student

The material has been designed to be taught in a classroom environment. The code is well commented but missing some contextual concepts and ideas that will be covered in class. Students with the following minimal background will get the most out of the class.

- Studied CS in school or has a minimum of two years of experience programming full time professionally.
- Familiar with structural and object oriented programming styles.
- Has worked with arrays, lists, queues and stacks.
- Understands processes, threads and synchronization at a high level.
- Operating Systems
  - Has worked with a command shell.
  - Knows how to maneuver around the file system.
  - Understands what environment variables are.

## Joining the Go Slack Community

We use a Slack channel to share links, code, and examples during the training. This is free. This is also the same Slack community you will use after training to ask for help and interact with may Go experts around the world in the community.

1. Using the following link, fill out your name and email address: https://invite.slack.gobridge.org
1. Check your email, and follow the link to the slack application.
1. Join the training channel by clicking on this link: https://gophers.slack.com/messages/training/
1. Click the “Join Channel” button at the bottom of the screen.

---

All material is licensed under the [Apache License Version 2.0, January 2004](http://www.apache.org/licenses/LICENSE-2.0).


ardanlabs/service

A Go application boilerplate template for quick starting projects following production best practices

# cookiecutter-golang

[![Build Status](https://travis-ci.org/lacion/cookiecutter-golang.svg?branch=master)](https://travis-ci.org/lacion/cookiecutter-golang)

Powered by [Cookiecutter](https://github.com/audreyr/cookiecutter), Cookiecutter Golang is a framework for jumpstarting production-ready go projects quickly.

## Features

- Generous `Makefile` with management commands
- Uses `go dep` (with optional go module support *requires go 1.11*)
- injects build time and git hash at build time.

## Optional Integrations

- Can use [viper](https://github.com/spf13/viper) for env var config
- Can use [cobra](https://github.com/spf13/cobra) for cli tools
- Can use [logrus](https://github.com/sirupsen/logrus) for logging
- Can create dockerfile for building go binary and dockerfile for final go binary (no code in final container)
- If docker is used adds docker management commands to makefile
- Option of TravisCI, CircleCI or None

## Constraints

- Uses `dep` or `mod` for dependency management
- Only maintained 3rd party libraries are used.

This project now uses docker multistage builds, you need at least docker version v17.05.0-ce to use the docker file in this template, [you can read more about multistage builds here](https://www.critiqus.com/post/multi-stage-docker-builds/).

## Docker

This template uses docker multistage builds to make images slimmer and containers only the final project binary and assets with no source code whatsoever.

You can find the image dokcer file in this [repo](https://github.com/lacion/alpine-golang-buildimage) and more information about docker multistage builds in this [blog post](https://www.critiqus.com/post/multi-stage-docker-builds/).

Apps run under non root user and also with [dumb-init](https://github.com/Yelp/dumb-init).

## Usage

Let's pretend you want to create a project called "echoserver". Rather than starting from scratch maybe copying 
some files and then editing the results to include your name, email, and various configuration issues that always 
get forgotten until the worst possible moment, get cookiecutter to do all the work.

First, get Cookiecutter. Trust me, it's awesome:
```console
$ pip install cookiecutter
```

Alternatively, you can install `cookiecutter` with homebrew:
```console
$ brew install cookiecutter
```

Finally, to run it based on this template, type:
```console
$ cookiecutter https://github.com/lacion/cookiecutter-golang.git
```

You will be asked about your basic info (name, project name, app name, etc.). This info will be used to customize your new project.

Warning: After this point, change 'Luis Morales', 'lacion', etc to your own information.

Answer the prompts with your own desired [options](). For example:
```console
full_name [Luis Morales]: Luis Morales
github_username [lacion]: lacion
app_name [mygolangproject]: echoserver
project_short_description [A Golang project.]: Awesome Echo Server
docker_hub_username [lacion]: lacion
docker_image [lacion/docker-alpine:latest]: lacion/docker-alpine:latest
docker_build_image [lacion/docker-alpine:gobuildimage]: lacion/docker-alpine:gobuildimage
use_docker [y]: y
use_git [y]: y
use_logrus_logging [y]: y
use_viper_config [y]: y
use_cobra_cmd [y]: y
Select use_ci:
1 - travis
2 - circle
3 - none
Choose from 1, 2, 3 [1]: 1
```

Enter the project and take a look around:
```console
$ cd echoserver/
$ ls
```

Run `make help` to see the available management commands, or just run `make build` to build your project.
```console
$ make help
$ make build
$ ./bin/echoserver
```

## Projects build with cookiecutter-golang

- [iothub](https://github.com/lacion/iothub) websocket multiroom server for IoT


cookiecutter-golang

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

goapp

Minimalistic single-file Go HTTP server template without third-party dependencies

# kickstart.go
[![.github/workflows/build.yaml](https://github.com/raeperd/kickstart.go/actions/workflows/build.yaml/badge.svg)](https://github.com/raeperd/kickstart.go/actions/workflows/build.yaml)  [![Go Report Card](https://goreportcard.com/badge/github.com/raeperd/kickstart.go)](https://goreportcard.com/report/github.com/raeperd/kickstart.go) [![Coverage Status](https://coveralls.io/repos/github/raeperd/kickstart.go/badge.svg?branch=main)](https://coveralls.io/github/raeperd/kickstart.go?branch=main) [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)  
Minimalistic HTTP server template in Go that is:
- Small (less than 300 lines of code)
- Single file
- Only standard library dependencies

**Not** a framework, but a starting point for building HTTP services in Go.
This project was first introduced in GopherCon Korea 2024, See [session in this link](https://www.youtube.com/live/DEZsPOSzNM0?si=ioPPAAb5JnOnpAoc&t=5113)(in Korean) and see [presentation in this link](https://raeperd.dev/go2024)(in English)

Inspired by [Mat Ryer](https://grafana.com/blog/2024/02/09/how-i-write-http-services-in-go-after-13-years) & [earthboundkid](https://blog.carlana.net/post/2023/golang-git-hash-how-to/) and even [kickstart.nvim](https://github.com/nvim-lua/kickstart.nvim)

## Features
- Graceful shutdown: Handles `SIGINT` and `SIGTERM` signals to shut down gracefully.
- Health endpoint: Returns the server's health status including version and revision.
- OpenAPI endpoint: Serves an OpenAPI specification using `embed` package
- Debug information: Provides various debug metrics including `pprof` and `expvars`.
- Access logging: Logs HTTP request details using `slog`.
- Panic recovery: Catch and log panics in HTTP handlers gracefully.
- Fully documented: Includes comments and documentation for all exported functions and types.

## Getting started
- Use this template to create a new repository
- Or fork the repository and make changes to suit your needs.

### Requirements
Go 1.24 or later

### Suggested Dependencies
- [golangci-lint](https://golangci-lint.run/)
- [air](https://github.com/air-verse/air)

### Build and run the server

```console
$ make run
```

- this will build the server and run it on port 8080
- Checkout Makefile for more

## Endpoints
- GET /health: Returns the health of the service, including version, revision, and modification status.
- GET /openapi.yaml: Returns the OpenAPI specification of the service.
- GET /debug/pprof: Returns the pprof debug information.
- GET /debug/vars: Returns the expvars debug information.

## How to

### How to start a new project
- Use this template to create a new repository
- Or fork the repository and make changes to suit your needs.
- Find and replace all strings `raeperd/kickstart.go` with your repository/image name

### How to remove all comments from the code

```console
$ sed -i '' '/^\/\/go:embed/! {/^\s*\/\/.*$/d; /^\s*\/\*\*/,/\*\//d;}' *.go
```

## Reference
- [GopherCon Korean 2024 Session](https://www.youtube.com/live/DEZsPOSzNM0?si=ioPPAAb5JnOnpAoc&t=5113) (in Korean)
- [How I write HTTP services in Go after 13 years | Grafana Labs](https://grafana.com/blog/2024/02/09/how-i-write-http-services-in-go-after-13-years/)


kickstart.go

Nunu is a scaffolding tool for building Go applications

<a href="https://trendshift.io/repositories/9047" target="_blank"><img src="https://trendshift.io/api/badge/repositories/9047" alt="go-nunu%2Fnunu | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>


# Nunu — A CLI tool for building Go applications.

Nunu is a scaffolding tool for building Go applications. Its name comes from a game character in League of Legends, a little boy riding on the shoulders of a Yeti. Just like Nunu, this project stands on the shoulders of giants, as it is built upon a combination of popular libraries from the Go ecosystem. This combination allows you to quickly build efficient and reliable applications.

🚀Tips: This project is very complete, so updates will not be very frequent, welcome to use.

- [简体中文介绍](https://github.com/go-nunu/nunu/blob/main/README_zh.md)
- [Português](https://github.com/go-nunu/nunu/blob/main/README_pt.md)
- [日本語](https://github.com/go-nunu/nunu/blob/main/README_jp.md)

![Nunu](https://github.com/go-nunu/nunu/blob/main/.github/assets/banner.png)

## Documentation
* [User Guide](https://github.com/go-nunu/nunu/blob/main/docs/en/guide.md)
* [Architecture](https://github.com/go-nunu/nunu/blob/main/docs/en/architecture.md)
* [Getting Started Tutorial](https://github.com/go-nunu/nunu/blob/main/docs/en/tutorial.md)
* [Unit Testing](https://github.com/go-nunu/nunu/blob/main/docs/en/unit_testing.md)
* [MCP Server](https://github.com/go-nunu/nunu-layout-mcp/blob/main/README.md)


## Features
- **Gin**: https://github.com/gin-gonic/gin
- **Gorm**: https://github.com/go-gorm/gorm
- **Wire**: https://github.com/google/wire
- **Viper**: https://github.com/spf13/viper
- **Zap**: https://github.com/uber-go/zap
- **Golang-jwt**: https://github.com/golang-jwt/jwt
- **Go-redis**: https://github.com/go-redis/redis
- **Testify**: https://github.com/stretchr/testify
- **Sonyflake**: https://github.com/sony/sonyflake
- **Gocron**:  https://github.com/go-co-op/gocron
- **Go-sqlmock**:  https://github.com/DATA-DOG/go-sqlmock
- **Gomock**:  https://github.com/golang/mock
- **Swaggo**:  https://github.com/swaggo/swag
- **Casbin**:  https://github.com/casbin/casbin
- **Pitaya**:  https://github.com/topfreegames/pitaya
- **MCP-GO**:  https://github.com/mark3labs/mcp-go

- More...

## Key Features
* **Low Learning Curve and Customization**: Nunu encapsulates popular libraries that Gophers are familiar with, allowing you to easily customize the application to meet specific requirements.
* **High Performance and Scalability**: Nunu aims to be high-performance and scalable. It uses the latest technologies and best practices to ensure that your application can handle high traffic and large amounts of data.
* **Security and Reliability**: Nunu uses stable and reliable third-party libraries to ensure the security and reliability of your application.
* **Modular and Extensible**: Nunu is designed to be modular and extensible. You can easily add new features and functionality by using third-party libraries or writing your own modules.
* **Complete Documentation and Testing**: Nunu has comprehensive documentation and testing. It provides extensive documentation and examples to help you get started quickly. It also includes a test suite to ensure that your application works as expected.

## Concise Layered Architecture
Nunu adopts a classic layered architecture. In order to achieve modularity and decoupling, it uses the dependency injection framework `Wire`.

![Nunu Layout](https://github.com/go-nunu/nunu/blob/main/.github/assets/layout.png)

## Nunu CLI

![Nunu](https://github.com/go-nunu/nunu/blob/main/.github/assets/screenshot.jpg)


## Directory Structure
```
.
├── api
│   └── v1
├── cmd
│   ├── migration
│   ├── server
│   │   ├── wire
│   │   │   ├── wire.go
│   │   │   └── wire_gen.go
│   │   └── main.go
│   └── task
├── config
├── deploy
├── docs
├── internal
│   ├── handler
│   ├── middleware
│   ├── model
│   ├── repository
│   ├── server
│   └── service
├── pkg
├── scripts
├── test
│   ├── mocks
│   └── server
├── web
├── Makefile
├── go.mod
└── go.sum

```

The project architecture follows a typical layered structure, consisting of the following modules:

* `cmd`: This module contains the entry points of the application, which perform different operations based on different commands, such as starting the server or executing database migrations. Each sub-module has a `main.go` file as the entry file, as well as `wire.go` and `wire_gen.go` files for dependency injection.
* `config`: This module contains the configuration files for the application, providing different configurations for different environments, such as development and production.
* `deploy`: This module is used for deploying the application and includes deployment scripts and configuration files.
* `internal`: This module is the core module of the application and contains the implementation of various business logic.

  - `handler`: This sub-module contains the handlers for handling HTTP requests, responsible for receiving requests and invoking the corresponding services for processing.

  - `job`: This sub-module contains the logic for background tasks.

  - `model`: This sub-module contains the definition of data models.

  - `repository`: This sub-module contains the implementation of the data access layer, responsible for interacting with the database.

  - `server`: This sub-module contains the implementation of the HTTP server.

  - `service`: This sub-module contains the implementation of the business logic, responsible for handling specific business operations.

* `pkg`: This module contains some common utilities and functions.

* `scripts`: This module contains some script files used for project build, test, and deployment operations.

* `storage`: This module is used for storing files or other static resources.

* `test`: This module contains the unit tests for various modules, organized into sub-directories based on modules.

* `web`: This module contains the frontend-related files, such as HTML, CSS, and JavaScript.

In addition, there are some other files and directories, such as license files, build files, and README. Overall, the project architecture is clear, with clear responsibilities for each module, making it easy to understand and maintain.

## Requirements
To use Nunu, you need to have the following software installed on your system:

* Go 1.19 or higher
* Git
* Docker (optional)
* MySQL 5.7 or higher (optional)
* Redis (optional)

### Installation

You can install Nunu with the following command:

```bash
go install github.com/go-nunu/nunu@latest
```

> Tips: If `go install` succeeds but the `nunu` command is not recognized, it is because the environment variable is not configured. You can add the GOBIN directory to the environment variable.

### Create a New Project

You can create a new Go project with the following command:

```bash
nunu new projectName
```

By default, it pulls from the GitHub source, but you can also use an accelerated repository in China:

```
// Use the basic template
nunu new projectName -r https://gitee.com/go-nunu/nunu-layout-basic.git
// Use the advanced template
nunu new projectName -r https://gitee.com/go-nunu/nunu-layout-advanced.git
```

This command will create a directory named `projectName` and generate an elegant Go project structure within it.

### Create Components

You can create handlers, services, repositories, and models for your project using the following commands:

```bash
nunu create handler user
nunu create service user
nunu create repository user
nunu create model user
```
or
```
nunu create all user
```

These commands will create components named `UserHandler`, `UserService`, `UserRepository`, and `UserModel`, respectively, and place them in the correct directories.

### Run the Project

You can quickly run the project with the following command:

```bash
nunu run
```

This command will start your Go project and support hot-reloading when files are updated.

### Compile wire.go

You can quickly compile `wire.go` with the following command:

```bash
nunu wire
```

This command will compile your `wire.go` file and generate the required dependencies.

## Contribution

If you find any issues or have any improvement suggestions, please feel free to raise an issue or submit a pull request. Your contributions are highly appreciated!

## License

Nunu is released under the MIT License. For more information, see the [LICENSE](LICENSE) file.

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=go-nunu/nunu&type=Date)](https://star-history.com/#go-nunu/nunu&Date)


nunu

Rapid, easy full-stack web development starter kit built in Go

pagoda

AI-friendly, production-ready Go REST API boilerplate with clean architecture, JWT authentication, RBAC, PostgreSQL, Docker hot-reload, and Swagger documentation

go-rest-api-boilerplate

A sample layout for Go application projects with the real code

# go-sample

[![Build Status](https://travis-ci.org/zitryss/go-sample.svg?branch=master)](https://travis-ci.org/zitryss/go-sample)
[![codecov](https://codecov.io/gh/zitryss/go-sample/branch/master/graph/badge.svg)](https://codecov.io/gh/zitryss/go-sample)
[![Go Report Card](https://goreportcard.com/badge/github.com/zitryss/go-sample)](https://goreportcard.com/report/github.com/zitryss/go-sample)
[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/zitryss/perfmon/blob/master/LICENSE)

A sample layout for Go application projects with the real code.



## Where it all comes from?

Ideas used to create the architecture and structure:
* [The Clean Architecture](http://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
* [DDD, Hexagonal, Onion, Clean, CQRS, … How I put it all together](https://herbertograca.com/2017/11/16/explicit-architecture-01-ddd-hexagonal-onion-clean-cqrs-how-i-put-it-all-together/)
* [Clean Architecture using Golang](https://medium.com/@eminetto/clean-architecture-using-golang-b63587aa5e3f)
* [Applying The Clean Architecture to Go applications](https://manuel.kiessling.net/2012/09/28/applying-the-clean-architecture-to-go-applications/)
* [Standard Package Layout](https://medium.com/@benbjohnson/standard-package-layout-7cdbc8391fc1)
* [How Do You Structure Your Go Apps](https://youtu.be/oL6JBUk6tj0)
* [How I write Go HTTP services after seven years](https://medium.com/statuscode/how-i-write-go-http-services-after-seven-years-37c208122831)



## Requirements

* [git](https://git-scm.com/)
* [docker](https://www.docker.com/)



## Installation

```
git clone https://github.com/zitryss/perfmon.git
```



## Usage

```
docker-compose up --build
```


go-sample

A simple skeleton for golang application with basic setup for real golang application

# GoBase

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Go Report Card](https://goreportcard.com/badge/github.com/wajox/gobase)](https://goreportcard.com/report/github.com/wajox/gobase)
[![Go Reference](https://pkg.go.dev/badge/github.com/wajox/gobase.svg)](https://pkg.go.dev/github.com/wajox/gobase)
[![codecov](https://codecov.io/gh/wajox/gobase/branch/master/graph/badge.svg?token=0K79C2LH2K)](https://codecov.io/gh/wajox/gobase)
[![Build Status](https://travis-ci.org/wajox/gobase.svg?branch=master)](https://travis-ci.org/wajox/gobase)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

This is a simple skeleton for golang application. Inspired by development experience and updated according to github.com/golang-standards/project-layout.

## How to use?

1. Clone the repository (with git client `git clone github.com/wajox/gobase [project_name]` or use it as template on github for creating a new project)
2. replace `github.com/wajox/gobase` with `[your_pkg_name]` in the all files

## Structure

* /api - OpenAPI specs, documentation generated by swag
* /cmd - apps
* /db - database migrations and seeds
* /docs - documentation
* /internal - application sources for internal usage
* /pkg - application sources for external usage(SDK and libraries)
* /test - some stuff for testing purposes

## Commands
```sh
# install dev tools(wire, golangci-lint, swag, ginkgo)
make install-tools

# start test environment from docker-compose-test.yml
make start-docker-compose-test

# stop test environment from docker-compose-test.yml
make stop-docker-compose-test

# build application
make build

# run all tests
make test-all

# run go generate
make gen

# generate OpenAPI docs with swag
make swagger

# generate source code from .proto files
make proto

# generate dependencies with wire
make deps
```

## Create new project

## With [clonegopkg](https://github.com/wajox/clonegopkg)

```sh
# install clonegopkg
go install github.com/wajox/clonegopkg@latest

# create your project
clonegopkg clone git@github.com:wajox/gobase.git github.com/wajox/newproject

# push to your git repository
cd ~/go/src/github.com/wajox/newproject
git add .
git commit -m "init project from gobase template"
git remote add origin git@github.com:wajox/newproject.git
git push origin master

```


## Tools and packages
* gin-gonic
* ginkgo with gomega
* spf13/viper
* spf13/cobra
* envy
* zerolog
* golangci-lint
* wire
* swag
* migrate
* protoc
* jsonapi
* docker with docker-compose


gobase

Golang project layout generator with plugins

# inizio

Golang project standard layout generator

[![GitHub Workflow Status](https://github.com/insidieux/inizio/workflows/Test/badge.svg)](https://github.com/insidieux/inizio/actions/workflows/test.yml?query=branch%3Amaster+event%3Apush)
[![Go Report Card](https://goreportcard.com/badge/github.com/insidieux/inizio)](https://goreportcard.com/report/github.com/insidieux/inizio)
[![codecov](https://codecov.io/gh/insidieux/inizio/branch/master/graph/badge.svg?token=BI6HEMPLB1)](https://codecov.io/gh/insidieux/inizio/branch/master)
![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/insidieux/inizio)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

`inizio` is a simple binary, which allows generating/bootstrapping golang project with [predefined layout](https://github.com/golang-standards/project-layout).

This project is easy can be extended, cause it also supports plugins for generation, based on [go-plugin](https://github.com/hashicorp/go-plugin) package. 

## Installing

Install `inizio` by running:

```shell
go get github.com/insidieux/inizio/cmd/inizio
```

## Usage

```shell
inizio \
  --plugins.config /etc/inizio/plugins.yaml \
  --plugins.path /usr/local/bin/inizio-plugins \
    path-to-project
```

## Example

![](./docs/inizio.gif)

Ensure that `$GOPATH/bin` is added to your `$PATH`.

## Documentation

- [User guide][]
- [Contributing guide][]
- [Write plugin guide][]

[User guide]: ./docs/user-guide.md
[Contributing guide]: ./docs/contributing.md
[Write plugin guide]: ./docs/write-plugin-guide.md


## License

[Apache][]

[Apache]: ./LICENSE


insidieux/inizio

Scaffold generates a starter Go project layout. Lets you focus on business logic implemented

# scaffold

[![Build Status](https://travis-ci.org/catchplay/scaffold.svg)](https://travis-ci.org/catchplay/scaffold)
[![codecov](https://codecov.io/gh/catchplay/scaffold/branch/master/graph/badge.svg)](https://codecov.io/gh/catchplay/scaffold)
[![Go Report Card](https://goreportcard.com/badge/github.com/catchplay/scaffold)](https://goreportcard.com/report/github.com/catchplay/scaffold)
[![GoDoc](https://godoc.org/github.com/catchplay/scaffold?status.svg)](https://godoc.org/github.com/catchplay/scaffold)

Scaffold generates starter Go project layout. Let you can focus on  buesiness logic implemeted. 

[![asciicast](https://asciinema.org/a/MA0ppdKfZSEl64cskUnqfsSiH.svg)](https://asciinema.org/a/MA0ppdKfZSEl64cskUnqfsSiH?autoplay=1&speed=2)

The following is Go project layout scaffold generated:

```
├── Dockerfile
├── Makefile
├── README.md
├── cmd
│   └── main.go
├── config
│   ├── config.go
│   ├── config.yml
│   ├── database.go
│   ├── http.go
│   └── release.go
├── docker-compose.yml
├── model
│   └── model.go
└── web
    ├── routes.go
    ├── server.go
    └── version.go
```

## Installation

 Download scaffold by using:
```sh
$ go get -u github.com/catchplay/scaffold
```

## Create a new project

1. Going to your new project folder:
```sh
# change to project directory
$ cd $GOPATH/src/path/to/project
```

2. Run `scaffold init` in the new project folder:

```sh
$ scaffold init
```

3. That will generate a whole new starter project files like:

```
Create Dockerfile
Create README.md
Create cmd/main.go
Create config/config.go
Create config/database.go
Create config/http.go
Create config/release.go
Create docker-compose.yml
Create model/model.go
Create web/routes.go
Create web/server.go
Create web/version.go
Create Makefile
Create config/config.yml
Success Created. Please excute `make up` to start service.

```

4. And you can run the new project by using:
```sh
$ make run 
```

The Best Go Libraries For Miscellaneous - Project Layout (20)