RFC: Gin template base directory structure for API

[gutakk]

Issue

This is our first Gin template and I would like your comment about this base directory structure. Note: This is for API projects. Feel free to comment or share your opinion.

.
├── .github/
├── config/
├── controllers/
    ├── v1
        ├── base.go
├── db/
├── helpers/
├── models/
    ├── base.go
├── services/
├── tests/
├── go.mod
├── go.sum
├── main.go

• .github contains github workflows.
• config contains app config, routers, database config and another config.
• controllers contains request handler.
  • v1 is the API versioning.
    • base.go is the base controller used by all controllers.
• db contains db related stuffs such as migration.
• helpers contains helper function for controllers, model and services.
• models contains the application model.
  • base.go is the base model used by all models.
• services contains business logics.
• tests contains test related stuff such as initializer or test helpers.

Note test files are in the same directory with the main file.

[carryall]

@gutakk Should we also have a test file to test the code base just like the codebase_spec.rb on rails template? 🤔

[gutakk]

@gutakk Should we also have a test file to test the code base just like the codebase_spec.rb on rails template? 🤔

Good catch but I'm not sure if Ginkgo allow us to run the command in the test. I will make a research and add this in #1

[olivierobert]

Since we are aiming an API-first template, I also recommend adding by default a directory for serializers.

Also, in general, how about following more https://github.com/opn-ooo/go-boilerplate:

.
├── .github/
├── cmd/
├── ├── main.go $ there can be another one for workers and this could combine some bootstrapping logic as done by Hoang on Beego https://github.com/hoangmirs/go-scraper/tree/development/bootstrap
├── config/
├── database/ # better be more explicit than just `db`
├── lib/ # instead of internals as it's more standard in most languages
├── ├── models/
├── ├──├── base.go
├── ├── services/
├── ├── web # just like in Phoenix as it allows to separate the business logic from the web layer
├── ├──├── controllers/
├── ├──├── params/ # it could also be called "forms" like in Beego to process the user inputs in controllers
├── ├──├── serializers/
├── tests/
├── go.mod
├── go.sum

OPN (formerly knows as Omise Labs) has battle-tested their template so it could be good to draw from their experience 💪

[gutakk]

Since we are aiming an API-first template, I also recommend adding by default a directory for serializers.

Also, in general, how about following more https://github.com/opn-ooo/go-boilerplate:

.
├── .github/
├── cmd/
├── ├── main.go $ there can be another one for workers and this could combine some bootstrapping logic as done by Hoang on Beego https://github.com/hoangmirs/go-scraper/tree/development/bootstrap
├── config/
├── database/ # better be more explicit than just `db`
├── lib/ # instead of internals as it's more standard in most languages
├── ├── models/
├── ├──├── base.go
├── ├── services/
├── ├── web # just like in Phoenix as it allows to separate the business logic from the web layer
├── ├──├── controllers/
├── ├──├── params/ # it could also be called "forms" like in Beego to process the user inputs in controllers
├── ├──├── serializers/
├── tests/
├── go.mod
├── go.sum

OPN (formerly knows as Omise Labs) has battle-tested their template so it could be good to draw from their experience 💪

looks clean, I adapt to align with our requirement like this. What do you think?

.
├── .github/
├── cmd/
    ├── api/
        ├── main.go
├── config/
├── database/
├── lib/
    ├── api/
        ├── v1/
            ├── controllers/
                ├── base.go
            ├── forms/
            ├── serializers/
    ├── models/
        ├── base.go
    ├── services/
├── helpers/
├── tests/
├── go.mod
├── go.sum

[olivierobert]

I am not sure about the needs to nest main.go in api. How would it like for workers or anything other main.go files there? The rest looks good to me.

[olivierobert]

Others ones for you to think about, where would you put:

• The oauth server: https://github.com/gutakk/go-google-scraper/blob/development/oauth/oauth_server.go?
• Middlewares?

Basically, try to imagine your own codebase for the IC in this new structure 😁

[gutakk]

I am not sure about the needs to nest main.go in api. How would it like for workers or anything other main.go files there? The rest looks good to me.

What I thought is one directory per one process. If we have both API server and worker, this will need to separate in two different processes and will be like this. What do you think?

.
├── bootstrap/ # base bootstrapping 
├── cmd/
    ├── api/
        ├── .air.toml # in case we use air for live reload
        ├── bootstrap.go # call necessary bootstrapping stuffs from bootstrap/ for api server
        ├── main.go
    ├── worker/
        ├── .air.toml # in case we use air for live reload
        ├── bootstrap.go # call necessary bootstrapping stuffs from bootstrap/ for worker
        ├── main.go

[gutakk]

Others ones for you to think about, where would you put:

• The oauth server: https://github.com/gutakk/go-google-scraper/blob/development/oauth/oauth_server.go?
• Middlewares?

Basically, try to imagine your own codebase for the IC in this new structure 😁

• oauth server, this can be a part of bootstrap as it is the setup step.
• middlewares should be inside lib as I think middlewares can share to multiple version of APIs.

[olivierobert]

All good for the structure so I think this issue can be closed 🥳