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文件

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 解析器使用)、下划线、中划线

参数规则

接收规则说明生效范围示例
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版本信息一样。
  • 规范写法
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语言或者微服务感兴趣，欢迎关注我，也欢迎直接私信我。

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.mzph.cn/bicheng/12222.shtml

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

测试项目实战--安享理财2（Jmeter接口测试）

测试项目实战--安享理财2（Jmeter接口测试）

说明： 1.访问地址： 本项目实战使用的是传智播客的安享理财项目（找了半天这个项目能免费用且能够满足测试实战需求） 前台：http://121.43.169.97:8081/ 后台：http://121.43.169.97:8082/ （点赞收藏…
阅读更多...
前端工程化 - 快速通关 - vue

前端工程化 - 快速通关 - vue

目录 npm 2.1环境 2.2命令 2.3使用流程 Vite 3.1简介 3.2实战 Vue3 4.1组件化 4.2SFC 4.3Vue工程 4.4基础使用 4.5进阶用法 4.6总结 npm npm 是 nodejs 中进行 包管理 的工具； 下载：Node.js — Run JavaScript Everywhere 2.1环境 ●安…
阅读更多...
KubeKey 部署 K8s v1.28.8 实战

KubeKey 部署 K8s v1.28.8 实战

在某些生产环境下，我们仅需要一个原生的 K8s 集群，无需部署 KubeSphere 这样的图形化管理控制台。在我们已有的技术栈里，已经习惯了利用 KubeKey 部署 KubeSphere 和 K8s 集群。今天，我将为大家实战演示如何在 openEuler 22.03 LT…
阅读更多...
使用DBeaver的第2天-使用sql导入数据

使用DBeaver的第2天-使用sql导入数据

使用sql导入数据这块我会仔细的说一下 首先位置一定要放在库上（实例），放在表上可不好使用哦 然后点击工具-再点击执行脚本 这样就执行成功了 但是如果你执行失败了，多半可能是因为本地没有部署mysql，记住只有本地有…
阅读更多...
【IOS】swift新手踩坑总汇

【IOS】swift新手踩坑总汇

这里写自定义目录标题 ESTabBarController_swiftQMUIKit ESTabBarController_swift Exception NSException * "调用了 pushViewController 但实际上没 push 成功&#xff0c;viewController&#xff1a;<HuangShan.ViewControllers: 0x106832a00>; superclass: EST…
阅读更多...
【强训笔记】day23

【强训笔记】day23

NO.1 思路&#xff1a;直接计算结果&#xff0c;先计算怪物可以抗几次攻击&#xff0c;再计算勇士受到的伤害&#xff0c;如果勇士的攻击力大于等于怪物的血量&#xff0c;那么就可以击杀无数只&#xff0c;如果勇士的血量正好是受到攻击的整数倍&#xff0c;那么击杀的怪物数…
阅读更多...
前端项目的准备工作

前端项目的准备工作

1.下载less或sass&#xff08;如果使用的话&#xff09; pnpm i -D less | pnpm i -D sass &#xff08;-D: 这是一个选项或标志&#xff0c;表示安装的软件包将被添加为开发依赖项&#xff08;devDependencies&#xff09;。开发依赖项是指在开发过程中需要使用的工具…
阅读更多...
【信息系统项目管理师知识点速记】风险管理：实施风险应对

【信息系统项目管理师知识点速记】风险管理：实施风险应对

实施风险应对是确保项目风险管理计划得以执行的关键步骤，旨在通过监控和执行预先设定的策略来减轻威胁、抓住机遇，以及维持项目目标的一致性。此过程概括如下： 目标： 确保风险应对计划的执行。最小化单个风险的负面影响。最大化利用单个风险带来的机会。持续管理项目范围内…
阅读更多...
web agent 学习 3：screen ai

web agent 学习 3：screen ai

学习论文&#xff1a;ScreenAI: A Vision-Language Model for UI and Infographics Understanding 摘要部分介绍了作者的screenai&#xff0c;是一个专门用于UI和信息图形理解的视觉语言模型。模型利用pix2struct灵活的补丁策略改进了PaLI架构&#xff0c;并在独特的数据集混合…
阅读更多...
ubuntu编译pcl时报错

ubuntu编译pcl时报错

报错如下 cc1plus: warning: -Wabi wont warn about anything [-Wabi] cc1plus: note: -Wabi warns about differences from the most up-to-date ABI, which is also used by default cc1plus: note: use e.g. -Wabi11 to warn about changes from GCC 7 在网上找到了一封邮件…
阅读更多...
国外新闻媒体投放：多元化媒体分发投稿平台-大舍传媒

国外新闻媒体投放：多元化媒体分发投稿平台-大舍传媒

