go-zero学习第二章进阶之API_go-zero syntax是用来干什么的(1)

本文链接：https://blog.csdn.net/2301_82243100/article/details/137762116

先自我介绍一下，小编浙江大学毕业，去过华为、字节跳动等大厂，目前阿里P7

深知大多数程序员，想要提升技能，往往是自己摸索成长，但自己不成体系的自学效果低效又漫长，而且极易碰到天花板技术停滞不前！

因此收集整理了一份《2024年最新Golang全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友。

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，涵盖了95%以上Go语言开发知识点，真正体系化！

由于文件比较多，这里只是将部分目录截图出来，全套包含大厂面经、学习笔记、源码讲义、实战项目、大纲路线、讲解视频，并且后续会持续更新

如果你需要这些资料，可以添加V获取：vip1024b （备注go）

正文

示例1：

// 空内容
@server()

// 有内容
@server (
// jwt 声明
// 如果 key 固定为 “jwt:”，则代表开启 jwt 鉴权声明
// value 则为配置文件的结构体名称
jwt: Auth

// 路由前缀
// 如果 key 固定为 “prefix:”
// 则代表路由前缀声明，value 则为具体的路由前缀值，字符串中没让必须以 / 开头
prefix: /v1

// 路由分组
// 如果 key 固定为 “group:”，则代表路由分组声明
// value 则为具体分组名称，在 goctl生成代码后会根据此值进行文件夹分组
group: Foo

// 中间件
// 如果 key 固定为 middleware:”，则代表中间件声明
// value 则为具体中间件函数名称，在 goctl生成代码后会根据此值进生成对应的中间件函数
middleware: AuthInterceptor

// 超时控制
// 如果 key 固定为 timeout:”，则代表超时配置
// value 则为具体中duration，在 goctl生成代码后会根据此值进生成对应的超时配置
timeout: 3s

// 其他 key-value，除上述几个内置 key 外，其他 key-value
// 也可以在作为 annotation 信息传递给 goctl 及其插件，但就
// 目前来看，goctl 并未使用。
foo: bar
)

示例2（实际使用）：

@server(
jwt: Auth
middleware: CheckUrl
group: app/appSystem
prefix: /app/appSystem
)

6 @doc 语句
@doc 语句是对单个路由的 meta 信息描述，一般为 key-value 值，可以传递给 goctl 及其插件来进行扩展生成。

示例1：

// 单行 @doc
@doc “foo”

// 空 @doc 组
@doc ()

// 有内容的 @doc 组
@doc (
foo: “bar”
bar: “baz”
)

示例2（实际使用）：

@doc(
summary: “XXX列表”
)

7 @handler 语句
@handler 语句是对单个路由的 handler 信息控制，主要用于生成 golang http.HandleFunc 的实现转换方法。

示例：

@handler foo

@handler GetClassLabelHandler

注意：不论定义的handler是否有handler后缀，goctl根据api实际生成的代码文件均会以xxxhandler为后缀，所以在api中定义handler时加不加handler后缀没有意义。

8 HTTP 路由语句
路由语句是对此 HTTP 请求的具体描述，包括请求方法，请求路径，请求体，响应体信息。

示例：

// 没有请求体和响应体的写法
get /ping

// 只有请求体的写法
get /foo (foo)

// 只有响应体的写法
post /foo returns (foo)

// 有请求体和响应体的写法
post /foo (foo) returns (bar)

9 HTTP 服务声明语句
示例：

// 带 @server 的写法
@server (
prefix: /v1
group: Login
)
service user {
@doc “登录”
@handler login
post /user/login (LoginReq) returns (LoginResp)

@handler getUserInfo
get /user/info/:id (GetUserInfoReq) returns (GetUserInfoResp)
}
@server (
prefix: /v1
middleware: AuthInterceptor
)
service user {
@doc “登录”
@handler login
post /user/login (LoginReq) returns (LoginResp)

@handler getUserInfo
get /user/info/:id (GetUserInfoReq) returns (GetUserInfoResp)
}

// 不带 @server 的写法
service user {
@doc “登录”
@handler login
post /user/login (LoginReq) returns (LoginResp)

@handler getUserInfo
get /user/info/:id (GetUserInfoReq) returns (GetUserInfoResp)
}

10 注释语句
在 api 领域特性语言中有 2 种格式：

单行注释以 // 开始，行尾结束。
多行注释（文档注释）以 /* 开始，以第一个 */ 结束。

3 API服务代码实战

参考1：请求参数

前面讲解了api文件的语法，这里在使用时具体讲解一些细节，主要有以下内容：

