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，且目录结构长这样：

学习API语法

对于Go语言开发者来说，Go-Zero的API语法学习和理解成本极低，我们可以很轻松的学会API语法。下面我会为大家介绍重点需要掌握的语法。更详细的语法规范，可以参考官网：API 规范 | go-zero Documentation
天生API文件

1. cd demo  
2. goctl api go -api demo.api -dir . -style gozero  

复制代码

• 底子的API文件
  

ID标识符

golang中的预界说类型、常量、函数，以及关键字在api内里同样实用

• 预界说
  

1. //预定义类型:  
2.     any bool byte comparable  
3.     complex64 complex128 error float32 float64  
4.     int int8 int16 int32 int64 rune string  
5.     uint uint8 uint16 uint32 uint64 uintptr  
6.   
7. //预定义常量:  
8.     true false iota  
9.   
10. //零值:  
11.     nil  
12.   
13. //预定义函数:  
14.     append cap close complex copy delete imag len  
15.     make new panic print println real recover  

复制代码

• 关键字
  

1. break        default      func         interface    select  
2. case         defer        go           map          struct  
3. chan         else         goto         package      switch  
4. const        fallthrough  if           range        type  
5. continue     for          import       return       var  

复制代码

tip:需要注意的是 goctl api不支持any类型！！！
类型声明

规则

• 类型声明必须以 type 开头
  
• 不需要声明 struct关键字
  
• 不支持嵌套结构体声明
  
• 不支持别名
  

示例

1. type StructureExample {  
2.     // 基本数据类型示例  
3.     BaseInt     int     `json:"base_int"`  
4.     BaseBool    bool    `json:"base_bool"`  
5.     BaseString  string  `json:"base_string"`  
6.     BaseByte    byte    `json:"base_byte"`  
7.     BaseFloat32 float32 `json:"base_float32"`  
8.     BaseFloat64 float64 `json:"base_float64"`  
9.     // 切片示例  
10.     BaseIntSlice     []int     `json:"base_int_slice"`  
11.     BaseBoolSlice    []bool    `json:"base_bool_slice"`  
12.     BaseStringSlice  []string  `json:"base_string_slice"`  
13.     BaseByteSlice    []byte    `json:"base_byte_slice"`  
14.     BaseFloat32Slice []float32 `json:"base_float32_slice"`  
15.     BaseFloat64Slice []float64 `json:"base_float64_slice"`  
16.     // map 示例  
17.     BaseMapIntString      map[int]string               `json:"base_map_int_string"`  
18.     BaseMapStringInt      map[string]int               `json:"base_map_string_int"`  
19.     BaseMapStringStruct   map[string]*StructureExample `json:"base_map_string_struct"`  
20.     BaseMapStringIntArray map[string][]int             `json:"base_map_string_int_array"`  
21.     // 匿名示例  
22.     *Base  
23.     // 指针示例  
24.     Base4 *Base `json:"base4"`  
25.       
26.     // 新的特性（ goctl >= 1.5.1 版本支持 ）  
27.     // 标签忽略示例  
28.     TagOmit string  
29. }  

复制代码

路由前缀

我们可以通过prefix关键字区分路由组

接着再使用goctl api天生代码以及swagger，将swagger导入apifox查看路由前缀，可以看见就增添了前缀/demo。
不知道怎么天生api代码的同学可以看我往期的gozero实战分享——go-zero goctl实战

服务分组

当我们的业务体量上来后，服务接口也会越来越多，天生的代码文件（handler、logic文件等）也会越来越多。这时候我们就需要对差别的接口按肯定的分组举行区分，用文件夹举行隔离，以便于开发和维护。

• 分组前的目录结构是这样的
  

• 我们先将天生的handler和logic文件删除。
  
• 只需要在@server语句块内里添加关键字group就能举行分组。分组后的结构如下图所示。
  

JWT校验

• 接下来我们再来看一下api文件中怎么开启jwt认证
  
• 在配置文件demo-api.yaml中添加jwt配置
  

• 在config文件中添加一个JWT认证需要的密钥和逾期时间配置
  

1. JwtAuth struct { // JWT 认证需要的密钥和过期时间配置  
2.     AccessSecret string  
3.     AccessExpire int64  
4. }  

复制代码

• 使用方法也很简单，我们在@service语句块中添加jwt关键字，使用Auth即可开启jwt。
  

• 通过测试请求我们可以看见返回401没有权限，说明jwt校验见效了
  

路由规则

• 路由必须以 / 开头 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：需要注意的是中间件首字母必须大写，否则无法被其他包导入。
  

• 在svc包的servicecontext.go中注册中间件
  

• 天生的中间件代码如下
  

API Import

• 当我们的业务体量上来后，api文件可能会越来越大，又或者我们有一些公共结构体。如果我们都写在同一个api文件中，那么api文件将会变得非常巨大，不易阅读和维护，这时候就需要拆解api文件，通过import来导入。
  

syntax

• 版本信息，import中的版本信息必须与被import的api版本信息一样。
  
• 规范写法
  

1. syntax = "v1"  

复制代码

• 我们创建一个新的文件demo1.api，并且将分组而写到这个api文件下。
  
• 由于我们的请求体和响应体是公共结构体，都写在demo.api下面了，我们通过import "demo.api"就能导入demo.api。
  

完整的api文件模板

1. syntax = "v1"  
2.   
3. type Request {  
4.     Name string `path:"name,options=you|me"`  
5. }  
6.   
7. type Response {  
8.     Message string `json:"message"`  
9. }  
10.   
11. @server (  
12.     prefix :/demo  
13.     group: demo_api  
14.     jwt: JwtAuth  
15.     middleware: Demo_middleware  
16. )  
17. // 分组1的服务  
18. service demo-api {  
19.     @handler DemoHandler  
20.     post /from (Request) returns (Response)  
21. }  
22.   
23. // 分组2的服务  
24. @server (  
25.     prefix :/demo1  
26.     group: demo_api1  
27. )  
28. service demo-api {  
29.     @handler DemoHandler1  
30.     get /from/:name(Request) returns (Response)  
31. }  

复制代码

总结

这篇文章详细介绍了如何使用Go-Zero举行API的界说，并举行了实际演示。希望对你有帮助。
我将继续更新Go-Zero系列文章，如果你对Go语言或者微服务感兴趣，欢迎关注我，也欢迎直接私信我。

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。