api is a domain-specific language developed in-house by go-zero. It aims to provide a human-friendly basic description language and serves as the most fundamental description language for generating HTTP services. The official goctl tool can convert api definitions into a structured project.
Overview
The api domain-specific language is composed of several major syntax blocks, including the syntax version, the info block, struct declarations, and service descriptions. Struct syntax is almost identical to Golang struct syntax, except that the struct keyword is removed.
Syntax statement
The syntax statement is used to mark the version of the api language. Different versions may have different syntax structures, and the language is continuously optimized as versions are upgraded. The current version is v1.
syntax = "v1"Info statement
The info statement is the meta information of the api language. It is only used to describe the current api file and does not participate in code generation for now. It still differs somewhat from comments: comments generally attach to a particular syntax statement, whereas the info statement is used to describe the api information as a whole.
// 不包含 key-value 的 info 块
info ()
// 包含 key-value 的 info 块
info (
foo: "bar"
bar:
)Import statement
The import statement is the syntax block for importing other api files into an api file. It supports both relative and absolute paths and does not support a package design.
// 单行 import
import "foo"
import "/path/to/file"
// import 组
import ()
import (
"bar"
"relative/to/file"
)Data types
Data types in api basically follow Golang data types and are used to describe the request/response body structures of REST services. Packages such as time.Time are not supported.
// 空结构体
type Foo {}
// 单个结构体
type Bar {
Foo int `json:"foo"`
Bar bool `json:"bar"`
Baz []string `json:"baz"`
Qux map[string]string `json:"qux"`
}
type Baz {
Bar `json:"baz"`
Array [3]int `json:"array"`
// 结构体内嵌 goctl 1.6.8 版本支持
Qux {
Foo string `json:"foo"`
Bar bool `json:"bar"`
} `json:"baz"`
}
// 空结构体组
type ()
// 结构体组
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 statement - @service
The service statement is an intuitive description of an HTTP service. It includes definitions such as the request handler, request method, request route, request body, response body, jwt switch, and middleware declarations.
// 空内容
@server()
// 有内容
@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 items
A service item (ServiceItemStmt) is a description of a single HTTP request, including @doc statements, @handler statements, and route statement information.
@doc statement
The @doc statement is a meta information description for a single route. It generally consists of key-value pairs and can be passed to goctl and its plugins for extended generation.
// 单行 @doc
@doc "foo"
// 空 @doc 组
@doc ()
// 有内容的 @doc 组
@doc (
foo: "bar"
bar: "baz"
)@handler statement
The @handler statement controls the handler information for a single route and is mainly used to generate a conversion method implementing golang’s http.HandleFunc.
@handler fooRoute statement
The route statement is a concrete description of a single HTTP request, including the request method, request path, request body, and response body.
// 没有请求体和响应体的写法
get /ping
// 只有请求体的写法
get /foo (foo)
// 只有响应体的写法
post /foo returns (foo)
// 有请求体和响应体的写法
post /foo (foo) returns (bar)A complete 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)
}
// 不带 @server 的写法
service user {
@doc "登录"
@handler login
post /user/login (LoginReq) returns (LoginResp)
@handler getUserInfo
get /user/info/:id (GetUserInfoReq) returns (GetUserInfoResp)
}Complete example
syntax = "v1"
info (
title: "api 文件完整示例写法"
desc: "演示如何编写 api 文件"
author: "keson.an"
date: "2022 年 12 月 26 日"
version: "v1"
)
type UpdateReq {
Arg1 string `json:"arg1"`
}
type ListItem {
Value1 string `json:"value1"`
}
type LoginReq {
Username string `json:"username"`
Password string `json:"password"`
}
type LoginResp {
Name string `json:"name"`
}
type FormExampleReq {
Name string `form:"name"`
}
type PathExampleReq {
// path 标签修饰的 id 必须与请求路由中的片段对应，如
// id 在 service 语法块的请求路径上一定会有 :id 对应，见下文。
ID string `path:"id"`
}
type PathExampleResp {
Name string `json:"name"`
}
@server (
jwt: Auth // 对当前 Foo 语法块下的所有路由，开启 jwt 认证，不需要则请删除此行
prefix: /v1 // 对当前 Foo 语法块下的所有路由，新增 /v1 路由前缀，不需要则请删除此行
group: g1 // 对当前 Foo 语法块下的所有路由，路由归并到 g1 目录下，不需要则请删除此行
timeout: 3s // 对当前 Foo 语法块下的所有路由进行超时配置，不需要则请删除此行
middleware: AuthInterceptor // 对当前 Foo 语法块下的所有路由添加中间件，不需要则请删除此行
maxBytes: 1048576 // 对当前 Foo 语法块下的所有路由添加请求体大小控制，单位为 byte,goctl 版本 >= 1.5.0 才支持
)
service Foo {
// 定义没有请求体和响应体的接口，如 ping
@handler ping
get /ping
// 定义只有请求体的接口，如更新信息
@handler update
post /update (UpdateReq)
// 定义只有响应体的结构，如获取全部信息列表
@handler list
get /list returns ([]ListItem)
// 定义有结构体和响应体的接口，如登录
@handler login
post /login (LoginReq) returns (LoginResp)
// 定义表单请求
@handler formExample
post /form/example (FormExampleReq)
// 定义 path 参数
@handler pathExample
get /path/example/:id (PathExampleReq) returns (PathExampleResp)
}