golang-standards / project-layout Goto Github PK
View Code? Open in Web Editor NEWStandard Go Project Layout
License: Other
Standard Go Project Layout
License: Other
I've always been a big fan of go and this is my first time trying to follow a suggested structure for my project instead of just making it up.
I was trying to use the internal/app/_your_app_
structure with a go module. To achieve this I had to add the below to my go.mod file and had to add a go.mod file to the relative folder, as I wanted to import as "github.com/sc7639/network-cli-tool/internal/app/command"
.
require github.com/sc7639/network-cli-tool/internal/app v0.0.0
replace github.com/sc7639/network-cli-tool/internal/app => ./internal/app/network-cli/
I'm just wondering if this is how you would suggest doing it or if there is a better way I'm seeing?
Thanks in advance for any help.
When using "Standard Go Project Layout" I face serious issue with /web
directory, which in my case contains really big frontend project. I'm working with yarn workspaces in that folder, so when I run for instance go mod tidy
command I'm getting the following warnings:
warning: ignoring symlink /home/sysadmin/Documents/<project>/web/node_modules/<some package>
Also I'm not sure if scanning entire /web folder for anything related to Go is very effecient.
So one possible solution is to rename /web
to /_web
.
P.S. running go help packages
we get the following:
...
Directory and file names that begin with "." or "_" are ignored
by the go tool, as are directories named "testdata".
What is a common approach when building API Server from swagger spec file (usually swagger.yml).
Command swagger generate server...
generates a bunch of .go files. Where those generated .go files should be placed.
Is a good approach to put them to /pkg/api/ ?
The examples folder seems to conflict with: Use singular form for collection repo/folder name. Thoughts?
This is a common layout pattern, but it's not universally accepted and some in the Go community don't recommend it.
In the /pkg
section; either state the pros/cons or link to something that expounds
I'd like to contribute a Traditional Chinese (zh-TW
) version of the README.
hi,
where to store cgo files? such as .h .so?
where put paths and router to make an API in this arquitecture
Go language documentation itself suggested to use the src directory. Why did you mention in your README that src should not be used.
If I want to add the Japanese version, should I add a file like README_ja.md
?
Also, when reviewing, I plan to have some Japanese people look at it.
Hello,
I'm new to go and have what I think is an extremely basic question: Where are the go.mod and go.sum file or files? Edit: and a follow on question, can you provide some example of go.mod files?
Thanks
This repo owner confuses beginners (golang-standards), actually its' not a standard. It's just an opinion of a group of coders and historical reasons as it's mentioned in the README and part of the project structure is a bad practice ( like vendor or pkg directories, we have something called mods now!) . I suggest to move this project to another organization called "golang-non-standard" or remove it.
The existence of this repository is harmful for Go beginners. People arrive here from Google searches, looking for ways to structure their small, simple packages. What they find is overwhelming, at the least.
It has several serious issues:
go.mod
file, while modules are becoming a standard for Go dependency managementpkg/
, which is outdated advice and no longer recommended for Go projects (as it adds a superfluous path component to every import).Please either spend some time to modernize this project, or delete it
It would be really helpful if you can give an example on how to use this layout for gRPC based microservice systems, since gRPC and Microservices are quiet common now a days.
Every document or blog I have found are merely some simple helloworld crap with a single directory of source files and no external libraries.
I'm trying to convert my k8s controller to using go modules because getting our CI/CD system to work with dep is an ungodly nightmare.
Is there a good doc or example of someone using go modules with a complex directory structure of many go packages at multiple levels?
What a hair-pulling nightmare go dependencies are.
Where to put "web" assets like .css
, .scss
/.sass
, .less
that need build, minify and copy to "web/static"?
Hi, I was wondering, where would you store .ddl files? In /configs
? In the same directory as the go database code that uses it?
Happy to see this attempt, but none of the decisions or suggestions are explained.
If there are valid reasons to use such a structure, it should be easy to list those reasons.
As someone who has my own preferred structure, I would need some reasons to switch. "Unifying everyone's structure" is a great argument for a unified structure, but not necessarily this structure.
Is there a best practice in GO for file server path name?
I can imagine "/files
" or "/static
".
What do you think?
Where should the generated Log and similar files be stored?
Named a storage
floader in the root directory?
It seems common to have a "testdata" directory for additional test data. Any specific reason why it's not included in this repo?
Hi, guys!
Thanks for repo, it's useful.
But I confused about a place of templates, localization files, sql files in the project structure. What do you think about that?
Thanks for showing how to name the directories. I also need to know how to:
How about adding some example code? Ideally, this would be a complete buildable repository with short .go
files and Makefile
that show best practices for building, running tests, linting, etc.
It would be great to incorporate the solution for golang/go#37554 , to save folks from having to understand 27 pages of technical discussion.
These things are not at all obvious. For example, the obvious command go build ...
does not produce any binaries. Running go build -v ...
produces no output and go build -vvv ...
doesn't work. And if I manage to produce a binary with go build cmd/example/example.go
, the corresponding go clean
does not delete it. Please put the appropriate commands in Makefile
.
Here's example code to get started:
// go.mod
// Allow others to import this module into their projects or use `go install`:
module github.com/org1/example
// For private code:
//module _/example
go 1.14
// lib1/lib1.go
package lib1
import "fmt"
func Func1() {
fmt.Println("lib1.Func1()")
}
// pkg/lib2/lib2.go
package lib2
import "fmt"
func Func2() {
fmt.Println("lib2.Func2()")
}
// cmd/example/example.go
package main
import (
"github.com/org1/example/lib1"
"github.com/org1/example/pkg/lib2"
// "_/example/lib1"
// "_/example/pkg/lib2"
)
func main() {
lib1.Func1()
lib2.Func2()
}
# Makefile
#GOCACHE=output/cache/ fails with "GOCACHE is not an absolute path"
GO_BUILD=go build -pkgdir output/pkg/ -i -o output/ -v -trimpath
buid: mkoutput
${GO_BUILD} ./...
mkoutput:
mkdir -p output/ output/pkg/
clean:
rm -rf output/
$ make
mkdir -p output/ output/pkg/
go build -pkgdir output/pkg/ -i -o output/ -v -trimpath ./...
runtime/internal/sys
math/bits
internal/race
unicode/utf8
unicode
runtime/internal/atomic
internal/cpu
sync/atomic
runtime/internal/math
internal/testlog
internal/bytealg
math
runtime
internal/reflectlite
sync
errors
sort
internal/oserror
io
strconv
syscall
reflect
internal/syscall/execenv
internal/syscall/unix
time
internal/poll
os
internal/fmtsort
fmt
github.com/org1/example/lib1
github.com/org1/example/pkg/lib2
github.com/org1/example/cmd/example
$ ls -alF output/
total 4240
drwxr-xr-x 4 user staff 128 Jul 9 17:03 ./
drwxr-xr-x 8 user staff 256 Jul 9 17:03 ../
-rwxr-xr-x 1 user staff 2170120 Jul 9 17:03 example*
drwxr-xr-x 20 user staff 640 Jul 9 17:03 pkg/
$ ./output/example
lib1.Func1()
lib2.Func2()
$ make clean
rm -rf output/
$
Edit: Added alternative _/example
module name. Ran go clean -cache
and now build command shows output.
The first thing you will run into when using go.mod, putting code outside GOPATH, and using the recommended folder structure is that your cmd/ does not have access to your internal or pkg folder. Therefore you are automatically required to resort to using the require/replace fix to actually get access to the code or actually split your code into actual modules and upload separately.
While the require/replace fix works and builds, your IDE will probably still have problems picking up the imports for good code navigation unless you manually update your go.mod file in the pkg or internal folder. (you cant use go build to update your go.mod/sum file as there is nothing to build in the folder) Of course, this is more of an IDE problem.
module some-api
replace some-pkg v0.0.0 => ../../pkg
require (
some-pkg v0.0.0
)
Would people still recommend this folder layout when using go modules, have multiple cmd applications, and especially when putting code outside the gopath? I am curious as I see more and more people starting to use modules and putting their code in a GOPATH-less environment and this is for sure bound to create problems and confusion when using modules as it requires "some" custom setup. Of course, nothing major once you figure it out.
Come to think of it, this is more of a general issue with go mod. You will run into this issue from the moment you put your main.go file in a subfolder and not the root.
The general consensus of the Go community has been converging on the idea that the pkg/
directory is a useless abstraction / indirection. Instead, people are encouraged to either put the packages in the top-level of the repository, or to create a repository structure that structures things based on their primary functionality of domain in the business logic.
So while in your example you may encourage people to have the following layout:
pkg/
server/
handlers/
poller/
config/
manager/
We instead would prefer:
server/
handlers/
poller/
config/
manager/
This may seem innocuous, but because this project has asserted itself as some sort of Go standards body what is being recommended here is being taken seriously. In the Slack workspace, where there are over 30k registered users, we quite often need to correct people who are using pkg/
and have them ignore the recommendations here. Some of the things recommended here are good, and I'd like to be able to use them as a resource. That said, considering the current pkg/
recommendation we're hard-pressed to use this as a resource because we have to tell people to ignore certain parts.
Hey,
I was wonderin what you think about the official Go documentation, which recommends creating a src
folder, whereas you tell us not to.
Here's the link: https://golang.org/doc/code.html
Hi,
I've created this question https://stackoverflow.com/questions/47788850/go-project-structure-best-practise in stack overflow and I wonder if the repo author can give is insight.
Thanks,
Sofia
Generally I'm still unsure about pkg, but lets keep that there #10. It still applies that you need your lib for external use must be independent from internal stuff.
Assuming I'd like to follow the current project-layout consensus, especially /pkg
and /internal
:
I have a lib implementing this requiring the implementer to return its app's current version here.
Now, the app's current version lays perfectly somewhere in /internal
and I really like not to have an include into /internal
.
version string
parameter, Version
field in a struct or SetVersion(version string)
method and such. That approach looks messy, as I probably would have to carry that option multiple "layers", but the caller has ultimate choice. But I don't like the option at all, that the caller has to set a version...Your thoughts from your angle?
`#!/bin/bash
PWD=$(pwd)
cd $PWD
if [[ "$1" = "" ]]; then
echo -ne "Please Input The Golang Porject Name: "
read project
if [ "$project" = "" ]; then
echo -e "demo";
PRO_NAME=demo;
else
PRO_NAME=$project;
fi
else
PRO_NAME=$1;
fi
#build directory
echo "Init $PRO_NAME Directory …"
mkdir -p $PRO_NAME/api
mkdir -p $PRO_NAME/assets
mkdir -p $PRO_NAME/build
mkdir -p $PRO_NAME/cmd
mkdir -p $PRO_NAME/conf
mkdir -p $PRO_NAME/deployments
mkdir -p $PRO_NAME/docs
mkdir -p $PRO_NAME/examples
mkdir -p $PRO_NAME/githooks
mkdir -p $PRO_NAME/init
mkdir -p $PRO_NAME/internal
mkdir -p $PRO_NAME/pkg
mkdir -p $PRO_NAME/scripts
mkdir -p $PRO_NAME/test
mkdir -p $PRO_NAME/third_patry
mkdir -p $PRO_NAME/tools
mkdir -p $PRO_NAME/vendor
mkdir -p $PRO_NAME/web
mkdir -p $PRO_NAME/website
cd $PRO_NAME
touch .gitkeep
go mod init $PRO_NAME
echo "Generate main.go "
cd cmd
echo "package main" > main.go
echo >> main.go
echo "import (" >> main.go
echo " \"fmt\"" >> main.go
echo ")" >> main.go
echo >> main.go
echo "func main() {" >> main.go
echo " fmt.Println(\"Hello $PRO_NAME!\")" >> main.go
echo "}" >> main.go
gofmt main.go
echo "Init $PRO_NAME Success!"`
Your comments on the use of a src/ directory aren't correct, at least in the GOPATH approach which has been the recommendation in the past:
https://golang.org/doc/gopath_code.html
Here's what happens if you don't have a src/ directory in your project:
lctl.go:3:8: cannot find package "lctlutil" in any of:
/home/dean/bin/go1.14.linux-amd64/go/src/lctlutil (from $GOROOT)
/home/dean/src/golang/integration/lctl/src/lctlutil (from $GOPATH)
/home/dean/src/golang/go3p/src/lctlutil
Go looks for a src/ directory.
Also the link in that section points to an updated page which doesn't mention the src/ directory. Apparently it has been updated for modules.
I've a service account file generated by Google which contains (secret) keys. I can't conclude from the current setup where to put these into.
My first idea was configs
. But for me, configs
can be public.
Does anyone have sample of dockerfile for standard project layout for the multi stage build ?
please help
Pulling out my hair to do something as simple (or in go- complex) as using dep
, gb
and make
to perform a simple build of a repo with this structure. Even if its opinionated it would help to show
Makefile
including gb
(the refs are good but much too complex for a beginner)dep
for installing dependencies as part of the make processWhat is a common approach when project is using a protobuf and gRPC?
*.proto
files?Thanks to everyone!
Hello,
It seems godoc can't find this project. My best guess is because there's no go files in this project. However, I'm getting the same behavior in a project of mine which has go files, just not in root directory. You can see by the broken badges in README.md. Any suggestions regarding the best way to solve this? Rethink this aspect of the project structure or check with the guys in godoc to see what can be done over there?
What happens if I put the frontend (SPA) inside the Web directory once I need to deploy ?
I mean, I use CI to build let's say three Docker containers, reprsenting my three microservices. With Cobra.
They are called mysoftware-collector
and mysoftware-pusher
and mysoftware-server
.
And on another Git repository, I develop the mysoftware-frontend
with Angular.
If I use the /web
for the frontend Angular files. How do I deploy it ?
Thanks !
I am building a microservices project with services written in Go, Python and JavaScript for the frontend, what is the best way to structure a multi language monorepo?
del
I was wondering what the internal/app
directory was for, exactly. The README.md says:
Put your actual application code in the
/internal/app
directory
What does it mean by your "actual application code"? I thought that application code goes in the /cmd/<app_name>/
directory. And if it's not part of the main package, shouldn't it then, by definition, be a package that belongs in either /pkg/
or /internal/pkg/
?
I've been placing internal packages directly in the /internal/
directory, and it's been working out well. I know this repo is simply a suggestion, and I might continue to do what I've been doing, but it would be awesome if you could explain to me why you chose the way that the docs suggest, as it might be better than my way for reasons I don't yet know. Thanks!
Add readme chinese translation.
As shown below.
This is a basic layout for Go application projects. It's not an official standard defined by the core Go dev team; however, it 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.
这是Go应用程序项目的基础布局。这不是Go核心开发团队定义的官方标准;无论是在经典项目还是在新兴的项目中,这都是Go生态系统中一组常见的项目布局模式。这其中有一些模式比另外的一些更受欢迎。它通过几个支撑目录为任何足够大规模的实际应用程序提供一些增强功能。
Thank you for this project. GitHub has just shipped a new feature that allows to mark a repository as a template for new repositories. Setting it up should take just a minute, but it's not something other developers can do via Pull Requests: it requires admin privileges.
Here's how to do it: https://github.blog/2019-06-06-generate-new-repositories-with-repository-templates/
The name organization name golang-standards
is misleading for beginners and people new to Go. It implies that the included repositories - which are misleading as well, btw - conclude official standards, which is definitly not the case.
The directories starting with .
or _
are not ignored by Go. At least I tried importing exported symbols from those packages and it totally works and builds
Not sure what do you mean by the phrase:
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
Why "web/template" (singular) instead of "web/templates" (plural)?
Please, delete this repo, because it brings nothing else but confusion and encourages bad practices in go (a lot around naming) especially for beginners.
Especially it's bad when new go developers start to advocate bad practices and use this repo as a reference.
Instead, create a list of resources that would bring knowledge about the "industry standards" (the way how go is written in stdlib)
Like those:
https://tour.golang.org/welcome/1
https://gobyexample.com/
https://blog.golang.org/context
https://ekocaman.com/go-context-c44d681da2e8
Would highly recommend to read this even if you’re advanced Gopher - http://devs.cloudimmunity.com/gotchas-and-common-mistakes-in-go-golang/
https://rakyll.org/style-packages/
One of the famous figures and main contributors to Go language, Rakyll, writes about importance of naming and structuring of the packages.
https://golang.org/doc/effective_go.html
Effective Go article is a community evangel of how effective Go code should be written.
https://github.com/golang/go/wiki/CodeReviewComments
Wiki page from Go repository with idiomatic code habits that would help you to avoid traps of trying to write Java (or C#, or TypeScript, or Javascript) in Go which never works.
https://www.youtube.com/watch?v=LMSbsW1Xpwg
In this lightning talk, Ben Johnson gives a quick idea of what kind of issues you might face with inappropriate project structure
https://www.youtube.com/watch?v=PTE4VJIdHPg
Peter Bourgon dives deeper into the ways of setting up the project structure that are more adopted within the industry, providing also more justifications on an issues that he was facing on his Go journey. A lot of his practices are widely used within the Go community.
What would be the approach to deploy the cmd/<name>/main.go
structure to Google App Engine?
The regular command gcloud app deploy --project=<whatever>
won't pick up that the main file is in another folder, and the entry file cannot be specified to the command.
I suppose the only hack-around would be to put the main.go
in the base directory for deployment purposes? Feels dirty.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.