Guidelines for Organizing Go Projects: Structure of the gobox-demo Template

In this post the author shares practical experience on how to structure a Go project, providing a public template repository gobox-demo that demonstrates the recommended layout.

Project organization

├── conf           // project configuration files
│   ├── http       // nginx‑like server config
│   │   ├── general
│   │   └── ssl
│   ├── rigger    // rigger config
│   │   └── tpl
│   └── server
├── logs                       // log files
├── src                        // Go source code
│   └── gdemo                  // project namespace
│       ├── conf               // config parsing
│       ├── controller         // MVC controller layer
│       │   └── api            // API subsystem controllers/actions
│       │       ├── demo       // DemoController
│       ├── errno              // error codes
│       ├── gvalue             // global variables
│       ├── idgen              // ID generator (MySQL implementation)
│       ├── main               // program entry points
│       │   └── api            // API subsystem entry
│       ├── misc               // miscellaneous utilities
│       ├── svc                // MVC service layer
│       │   ├── demo           // DemoSvc
│       └── vendor             // third‑party packages
├── tmp     // temporary files
└── tools   // helper scripts

Controller and action organization

Instead of placing many actions in a single controller file, each action is split into its own file for clarity.

controller/
├── api              // API subsystem controllers and actions
│   ├── base.go      // common base
│   ├── demo         // DemoController
│   │   ├── add.go   // AddAction
│   │   ├── base.go  // DemoController base
│   │   ├── del.go   // DelAction
│   │   ├── edit.go  // EditAction
│   │   ├── get.go   // GetAction
│   │   └── index.go // IndexAction
└── base.go          // generic base

Service layer organization

svc/
├── base.go            // generic base
├── demo               // DemoSvc implementation
│   ├── demo.go
│   └── demo_test.go
├── redis_base.go     // basic Redis operations
├── sql_base.go       // basic SQL operations
└── sql_redis_bind.go // common pattern: Redis cache + MySQL storage

Other notes

The remaining packages contain frequently used utilities, and any internal company‑specific code (such as deployment scripts) is kept in separate directories that are not published.

The author emphasizes a minimalist approach: only include features the team actually uses, keep naming clear, and maintain a layered hierarchy so that the project structure itself reveals where each functionality belongs.

Conclusion

The author hopes the shared experience helps readers build well‑organized Go projects and invites feedback on any inaccuracies.