示例项目 | GoFrame官网 - 类似PHP-Laravel,Java-SpringBoot的Go企业级开发框架

Version: Latest

示例是最好的文档，我们为大家准备了一个简单的 API 示例项目，大家可以通过示例项目源码更进一步学习框架使用。当大家在阅读示例项目的源码时有疑问的地方，请查阅开发手册中对应的模块文档。

项目介绍

我们以一个简单的基于 HTTP 的 API Service 为例来介绍如何使用 GoFrame 框架以及相应的 CLI 工具来开发一个接口项目。

代码地址： https://github.com/gogf/gf-demo-user

git clone https://github.com/gogf/gf-demo-user

请先尝试将此项目在本地运行起来。再接下来我们将会给大家介绍这个示例项目的一些细节。

要点介绍

接口定义

接口注册文件位于 api 目录下，由于该项目采用了规范路由注册方式，因此在API结构体的属性中包含一些标签。其中结构体属性的 v 标签表示校验规则，请求参数进入 HTTP Server 后将会被自动执行校验（框架有非常强大的数据校验组件，更详细的介绍请参考章节：数据校验）

tip

框架中所有涉及到的标签请参考章节：常见问题(FAQ)

路由注册

路由注册往往在 cmd 包中，在本项目中，仍旧采用灵活的分组路由注册方式。在部分路由中带有鉴权中间件，这部分路由需要鉴权后才能访问，感兴趣的小伙伴可以仔细研究下源码的实现原理。关于路由中间件的详细介绍请参考章节：路由管理-中间件/拦截器

常量管理

项目的全局访问常量位于 internal/consts 包下，供项目所有的包全局可访问， 全局常量通过不同的文件以及名称命名前缀来区分不同的业务模块。需要注意的是，不建议所有的常量都丢到 internal/consts 下，非公开的常量建议放到对应的包下面闭环维护。

控制器定义

控制器往往不带有任何的业务逻辑，负责 API 接口数据结构的输入与输出，调用一个或多个 service 实现具体的业务逻辑。关于项目工程设计中各个部分的职责请参考章节：工程目录设计🔥

数据库访问

驱动引入（仅一次）

首先，需要引入对应的驱动文件，由于我们这里使用的是 MySQL，我们需要在 main.go 中引入以下驱动文件：

tip

关于驱动的支持以及使用请参考链接： https://github.com/gogf/gf/tree/master/contrib/drivers

数据库配置

数据库的配置使用 database 配置项，关于数据库配置的详细介绍请参考章节： ORM使用配置

dao代码生成

在业务项目中，我们 推荐使用 dao/do/entity 的方式操作数据库， 这些文件都是通过开发工具自动生成的，由开发工具统一维护。

代码生成方式通过 make dao 命令，或者 gf gen dao 命令，如下：

tip

关于数据库痛点及设计请参考章节： DAO封装设计，关于数据库代码文件生成工具的介绍请参考章节：数据规范-gen dao

业务模型

业务项目中内部 模块间交互的数据结构 由 model 包维护，供全局访问。更多的介绍请参考章节：数据模型与业务模型

服务接口

为了降低业务项目内部模块间的耦合，框架将模块间的依赖抽象为了接口，由 internal/service 包维护。 internal/service 可以由开发者自定义维护接口，也可以通过 internal/logic 业务封装的代码按照一定规则自动生成接口代码文件。具体请参考章节：模块规范-gen service

业务实现

业务的具体实现由 internal/logic 包维护，通过依赖注入的方式注册具体的实现对象到 internal/service 包下。

依赖注入

业务实现的依赖注入使用的是匿名包初始化方法 init，在匿名包初始化方法内部使用 service.RegisterXxx 的方式注入具体的接口实现对象。

增加引入（仅一次）

匿名包初始化方法需要通过 import 方式引入，该引入用于将业务逻辑具体实现注册到 internal/service 下。这种依赖往往需要在 main.go 中顶部引入。

tip

需要注意，在通过框架开发工具自动生成 service 层接口文件时，开发工具同时也会自动更新最外层的 main.go，自动增加 logic 引入，无需开发者操心。

代码生成

框架的目的是让开发者将精力聚焦于业务逻辑实现本身。在开发业务项目时，非业务相关的冗余代码都可以通过开发工具生成，例如以下层级代码：

controller
dao/entity/do
service

更详细的介绍请参考开发工具章节：代码生成-gen(🔥重点🔥)

接口测试

我们通过 curl 命令来对其中两个接口执行简单的测试。

用户注册 - `/user/signup`

注册一个账号 test001，昵称为 john，密码为 123456。

curl -d 'nickname=john&passport=test001&password=123456&password2=123456' http://127.0.0.1:8000/user/sign-up

{"code":0,"message":"","data":null}

我们再次使用刚才的信息注册一次试试。

curl -d 'nickname=john&passport=test001&password=123456&password2=123456' http://127.0.0.1:8000/user/sign-up

{"code":50,"message":"Passport \"test001\" is already token by others","data":null}

可以看到注册失败了，相同名称只能注册一个账号。

用户登录 - `/user/signin`

我们先访问获取用户信息的接口，验证鉴权中间件是否生效。

curl http://127.0.0.1:8000/user/profile

Forbidden

我们用刚才注册的账号登录。

curl -i -d 'passport=test001&password=123456' http://127.0.0.1:8000/user/sign-in

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin,Content-Type,Accept,User-Agent,Cookie,Authorization,X-Auth-Token,X-Requested-With
Access-Control-Allow-Methods: GET,PUT,POST,DELETE,PATCH,HEAD,CONNECT,OPTIONS,TRACE
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 3628800
Content-Type: application/json
Server: GoFrame HTTP Server
Set-Cookie: gfsessionid=14sc9nep0u6yl0cieluexn0n0w2008q7; Path=/; Expires=Wed, 09 Mar 2022 15:52:44 GMT; SameSite
Trace-Id: 4830f6adbb72da16f34b7162f93080d8
Date: Tue, 08 Mar 2022 15:52:44 GMT
Content-Length: 35

{"code":0,"message":"","data":null}

我们这里使用了 -i 选项用于终端打印出服务端返回的 Header 信息，目的是为了获取 sessionid。 GoFrame 框架默认的 sessionid 名称为 gfsessionid，我们看到返回的 Header 中已经有了，并且是通过 Cookie 方式返回的。

随后我们再次访问获取用户信息接口，并且这次提交 gfsessionid，该信息可以通过 Header 也可以通过 Cookie 提交，服务端都是能够自动识别的。

curl -H 'gfsessionid:14sc9nep0u6yl0cieluexn0n0w2008q7' http://127.0.0.1:8000/user/profile

{"code":0,"message":"","data":{"id":1,"passport":"test001","password":"123456","nickname":"john","createAt":"2022-03-08 23:51:40","updateAt":"2022-03-08 23:51:40"}}

项目介绍​

要点介绍​

接口定义​

路由注册​

常量管理​

控制器定义​

数据库访问​

驱动引入（仅一次）​

数据库配置​

dao代码生成​

业务模型​

服务接口​

业务实现​

依赖注入​

增加引入（仅一次）​

代码生成​

接口测试​

用户注册 - /user/signup​

用户登录 - /user/signin​

更多示例​