当前位置：首页 > news >正文

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

news 2025/7/3 15:49:21

参考来源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: /v1group: Login
)
service user {@doc "登录"@handler loginpost /user/login (LoginReq) returns (LoginResp)@handler getUserInfoget /user/info/:id (GetUserInfoReq) returns (GetUserInfoResp)
}
@server (prefix: /v1middleware: AuthInterceptor
)
service user {@doc "登录"@handler loginpost /user/login (LoginReq) returns (LoginResp)@handler getUserInfoget /user/info/:id (GetUserInfoReq) returns (GetUserInfoResp)
}