API 规范

概述

api 是 go-zero 自研的领域特性语言（下文称 api 语言 或 api 描述语言），旨在实现人性化的基础描述语言，作为生成 HTTP 服务最基本的描述语言。

api 领域特性语言包含语法版本，info 块，结构体声明，服务描述等几大块语法组成，其中结构体和 Golang 结构体 语法几乎一样，只是移出了 struct 关键字。

目标

  • 学习成本低
  • 可读性强
  • 扩展自由
  • HTTP 服务一键生成
  • 编写一个 api 文件，生成多种语言代码服务

语法标记符号

api 语法是使用 扩展巴科斯范式（EBNF） 来描述的，在扩展巴科斯范式中指定

  1. Syntax      = { Production } .
  2. Production  = production_name "=" [ Expression ] "." .
  3. Expression  = Term { "|" Term } .
  4. Term        = Factor { Factor } .
  5. Factor      = production_name | token [ "…" token ] | Group | Option | Repetition .
  6. Group       = "(" Expression ")" .
  7. Option      = "[" Expression "]" .
  8. Repetition  = "{" Expression "}" .

Production 由 Term 和如下操作符组成，如下操作符优先级递增：

  1. |   alternation
  2. ()  grouping
  3. []  option (0 or 1 times)
  4. {}  repetition (0 to n times)

形式 a...b 表示从 a 到 b 的一组字符作为替代，如 0...9 代表 0 到 9 的有效数值。

. 表示 ENBF 的终结符号。

API 规范 - 图1注意

产生式的名称如果为小写，则代表终结 token，驼峰式的产生式名称则为非终结符 token，如：

  1. // 终结 token
  2. number = "0"..."9" .
  3. lower_letter = "a"..."z" .
  5. // 非终结 token
  6. DataType = TypeLit | TypeGroup .
  7. TypeLit  = TypeAlias | TypeStruct .

源代码表示

源代码表示是用来描述 api 语法的最基础元素。

字符

  1. newline        = /* 代表换行符， Unicode 值为 U+000A */ .
  2. unicode_char   = /* 除换行符 newline 外的其他 Unicode 字符 */ .
  3. unicode_letter = /* 字母 a...z|A...Z Unicode */ .
  4. unicode_digit  = /* 数值 0...9 Unicode */ .

字母和数字

下划线字符 _ (U+005F) 被视为小写字母。

  1. letter        = "A"..."Z" | "a"..."z" | "_" .
  2. decimal_digit = "0" … "9" .

抽象语法树

抽象语法树（Abstract Syntax Tree，AST），或简称语法树（Syntax tree），是源代码语法结构的一种抽象表示。它以树状的形式表现编程语言的语法结构，树上的每个节点都表示源代码中的一种结构。之所以说语法是“抽象”的，是因为这里的语法并不会表示出真实语法中出现的每个细节。比如，嵌套括号被隐含在树的结构中，并没有以节点的形式呈现；而类似于 if-condition-then 这样的条件跳转语句，可以使用带有三个分支的节点来表示。

抽象语法树是代码的树形表示。它们是编译器工作方式的基本组成部分。当编译器转换一些代码时，基本上有以下步骤：

  • 词法分析（Lexical Analysis）
  • 语法分析（Syntax Analysis）
  • 代码生成（Code Generation）

AST 分析过程

词法分析

词法分析（Lexical Analysis）是计算机科学中将字符序列转换为记号（token）序列的过程。进行词法分析的程序或者函数叫作词法分析器（lexical analyzer，简称 lexer），也叫扫描器（scanner）。词法分析器一般以函数的形式存在，供语法分析器调用。

在 api 语言中，词法分析是将字符转换为词法元素序列的过程，其中词法元素包括 注释 和 Token。

词法元素

注释

在 api 领域特性语言中有 2 种格式：

  1. 单行注释以 // 开始，行尾结束。

    1. // 这是一个单行注释示例

  2. 多行注释（文档注释）以 /* 开始，以第一个 */ 结束。

    1. /*这是在同意行内的文档注释*/
    2. /*
    3. 这是在多行的文档注释
    4. */
Token

