Go-Zero界说API实战：探索API语法规范与最佳实践（五）
前言上一篇文章带你实现了Go-Zero模板定制化，本文将继续分享如何使用GO-ZERO举行业务开发。
通过编写API层，我们可以或许对外举行接口的袒露，因此学习规范的API层编写姿势是很重要的。
通过本文的分享，你将可以或许学习到Go-Zero的API语法规范，以及学会实际上手使用。
概述
下文所说的是 api 是 go-zero 自研的范畴特性语言（下文称 api 语言 或 api 描述语言），旨在实现人性化的底子描述语言，作为天生 HTTP 服务最基本的描述语言。
api 范畴特性语言包含语法版本、info 块、结构体声明、服务描述等几大块语法构成，其中结构体和 Golang 结构体 语法险些一样，只是移除了 struct 关键字。
实战前准备
首先需要你在本地安装goctl、go-zero，下载讲授和地点点击这里，按照教程操作即可，非常简单。
下面按次序和我操作吧，对使用模板快速天生API层不清楚的同学务必先看我前篇文章：Go-Zero goctl实战
这里我假设你已经创建好了一个API服务的demo，且目录结构长这样：
https://files.mdnice.com/user/36414/737c9348-7653-4712-b19c-14699f11fbf1.png
学习API语法
对于Go语言开发者来说，Go-Zero的API语法学习和理解成本极低，我们可以很轻松的学会API语法。下面我会为大家介绍重点需要掌握的语法。更详细的语法规范，可以参考官网：API 规范 | go-zero Documentation
天生API文件
cd demo
goctl api go -api demo.api -dir . -style gozero
[*]底子的API文件
https://files.mdnice.com/user/36414/1502a109-078a-46c9-82fc-5285a342dda7.png
ID标识符
golang中的预界说类型、常量、函数，以及关键字在api内里同样实用
[*]预界说
//预定义类型:
any bool byte comparable
complex64 complex128 error float32 float64
int int8 int16 int32 int64 rune string
uint uint8 uint16 uint32 uint64 uintptr
//预定义常量:
true false iota
//零值:
nil
//预定义函数:
append cap close complex copy delete imag len
make new panic print println real recover
[*]关键字
break default func interface select
case defer go map struct
chan else goto package switch
const fallthroughif range type
continue for import return vartip:需要注意的是 goctl api不支持any类型！！！
类型声明
规则
[*]类型声明必须以 type 开头
[*]不需要声明 struct关键字
[*]不支持嵌套结构体声明
[*]不支持别名
示例
type StructureExample {
// 基本数据类型示例
BaseInt int `json:"base_int"`
BaseBool bool `json:"base_bool"`
BaseStringstring`json:"base_string"`
BaseByte byte `json:"base_byte"`
BaseFloat32 float32 `json:"base_float32"`
BaseFloat64 float64 `json:"base_float64"`
// 切片示例
BaseIntSlice []int `json:"base_int_slice"`
BaseBoolSlice []bool `json:"base_bool_slice"`
BaseStringSlice[]string`json:"base_string_slice"`
BaseByteSlice []byte `json:"base_byte_slice"`
BaseFloat32Slice []float32 `json:"base_float32_slice"`
BaseFloat64Slice []float64 `json:"base_float64_slice"`
// map 示例
BaseMapIntString mapstring `json:"base_map_int_string"`
BaseMapStringInt mapint `json:"base_map_string_int"`
BaseMapStringStruct map*StructureExample `json:"base_map_string_struct"`
BaseMapStringIntArray map[]int `json:"base_map_string_int_array"`
// 匿名示例
*Base
// 指针示例
Base4 *Base `json:"base4"`
// 新的特性（ goctl >= 1.5.1 版本支持 ）
// 标签忽略示例
TagOmit string
}路由前缀
我们可以通过prefix关键字区分路由组
https://files.mdnice.com/user/36414/c7cb5a99-1ca4-43be-9587-0bb1fd2677ff.png
接着再使用goctl api天生代码以及swagger，将swagger导入apifox查看路由前缀，可以看见就增添了前缀/demo。
不知道怎么天生api代码的同学可以看我往期的gozero实战分享——go-zero goctl实战
https://files.mdnice.com/user/36414/25d3a597-3beb-494f-8d6c-f9ad795d8dd9.png
服务分组
当我们的业务体量上来后，服务接口也会越来越多，天生的代码文件（handler、logic文件等）也会越来越多。这时候我们就需要对差别的接口按肯定的分组举行区分，用文件夹举行隔离，以便于开发和维护。
[*]分组前的目录结构是这样的
https://files.mdnice.com/user/36414/fbedb648-4c68-40ba-9790-b9cdec7e41fe.png
[*]我们先将天生的handler和logic文件删除。
[*]只需要在@server语句块内里添加关键字group就能举行分组。分组后的结构如下图所示。
https://files.mdnice.com/user/36414/08c2ef6b-4ab0-40f9-95a7-e3e16da539eb.png
JWT校验
[*]接下来我们再来看一下api文件中怎么开启jwt认证
[*]在配置文件demo-api.yaml中添加jwt配置
https://files.mdnice.com/user/36414/a60fd19a-d463-4445-bb7e-a759fb636234.png
[*]在config文件中添加一个JWT认证需要的密钥和逾期时间配置
JwtAuth struct { // JWT 认证需要的密钥和过期时间配置
AccessSecret string
AccessExpire int64
}https://files.mdnice.com/user/36414/84531b4a-cd8e-43d6-9333-6bea58146c57.png
[*]使用方法也很简单，我们在@service语句块中添加jwt关键字，使用Auth即可开启jwt。
https://files.mdnice.com/user/36414/3862faa7-75b1-4aea-8591-9f714ed7bf0f.png
[*]通过测试请求我们可以看见返回401没有权限，说明jwt校验见效了
https://files.mdnice.com/user/36414/d8df8ed3-de62-4abc-a0ec-def105e24484.png
路由规则
[*]路由必须以 / 开头 2. 路由节点必须以 / 分隔
[*]路由节点中可以包含 :，但是 : 必须是路由节点的第一个字符，: 背面的节点值必须要在结请求体中有 path tag 声明，用于接收路由参数，详细规则可参考 路由参数。 4. 路由节点可以包含字母、数字(goctl 1.5.1 支持，可参考新版 API 解析器使用)、下划线、中划线
参数规则
接收规则说明见效范围示例jsonjson 序列化请求体&响应体json:"foo"path路由参数请求体path:"id"formpost 请求的表单(支持 content-type 为 form-data 和 x-www-form-urlencoded) 参数请求接收标识，get 请求的 query 参数接收标识请求体form:"name"headerhttp 请求体接收标识请求体header:"Content-Length"中间件声明
[*]想要使用中间件，可以在@server语句块中使用关键字middleware天生一个中间件模板。
[*]TIP：需要注意的是中间件首字母必须大写，否则无法被其他包导入。
https://files.mdnice.com/user/36414/2f885474-dc62-4297-a926-0b9cf17dae2d.png
[*]在svc包的servicecontext.go中注册中间件
https://files.mdnice.com/user/36414/0fe8d47e-b1c5-433d-81d8-51fb677798dc.png
[*]天生的中间件代码如下
https://files.mdnice.com/user/36414/8b89b0bd-bd98-4619-8a91-254c89a45547.png
API Import
[*]当我们的业务体量上来后，api文件可能会越来越大，又或者我们有一些公共结构体。如果我们都写在同一个api文件中，那么api文件将会变得非常巨大，不易阅读和维护，这时候就需要拆解api文件，通过import来导入。
syntax
[*]版本信息，import中的版本信息必须与被import的api版本信息一样。
[*]规范写法
syntax = "v1"
[*]我们创建一个新的文件demo1.api，并且将分组而写到这个api文件下。
[*]由于我们的请求体和响应体是公共结构体，都写在demo.api下面了，我们通过import "demo.api"就能导入demo.api。
https://files.mdnice.com/user/36414/d0acb93c-4254-4d42-a51e-3071ed97f84d.png
完整的api文件模板
syntax = "v1"
type Request {
Name string `path:"name,options=you|me"`
}
type Response {
Message string `json:"message"`
}
@server (
prefix :/demo
group: demo_api
jwt: JwtAuth
middleware: Demo_middleware
)
// 分组1的服务
service demo-api {
@handler DemoHandler
post /from (Request) returns (Response)
}
// 分组2的服务
@server (
prefix :/demo1
group: demo_api1
)
service demo-api {
@handler DemoHandler1
get /from/:name(Request) returns (Response)
}总结
这篇文章详细介绍了如何使用Go-Zero举行API的界说，并举行了实际演示。希望对你有帮助。
我将继续更新Go-Zero系列文章，如果你对Go语言或者微服务感兴趣，欢迎关注我，也欢迎直接私信我。
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。
页:
[1]