path参数
form参数
json参数
header参数
参数修饰符
文件上传/下载
请求体大小限制
api分组
中间件
统一返回信息
鉴权【需要结合rpc服务，下一节再讲解】

1、2、3、4、5、6、7都是针对请求参数，1、2、3、4可以划归为一组，在绑定参数时，只能选择1、2、3、4其中一个。

请求参数：

标签类型	描述	提供方	使用范围	示例
path	路由path，如/foo/:id	go-zero	request	`path:"id"`
form	标志请求体是一个form（`POST`方法时）或者一个query(`GET`方法时/search?name=keyword)	go-zero	request	`form:"name"`
json	json序列化tag	golang	request、response	`json:"fooo"`
header	HTTP header，如 `Name: value`	go-zero	request	`header:"name"`

参数修饰符：

标签类型	描述	提供方	使用范围	示例
optional	定义当前字段为可选参数	go-zero	request	`json:"name,optional"`
options	定义当前字段的枚举值，多个以,隔开	go-zero	request	`json:"gender,options=male,emale"`
default	定义当前字段默认值	go-zero	request	`json:"gender,default=male"`
range	定义当前字段`数值`范围	go-zero	request	`json:"age,range=[0:120]"`

3.1 请求参数、文件上传/预览、分组示例

代码：请求参数、文件上传/预览、分组示例代码示例
1 api文件：

syntax = “v1”

info(
title : “go-zero-api”
desc: “ucenter”
author: “ximuqi”
email: “xxx”
version: “0.0.1”
)

type (
/* 1 公用类（json） */
BaseModelJson {
Id int64 json:"id" // id
Name string json:"name,optional" // 名称
Data string json:"data,optional" // 数据
}

/* 2 公用类（form） */
BaseModelForm {
Id int64 form:"id" // id
Name string form:"name,optional" // 名称
Data string form:"data,optional" // 数据
}

/* 3 公用类 Path */
PathReq {
Id int64 path:"id" // id
Name string path:"name" // 名称
}

/* 4 上传文件 */
FileUploadReq {
Id int64 form:"id" // 父级-id
Type int64 form:"type,optional" // 类型 1：证书文件；2：私钥文件
FileList []*byte form:"fileList,optional" // 文件列表
}

/* 5 下载/预览文件 */
FileShowReq {
Id int64 form:"id" // 文件-id
FileUrl string form:"fileUrl,optional" // 文件地址
}

/* 6 用户账号密码登录 model */
UserModel {
Account string json:"account" // 账号
Password string json:"password" // 密码
Gender int64 json:"gender,options=1:2:3" // 性别 1：未设置；2：男性；3：女性
Current int64 json:"current,optional,default=1" // 当前页码
PageSize int64 json:"pageSize,optional,default=20" // 每页数量
}

/* 7 用户登录返回 model */
UserLoginResp {
Id int64 json:"id" // 用户id
Account string json:"account" // 账号
Username string json:"username" // 登录账号
Gender int64 json:"gender" // 性别 1：未设置；2：男性；3：女性
Avatar string json:"avatar" // 头像
AccessToken string json:"token" // token
AccessExpire int64 json:"accessExpire" // 过期时间戳
RefreshAfter int64 json:"refreshAfter" //
}
)

@server(
middleware: Check
group: ucenter
prefix: /ucenter
)
service uCenter {
@doc(
summary: “1 json参数”
)
@handler jsonParam
post /jsonParam (BaseModelJson) returns (BaseModelJson)

@doc(
summary: “2 表单参数（post）”
)
@handler formParamPost
post /formParamPost (BaseModelForm) returns (BaseModelJson)

@doc(
summary: “3 表单参数（Get）”
)
@handler formParamGet
get /formParamGet (BaseModelForm) returns (BaseModelJson)

@doc(
summary: “4 path参数”
)
@handler pathParam
get /pathParam/:id/:name (PathReq) returns (BaseModelJson)

@doc(
summary: “5 文件上传”
)
@handler uploadFile
post /uploadFile (FileUploadReq) returns (BaseModelJson)

@doc(
summary: “6 文件下载”
)
@handler downloadFile
get /downloadFile (FileShowReq)

@doc(
summary: “7 文件预览”
)
@handler previewFile
get /previewFile (FileShowReq)
}

@server(
group: group2
prefix: /group2
)
service uCenter {
@doc(
summary: “8 登录”
)
@handler login
post /login (UserModel) returns (UserLoginResp)
}

2 api生成api服务命令

go-zero-api\api> goctl api go -api ./doc/ucenter.api -dir ./code

3 代码结构

#查看目录文件结构
tree /f
#查看目录结构
tree

