/goframe-v2

Quick Demo

Introduction

quick-demo is a quick-start HTTP service example that demonstrates rapid development with GoFrame framework. It provides a complete RESTful API implementation with user CRUD operations, MySQL database integration, and automatic OpenAPI documentation generation. This example follows GoFrame's standard project structure and best practices, making it an ideal starting point for learning GoFrame or building new projects.

Project Structure

quick-demo/
├── api/                  # API interface definitions
│   └── user/             # User module API
│       ├── user.go        # API definition for completeness check(auto-generated by "gf gen ctrl")
│       └── v1/            # API definition version v1
├── internal/             # Internal implementation
│   ├── cmd/              # Command layer
│   │   └── cmd.go        # Server initialization
│   ├── consts/           # Constants
│   ├── controller/       # Controller layer
│   │   ├── hello/        # Hello controller
│   │   └── user/         # User CRUD controllers
│   ├── dao/              # Data Access Objects (auto-generated)
│   ├── model/            # Data models
│   │   ├── do/           # Data objects (auto-generated)
│   │   └── entity/       # Database entities (auto-generated)
│   └── service/          # Business logic layer
├── manifest/             # Application manifest
│   ├── config/           # Configuration files
│   │   └── config.yaml   # Main configuration
│   ├── deploy/           # Deployment configs
│   └── docker/           # Docker configurations
├── main.go               # Application entry point
└── go.mod                # Go module definition

Features

• RESTful API Design: Complete user CRUD operations with RESTful conventions
• MySQL Integration: Database operations using GoFrame's DAO pattern and ORM
• OpenAPI/Swagger: Automatic API documentation generation and Swagger UI
• Standard Structure: Follows GoFrame's recommended project structure for scalability
• Auto Code Generation: DAO, entity, and model code auto-generated from database schema
• Validation: Built-in request parameter validation with rules
• Configuration Management: YAML-based configuration with environment support
• Middleware: Unified response handling middleware for consistent API responses
• Hello World Example: Simple example demonstrating basic HTTP handling

Requirements

• Go 1.23.0 or higher
• MySQL 8.0 or higher

Prerequisites

Start MySQL using Docker:

docker run -d \
  --name mysql \
  -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=12345678 \
  -e MYSQL_DATABASE=test \
  mysql:8.0

Create user table:

CREATE TABLE `user` (
  `id` int unsigned NOT NULL AUTO_INCREMENT COMMENT 'user id',
  `name` varchar(50) NOT NULL COMMENT 'user name',
  `status` int NOT NULL DEFAULT '0' COMMENT 'user status',
  `age` int unsigned NOT NULL COMMENT 'user age',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Installation

cd /path/to/examples/practices/quick-demo
go mod tidy

Usage

Start the server:

go run main.go

The server will start on http://localhost:8000.

Access API documentation:

• Swagger UI: http://localhost:8000/swagger
• OpenAPI Spec: http://localhost:8000/api.json

API Reference

Hello API

GET /hello

Returns "Hello World!" message.

curl http://localhost:8000/hello

User APIs

Create User

POST /user

curl -X POST http://localhost:8000/user \
  -H "Content-Type: application/json" \
  -d '{
    "name": "john",
    "age": 25
  }'

Response:

{
  "code": 0,
  "message": "",
  "data": {
    "id": 1
  }
}

Update User

PUT /user/{id}

curl -X PUT http://localhost:8000/user/1 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "john_updated",
    "age": 26,
    "status": 0
  }'

Delete User

DELETE /user/{id}

curl -X DELETE http://localhost:8000/user/1

Get One User

GET /user/{id}

curl http://localhost:8000/user/1

Response:

{
  "code": 0,
  "message": "",
  "data": {
    "id": 1,
    "name": "john",
    "status": 0,
    "age": 25
  }
}

Get User List

GET /user

# Get all users
curl http://localhost:8000/user

# Filter by age
curl "http://localhost:8000/user?age=25"

# Filter by status
curl "http://localhost:8000/user?status=0"

Response:

{
  "code": 0,
  "message": "",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "john",
        "status": 0,
        "age": 25
      }
    ]
  }
}

Implementation Details

API Definition

API interfaces are defined using GoFrame's g.Meta tags for automatic routing and documentation:

type CreateReq struct {
    g.Meta `path:"/user" method:"post" tags:"User" summary:"Create user"`
    Name   string `v:"required|length:3,10" dc:"user name"`
    Age    uint   `v:"required|between:18,200" dc:"user age"`
}

Controller Implementation

Controllers implement the business logic for each API endpoint:

func (c *ControllerV1) Create(ctx context.Context, req *v1.CreateReq) (res *v1.CreateRes, err error) {
    insertId, err := dao.User.Ctx(ctx).Data(do.User{
        Name:   req.Name,
        Status: v1.StatusOK,
        Age:    req.Age,
    }).InsertAndGetId()
    if err != nil {
        return nil, err
    }
    res = &v1.CreateRes{Id: insertId}
    return
}

DAO Pattern

The project uses GoFrame's DAO pattern for database operations with auto-generated code:

• dao/: Database access layer (auto-generated)
• model/do/: Data objects for database operations (auto-generated)
• model/entity/: Database table structures (auto-generated)

Response Middleware

Unified response handling middleware ensures consistent API responses with code, message, and data fields.

Configuration

Configuration is managed through manifest/config/config.yaml:

server:
  address: ":8000"
  openapiPath: "/api.json"
  swaggerPath: "/swagger"

database:
  default:
    link: "mysql:root:12345678@tcp(127.0.0.1:3306)/test"