README
¶
Api语法描述
api示例
/**
* api语法示例及语法说明
*/
// api语法版本
syntax = "v1"
// import literal
import "foo.api"
// import group
import (
"bar.api"
"foo/bar.api"
)
info(
author: "songmeizi"
date: "2020-01-08"
desc: "api语法示例及语法说明"
)
// type literal
type Foo{
Foo int `json:"foo"`
}
// type group
type(
Bar{
Bar int `json:"bar"`
}
)
// service block
@server(
jwt: Auth
group: foo
)
service foo-api{
@doc "foo"
@handler foo
post /foo (Foo) returns (Bar)
}
api语法结构
- syntax语法声明
- import语法块
- info语法块
- type语法块
- service语法块
- 隐藏通道
温馨提示️
在以上语法结构中，各个语法块从语法上来说，按照语法块为单位，可以在.api文件中任意位置声明， 但是为了提高阅读效率，我们建议按照以上顺序进行声明，因为在将来可能会通过严格模式来控制语法块的顺序。
syntax语法声明
syntax是新加入的语法结构，该语法的引入可以解决：
- 快速针对api版本定位存在问题的语法结构
- 针对版本做语法解析
- 防止api语法大版本升级导致前后不能向前兼容
警告 ⚠️
被import的api必须要和main api的syntax版本一致。
语法定义
'syntax'={checkVersion(p)}STRING
语法说明
syntax：固定token，标志一个syntax语法结构的开始
checkVersion：自定义go方法，检测
STRING是否为一个合法的版本号，目前检测逻辑为，STRING必须是满足(?m)"v[1-9][0-9]*"正则。STRING：一串英文双引号包裹的字符串，如"v1"
一个api语法文件只能有0或者1个syntax语法声明，如果没有syntax，则默认为v1版本
正确语法示例 ✅
eg1：不规范写法
syntax="v1"
eg2：规范写法(推荐)
syntax = "v2"
错误语法示例 ❌
eg1：
syntax = "v0"
eg2：
syntax = v1
eg3：
syntax = "V1"
import语法块
随着业务规模增大，api中定义的结构体和服务越来越多，所有的语法描述均为一个api文件，这是多么糟糕的一个问题， 其会大大增加了阅读难度和维护难度，import语法块可以帮助我们解决这个问题，通过拆分api文件， 不同的api文件按照一定规则声明，可以降低阅读难度和维护难度。
警告 ⚠️
这里import不像golang那样包含package声明，仅仅是一个文件路径的引入，最终解析后会把所有的声明都汇聚到一个spec.Spec中。 不能import多个相同路径，否则会解析错误。
语法定义
'import' {checkImportValue(p)}STRING
|'import' '(' ({checkImportValue(p)}STRING)+ ')'
语法说明
import：固定token，标志一个import语法的开始
checkImportValue：自定义go方法，检测
STRING是否为一个合法的文件路径，目前检测逻辑为，STRING必须是满足(?m)"(/?[a-zA-Z0-9_#-])+\.api"正则。STRING：一串英文双引号包裹的字符串，如"foo.api"
正确语法示例 ✅
eg：
import "foo.api"
import "foo/bar.api"
import(
"bar.api"
"foo/bar/foo.api"
)
错误语法示例 ❌
eg：
import foo.api
import "foo.txt"
import (
bar.api
bar.api
)
info语法块
info语法块是一个包含了多个键值对的语法体，其作用相当于一个api服务的描述，解析器会将其映射到spec.Spec中， 以备用于翻译成其他语言(golang、java等) 时需要携带的meta元素。如果仅仅是对当前api的一个说明，而不考虑其翻译 时传递到其他语言，则使用简单的多行注释或者java风格的文档注释即可，关于注释说明请参考下文的 隐藏通道。
警告 ⚠️
不能使用重复的key，每个api文件只能有0或者1个info语法块
语法定义
'info' '(' (ID {checkKeyValue(p)}VALUE)+ ')'
语法说明
info：固定token，标志一个info语法块的开始
checkKeyValue：自定义go方法，检测
VALUE是否为一个合法值。VALUE：key对应的值，可以为单行的除'\r','\n','/'后的任意字符，多行请以""包裹，不过强烈建议所有都以""包裹
正确语法示例 ✅
eg1：不规范写法
info(
foo: foo value
bar:"bar value"
desc:"long long long long
long long text"
)
eg2：规范写法(推荐)
info(
foo: "foo value"
bar: "bar value"
desc: "long long long long long long text"
)
错误语法示例 ❌
eg1：没有key-value内容
info()
eg2：不包含冒号
info(
foo value
)
eg3：key-value没有换行
info(foo:"value")
eg4：没有key
info(
: "value"
)
eg5：非法的key
info(
12: "value"
)
eg6：移除旧版本多行语法
info(
foo: >
some text
<
)
type语法块
在api服务中，我们需要用到一个结构体(类)来作为请求体，响应体的载体，因此我们需要声明一些结构体来完成这件事情， type语法块由golang的type演变而来，当然也保留着一些golang type的特性，沿用golang特性有：
- 保留了golang内置数据类型
bool,int,int8,int16,int32,int64,uint,uint8,uint16,uint32,uint64,uintptr,float32,float64,complex64,complex128,string,byte,rune, - 兼容golang struct风格声明
- 保留golang关键字
警告 ⚠️
- 不支持alias
- 不支持time.Time数据类型
- 结构体名称、字段名称、不能为golang关键字
语法定义
由于其和golang相似，因此不做详细说明，具体语法定义请在ApiParser.g4中查看typeSpec定义。
语法说明
参考golang写法
正确语法示例 ✅
eg1：不规范写法
type Foo struct{
Id int `path:"id"` // ①
Foo int `json:"foo"`
}
type Bar struct{
// 非导出型字段
bar int `form:"bar"`
}
type(
// 非导出型结构体
fooBar struct{
FooBar int
}
)
eg2：规范写法（推荐）
type Foo{
Id int `path:"id"`
Foo int `json:"foo"`
}
type Bar{
Bar int `form:"bar"`
}
type(
FooBar{
FooBar int
}
)
错误语法示例 ❌
eg
type Gender int // 不支持
// 非struct token
type Foo structure{
CreateTime time.Time // 不支持time.Time
}
// golang关键字 var
type var{}
type Foo{
// golang关键字 interface
Foo interface
}
type Foo{
foo int
// map key必须要golang内置数据类型
m map[Bar]string
}
① tag说明
tag定义和golang中json tag语法一样，除了json tag外，go-zero还提供了另外一些tag来实现对字段的描述， 详情见下表。
-
tag表
tag key 描述 提供方 有效范围 示例 json json序列化tag golang request、response json:"fooo"path 路由path，如 /foo/:idgo-zero request path:"id"form 标志请求体是一个form（POST方法时）或者一个query(GET方法时 /search?name=keyword)go-zero request form:"name" -
tag修饰符
常见参数校验描述
tag key 描述 提供方 有效范围 示例 optional 定义当前字段为可选参数 go-zero request json:"name,optional"options 定义当前字段的枚举值,多个以竖线②隔开 go-zero request json:"gender,options=male"default 定义当前字段默认值 go-zero request json:"gender,default=male"range 定义当前字段数值范围 go-zero request json:"age,range=[0:120]"② 竖线：|
温馨提示
tag修饰符需要在tag value后以引文逗号,隔开
service语法块
service语法块用于定义api服务，包含服务名称，服务metadata，中间件声明，路由，handler等。
警告 ⚠️
- main api和被import的api服务名称必须一致，不能出现服务名称歧义。
- handler名称不能重复
- 路由（请求方法+请求path）名称不能重复
- 请求体必须声明为普通（非指针）struct，响应体做了一些向前兼容处理，详请见下文说明
语法定义
serviceSpec: atServer? serviceApi;
atServer: '@server' lp='(' kvLit+ rp=')';
serviceApi: {match(p,"service")}serviceToken=ID serviceName lbrace='{' serviceRoute* rbrace='}';
serviceRoute: atDoc? (atServer|atHandler) route;
atDoc: '@doc' lp='('? ((kvLit+)|STRING) rp=')'?;
atHandler: '@handler' ID;
route: {checkHttpMethod(p)}httpMethod=ID path request=body? returnToken=ID? response=replybody?;
body: lp='(' (ID)? rp=')';
replybody: lp='(' dataType? rp=')';
// kv
kvLit: key=ID {checkKeyValue(p)}value=LINE_VALUE;
serviceName: (ID '-'?)+;
path: (('/' (ID ('-' ID)*))|('/:' (ID ('-' ID)?)))+;
语法说明
serviceSpec：包含了一个可选语法块
atServer和serviceApi语法块，其遵循序列模式（编写service必须要按照顺序，否则会解析出错）atServer： 可选语法块，定义key-value结构的server metadata，'@server'表示这一个server语法块的开始，其可以用于描述serviceApi或者route语法块，其用于描述不同语法块时有一些特殊关键key 需要值得注意，见 atServer关键key描述说明。
serviceApi：包含了1到多个
serviceRoute语法块serviceRoute：按照序列模式包含了
atDoc,handler和routeatDoc：可选语法块，一个路由的key-value描述，其在解析后会传递到spec.Spec结构体，如果不关心传递到spec.Spec, 推荐用单行注释替代。
handler：是对路由的handler层描述，可以通过atServer指定
handlerkey来指定handler名称， 也可以直接用atHandler语法块来定义handler名称atHandler：'@handler' 固定token，后接一个遵循正则
[_a-zA-Z][a-zA-Z_-]*)的值，用于声明一个handler名称route：路由，有
httpMethod、path、可选request、可选response组成，httpMethod是必须是小写。body：api请求体语法定义，必须要由()包裹的可选的ID值
replyBody：api响应体语法定义，必须由()包裹的struct、
array(向前兼容处理，后续可能会废弃，强烈推荐以struct包裹，不要直接用array作为响应体)kvLit： 同info key-value
serviceName: 可以有多个'-'join的ID值
path：api请求路径，必须以'/'或者'/:'开头，切不能以'/'结尾，中间可包含ID或者多个以'-'join的ID字符串
atServer关键key描述说明
修饰service时
| key | 描述 | 示例 |
|---|---|---|
| jwt | 声明当前service下所有路由需要jwt鉴权，且会自动生成包含jwt逻辑的代码 | jwt: Auth |
| group | 声明当前service或者路由文件分组 | group: login |
| middleware | 声明当前service需要开启中间件 | middleware: AuthMiddleware |
修饰route时
| key | 描述 | 示例 |
|---|---|---|
| handler | 声明一个handler | - |
正确语法示例 ✅
eg1：不规范写法
@server(
jwt: Auth
group: foo
middleware: AuthMiddleware
)
service foo-api{
@doc(
summary: foo
)
@server(
handler: foo
)
// 非导出型body
post /foo/:id (foo) returns (bar)
@doc "bar"
@handler bar
post /bar returns ([]int)// 不推荐数组作为响应体
@handler fooBar
post /foo/bar (Foo) returns // 可以省略'returns'
}
eg2：规范写法（推荐）
@server(
jwt: Auth
group: foo
middleware: AuthMiddleware
)
service foo-api{
@doc "foo"
@handler: foo
post /foo/:id (Foo) returns (Bar)
}
service foo-api{
@handler ping
get /ping
@doc "foo"
@handler: bar
post /bar/:id (Foo)
}
错误语法示例 ❌
// 不支持空的server语法块
@server(
)
// 不支持空的service语法块
service foo-api{
}
service foo-api{
@doc kkkk // 简版doc必须用英文双引号引起来
@handler foo
post /foo
@handler foo // 重复的handler
post /bar
@handler fooBar
post /bar // 重复的路由
// @handler和@doc顺序错误
@handler someHandler
@doc "some doc"
post /some/path
// handler缺失
post /some/path/:id
@handler reqTest
post /foo/req (*Foo) // 不支持除普通结构体外的其他数据类型作为请求体
@handler replyTest
post /foo/reply returns (*Foo) // 不支持除普通结构体、数组(向前兼容，后续考虑废弃)外的其他数据类型作为响应体
}
隐藏通道
隐藏通道目前主要为空白符号，换行符号以及注释，这里我们只说注释，因为空白符号和换行符号我们目前拿来也无用。
单行注释
语法定义
'//' ~[\r\n]*
语法说明
由语法定义可知道，单行注释必须要以//开头，内容为不能包含换行符
正确语法示例 ✅
// doc
// comment
错误语法示例 ❌
// break
line comments
java风格文档注释
语法定义
'/*' .*? '*/'
语法说明
由语法定义可知道，单行注释必须要以/*开头，*/结尾的任意字符。
正确语法示例 ✅
/**
* java-style doc
*/
错误语法示例 ❌
/*
* java-style doc */
*/
Doc&Comment
如果想获取某一个元素的doc或者comment开发人员需要怎么定义？
Doc
我们规定上一个语法块（非隐藏通道内容）的行数line+1到当前语法块第一个元素前的所有注释(当行，或者多行)均为doc， 且保留了
//、/*、*/原始标记。
Comment
我们规定当前语法块最后一个元素所在行开始的一个注释块(当行，或者多行)为comment 且保留了
//、/*、*/原始标记。
语法块Doc和Comment的支持情况
| 语法块 | parent语法块 | Doc | Comment |
|---|---|---|---|
| syntaxLit | api | ✅ | ✅ |
| kvLit | infoSpec | ✅ | ✅ |
| importLit | importSpec | ✅ | ✅ |
| typeLit | api | ✅ | ❌ |
| typeLit | typeBlock | ✅ | ❌ |
| field | typeLit | ✅ | ✅ |
| key-value | atServer | ✅ | ✅ |
| atHandler | serviceRoute | ✅ | ✅ |
| route | serviceRoute | ✅ | ✅ |
以下为对应语法块解析后细带doc和comment的写法
// syntaxLit doc
syntax = "v1" // syntaxLit commnet
info(
// kvLit doc
author: songmeizi // kvLit comment
)
// typeLit doc
type Foo {}
type(
// typeLit doc
Bar{}
FooBar{
// filed doc
Name int // filed comment
}
)
@server(
/**
* kvLit doc
* 开启jwt鉴权
*/
jwt: Auth /**kvLit comment*/
)
service foo-api{
// atHandler doc
@handler foo //atHandler comment
/*
* route doc
* post请求
* path为 /foo
* 请求体：Foo
* 响应体：Foo
*/
post /foo (Foo) returns (Foo) // route comment
}
Documentation
Source Files
Directories