跳到主要内容
版本：2.10.x(Latest)

快速开发示例

Github Source: https://github.com/gogf/examples/tree/main/practices/quick-demo

简介​

quick-demo是一个快速入门HTTP服务示例，展示如何使用GoFrame框架进行快速开发。它提供了完整的RESTful API实现，包含用户CRUD操作、MySQL数据库集成以及OpenAPI/Swagger文档自动生成。该示例遵循GoFrame的标准项目结构和最佳实践，是学习GoFrame或构建新项目的理想起点。

项目结构​

quick-demo/
├── api/                  # API接口定义
│   ├── hello/            # Hello模块API
│   │   └── v1/
│   │       └── hello.go  # Hello API定义
│   └── user/             # 用户模块API
│       └── v1/
│           └── user.go   # 用户CRUD API定义
├── internal/             # 内部实现
│   ├── cmd/              # 命令层
│   │   └── cmd.go        # 服务器初始化
│   ├── consts/           # 常量
│   ├── controller/       # 控制器层(自动生成 + 接口实现)
│   │   ├── hello/        # Hello控制器
│   │   └── user/         # 用户CRUD控制器
│   ├── dao/              # 数据访问对象（自动生成）
│   ├── model/            # 数据模型
│   │   ├── do/           # 数据对象（自动生成）
│   │   └── entity/       # 数据库实体（自动生成）
│   └── service/          # 业务逻辑层
├── manifest/             # 应用清单
│   ├── config/           # 配置文件
│   │   └── config.yaml   # 主配置
│   ├── deploy/           # 部署配置
│   ├── docker/           # Docker配置
│   └── i18n/             # 国际化
├── resource/             # 静态资源
├── utility/              # 工具函数
├── main.go               # 应用程序入口
└── go.mod                # Go模块定义

特性​

  • RESTful API设计：遵循RESTful规范的完整用户CRUD操作
  • MySQL集成：使用GoFrame的DAO模式和ORM进行数据库操作
  • OpenAPI/Swagger：自动生成API文档和Swagger UI
  • 标准结构：遵循GoFrame推荐的项目结构，具有良好的可扩展性
  • 代码自动生成：从数据库表结构自动生成DAO、entity和model代码
  • 请求验证：内置请求参数验证规则
  • 配置管理：基于YAML的配置，支持环境变量
  • 中间件：统一的响应处理中间件，确保API响应格式一致
  • Hello World示例：简单示例展示基本的HTTP处理

要求​

  • Go 1.23.0或更高版本
  • MySQL 8.0或更高版本

前置条件​

使用Docker启动MySQL：

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

创建用户表：

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;

安装​

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

使用​

启动服务：

go run main.go

服务将在http://localhost:8000启动。

访问API文档：

API参考​

Hello API​

GET /hello

返回"Hello World!"消息。

curl http://localhost:8000/hello

用户APIs​

创建用户

POST /user

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

响应：

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

更新用户

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/{id}

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

获取单个用户

GET /user/{id}

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

响应：

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

获取用户列表

GET /user

# 获取所有用户
curl http://localhost:8000/user

# 按年龄过滤
curl "http://localhost:8000/user?age=25"

# 按状态过滤
curl "http://localhost:8000/user?status=0"

响应：

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

实现细节​

API定义​

API接口使用GoFrame的g.Meta标签定义，实现自动路由和文档生成：

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"`
}

控制器实现​

控制器实现每个API端点的业务逻辑：

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模式​

项目使用GoFrame的DAO模式进行数据库操作，代码自动生成：

  • dao/：数据访问层（自动生成）
  • model/do/：数据库操作的数据对象（自动生成）
  • model/entity/：数据库表结构（自动生成）

响应中间件​

统一响应处理中间件确保API响应格式一致，包含code、message和data字段。

配置​

配置通过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"