https://github.com/veops/gin-api-template
A simple project construction template based on the gin framework.
https://github.com/veops/gin-api-template
cobra gin go golang orm rest-api zap
Last synced: 7 months ago
JSON representation
A simple project construction template based on the gin framework.
- Host: GitHub
- URL: https://github.com/veops/gin-api-template
- Owner: veops
- License: apache-2.0
- Created: 2023-11-06T04:43:59.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-11-08T03:41:37.000Z (over 2 years ago)
- Last Synced: 2025-04-11T08:45:29.985Z (12 months ago)
- Topics: cobra, gin, go, golang, orm, rest-api, zap
- Language: Go
- Homepage:
- Size: 271 KB
- Stars: 30
- Watchers: 4
- Forks: 12
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
A simple project template based on gin framework
[](https://github.com/veops/gin-api-template/blob/main/LICENSE)
[](https://github.com/gin-gonic/gin)
[](https://github.com/uber-go/zap)
[](https://go.dev/dl/)
------------------------------
[中文](README_cn.md)
## Overview
A simple project construction template based on the gin framework.
If you want to quickly build a backend project using golang, this template is perfect for you.
You can directly use this project and quickly develop your own project based on it.
## Architecture Overview
``` shell
├── cmd
│ ├── apps # Subdirectory for sub-projects`
│ │ ├── config.example.yaml # Example configuration file for startup
│ │ └── server.go # Starts a specific sub-project`
│ └── main.go # The entpoint for starting the project.
├── docs # various documents
│ └── images
└── pkg # Core code package of the project`
├── conf
│ └── conf.go # Global configuration settings`
├── logger # Logging settings
├── server # Core logic block of the project. If there are multiple sub-modules, multiple directories can be created. Here is an example of a server directory is provided.
│ ├── auth # Authentication module`
│ │ └── acl # Default ACL authentication
│ │ └── ... # Any other authentication can be placed in a separate directory, such as ldap
│ ├── controller # Controller module`
│ │ ├── controller.go # Definition of a global controller
│ │ └── hello.go # An example API. Each type of API interface should have a separate file for better organization.
│ ├── model # Configuration of storage structures, including model configurations for various database storages, such as definitions of database fields, etc.
│ │ └── hello.go
│ ├── router # Various router definitions
│ │ ├── middleware # Definition of various middlewares
│ │ │ ├── auth.go # Authentication
│ │ │ ├── cache.go # Cache
│ │ │ ├── log.go # Logging
│ │ │ └── ...
│ │ ├── router.go # Global router configuration
│ │ └── routers.go # Configuration of various routes. The main logic of the API code is configured here.
│ └── storage # Implementation of backend storage`
│ ├── cache # Cache implementation`
│ │ ├── local # In-memory storage
│ │ └── redis # Redis storage
│ └── db # Storage for various databases
│ └── mysql
└── util # Contains various common functions and utilities
└── util.go
```
## Features
- **Cobra** for command-line startup.
- Uses **YAML** format for configuration files.
- Logging is done using Zap, which provides **logging output** , **log rotation** , **Dynamically modify the log output level** .
- **router configuration**.
- **multiple middlewares**.
## Getting Started
### Step 1. Clone the project
```sh
git clone git@github.com:veops/gin-api-template.git
```
### Step 2. Modify config file
```sh
cd gin-api-template/cmd
cp apps/config.example.yaml apps/config.yaml
# modify config.yaml
```
### Step 3. Build and run the project
```
go build -o server main.go
./server run -c apps
```
### Step 4. Validation
> Verify any one of the following is normal.
- **Service availability check**, **Must-have as an API service**
```
curl -X GET http://localhost:8080/-/health
```
response is: `OK`
- **Dynamically modify the log level**. This API is convenient for adjusting the log output level dynamically without the need to restart the service, making it easier to troubleshoot issues when encountered.
```
curl -X PUT localhost:8080/-/log/level -H "Content-Type: application/json" -d '{"level":"debug"}'
```
response is:
```json
{"level":"debug"}
```
- Regular API validation.
```shell
curl -X GET http://localhost:8080/api/v1/hello
```
response is:
```json
{
"code":0,
"data":{
"Time":"2023-11-06T09:36:55.830076+08:00"
},
"message":"hello world"
}
```
## FAQ
### How can I add new routes(i.e. api)
> 1. Write your own handler in pkg/server/controller, just like what hello.go does
> 2. Register your handler to routes in pkg/server/router/routes.go
### How can I add new middlewares
> 1. There all some middlewares providered by default in pkg/server/middlware, therefore, plaease check them firstly. If you do not find what you need, just write your own one here.
> 2. Then you should register yours in the setupRouter() function in pkg/server/router
### How to use my own authorization
> 1. Add your own authorization way in pkg/server/router/middleware/auth.go. ACL, white list and basic auth is provided by default.
> 2. Rearrange the order of auth functions if you need in Auth() function
### What is ACL
> 1. A role-based resource permission management service. Please check defails here [https://github.com/veops/acl](https://github.com/veops/acl)
### How to use my prefered database
> 1. Since this project is a common template and cohices of db is much different in different conditions, we did not provide a default one, the folder of mysql is just used to demonstrate.
> 2. Suppose you want to add mongo database. You can add a folder in db with a file named mongo.go in it. Then you should finish init logic of mongo.
> 3. Add mongo config struct in conf/conf.go
> 4. Add mongo config in your config.yaml file