Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yakuter/ugin
UGin is an API boilerplate written in Go (Golang) with Gin Framework.
https://github.com/yakuter/ugin
api boilerplate example gin gin-gonic gorm mysql postgres sqlite viper
Last synced: 4 days ago
JSON representation
UGin is an API boilerplate written in Go (Golang) with Gin Framework.
- Host: GitHub
- URL: https://github.com/yakuter/ugin
- Owner: yakuter
- License: apache-2.0
- Created: 2019-03-10T20:14:40.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2021-11-21T13:10:45.000Z (about 3 years ago)
- Last Synced: 2024-12-09T04:36:28.706Z (13 days ago)
- Topics: api, boilerplate, example, gin, gin-gonic, gorm, mysql, postgres, sqlite, viper
- Language: Go
- Homepage:
- Size: 381 KB
- Stars: 227
- Watchers: 8
- Forks: 36
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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**:
```bash
// 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.