引言 随着全球信息传播的加速和全球化的发展&#xff0c;国外新闻媒体的推广变得越来越重要。在这个数字化时代&#xff0c;多元化的媒体分发投放成为了有效推广的关键。本文将介绍大舍传媒在国外新闻媒体推广中的经验与策略。 国外新闻媒体的重要性 国外新闻媒体是获取国际…
阅读更多...
insert语句的锁

insert语句的锁

insert … select 语句 CREATE TABLE t (id int(11) NOT NULL AUTO_INCREMENT,c int(11) DEFAULT NULL,d int(11) DEFAULT NULL,PRIMARY KEY (id),UNIQUE KEY c (c) ) ENGINEInnoDB;insert into t values (null, 1, 1); insert into t values (null, 2, 2); insert into t v…
阅读更多...
网页转长图插件html2canvas【前端】

网页转长图插件html2canvas【前端】

网页转长图插件html2canvas【前端】 前言版权开源推荐网页转长图插件html2canvas【前端】wkImageStorage流程使用后端application.propertiesWkConfigShareControllerImageCleanupTask 前端html2canvas.jsshare.htmlshare.jsgetShare.jsgetShare.html 最后 前言 2024-5-10 18:…
阅读更多...
超分辨率重建——CAMixerSR网络训练与推理测试（详细图文教程）

超分辨率重建——CAMixerSR网络训练与推理测试（详细图文教程）

&#x1f4aa; 专业从事且热爱图像处理&#xff0c;图像处理专栏更新如下&#x1f447;&#xff1a; &#x1f4dd;《图像去噪》 &#x1f4dd;《超分辨率重建》 &#x1f4dd;《语义分割》 &#x1f4dd;《风格迁移》 &#x1f4dd;《目标检测》 &#x1f4dd;《暗光增强》 &a…
阅读更多...
iOS Swift 中使用 ReplayKit 进行屏幕录制并获取文件路径

iOS Swift 中使用 ReplayKit 进行屏幕录制并获取文件路径

在 iOS 开发中&#xff0c;屏幕录制是一项强大的功能&#xff0c;尤其在应用演示、教育教程或游戏录屏等场景中非常有用。Apple 提供了一个名为 ReplayKit 的框架&#xff0c;允许开发者直接在应用中添加屏幕录制功能。本文将详细介绍如何使用 Swift 和 ReplayKit 结合 AVFound…
阅读更多...
在做题中学习（56）：二维前缀和模板

在做题中学习（56）：二维前缀和模板

【模板】二维前缀和_牛客题霸_牛客网 (nowcoder.com) 理解题意&#xff1a; 要求的是(x1,y1) - (x2,y2)这段区间的和。 解法&#xff1a;二维前缀和 1. 和一维前缀和一样&#xff0c;需要有一个同等规模的dp数组&#xff0c;用来保存一段连续区域的和。 在二维dp中&#xff0…
阅读更多...
客户案例：CACTER云网关为企业O365系统提供安全新护盾

客户案例：CACTER云网关为企业O365系统提供安全新护盾

一、客户背景 某智能驾驶企业是一家国际性的高科技创新型企业&#xff0c;其智能驾驶领域处于全球领先地位&#xff0c;专注于为广大客户提供个性化的智能驾驶解决方案&#xff0c;共建美好智能新时代。 使用产品&#xff1a;CACTER邮件安全云网关 二、痛点难点问题 根据…
阅读更多...
最强特征点检测算法 DeDoDe v1/v2

最强特征点检测算法 DeDoDe v1/v2

论文地址v1：https://arxiv.org/pdf/2308.08479 论文地址v1：https://arxiv.org/pdf/2404.08928 代码地址：GitHub - Parskatt/DeDoDe: [3DV 2024 Oral] DeDoDe 🎶 Detect, Dont Describe --- Describe, Dont Detect, for Local Feature Matching 实测确实牛X！ DeDoDeV1 关…
阅读更多...
网安热议 | 中小企面临什么网络安全困扰？中小企网络安全是不是智商税？

网安热议 | 中小企面临什么网络安全困扰？中小企网络安全是不是智商税？

近日&#xff0c;Coro 公司表示&#xff0c;许多中小型企业的 IT 人员被开发安全工作中多工具操作的复杂性和安全需求&#xff0c;压得“喘不过气”&#xff0c;导致其可能错过很多关键安全事件告警信息&#xff0c;从而将公司的网络安全置于危险之地。 研究机构采访了美国多行…
阅读更多...
Python基本统计分析

Python基本统计分析

常见的统计分析方法 import numpy as np import scipy.stats as spss import pandas as pd 鸢尾花数据集 https://github.com/mwaskom/seaborn-data df pd.read_csv("iris.csv",index_col"species") v1 df.loc["versicolor",:].petal_lengt…
阅读更多...
最新文章

Copyright @ 2022~2023