Although there is no official mandatory standard for the Go project structure, the community generally adopts an organization method with directories such as cmd, internal, and pkg as the core. 1. cmd/ stores the main program entrance, and each executable file corresponds to a subdirectory. main.go only serves as initialization and startup services; 2. internal/ stores private business logic, layered by handler, service, repository, and model to ensure that the code is decoupled and cannot be referenced externally; 3. pkg/ stores public libraries that can be reused by external projects; 4. api/ stores interface definition files for gRPC or OpenAPI and supports version management; 5. config/stores configuration files for different environments, scripts/stores construction, deployment, migration and other automation scripts; 6. deploy/ contains Dockerfile and K8s deployment lists to facilitate CI/CD integration; 7. tests/ can store integrated or end-to-end test cases, different from unit tests. This structure is suitable for medium and large projects. Small projects can be simplified into main.go with handler, service, model and other basic directories. The key is to keep the logic clear and easy to maintain.

There are no official mandatory standards for the Go project structure, but the community widely adopts some conventional organizational methods, especially referring to the practices recommended by the official Go open source projects (such as Kubernetes, Terraform) and the Go team. Below is a typical example of Go project structure suitable for medium and large projects and explains the role of each directory.

? Typical Go project structure

 my-project/
├── cmd/ # Main program entrance│ └── app/ # For example: cmd/app/main.go
│ └── main.go
├── internal/ # Private business logic, not exposed to the outside world│ ├── handler/ # HTTP processor│ ├── service/ # Business service layer│ ├── repository/ # Data access layer (DB, cache, etc.)
│ ├── model/ # Data structure definition (such as structure)
│ └── config/ # Configuration parsing and management ├── pkg/ # Reusable public library (can be referenced by external projects)
│ └── util/
│ └── logger.go
├── api/ # API documentation or proto file (gRPC)
│ └── v1/
├── config/ # configuration file (YAML, JSON, etc.)
│ └── config.yaml
├── scripts/ # scripts: deployment, construction, database migration, etc.│ ├── deploy.sh
│ └── migrate.sh
├── deploy/ # Deployment related: Dockerfile, K8s list, etc.│ ├── Dockerfile
│ └── k8s/
├── tests/ # External test script or integration test case│ └── integration_test.go
├── go.mod # Go module definition ├── go.sum # Dependency verification└── README.md

? Why organize like this?

1. cmd/ —— Program entry

• Each executable file corresponds to a subdirectory (such as cmd/api , cmd/worker ).
• main.go is here, responsible for initializing dependencies and starting services.
• Keep main.go concise and only do "glue code".

 // cmd/app/main.go
package main

import "my-project/internal/handler"

func main() {
    handler.StartServer()
}

2. internal/ ——Private code

• All code that you don't want to be imported by external projects is placed here.
• Go language native support: packages under internal cannot be import by external modules.
• Divide catalogs by responsibilities (similar to MVC or Clean Architecture):
  • model : Structural definition (such as User, Post)
  • repository : Interaction with database (CRUD)
  • service : business logic (such as creating a user, sending messages)
  • handler : HTTP routing processing (docking with Gin, Echo, etc.)

3. pkg/ ——Reusable public package

• Stores tool functions or general components that can be referenced by other projects.
• For example: pkg/log , pkg/middleware , pkg/validator .
• Note: If the project is a library, pkg may be the home directory.

4. api/ ——Interface definition

• If using gRPC or OpenAPI, put the .proto or .yaml file here.
• Versioning management: api/v1/ , api/v2/
• Can be used with code generation tools such as protoc.

5. config/ and scripts/

• config/ : Store configuration files for different environments (dev.yaml, prod.yaml)
• scripts/ : Automated scripts, such as:
  • Build a mirror
  • Database migration
  • Local startup service

6. deploy/ ——Deployment related

• Dockerfile : Container image construction
• k8s/ : Kubernetes deployment manifest (YAML)
• CI/CD friendly, easy to release automatically

7. tests/ (optional)

• Although Go tests usually use _test.go files and go test , complex integration tests can be put here.
• Or use e2e/ directory to do end-to-end testing.

?? Notes

• Don't abuse pkg/ : Not all code should be thrown into pkg . Only those that are truly universal and reusable can be placed.
• Avoid "big mud ball" structure : do not pile all .go files in the root directory.
• Reasonable layering : handler → service → repository is a common pattern that helps decouple.
• The module name is clear : It is recommended to write the module name in go.mod in reverse using the domain name, such as github.com/yourname/my-project

? Small project simplified version

If you are just making a simple web service or CLI tool, it can be simplified:

 simple-api/
├── main.go
├── handler/
├── service/
├── model/
├── go.mod
└── README.md

As long as the logic is clear and easy to maintain, small projects do not have to be over-designed.

Basically that's it. Go's project structure focuses on clarity, maintenance, and intuition , and can write high-quality code without complex frameworks.

The above is the detailed content of go by example project structure. For more information, please follow other related articles on the PHP Chinese website!