zero-api is a RESTful API description language.
zeromicro / zero-api Goto Github PK
View Code? Open in Web Editor NEWzero-api is a RESTful API description language.
License: MIT License
zero-api is a RESTful API description language.
License: MIT License
zero-api 是一种声明 HTTP API 的语言,他可以通过 goctl 翻译成基于 go-zero 的服务代码。
语法使用Extended Backus-Naur Form (EBNF)指定, 实例如下:
Production = production_name "=" [ Expression ] "." .
Expression = Alternative { "|" Alternative } .
Alternative = Term { Term } .
Term = production_name | token [ "…" token ] | Group | Option | Repetition .
Group = "(" Expression ")" .
Option = "[" Expression "]" .
Repetition = "{" Expression "}" .
结果是由术语和以下操作符构造的表达式,优先级递增:
| 交替
() 分组
[] 可选(0 或 1 次)
{} 重复(0 到 n 次)
原代码需要使用 UTF-8 编码,我们会区分大小写。
以下术语用来表示特定的 Unicode 字符类:
newline = /* Unicode 码位U+000A */ .
unicode_char = /* 除了换行符的其他任意 Unicode 码位 */ .
unicode_letter = /* 分类为 “Letter” 的 Unicode 码位 */ .
unicode_digit = /* 分类为“Number, decimal digit”的Unicode码位 */ .
下划线 _(U+005F) 被认为字母。
letter = unicode_letter | "_" .
decimal_digit = "0" … "9" .
binary_digit = "0" | "1" .
octal_digit = "0" … "7" .
hex_digit = "0" … "9" | "A" … "F" | "a" … "f" .
注释作为文档,有 2 种格式:
注释不能在 rune 和 string literal 中出现、
Tokens 组成了 API 语言的词汇表。有四个分类: 标识符 、 关键字 、 运算符和标点以及字面值 。 空白 是由空格(U+0020)、水平制表(U+0009)、回车(U+000D)和新行(U+000A)所组成的,空白一般会被忽略,除非它分隔了组合在一起会形成单一 token 的 tokens. 并且,新行或者文件结尾可能会触发 分号 的插入。当把输入的内容区分为 tokens 时,每一个 token 都是可组成有效 token 的最长字符序列。
正式的语法使用分号 ; 作为一定数量的语句终结符。
TODO: api 分号可以忽略的 case
标识符用于命名程序中的实体——比如变量和类型。它是一个或者多个字母和数字的序列组合。标识符的第一个字符必须是一个字母。
identifier = letter { letter | unicode_digit } .
a
_x9
ThisVariableIsExported
αβ
TODO: 预声明标识符
如一下关键字是固定保留的,不可以用作标识符。 因为 API 将会翻译成 GO 语言,所以 API 关键字包含 GO 语言的关键字。
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
TODO: 添加 API 关键字
string_lit = raw_string_lit | interpreted_string_lit | value_string_lit .
raw_string_lit = "`" { unicode_char | newline } "`" .
interpreted_string_lit = `"` { unicode_value | byte_value } `"` .
value_string_lit = { unicode_value | byte_value } .
`abc` // 同 "abc"
`\n
\n` // 同 "\\n\n\\n"
"\n"
"\"" // 同 `"`
"Hello, world!\n"
"日本語"
"\u65e5本\U00008a9e"
"\xff\u00FF"
"\uD800" // 非法: 代理了一半
"\U00110000" // 非法: 无效的 Unicode 码位
每个源文件都是由以下的组成:
SourceFile = SyntaxDecl ";" { ImportDecl ";" } [ InfoDecl ";" ] { TypeDecl | ServiceDecl ":"}
语法版本控制 API 的语法版本。
SyntaxDecl = "syntax" "=" SyntaxName .
SyntaxName = string_lit .
语法版本示例
syntax = "v1";
导出声明用于 当前 API 文件导入其他 API 的时候使用。
ImportDecl = "import" ( ImportPath | "(" { ImportPath ";" } ")" ) .
ImportPath = string_lit .
信息声明用于声明 API 的一些额外信息。
InfoDecl = "info" "(" { InfoElement ";"} ")" .
InfoElement = identifier ":" string_lit .
info (
auth: "dylan"
desc: `desc`
)
一个类型声明绑定了一个标识符(也就是 类型名 )到一个 类型 。目前 API 只支持类型定义。
TypeDecl = "type" ( TypeDef | "(" { TypeDef ";" } ")" ) .
TypeDef = identifier Type .
类型确定一组值。
Type = TypeName | TypeLit | "(" Type ")" .
TypeName = identifier | QualifiedIdent .
TypeLit = ArrayType | StructType | PointerType |
SliceType | MapType .
结构是命名元素的序列,称为字段,每个字段有一个名称和一个类型。字段名可以显式指定(IdentifierList)或隐式指定(EmbeddedField)。在结构中,非空字段名必须是唯一的。
StructType = [ "struct" ] "{" { FieldDecl ";" } "}" .
FieldDecl = (identifier Type | EmbeddedField) [ Tag ] .
EmbeddedField = [ "*" ] TypeName .
Tag = string_lit .
指针类型表示指向一给定类型的 变量 的所有指针的集合,这个给定类型称为该指针的 基础类型 。
PointerType = "*" Type .
ArrayType = "[" ArrayLength, "]" Type .
ArrayLength = Expression .
SliceType = "[", "]", Type .
映射是由一种类型的元素所组成的无序组,这个类型被称为元素类型, 其元素被一组另一种类型的唯一 键 索引,这个类型被称为键类型。
MapType = "map" "[" Type "]" Type .
服务为 API 定义的路由服务,一个 API 可以有多个 Service, 但是必须 ServiceName 必须同名。
ServiceDecl = (ServiceExtDecl) ServiceBody
ServiceBody = "service" identifier "(" { RouteDecl } ")"
RouteDecl = (Doc) ";" Handler ";" Method Path (Request) (Response)
Doc = "@doc" string_lit
Handler = "@handler" identifier
Method = "get" | "post" | "put" | "header"
Path = "/" (":") identifier { Path }
Request = "(" identifier ")"
Response = "returns" "(" identifier ")"
服务 @service 扩展信息定义。
ServiceExtDecl = "@service" "(" { ServiceExtElement } ")"
ServiceExtElement = identifier ":" string_lit .
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.