# 附录1: api语法定义

# Api语法描述


## api示例


```bash
/**
 * 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版本一致。



**语法定义**


```antlrv4
'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：不规范写法


```api
syntax="v1"
```


eg2：规范写法(推荐)


```api
syntax = "v2"
```


**错误语法示例** ❌


eg1：


```api
syntax = "v0"
```


eg2：


```api
syntax = v1
```


eg3：


```api
syntax = "V1"
```


## import语法块


随着业务规模增大，api中定义的结构体和服务越来越多，所有的语法描述均为一个api文件，这是多么糟糕的一个问题， 其会大大增加了阅读难度和维护难度，import语法块可以帮助我们解决这个问题，通过拆分api文件，
不同的api文件按照一定规则声明，可以降低阅读难度和维护难度。


> ### 警告 ⚠️
> 这里import不像golang那样包含package声明，仅仅是一个文件路径的引入，最终解析后会把所有的声明都汇聚到一个spec.Spec中。
> 不能import多个相同路径，否则会解析错误。



**语法定义**


```antlrv4
'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：


```api
import "foo.api"
import "foo/bar.api"

import(
    "bar.api"
    "foo/bar/foo.api"
)
```


**错误语法示例** ❌


eg：


```api
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语法块



**语法定义**


```antlrv4
'info' '(' (ID {checkKeyValue(p)}VALUE)+ ')'
```


**语法说明**


> info：固定token，标志一个info语法块的开始
> checkKeyValue：自定义go方法，检测`VALUE`是否为一个合法值。
> VALUE：key对应的值，可以为单行的除'\r','\n','/'后的任意字符，多行请以""包裹，不过强烈建议所有都以""包裹



**正确语法示例** ✅


eg1：不规范写法


```api
info(
foo: foo value
bar:"bar value"
    desc:"long long long long
long long text"
)
```


eg2：规范写法(推荐)


```api
info(
    foo: "foo value"
    bar: "bar value"
    desc: "long long long long long long text"
)
```


**错误语法示例** ❌


eg1：没有key-value内容


```api
info()
```


eg2：不包含冒号


```api
info(
    foo value
)
```


eg3：key-value没有换行


```api
info(foo:"value")
```


eg4：没有key


```api
info(
    : "value"
)
```


eg5：非法的key


```api
info(
    12: "value"
)
```


eg6：移除旧版本多行语法


```api
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](https://github.com/tal-tech/go-zero/blob/master/tools/goctl/api/parser/g4/ApiParser.g4)中查看typeSpec定义。



**语法说明**


> 参考golang写法



**正确语法示例** ✅


eg1：不规范写法


```api
type Foo struct{
    Id int `path:"id"` // ①
    Foo int `json:"foo"`
}

type Bar struct{
    // 非导出型字段
    bar int `form:"bar"`
}

type(
    // 非导出型结构体
    fooBar struct{
        FooBar int
    }
)
```


eg2：规范写法（推荐）


```api
type Foo{
    Id int `path:"id"`
    Foo int `json:"foo"`
}

type Bar{
    Bar int `form:"bar"`
}

type(
    FooBar{
        FooBar int
    }
)
```


**错误语法示例** ❌


eg


```api
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/:id` | go-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，响应体做了一些向前兼容处理，详请见下文说明



**语法定义**


```antlrv4
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和`route`
> atDoc：可选语法块，一个路由的key-value描述，其在解析后会传递到spec.Spec结构体，如果不关心传递到spec.Spec,
> 推荐用单行注释替代。
> handler：是对路由的handler层描述，可以通过atServer指定`handler` key来指定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：不规范写法


```api
@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：规范写法（推荐）


```api
@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)
}
```


**错误语法示例** ❌


```api
// 不支持空的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) // 不支持除普通结构体、数组(向前兼容，后续考虑废弃)外的其他数据类型作为响应体
}
```


## 隐藏通道


隐藏通道目前主要为空百符号，换行符号以及注释，这里我们只说注释，因为空白符号和换行符号我们目前拿来也无用。


### 单行注释


**语法定义**


```antlrv4
'//' ~[\r\n]*
```


**语法说明**
由语法定义可知道，单行注释必须要以`//`开头，内容为不能包含换行符


**正确语法示例** ✅


```api
// doc
// comment
```


**错误语法示例** ❌


```api
// break
line comments
```


### java风格文档注释


**语法定义**


```antlrv4
'/*' .*? '*/'
```


**语法说明**


由语法定义可知道，单行注释必须要以`/*`开头，`*/`结尾的任意字符。


**正确语法示例** ✅


```api
/**
 * java-style doc
 */
```


**错误语法示例** ❌


```api
/*
 * java-style doc */
 */
```


## Doc&Comment


如果想获取某一个元素的doc或者comment开发人员需要怎么定义？


**Doc**


> 我们规定上一个语法块（非隐藏通道内容）的行数line+1到当前语法块第一个元素前的所有注释(当行，或者多行)均为doc， 且保留了`//`、`/*`、`*/`原始标记。



**Comment**


> 我们规定当前语法块最后一个元素所在行开始的一个注释块(当行，或者多行)为comment 且保留了`//`、`/*`、`*/`原始标记。



语法块Doc和Comment的能够解析到ast的case

| 语法块 | parent语法块 | Doc | Comment |
| :--- | :--- | :--- | :--- |
| syntaxLit | api | ✅ | ✅ |
| kvLit | infoSpec | ✅ | ✅ |
| importLit | importSpec | ✅ | ✅ |
| typeLit | api | ✅ | ❌ |
| typeLit | typeBlock | ✅ | ❌ |
| field | typeLit | ✅ | ✅ |
| key-value | atServer | ✅ | ✅ |
| atHandler | serviceRoute | ✅ | ✅ |
| route | serviceRoute | ✅ | ✅ |



以下为对应语法块解析后会带入AST的写法


```api
// 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
}
```

<Vssue title="附录1" />