GoZero微服务个人探究之路（九）api文件编写总结

参考来源go-zero官方文档https://go-zero.dev/docs/tutorials

前言

go-zero是目前star最多的go语言微服务框架，api 是 go-zero特殊的语言，类型文件，go-zero自带的goctl可以通过.api文件生成http服务代码

api文件内容编写

不可使用关键字

沿用了golang的关键字，这些都不可以使用

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

syntax语句

代表了api语言版本，当前就是v1版本

syntax = "v1"

info语句

info对api文件编写描述信息，目前不会参与到goctl代码生成

info语句
info (
foo: "bar"
bar:
)

import语句

用于import其他api文件，支持相对和绝对路径
import "/path/to/file"

import (
"bar"
"relative/to/file"
)

数据类型

数据类型沿用golang数据类型，目前不支持数组，支持切片，不支持别名

不需要声明struct关键字

//单个结构体

type Bar {
Foo int `json:"foo"`
Bar bool `json:"bar"`
Baz []string `json:"baz"`
Qux map[string]string `json:"qux"`
}

//结构体组

type (
Int int
Integer = int
        Bar {
        Foo int `json:"foo"`
        Bar bool `json:"bar"`
        Baz []string `json:"baz"`
        Qux map[string]string `json:"qux"`
        }
)

service语句*

@server描述服务的meta信息

@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
)

写service语句还需了解如下内容

@doc语句

对单个路由的meta信息描述

@doc (
foo: "bar"
bar: "baz"
)

@handler语句

描述单个路由的handler信息

@handler foo

路由语句

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

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

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

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

service语句的示例写法

// 带 @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)
}

补充

路由前缀prefix

可以为同样的路由名指定不同的前缀，v1、v2

在routes.go里面，代码体现如下

服务分组group

指定分组的信息后，生成的代码更加逻辑清晰

签名开关signature

在@server部分可以设置signature为true来开启签名功能

生成routes.go代码示例如下

JWT认证

@server里面设置jwt:Auth开启

goctl生成代码如下

代码生成后的 jwt 认证，框架只做了服务端逻辑，对于 jwt token 的生成及 refresh token 仍需要开发者自行实现

中间件声明

在@server内通过middleware:来指定中间件，多个中间件逗号分隔

生成的目录结构就会有中间件代码