Token 是组成节点的最基本元素，由 标识符（identifier）、关键字（keyword）、运算符（operator）、标点符号（punctuation）、字面量（literal）组成，空白符（White space）一般由空格（U+0020）、水平制表符（U+0009）、回车符（U+000D）和 换行符（U+000A）组成，在 api 语言中，Token 不包含 运算符（operator）。

Token 的 Golang 结构体定义为：

  1. type Token struct {
  2.     Type     Type
  3.     Text     string
  4.     Position Position
  5. }
  7. type Position struct {
  8.     Filename string
  9.     Line     int
  10.     Column   int
  11. }

如 api 语句 syntax="v1"，其词法化后的为：

文本类型
syntax标识符
=操作符
“v1”字符串
ID 标识符

ID 标识符一般是结构体，变量，类型等的名称实体，ID 标识符一般有 1 到 n 个字母和数字组成，且开头必须为字母（记住上文提到的 _ 也被当做小写字母看待），其 EBNF 表示法为：

  1. identifier = letter { letter | unicode_digit } .

ID 标识符示例：

  1. a
  2. _a1
  3. GoZero

有些 ID 标识符是预先定义的，api 沿用了 Golang 预定义 ID 标识符 。

  1. 预定义类型:
  2.     any bool byte comparable
  3.     complex64 complex128 error float32 float64
  4.     int int8 int16 int32 int64 rune string
  5.     uint uint8 uint16 uint32 uint64 uintptr
  7. 预定义常量:
  8.     true false iota
  10. 零值:
  11.     nil
  13. 预定义函数:
  14.     append cap close complex copy delete imag len
  15.     make new panic print println real recover
关键字

关键字是一些特殊的 ID 标识符，是系统保留字，api 的关键字沿用了 Golang 关键字，结构体中不得使用 Golang 关键字作为标识符。

Golang 关键字

  1. break        default      func         interface    select
  2. case         defer        go           map          struct
  3. chan         else         goto         package      switch
  4. const        fallthrough  if           range        type
  5. continue     for          import       return       var
标点符号

标点符号可以用于对 Token、表达式做分割、分组，以下是 api 语言中的标点符号：

  1. -    ,    (    )
  2. *    .    [    ]
  3. /    ;    {    }
  4. =    :    ,    ;
  5. ...
字符串

字符串字面量是由一组字符序列组成的常量。在 api 中沿用了 Golang 的字符串，有 2 种形式： 原始字符串（raw string）和普通符串（双引号字符串）。

原始字符串的字符序列在两个反引号之间，除反引号外，任何字符都可以出现，如 `foo`；

普通字符串的字符序列在两个双引号之间，除双引号外，任何字符都可以出现，如 “foo”。

API 规范 - 图2注意

在 api 语言中，双引号字符串不支持 \" 来实现字符串转义。

  1. string_lit             = raw_string_lit | interpreted_string_lit .
  2. raw_string_lit         = "`" { unicode_char | newline } "`" .
  3. interpreted_string_lit = `"` { unicode_value | byte_value } `"` .

字符串示例：

  1. // 原始字符串
  2. ``
  3. `foo`
  4. `bar`
  5. `json:"baz"`
  7. // 普通字符串
  8. ""
  9. "foo"
  10. "bar"

语法分析

语法分析（Syntax Analysis）又叫语法解析，这个过程是将词法元素转换为树的过程，而语法树一般由节点（Node）、表达式（Expression）、语句（Statement）组成，语法解析的过程除了词汇转换成树外，还需要完成语义分析。

节点

节点（Node）是 Token 的变体，是一个接口类型，是组成表达式、语句的基本元素，其在 Golang 中的结构体定义为：

  1. // Node represents a node in the AST.
  2. type Node interface {
  3.     // Pos returns the position of the first character belonging to the node.
  4.     Pos() token.Position
  5.     // End returns the position of the first character immediately after the node.
  6.     End() token.Position
  7.     // Format returns the node's text after format.
  8.     Format(...string) string
  9.     // HasHeadCommentGroup returns true if the node has head comment group.
  10.     HasHeadCommentGroup() bool
  11.     // HasLeadingCommentGroup returns true if the node has leading comment group.
  12.     HasLeadingCommentGroup() bool
  13.     // CommentGroup returns the node's head comment group and leading comment group.
  14.     CommentGroup() (head, leading CommentGroup)
  15. }

表达式

