2017-09-09 16:39:12 +00:00
# Standard Go Project Layout
2017-09-09 20:10:53 +00:00
This is a basic layout for Go application projects. It represents the most common directory structure with a number of small enhancements along with several supporting directories common to any real world application.
2017-09-09 22:18:01 +00:00
Clone the repository, keep what you need and delete everything else!
2017-09-11 21:09:15 +00:00
[Go Project Layout ](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2 ) - additional background information.
2017-09-09 22:18:01 +00:00
## Go Directories
2017-09-11 18:50:28 +00:00
### `/cmd`
2017-09-09 22:18:01 +00:00
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` ).
2018-02-01 01:45:24 +00:00
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!
2017-09-09 22:18:01 +00:00
It's common to have a small main function that imports and invokes the code from the `/internal` and `/pkg` directories.
2017-09-11 18:50:28 +00:00
### `/internal`
2017-09-09 22:18:01 +00:00
Private application and library code.
Put your actual application code 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` ).
2017-09-11 18:50:28 +00:00
### `/pkg`
2017-09-09 22:18:01 +00:00
Library code that's safe 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 :-)
2017-09-11 18:50:28 +00:00
### `/vendor`
2017-09-09 22:18:01 +00:00
Application dependencies (managed manually or by your favorite dependency management tool).
Don't commit your application dependencies if you are building a library.
## Service Application Directories
2017-09-11 18:50:28 +00:00
### `/api`
2017-09-09 22:18:01 +00:00
OpenAPI/Swagger specs, JSON schema files, protocol definition files.
## Web Application Directories
2017-09-11 18:50:28 +00:00
### `/web`
2017-09-09 22:18:01 +00:00
Web application specific components: static web assets, server side templates and SPAs.
## Common Application Directories
2017-09-11 18:50:28 +00:00
### `/configs`
2017-09-09 22:18:01 +00:00
Configuration file templates or default configs.
Put your `confd` or `consule-template` template files here.
2017-09-11 18:50:28 +00:00
### `/init`
2017-09-09 22:18:01 +00:00
System init (systemd, upstart, sysv) and process manager/supervisor (runit, supervisord) configs.
2017-09-11 18:50:28 +00:00
### `/scripts`
2017-09-09 22:18:01 +00:00
Scripts to perform various build, install, analysis, etc operations.
These scripts keep the root level Makefile small and simple.
2017-09-11 18:50:28 +00:00
### `/build`
2017-09-09 22:18:01 +00:00
Packaging and Continous 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.
2017-09-11 18:50:28 +00:00
### `/deployments`
2017-09-09 22:18:01 +00:00
2017-09-11 06:17:05 +00:00
IaaS, PaaS, system and container orchestration deployment configurations and templates (docker-compose, kubernetes/helm, mesos, terraform, bosh).
2017-09-09 22:18:01 +00:00
2017-09-11 18:50:28 +00:00
### `/test`
2017-09-09 22:18:01 +00:00
Additional external test apps and test data.
## Other Directories
2017-09-11 18:50:28 +00:00
### `/docs`
2017-09-09 22:18:01 +00:00
2017-09-11 06:17:05 +00:00
Design and user documents (in addition to your godoc generated documentation).
2017-09-09 22:18:01 +00:00
2017-09-11 18:50:28 +00:00
### `/tools`
2017-09-09 22:18:01 +00:00
Supporting tools for this project. Note that these tools can import code from the `/pkg` and `/internal` directories.
2017-09-11 18:50:28 +00:00
### `/examples`
2017-09-09 22:18:01 +00:00
Examples for your applications and/or public libraries.
2017-09-11 18:50:28 +00:00
### `/third_party`
2017-09-09 22:18:01 +00:00
External helper tools, forked code and other 3rd party utilities (e.g., Swagger UI).
2017-09-11 18:50:28 +00:00
### `/githooks`
2017-09-09 22:18:01 +00:00
Git hooks.
2017-09-11 18:50:28 +00:00
### `/assets`
2017-09-09 22:18:01 +00:00
Other assets to go along with your repository.
2017-09-11 06:17:05 +00:00
## Badges
2017-09-09 22:18:01 +00:00
2017-09-11 18:16:11 +00:00
* [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.
* [GoDoc ](http://godoc.org ) - It will provide online version of your GoDoc generated documentation. Change the link to point to your project.
* Release - It will show the latest release number for your project. Change the github link to point to your project.
2017-09-11 06:17:05 +00:00
[](https://goreportcard.com/report/github.com/golang-standards/project-layout)
[](http://godoc.org/github.com/golang-standards/project-layout)
[](https://github.com/golang-standards/project-layout/releases/latest)
2017-09-09 22:18:01 +00:00
2017-09-11 18:16:11 +00:00
## Notes
2017-09-09 22:18:01 +00:00
2017-09-11 18:16:11 +00:00
A more opinionated project template with sample/reusable configs, scripts and code is a WIP.
2017-09-09 20:10:53 +00:00