目录结构：

└─api
├─code
│ ├─etc
│ └─internal
│ ├─config
│ ├─handler
│ │ ├─group2
│ │ └─ucenter
│ ├─logic
│ │ ├─group2
│ │ └─ucenter
│ ├─middleware
│ ├─svc
│ └─types
└─doc

目录结构说明：
etc：静态配置文件目录
conf：静态配置文件对应的结构体声明目录
handler：handler 为固定后缀，其下的两个分组一般不需要修改，只有在文件上传下载时需要特殊处理。
logic：业务目录，所有业务编码文件都存放在这个目录下面，logic 为固定后缀。
middleware：中间件。
svc：依赖注入目录，所有 logic 层需要用到的依赖都要在这里进行显式注入。
types：结构体存放目录。

通过目录结构可以看到，在handler和logic目录下都有ucenter、group2文件夹，这是分组的结果，我们的逻辑代码主要在logic下。

4 请求测试
根据.api文件api模块代码生成时默认的端口是 8888，查看及修改是在etc目录下的yaml文件，具体修改详见代码。

1 json参数请求测试
在logic/ucenter目录下jsonparamlogic.go编写代码逻辑。

请求地址：http://localhost:8888/ucenter/jsonParam
请求方式：POST
请求格式：JSON
请求数据：{"id":1,"name":"测试"}
返回结果：{"id":1,"name":"测试","data":""}

2 form参数请求测试【POST】
在logic/ucenter目录下formparampostlogic.go编写代码逻辑。

请求地址：http://localhost:8888/ucenter/formParamPost
请求方式：POST
请求格式：FORM
请求数据：id=2,name="hello"
返回结果：{"id":2,"name":"hello","data":""}

3 form参数请求测试【GET】
在logic/ucenter目录下formparamgetlogic.go编写代码逻辑。

请求地址：http://localhost:8888/ucenter/formParamGet?id=3&name=hello&data=测试
请求方式：GET
请求格式：URL参数
请求数据：id=3&name=hello&data=测试"
返回结果：{"id":3,"name":"hello","data":"测试"}

4 path参数请求测试
在logic/ucenter目录下pathparamlogic.go编写代码逻辑。

请求地址：http://localhost:8888/ucenter/pathParam/4/hello
请求方式：GET
请求格式：URL参数
请求数据：id=4&name=hello"
返回结果：{"id":4,"name":"hello"}

5 文件上传请求测试
在logic/ucenter目录下uploadfilelogic.go编写代码逻辑。

注意：go-zero对上传文件有大小限制，默认最大为1MB，可在etc目录下的yaml文件中修改大小MaxBytes，并设置上传文件的存储路径。

Name: uCenter
Host: 0.0.0.0
Port: 8888

#web请求到此api服务的超时时间
Timeout: 10000

将请求体最大允许字节数从1MB改为1000MB

MaxBytes: 1048576000

#文件
UploadFile:
MaxFileNum: 1000
MaxFileSize: 1048576000 # 1000MB
SavePath: projects/go-zero-api/uploadFiles/

#日志配置
Log:
Mode: file
Path: log/go-zero-api
Level: error
Compress: true
KeepDays: 180

请求地址：http://localhost:8888/ucenter/downloadFile
请求方式：GET
请求格式：FORM
请求数据：id=1&name=1_aab7803750b6412e98a9c63196efc6e8.png
返回结果：{"id":5,"name":"","data":"操作成功"}

6 文件下载
文件下载是把数据写到响应流中，所以需要同时修改downloadfilehandler.go和downloadfilelogic.go，详见代码。

7 文件预览
文件预览也是把数据写到响应流中，所以需要同时修改previewfilehandler.go和previewfilelogic.go，预览针对的是多媒体文件，如音视频、照片等，比下载少了在响应流中的流配置以及文件名称，详见代码。

3.2 中间件、统一返回信息代码示例

代码：中间件、统一返回信息代码示例

全局中间件的讲解

中间件
统一返回信息

中间件：
在3.1 请求参数、文件上传/预览、分组示例 中的api文件中已经涉及了【局部】中间件，但未深入讲解。实际上api服务的中间件分为局部中间件和全局中间件，在中间件中可以拦截请求/响应并作处理。

全局中间件是加在启动类上的，全局中间件、局部中间件都是一样的，只是位置不一样罢了：

// 全局中间件：用法一
server.Use(func(next http.HandlerFunc) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
logx.Info(“全局中间件”)
next(w, r)
}
})

// 全局中间件：用法二
server.Use(middleware.NewCheckUrlMiddleware().Handle)