表达式（Expression）是组成语句的基本元素，可以理解为一个句子中的 “短语”，在 api 语言中包含的表达式如下：

  1. 数据类型表达式
  2. 结构体中的 field 表达式
  3. key-value 表达式
  4. 服务声明表达式
  5. HTTP 请求/响应体表达式
  6. HTTP 路由表达式

在 api 中 Golang 的结构体定义为：

  1. // Expr represents an expression in the AST.
  2. type Expr interface {
  3.     Node
  4.     exprNode()
  5. }

语句

语句（Statement）是组成抽象语法树的基本元素，抽象语法树可以理解成一篇文章，而语句是组成文章的多条句子，在 api 语言中包含语句如下：

  1. @doc 语句
  2. @handler 语句
  3. @server 语句
  4. HTTP 服务的请求/响应体语句
  5. 注释语句
  6. import 语句
  7. info 语句
  8. HTTP 路由语句
  9. HTTP 服务声明语句
  10. syntax 语句
  11. 结构体语句

在 api 中 Golang 的结构体定义为：

  1. // Stmt represents a statement in the AST.
  2. type Stmt interface {
  3.     Node
  4.     stmtNode()
  5. }

代码生成

我们一旦有了抽象语法树，就可以通过它来打印或者生成不同的代码了，在 api 抽象语法树行成后，可以支持：

  1. 打印 AST
  2. api 语言格式化
  3. Golang HTTP 服务生成
  4. Typescript 代码生成
  5. Dart 代码生成
  6. Kotlin 代码生成

除此之外，还可以根据 AST 进行扩展，比如插件：

  1. goctl-go-compact
  2. goctl-swagger
  3. goctl-php

api 语法标记

  1. api = SyntaxStmt | InfoStmt | { ImportStmt } | { TypeStmt } | { ServiceStmt } .

syntax 语句

syntax 语句用于标记 api 语言的版本，不同的版本可能语法结构有所不同，随着版本的提升会做不断的优化，当前版本为 v1。

syntax 的 EBNF 表示为：

  1. SyntaxStmt = "syntax" "=" "v1" .

syntax 语法写法示例：

  1. syntax = "v1"

info 语句

info 语句是 api 语言的 meta 信息，其仅用于对当前 api 文件进行描述，暂不参与代码生成，其和注释还是有一些区别，注释一般是依附某个 syntax 语句存在，而 info 语句是用于描述整个 api 信息的，当然，不排除在将来会参与到代码生成里面来，info 语句的 EBNF 表示为：

  1. InfoStmt         = "info" "(" { InfoKeyValueExpr } ")" .
  2. InfoKeyValueExpr = InfoKeyLit [ interpreted_string_lit ] .
  3. InfoKeyLit       = identifier ":" .

info 语句写法示例：

  1. // 不包含 key-value 的 info 块
  2. info ()
  4. // 包含 key-value 的 info 块
  5. info (
  6.     foo: "bar"
  7.     bar:
  8. )

import 语句

import 语句是在 api 中引入其他 api 文件的语法块，其支持相对/绝对路径，不支持 package 的设计，其 EBNF 表示为：

  1. ImportStmt        = ImportLiteralStmt | ImportGroupStmt .
  2. ImportLiteralStmt = "import" interpreted_string_lit .
  3. ImportGroupStmt   = "import" "(" { interpreted_string_lit } ")" .

import 语句写法示例：

  1. // 单行 import
  2. import "foo"
  3. import "/path/to/file"
  5. // import 组
  6. import ()
  7. import (
  8.     "bar"
  9.     "relative/to/file"
  10. )

数据类型

