Go Project: Difference between revisions
Line 128: | Line 128: | ||
=Microservice-based Project Layout= | =Microservice-based Project Layout= | ||
{{Internal|Microservices_in_Go#Project_Layout|Microservices in Go | Project Layout}} | {{Internal|Microservices_in_Go#Project_Layout|Microservices in Go | Project Layout}} | ||
=Project Bootstrap= | |||
<font color=darkkhaki>Follow the same template as [[Python Project Bootstrap]]. Use | |||
=TODO= | =TODO= |
Revision as of 19:09, 19 September 2024
External
- https://github.com/golang-standards/project-layout
- https://medium.com/@benbjohnson/standard-package-layout-7cdbc8391fc1
Internal
TODO
- Where are the generated executables placed? In a transient
./build
? This is how YuniKorn does it. The project layout document does not say anything about it.
Overview
This page collects recommendation and facts about Go projects and it was mainly written with the assumption that one project lives in its own repository and contains a single module, as described in Packages, Modules, Projects and Repositories. Of course project can contain multiple modules, but that is not recommended.
A Java-style /src
is not recommended.
Project Layout
This layout is inspired by:
. ├── api │ ├── openapi.yaml │ ├── openapi-spec.gen.go # Generated from openapi.yaml │ ├── openapi-types.gen.go # Generated from openapi.yaml │ └── file1.proto, ... ├── protobuf # Alternative directory for Protocol Buffer files. │ ├── somepkgpb │ │ ├── file1.proto │ │ └── file2.proto │ └── someotherpkgpb │ ├── file3.proto │ └── file4.proto │ ├── cmd │ ├── myserver │ │ └── main.go │ └── myclient │ └── main.go ├── pkg ├── internal │ └── server │ └── openapi-http-server.gen.go # Generated from openapi.yaml ├── config ├── scripts │ ├── build-myserver.sh │ └── build-myclient.sh ├── docs ├── Makefile ├── README.md ├── go.mod ├── go.sum └── .gitignore
Directories
api
The directory contains OpenAPI specification files, JSON schema files, protocol definition files.
One option is to also place the type and the spec files generated by the OpenAPI code generator, as shown in the layout above. For more details on how to generate code from the OpenAPI specification, see:
Protocol Buffer Support
Protocol Buffer files can be placed in this directory. Alternatively, a protobuf
or a protocol
can be used. Also see:
cmd
The directory contains the main applications for this project. If the project has multiple executables, the code fore each should live under their own directory, and the name of the directory should match the name of the executable. This convention aligns with the behavior of the go build
command, which names the executable after the name of its parent directory. The Go code file name can be either main.go
, which is preferred, or the name of the command myserver.go
. Different projects use one of these two conventions. Do not put a lot of code in the /cmd
directory. If you think the code can be imported and used in other projects, put it in the /pkg
directory. If the code is not reusable, put it in the /internal
directory. It's common to have a small main
function that imports and invokes the code from the /internal
and /pkg
directories and nothing else.
main.go
Some project name this file myserver.go
.
package main
import "fmt"
func main() {
fmt.Print("starting my service ...\n")
}
pkg
Place here the packages publicly exported by the module. The presence of a package in this directory shows that it is OK to be used by external applications. Other projects will import these libraries expecting the to work, so think twice before putting something there. The internal
directory is a better way to ensure your private packages are not importable, because this is enforced by the complier.
internal
This is the module code that shouldn't be imported by the module's dependent application or libraries. This layout pattern is enforced by the Go compiler. For more details, see:
config
Configuration file templates and default configuration.
scripts
This directory contain scripts to perform various build functions, install, analysis, etc.
They should be used by Makefile
, which will keep the file small and simple.
docs
Generated documentation, user documentation, design documentation.
Files
Makefile
Makefile
should prefer to use scripts from the /scripts
directory, which should keep it simple.
.PHONY: build
build: myserver myclient
myserver:
"$(CURDIR)/scripts/build-myserver.sh"
myserver:
"$(CURDIR)/scripts/build-myclient.sh"
Example to process: https://github.com/hashicorp/terraform/blob/main/Makefile
Generated Code
Placed within the regular layout, though files have a .gen.go
extension.
Microservice-based Project Layout
Project Bootstrap
Follow the same template as Python Project Bootstrap. Use
TODO
- Finish parsing https://github.com/golang-standards/project-layout
- Integrate Vendoring