yakuter/ugin

UGin is an API boilerplate written in Go (Golang) with Gin Framework.

UGin - Ultimate Gin API

UGin is an API boilerplate written in Go (Golang) with Gin Framework. https://github.com/gin-gonic/gin

Database Support

UGin uses gorm as an ORM. So Sqlite3, MySQL and PostgreSQL is supported. You just need to edit config.yml file according to your setup.

config.yml content:

database:
  driver: "postgres"
  dbname: "ugin"
  username: "user"
  password: "password"
  host: "localhost"
  port: "5432"

Default Models

UGin has two models (Post and Tag) as boilerplate to show relational database usage.

/model/post-model.go content:

type Post struct {
	gorm.Model
	Name        string `json:"Name" gorm:"type:varchar(255)"`
	Description string `json:"Description"  gorm:"type:text"`
	Tags        []Tag  // One-To-Many relationship (has many - use Tag's UserID as foreign key)
}

type Tag struct {
	gorm.Model
	PostID      uint   `gorm:"index"` // Foreign key (belongs to)
	Name        string `json:"Name" gorm:"type:varchar(255)"`
	Description string `json:"Description" gorm:"type:text"`
}

Filtering, Search and Pagination

UGin has it's own filtering, search and pagination system. You just need to use these parameters.

Query parameters:

/posts/?Limit=2
/posts/?Offset=0
/posts/?Sort=ID
/posts/?Order=DESC
/posts/?Search=hello

Full: http://localhost:8081/posts/?Limit=25&Offset=0&Sort=ID&Order=DESC&Search=hello

Running

To run UGin with Docker, firstly build an image:

make build-image

To run Ugin with MySQL:

make run-app-mysql

To run Ugin with PostgreSQL:

make run-app-postgres

Application will be served at ":8081"

Logging

UGin has a very powerful logging logic. There is application log (ugin.log), database log (ugin.db.log) and access log (ugin.access.log)

ugin.log:

INFO 2021-09-19T00:33:32+03:00 Server is starting at 127.0.0.1:8081
ERROR 2021-09-19T00:39:19+03:00 Failed to open log file ugin.log

ugin.db.log:

2021/09/19 00:33:32 /home/user/projects/ugin/pkg/database/database.go:76
[0.023ms] [rows:-] SELECT * FROM `posts` LIMIT 1

2021/09/19 00:33:32 /home/user/go/pkg/mod/gorm.io/driver/[email protected]/migrator.go:261
[0.015ms] [rows:-] SELECT count(*) FROM sqlite_master WHERE type = "index" AND tbl_name = "posts" AND name = "idx_posts_deleted_at"

2021/09/19 00:33:32 /home/user/go/pkg/mod/gorm.io/driver/[email protected]/migrator.go:32
[0.010ms] [rows:-] SELECT count(*) FROM sqlite_master WHERE type='table' AND name="tags"

2021/09/19 00:33:32 /home/user/projects/ugin/pkg/database/database.go:76
[0.011ms] [rows:-] SELECT * FROM `tags` LIMIT 1

ugin.access.log:

[GIN] 2021/09/19 - 00:33:43 | 200 |    9.255625ms |       127.0.0.1 | GET      "/posts/"
[GIN] 2021/09/19 - 00:41:51 | 200 |     6.41675ms |       127.0.0.1 | GET      "/posts/4"

Routes

Default UGin routes are listed below.

METHOD	ROUTE	FUNCTION
GET	/posts/	github.com/yakuter/ugin/controller.(*Controller).GetPosts
GET	/posts/:id	github.com/yakuter/ugin/controller.(*Controller).GetPost
POST	/posts/	github.com/yakuter/ugin/controller.(*Controller).CreatePost
PUT	/posts/:id	github.com/yakuter/ugin/controller.(*Controller).UpdatePost
DELETE	/posts/:id	github.com/yakuter/ugin/controller.(*Controller).DeletePost
GET	/postsjwt/	github.com/yakuter/ugin/controller.(*Controller).GetPosts
GET	/postsjwt/:id	github.com/yakuter/ugin/controller.(*Controller).GetPost
POST	/postsjwt/	github.com/yakuter/ugin/controller.(*Controller).CreatePost
PUT	/postsjwt/:id	github.com/yakuter/ugin/controller.(*Controller).UpdatePost
DELETE	/postsjwt/:id	github.com/yakuter/ugin/controller.(*Controller).DeletePost
POST	/auth/signup	github.com/yakuter/ugin/controller.(*Controller).Signup
POST	/auth/signin	github.com/yakuter/ugin/controller.(*Controller).Signin
POST	/auth/refresh	github.com/yakuter/ugin/controller.(*Controller).RefreshToken
POST	/auth/check	github.com/yakuter/ugin/controller.(*Controller).CheckToken
GET	/admin/dashboard	github.com/yakuter/ugin/controller.Dashboard