api 中的数据类型基本沿用了 Golang 的数据类型，用于对 rest 服务的请求/响应体结构的描述，其 EBNF 表示为：

  1. TypeStmt          = TypeLiteralStmt | TypeGroupStmt .
  2. TypeLiteralStmt   = "type" TypeExpr .
  3. TypeGroupStmt     = "type" "(" { TypeExpr } ")" .
  4. TypeExpr          = identifier [ "=" ] DataType .
  5. DataType          = AnyDataType | ArrayDataType | BaseDataType |
  6.                     InterfaceDataType | MapDataType | PointerDataType |
  7.                     SliceDataType | StructDataType .
  8. AnyDataType       = "any" .
  9. ArrayDataType     = "[" { decimal_digit } "]" DataType .
  10. BaseDataType      = "bool"    | "uint8"     | "uint16"     | "uint32" | "uint64"  |
  11.                     "int8"    | "int16"     | "int32"      | "int64"  | "float32" |
  12.                     "float64" | "complex64" | "complex128" | "string" | "int"     |
  13.                     "uint"    | "uintptr"   | "byte"       | "rune"   | "any"     | .
  15. InterfaceDataType = "interface{}" .
  16. MapDataType       = "map" "[" DataType "]" DataType .
  17. PointerDataType   = "*" DataType .
  18. SliceDataType     = "[" "]" DataType .
  19. StructDataType    = "{" { ElemExpr } "}" .
  20. ElemExpr          = [ ElemNameExpr ]  DataType [ Tag ].
  21. ElemNameExpr      = identifier { "," identifier } .
  22. Tag               = raw_string_lit .

数据类型写法示例：

  1. // 别名类型 [1]
  2. type Int int
  3. type Integer = int
  5. // 空结构体
  6. type Foo {}
  8. // 单个结构体
  9. type Bar {
  10.     Foo int               `json:"foo"`
  11.     Bar bool              `json:"bar"`
  12.     Baz []string          `json:"baz"`
  13.     Qux map[string]string `json:"qux"`
  14. }
  16. type Baz {
  17.     Bar    `json:"baz"`
  18.     // 结构体内嵌 [2]
  19.     Qux {
  20.         Foo string `json:"foo"`
  21.         Bar bool   `json:"bar"`
  22.     } `json:"baz"`
  23. }
  25. // 空结构体组
  26. type ()
  28. // 结构体组
  29. type (
  30.     Int int
  31.     Integer = int
  32.     Bar {
  33.         Foo int               `json:"foo"`
  34.         Bar bool              `json:"bar"`
  35.         Baz []string          `json:"baz"`
  36.         Qux map[string]string `json:"qux"`
  37.     }
  38. )
API 规范 - 图3注意

[1] 虽然语法上支持别名，但是在语义分析时会对别名进行拦截，这或在将来进行放开。

[2] 虽然语法上支持结构体内嵌，但是在语义分析时会对别名进行拦截，这或在将来进行放开。

除此之外：

  1. 目前 api 语法中虽然支持了数组的语法，但是在语义分析时会对数组进行拦截，目前建议用切片替代，这或在将来放开。
  2. 不支持 package 设计，如 time.Time。

service 语句

service 语句是对 HTTP 服务的直观描述，包含请求 handler，请求方法，请求路由，请求体，响应体，jwt 开关，中间件声明等定义。

其 EBNF 表示为：

  1. ServiceStmt     = [ AtServerStmt ] "service" ServiceNameExpr "("
  2.                   { ServiceItemStmt } ")" .
  3. ServiceNameExpr = identifier [ "-api" ] .

@server 语句

@server 语句是对一个服务语句的 meta 信息描述，其对应特性包含但不限于：

  • jwt 开关
  • 中间件
  • 路由分组
  • 路由前缀

@server 的 EBNF 表示为：

  1. AtServerStmt     = "@server" "(" {  AtServerKVExpr } ")" .
  2. AtServerKVExpr   = AtServerKeyLit [ AtServerValueLit ] .
  3. AtServerKeyLit   = identifier ":" .
  4. AtServerValueLit = PathLit | identifier { "," identifier } .
  5. PathLit          = `"` { "/" { identifier | "-" identifier} } `"` .

@server 写法示例：

  1. // 空内容
  2. @server()
  4. // 有内容
  5. @server (
  6.     // jwt 声明
  7.     // 如果 key 固定为 “jwt:”，则代表开启 jwt 鉴权声明
  8.     // value 则为配置文件的结构体名称
  9.     jwt: Auth
  11.     // 路由前缀
  12.     // 如果 key 固定为 “prefix:”
  13.     // 则代表路由前缀声明，value 则为具体的路由前缀值，字符串中没让必须以 / 开头
  14.     prefix: /v1
  16.     // 路由分组
  17.     // 如果 key 固定为 “group:”，则代表路由分组声明
  18.     // value 则为具体分组名称，在 goctl生成代码后会根据此值进行文件夹分组
  19.     group: Foo
  21.     // 中间件
  22.     // 如果 key 固定为 middleware:”，则代表中间件声明
  23.     // value 则为具体中间件函数名称，在 goctl生成代码后会根据此值进生成对应的中间件函数
  24.     middleware: AuthInterceptor
  26.     // 超时控制
  27.     // 如果 key 固定为  timeout:”，则代表超时配置
  28.     // value 则为具体中duration，在 goctl生成代码后会根据此值进生成对应的超时配置
  29.     timeout: 3s
  31.     // 其他 key-value，除上述几个内置 key 外，其他 key-value
  32.     // 也可以在作为 annotation 信息传递给 goctl 及其插件，但就
  33.     // 目前来看，goctl 并未使用。
  34.     foo: bar
  35. )

