My Gin App

This is a modern web service development template built with Go and the Gin framework.

It integrates best practice libraries like GORM and Viper, aiming to provide a clear, extensible, and flexible development starting point.

Features

• Language: Go
• Web Framework: Gin
• ORM: GORM
• Configuration Management: Viper
• Environment Variables: godotenv
• Containerization: Docker

Quick Start

Prerequisites

• Go (1.21+)
• MySQL Database
• Make

Installation & Configuration

# 1. Clone the project (if needed)
# git clone ...

# 2. Navigate to the project directory
cd my-gin-app

# 3. Copy the .env file
cp .env.example .env

# 4. Modify the .env file
# Update SERVER_PORT and DATABASE_DSN according to your local environment
nano .env

Important: The database pointed to by DATABASE_DSN needs to be pre-created.

Run the Service

make run

When the service starts, GORM will automatically create or update table structures in the database based on definitions in models.

Available Commands (Makefile)

• make run: Start the web service for development.
• make build: Build a binary executable for production.
• make test: Run all tests in the project.
• make clean: Clean up build artifacts.

Project Structure

.
├── cmd/server/main.go      # Application entry point
├── configs/                # Configuration files directory
│   └── config.yaml
├── internal/               # Internal application code
│   └── app/
│       ├── handlers/       # HTTP handlers (Controllers)
│       ├── models/         # Data models (GORM Models)
│       ├── router/         # Route definitions
│       └── services/       # Business logic layer
├── pkg/                    # Public libraries/packages
│   └── database/           # Database connection and initialization
├── .env.example            # Environment variable example file
├── .gitignore              # Git ignore file
├── DOC.md                  # Development documentation (in Chinese)
├── Dockerfile              # Docker containerization file
├── go.mod                  # Go module dependencies
├── go.sum
└── Makefile                # Common commands

API Endpoints

• GET /v1/ping: Health check endpoint.

  • Success Response (200 OK):

    {
      "code": 0,
      "data": "pong",
      "msg": "操作成功"
    }

• GET /v1/users: Get a list of all users.

  • Success Response (200 OK):

    {
      "code": 0,
      "data": [
        {
          "ID": 1,
          "CreatedAt": "2023-10-27T10:00:00Z",
          "UpdatedAt": "2023-10-27T10:00:00Z",
          "DeletedAt": null,
          "name": "Test User",
          "email": "test@example.com"
        }
      ],
      "msg": "操作成功"
    }

• POST /v1/users: Register a new user.

  • Request Body:

    {
      "name": "New User",
      "email": "newuser@example.com"
    }

  • Success Response (200 OK):

    {
      "code": 0,
      "data": {
        "ID": 2,
        "CreatedAt": "2023-10-27T11:00:00Z",
        "UpdatedAt": "2023-10-27T11:00:00Z",
        "DeletedAt": null,
        "name": "New User",
        "email": "newuser@example.com"
      },
      "msg": "操作成功"
    }

  • Error Response (400 Bad Request):

    {
      "code": 4001,
      "data": {},
      "msg": "Key: 'RegisterUserInput.Name' Error:Field validation for 'Name' failed on the 'required' tag"
    }

Dockerization

The project provides a multi-stage build Dockerfile to easily package the application into a lightweight Docker image.

Build Image:

docker build -t my-gin-app .

Run Container:

When running the container, you can pass environment variables via -e to configure the application inside the container.

docker run -p 8080:8080 -e DATABASE_DSN="your_production_dsn" my-gin-app

Documentation

For more detailed information about the project structure, configuration management, and how to add new features, please refer to DOC.md (in Chinese).