Gin Running Mode

Gin framework listens GIN_MODE environment variable to set running mode. This mode enables/disables access log. Just run one of these commands before running UGin:

// Debug mod
export GIN_MODE=debug
// Test mod
export GIN_MODE=test
// Release mod
export GIN_MODE=release

Packages

UGin uses great open source projects list below: Gin for main framework, Gorm for database and Viper for configuration.

go get -u github.com/gin-gonic/gin
go get -u github.com/jinzhu/gorm
go get -u github.com/jinzhu/gorm/dialects/postgres
go get -u github.com/jinzhu/gorm/dialects/sqlite
go get -u github.com/jinzhu/gorm/dialects/mysql
go get -u github.com/spf13/viper

Middlewares

1. Logger and Recovery Middlewares

Gin has 2 important built-in middlewares: Logger and Recovery. UGin calls these two in default.

router := gin.Default()

This is same with the following lines.

router := gin.New()
router.Use(gin.Logger())
router.Use(gin.Recovery())

2. CORS Middleware

CORS is important for API's and UGin has it's own CORS middleware in include/middleware.go. CORS middleware is called with the code below.

router.Use(include.CORS())

There is also a good repo for this: https://github.com/gin-contrib/cors

3. BasicAuth Middleware

Almost every API needs a protected area. Gin has BasicAuth middleware for protecting routes. Basic Auth is an authorization type that requires a verified username and password to access a data resource. In UGin, you can find an example for a basic auth. To access these protected routes, you need to add Basic Authorization credentials in your requests. If you try to reach these endpoints from browser, you should see a window prompting you for username and password.

authorized := router.Group("/admin", gin.BasicAuth(gin.Accounts{
    "username": "password",
}))

// /admin/dashboard endpoint is now protected
authorized.GET("/dashboard", controller.Dashboard)

What is next?

• Ugin needs a user service and an authentication method with JWT.

ugin's Issues

Dockerize ugin (an API written with Go and Gin framework)

We need a Dockerfile and docker-compose.yml file to make it run easily in any environment with docker.

docker-compose.yml should have 2 services:

1. ugin
2. database (mysql and postgres)

How to build?

Hi @yakuter, I've got a really dumb question: Is this boilerplate buildable? I'm about to go in and change all the imports, but figured I'll ask you first since I'm a Golang newbie. Thank you!

main.go:4:2: cannot find package "ugin/pkg/config" in any of:
	/opt/go/1.15.3/src/ugin/pkg/config (from $GOROOT)
	/home/vagrant/go/src/ugin/pkg/config (from $GOPATH)
main.go:5:2: cannot find package "ugin/pkg/database" in any of:
	/opt/go/1.15.3/src/ugin/pkg/database (from $GOROOT)
	/home/vagrant/go/src/ugin/pkg/database (from $GOPATH)
main.go:6:2: cannot find package "ugin/pkg/router" in any of:
	/opt/go/1.15.3/src/ugin/pkg/router (from $GOROOT)
	/home/vagrant/go/src/ugin/pkg/router (from $GOPATH)

Publishing image to GitHub Packages

After #16 issue solved, we can add publishing the image to GitHub,
https://docs.github.com/en/actions/publishing-packages/publishing-docker-images#publishing-images-to-github-packages
https://github.com/features/packages

-

finding module for package github.com/yakuter/ugin/pkg/logger

go mod tidy

go: finding module for package github.com/yakuter/ugin/pkg/logger
github.com/yakuter/ugin imports
github.com/yakuter/ugin/pkg/logger: no matching versions for query "latest"

boilerplate setup

Hello,

ugin seems to be clean and well written, Thank you!
But can you please add some setup instructions in readme. Also, the readme says "Ugin needs a user service and an authentication method with JWT", but looking at the code and commit messages, it seems that JWT is already integrated. Some instructions for that will also be helpful.

Thank you again..

Update jwt-go package

Can anyone update github.com/dgrijalva/jwt-go package?