Skip to main content
Version: 2.7.x(Latest)

基础环境​

Go 环境​

GoFrame是基于Go语言的 Web 后端框架，首先，我们需要拥有一个Go语言的开发环境，才能进行后续的学习。确保你的Go版本在1.20以上即可。

$ go version
go version go1.22.2 windows/amd64

数据库​

软件程序在使用过程中会产生许多数据，这些数据最后需要存储到数据库中。所以你需要准备好一个数据库，本书以MySQL为例，示例项目的数据库名称为star。

除MySQL外，GoFrame还支持MariaDB、TiDB、PostgreSQL、SQL Server、SQLite、Oracle、ClickHouse、DM多种数据库。只需要简单的修改配置、引入相关的驱动即可，这点会在使用时详细说明。

接口测试工具​

接口开发完成后，我会使用curl命令来测试接口是否符合预期。但是命令行总是不方便的，所以推荐你准备一个接口测试工具，将curl命令转换到工具中进行测试。比较流行的测试工具有Postman、Apifox、Apipost等，它们大同小异，你可以根据自己的喜好选择一个。

安装 GF CLI 工具​

GoFrame 框架提供了功能强大的开发辅助工具，是框架的一个重要组成部分。用于创建项目、生成代码、运行项目等。我们可以通过以下命令安装最新的GF CLI：

$ go install github.com/gogf/gf/cmd/gf/v2@latest

结束后运行以下命令检查是否安装成功：

$ gf version
v2.8.0
Welcome to GoFrame!
Env Detail:
  Go Version: go1.22.2 windows/amd64
  GF Version(go.mod): cannot find go.mod
...

本书的开发环境是Go 1.22.2和GoFrame v2.8.0，如果你的版本和我不一致，也无需担心，Go和GoFrame都有着强大的向下兼容性。

Github 不能访问​

在国内由于网络原因，访问Github可能会失败，这是国内程序员必然会遇到的问题，你可以在网上找寻一个可用的Github镜像来解决此问题或使用其他代理工具。

初始化项目​

准备好环境后，我们就可以正式初始化项目了。找好你要存放程序的目录，执行以下命令：

$ gf init star
initializing...
initialization done!
you can now run "cd star && gf run main.go" to start your journey, enjoy!

star是项目名称，代表星辰英语本的意思，你也可以取一个你喜欢的名字。接下来进入目录并运行项目。

$ cd star && gf run main.go
build: .\main.go
go build -o .\main.exe  .\main.go
.\main.exe 
build running pid: 13628
2024-11-06 16:45:46.015 [INFO] pid[13628]: http server started listening on [:8000]
2024-11-06 16:45:46.015 [INFO] {4c9b7c33a654051860769a5fdef82a84} swagger ui is serving at address: http://127.0.0.1:8000/swagger/
2024-11-06 16:45:46.015 [INFO] {4c9b7c33a654051860769a5fdef82a84} openapi specification is serving at address: http://127.0.0.1:8000/api.json

  ADDRESS | METHOD |   ROUTE    |                        HANDLER                        |           MIDDLEWARE
----------|--------|------------|-------------------------------------------------------|----------------------------------
  :8000   | ALL    | /api.json  | github.com/gogf/gf/v2/net/ghttp.(*Server).openapiSpec |
----------|--------|------------|-------------------------------------------------------|----------------------------------
  :8000   | GET    | /hello     | star/internal/controller/hello.(*ControllerV1).Hello  | ghttp.MiddlewareHandlerResponse
----------|--------|------------|-------------------------------------------------------|----------------------------------
  :8000   | ALL    | /swagger/* | github.com/gogf/gf/v2/net/ghttp.(*Server).swaggerUI   | HOOK_BEFORE_SERVE
----------|--------|------------|-------------------------------------------------------|----------------------------------

因为演示使用的是Windows系统，所以生成的是main.exe文件，如果你使用的是Mac/Linux系统，生成的是main文件。

然后我们在浏览器中输入http://127.0.0.1:8000/hello，或者使用接口测试工具访问，看到Hello, GoFrame!即表示你已经成功启动了一个GoFrame项目。恭喜您走出了伟大编程的第一步！

如果你使用的编辑器是IntelliJ IDEA或者GoLand，可以安装GoFrame Helper插件，以提供更友善的代码提示和自动补全功能等功能。

升级项目​

默认安装的GoFrame不一定是最新版本，你可以在项目目录下执行up命令升级：

$ gf up

项目目录结构​

项目初始化后，我们来看一下项目的目录结构：

目录/文件名称说明描述
api对外接口对外提供服务的输入/输出数据结构定义。考虑到版本管理需要，往往以 api/xxx/v1... 存在。
hack工具脚本存放项目开发工具、脚本等内容。例如，CLI 工具的配置，各种 shell/bat 脚本等文件。
internal内部逻辑业务逻辑存放目录。通过 Golang internal 特性对外部隐藏可见性。
    cmd入口指令命令行管理目录。可以管理维护多个命令行。
    consts常量定义项目所有常量定义。
    controller接口处理接收/解析用户输入参数的入口/接口层。
    dao数据访问数据访问对象，这是一层抽象对象，用于和底层数据库交互，仅包含最基础的 CURD 方法。
    logic业务封装业务逻辑封装管理，特定的业务逻辑实现和封装。往往是项目中最复杂的部分。
    model结构模型数据结构管理模块，管理数据实体对象，以及输入与输出数据结构定义。
        do领域对象用于 dao 数据操作中业务模型与实例模型转换，由工具维护，用户不能修改。
        entity数据模型数据模型是模型与数据集合的一对一关系，由工具维护，用户不能修改。
    service业务接口用于业务模块解耦的接口定义层。具体的接口实现在 logic 中进行注入。
manifest交付清单包含程序编译、部署、运行、配置的文件。常见内容如下：
    config配置管理配置文件存放目录。
    docker镜像文件Docker 镜像相关依赖文件，脚本文件等等。
    deploy部署文件部署相关的文件。默认提供了 Kubernetes 集群化部署的 Yaml 模板，通过 kustomize 管理。
    protobuf协议文件GRPC 协议时使用的 protobuf 协议定义文件，协议文件编译后生成 go 文件到 api 目录。
resource静态资源静态资源文件。这些文件往往可以通过资源打包/镜像编译的形式注入到发布文件中。
go.mod依赖管理使用 Go Module 包管理的依赖描述文件。
main.go入口文件程序入口文件。

看起来似乎一头雾水啊，不必担心，重要的目录都会在后面陆续用到。

然后我们把初始的示例文件全部删除，留下一个空白的环境，用作后续开发。先按CTRL+C终止项目运行，删除如下目录内的所有文件：

api/*
internal/controller/*

编辑cmd文件，去掉不必要的代码。

internal/cmd/cmd.go

package cmd

import (
    "context"

    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/net/ghttp"
    "github.com/gogf/gf/v2/os/gcmd"
)

var (
    Main = gcmd.Command{
        Name:  "main",
        Usage: "main",
        Brief: "start http server",
        Func: func(ctx context.Context, parser *gcmd.Parser) (err error) {
            s := g.Server()
            s.Group("/", func(group *ghttp.RouterGroup) {
                group.Middleware(ghttp.MiddlewareHandlerResponse)
            })
            s.Run()
            return nil
        },
    }
)