首页 > 其他分享 >Go-Zero定义API实战:探索API语法规范与最佳实践(五)

Go-Zero定义API实战:探索API语法规范与最佳实践(五)

时间:2024-05-14 15:58:09浏览次数:25  
标签:string api demo json Zero API base Go

前言

上一篇文章带你实现了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文件

cd demo  
goctl api go -api demo.api -dir . -style gozero  
  • 基础的API文件

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        fallthrough  if           range        type  
continue     for          import       return       var  

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

类型声明

规则

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

示例

type StructureExample {  
    // 基本数据类型示例  
    BaseInt     int     `json:"base_int"`  
    BaseBool    bool    `json:"base_bool"`  
    BaseString  string  `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      map[int]string               `json:"base_map_int_string"`  
    BaseMapStringInt      map[string]int               `json:"base_map_string_int"`  
    BaseMapStringStruct   map[string]*StructureExample `json:"base_map_string_struct"`  
    BaseMapStringIntArray map[string][]int             `json:"base_map_string_int_array"`  
    // 匿名示例  
    *Base  
    // 指针示例  
    Base4 *Base `json:"base4"`  
      
    // 新的特性( goctl >= 1.5.1 版本支持 )  
    // 标签忽略示例  
    TagOmit string  
}  

路由前缀

我们可以通过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认证需要的密钥和过期时间配置
JwtAuth struct { // JWT 认证需要的密钥和过期时间配置  
    AccessSecret string  
    AccessExpire int64  
}  

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

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

路由规则

  1. 路由必须以 / 开头 2. 路由节点必须以 / 分隔
  2. 路由节点中可以包含 :,但是 : 必须是路由节点的第一个字符,: 后面的节点值必须要在结请求体中有 path tag 声明,用于接收路由参数,详细规则可参考 路由参数。 4. 路由节点可以包含字母、数字(goctl 1.5.1 支持,可参考 新版 API 解析器使用)、下划线、中划线

参数规则

接收规则 说明 生效范围 示例
json json 序列化 请求体&响应体 json:"foo"
path 路由参数 请求体 path:"id"
form post 请求的表单(支持 content-type 为 form-datax-www-form-urlencoded) 参数请求接收标识,get 请求的 query 参数接收标识 请求体 form:"name"
header http 请求体接收标识 请求体 header:"Content-Length"

中间件声明

  • 想要使用中间件,可以在@server语句块中使用关键字middleware生成一个中间件模板。
  • TIP:需要注意的是中间件首字母必须大写,否则无法被其他包导入。

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

  • 生成的中间件代码如下

API Import

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

syntax

  • 版本信息,import中的版本信息必须与被import的api版本信息一样。
  • 规范写法
syntax = "v1"  
  • 我们创建一个新的文件demo1.api,并且将分组而写到这个api文件下。
  • 因为我们的请求体和响应体是公共结构体,都写在demo.api下面了,我们通过import "demo.api"就能导入demo.api。

完整的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语言或者微服务感兴趣,欢迎关注我,也欢迎直接私信我。

标签:string,api,demo,json,Zero,API,base,Go
From: https://www.cnblogs.com/wangzhongyang/p/18191472

相关文章

  • Django RESTful API设计与实践指南
    title:DjangoRESTfulAPI设计与实践指南date:2024/5/1415:37:45updated:2024/5/1415:37:45categories:后端开发tags:DjangoRESTAPI设计版本控制安全认证性能优化部署策略实战项目第1章:Django基础知识1.1Django简介:Django是一个使用Python语言开发......
  • [Algorithm] Prim's Algorithm
    Prim'salgorithmisapopularmethodusedincomputerscienceforfindingaminimumspanningtreeforaconnected,undirectedgraph.Thismeansitfindsasubsetoftheedgesthatformsatreethatincludeseveryvertex,wherethetotalweightofall......
  • THUSC2024 & APIO2024 游记
    THUSC2024Day0Day1THUSC极速版?上午试机,水\(100+\varepsilon\)分跑路,日常不做元旦激光炮(下午直接快进到Day1(那我缺的讲座这一块,谁给我补啊?).首先开T1好像就是一个简单状压数位DP,不过不太会写数位DP了,大概1.5h后获得了85pts.然后看T2,预计是高明题,所以直接......
  • 一次性临时gmail邮箱 API免费调用
    如果你不想在某些平台注册时使用自己的邮箱,可以使用iDataRiver平台提供的一次性匿名邮箱API,可每次随机获取一个临时邮箱,支持gmail,重点是免费使用。临时邮箱API文档https://idatariver.com/zh-cn/project/temp-mail-api-cbea接口列表1.随机获取一个邮箱(可指定获取gmail)获取......
  • USB-CyAPI
    1.引用CyAPI.lib2.USBCOM.h1#pragmaonce23#include<QtWidgets/QDialog>4#include"ui_USBCOM.h"5#include<Windows.h>6#include"cyAPI.h"7#include<QTimer>8classUSBCOM:publicQDialog9{10Q_......
  • GO 中间件方式执行额外任务
    packagemainimport( "database/sql" "fmt" "mylog" "time")typeMiddlewarestruct{}/*如遇错误,执行额外任务*/func(m*Middleware)Println(vinterface{}){ iferr,ok:=v.(error);ok{ mylog.Println("执行额外任务:&......
  • apisix~lua插件开发与插件注册
    开发插件的步骤在APISIX中,要自定义插件,一般需要按照以下步骤进行操作:编写Lua脚本:首先,你需要编写Lua脚本来实现你想要的功能。可以根据APISIX提供的插件开发文档和示例进行编写。将Lua脚本放置到APISIX插件目录:将编写好的Lua脚本文件放置到APISIX的插件目录下,一般是/usr/loc......
  • 今天学了vue3的composition API
    代码量:60左右时间:1h搏客量:1<!DOCTYPEhtml><htmllang="en"><head><metacharset="UTF-8"><linkrel="icon"href="/favicon.ico"><metaname="viewport"content="wi......
  • mongodb数据库:手动释放磁盘空间
    平台:阿里云mongoDB云数据库版本:Mongodb4.2数据库集群方案:一主二从三分片需求:手动释放过剩磁盘空间从文档解析可知:delete数据或者做分片数据迁移,并不会释放磁盘空间,而是将这些空间标记为reuse可重用状态,后续新写入的数据会重用这部分空间。需求是手动释放这些空间,使用compact......
  • 【django学习-22】列表界面搜索功能
    1.需求:靓号列表界面,根据手机号码模糊匹配2.前端传search_data<divstyle="float:right;width:300px;"><formmethod="get"><divclass="input-group"><inputtype="text"name="q"clas......