{"id":20282593,"url":"https://github.com/veops/gin-api-template","last_synced_at":"2025-09-09T14:08:24.601Z","repository":{"id":205753245,"uuid":"714904328","full_name":"veops/gin-api-template","owner":"veops","description":"A simple project construction template based on the gin framework. ","archived":false,"fork":false,"pushed_at":"2023-11-08T03:41:37.000Z","size":278,"stargazers_count":30,"open_issues_count":1,"forks_count":12,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-11T08:45:29.985Z","etag":null,"topics":["cobra","gin","go","golang","orm","rest-api","zap"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/veops.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-11-06T04:43:59.000Z","updated_at":"2025-03-13T10:52:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"eaab05d9-6663-4b8d-8186-332831bc3235","html_url":"https://github.com/veops/gin-api-template","commit_stats":null,"previous_names":["veops/gin-api-template"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/veops/gin-api-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veops%2Fgin-api-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veops%2Fgin-api-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veops%2Fgin-api-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veops%2Fgin-api-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/veops","download_url":"https://codeload.github.com/veops/gin-api-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veops%2Fgin-api-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274308299,"owners_count":25261221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-09T02:00:10.223Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cobra","gin","go","golang","orm","rest-api","zap"],"created_at":"2024-11-14T14:10:28.940Z","updated_at":"2025-09-09T14:08:24.586Z","avatar_url":"https://github.com/veops.png","language":"Go","readme":"\u003ch3 align=\"center\"\u003eA simple project template based on gin framework\u003c/h3\u003e\n\u003cdiv align=\"center\"\u003e\n\n[![Licence](https://img.shields.io/badge/Licence-Apache-brightgreen)](https://github.com/veops/gin-api-template/blob/main/LICENSE)\n[![API](https://img.shields.io/badge/API-gin-blue)](https://github.com/gin-gonic/gin)\n[![Log](https://img.shields.io/badge/Log-zap-green)](https://github.com/uber-go/zap)\n[![Golang](https://img.shields.io/badge/go-1.18+-blue)](https://go.dev/dl/)\n\u003c/div\u003e\n\n------------------------------\n\n[中文](README_cn.md)\n## Overview\nA simple project construction template based on the gin framework.\n\nIf you want to quickly build a backend project using golang, this template is perfect for you.\nYou can directly use this project and quickly develop your own project based on it.\n\n## Architecture Overview\n\n\n``` shell\n├── cmd\n│   ├── apps # Subdirectory for sub-projects`\n│   │   ├── config.example.yaml # Example configuration file for startup\n│   │   └── server.go # Starts a specific sub-project`\n│   └── main.go # The entpoint for starting the project.\n├── docs # various documents\n│   └── images\n└── pkg  # Core code package of the project`\n    ├── conf\n    │   └── conf.go # Global configuration settings` \n    ├── logger # Logging settings\n    ├── 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.\n    │   ├── auth # Authentication module` \n    │   │   └── acl # Default ACL authentication\n    │   │   └── ... # Any other authentication can be placed in a separate directory, such as ldap \n    │   ├── controller # Controller module`\n    │   │   ├── controller.go # Definition of a global controller\n    │   │   └── hello.go # An example API. Each type of API interface should have a separate file for better organization. \n    │   ├── model # Configuration of storage structures, including model configurations for various database storages, such as definitions of database fields, etc.\n    │   │   └── hello.go\n    │   ├── router # Various router definitions\n    │   │   ├── middleware # Definition of various middlewares\n    │   │   │   ├── auth.go # Authentication\n    │   │   │   ├── cache.go # Cache\n    │   │   │   ├── log.go # Logging\n    │   │   │   └── ... \n    │   │   ├── router.go # Global router configuration\n    │   │   └── routers.go # Configuration of various routes. The main logic of the API code is configured here.\n    │   └── storage # Implementation of backend storage`\n    │       ├── cache # Cache implementation` \n    │       │   ├── local # In-memory storage\n    │       │   └── redis # Redis storage\n    │       └── db # Storage for various databases\n    │           └── mysql\n    └── util # Contains various common functions and utilities\n        └── util.go\n```\n\n## Features\n- **Cobra** for command-line startup.\n- Uses **YAML** format for configuration files.\n- Logging is done using Zap, which provides **logging output** , **log rotation** , **Dynamically modify the log output level** .\n- **router configuration**.\n- **multiple middlewares**.\n\n## Getting Started\n### Step 1. Clone the project\n```sh\ngit clone git@github.com:veops/gin-api-template.git\n\n```\n### Step 2. Modify config file\n```sh\ncd gin-api-template/cmd\ncp apps/config.example.yaml apps/config.yaml \n# modify config.yaml\n```\n### Step 3. Build and run the project\n```\ngo build -o server main.go \n./server run -c apps\n```\n\n\n### Step 4. Validation\n\u003e Verify any one of the following is normal.\n- **Service availability check**, **Must-have as an API service**\n```\ncurl -X GET http://localhost:8080/-/health\n```\nresponse is: `OK`\n- **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.\n```\ncurl -X PUT localhost:8080/-/log/level -H \"Content-Type: application/json\" -d '{\"level\":\"debug\"}'\n```\nresponse is:\n```json\n{\"level\":\"debug\"}\n```\n- Regular API validation.\n```shell\ncurl -X GET http://localhost:8080/api/v1/hello\n```\nresponse is:\n```json\n{\n  \"code\":0,\n  \"data\":{\n    \"Time\":\"2023-11-06T09:36:55.830076+08:00\"\n  },\n  \"message\":\"hello world\"\n}\n```\n\n## FAQ\n\n### How can I add new routes(i.e. api)\n\u003e 1. Write your own handler in pkg/server/controller, just like what hello.go does\n\u003e 2. Register your handler to routes in pkg/server/router/routes.go\n\n### How can I add new middlewares\n\u003e 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.\n\u003e 2. Then you should register yours in the setupRouter() function in pkg/server/router\n\n### How to use my own authorization\n\u003e 1. Add your own authorization way in pkg/server/router/middleware/auth.go. ACL, white list and basic auth is provided by default.\n\u003e 2. Rearrange the order of auth functions if you need in Auth() function\n\n### What is ACL\n\n\u003e 1. A role-based resource permission management service. Please check defails here [https://github.com/veops/acl](https://github.com/veops/acl)\n\n### How to use my prefered database\n\u003e 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.\n\u003e 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.\n\u003e 3. Add mongo config struct in conf/conf.go\n\u003e 4. Add mongo config in your config.yaml file","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveops%2Fgin-api-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fveops%2Fgin-api-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveops%2Fgin-api-template/lists"}