服务条目

服务条目（ServiceItemStmt）是对单个 HTTP 请求的描述，包括 @doc 语句，handler 语句，路由语句信息，其 EBNF 表示为：

  1. ServiceItemStmt = [ AtDocStmt ] AtHandlerStmt RouteStmt .
@doc 语句

@doc 语句是对单个路由的 meta 信息描述，一般为 key-value 值，可以传递给 goctl 及其插件来进行扩展生成，其 EBNF 表示为：

  1. AtDocStmt        = AtDocLiteralStmt | AtDocGroupStmt .
  2. AtDocLiteralStmt = "@doc" interpreted_string_lit .
  3. AtDocGroupStmt   = "@doc" "(" { AtDocKVExpr } ")" .
  4. AtDocKVExpr      = AtServerKeyLit  interpreted_string_lit .
  5. AtServerKeyLit   = identifier ":" .

@doc 写法示例：

  1. // 单行 @doc
  2. @doc "foo"
  4. // 空 @doc 组
  5. @doc ()
  7. // 有内容的 @doc 组
  8. @doc (
  9.     foo: "bar"
  10.     bar: "baz"
  11. )
@handler 语句

@handler 语句是对单个路由的 handler 信息控制，主要用于生成 golang http.HandleFunc 的实现转换方法，其 EBNF 表示为：

  1. AtHandlerStmt = "@handler" identifier .

@handler 写法示例：

  1. @handler foo
路由语句

路由语句是对单此 HTTP 请求的具体描述，包括请求方法，请求路径，请求体，响应体信息，其 EBNF 表示为：

  1. RouteStmt = Method PathExpr [ BodyStmt ] [ "returns" ] [ BodyStmt ].
  2. Method    = "get"     | "head"    | "post" | "put" | "patch" | "delete" |
  3.             "connect" | "options" | "trace" .
  4. PathExpr  = "/" identifier { ( "-" identifier ) | ( ":" identifier) } .
  5. BodyStmt  = "(" identifier ")" .

路由语句写法示例：

  1. // 没有请求体和响应体的写法
  2. get /ping
  4. // 只有请求体的写法
  5. get /foo (foo)
  7. // 只有响应体的写法
  8. post /foo returns (foo)
  10. // 有请求体和响应体的写法
  11. post /foo (foo) returns (bar)

service 写法示例

  1. // 带 @server 的写法
  2. @server (
  3.     prefix: /v1
  4.     group: Login
  5. )
  6. service user {
  7.     @doc "登录"
  8.     @handler login
  9.     post /user/login (LoginReq) returns (LoginResp)
  11.     @handler getUserInfo
  12.     get /user/info/:id (GetUserInfoReq) returns (GetUserInfoResp)
  13. }
  14. @server (
  15.     prefix: /v1
  16.     middleware: AuthInterceptor
  17. )
  18. service user {
  19.     @doc "登录"
  20.     @handler login
  21.     post /user/login (LoginReq) returns (LoginResp)
  23.     @handler getUserInfo
  24.     get /user/info/:id (GetUserInfoReq) returns (GetUserInfoResp)
  25. }
  28. // 不带 @server 的写法
  29. service user {
  30.     @doc "登录"
  31.     @handler login
  32.     post /user/login (LoginReq) returns (LoginResp)
  34.     @handler getUserInfo
  35.     get /user/info/:id (GetUserInfoReq) returns (GetUserInfoResp)
  36. }
API 规范 - 图4温馨提示

完整的 api 语法示例可参考 《API 定义完整示例》

参考文献