创建user.api文件

$ goctl api -o user.api

user.api文件内容

从图中我们可以看到有 import、info、type、service 4个元素块

import块

一个包含service的api文件对应一个微服务，在实际场景中，微服务用到的struct会特别多，如果过多的struct都定义到一个api文件中，则会显得非常拥挤，增加代码阅读难度。

api文件引入，多个api文件以换行符分割，被引入api文件可以包含struct和service内容

语法格式

import $api

$api: api文件相对/绝对路径

语法示例

import "foo1.api"
import "foo2.api"

info块

api文件进行描述

语法格式

info(
    // key-value
)

key-value

key描述示例
title标题title:"api描述"
desc说明desc:"api语法描述"
author作者author:"keson"
email邮件email:"keson@xiaoheiban.cn"
version版本version:"v1.0.0"









语法示例

info(
  title: "api demo"
  desc: "show how define api grammar"
  author: "keson"
  email: "keson@xiaoheiban.cn"
)

type块

api用到的struct，包含request、response等

语法格式

同golang语法一致

语法示例

type request struct {
  ping string `json:"ping"` // 见 #tag描述
}

tag描述

key描述支持生效范围示例
jsonjson序列化tagGolangrequest、responsejson:"name,optional"
path路由path值，配合路由使用go-zerorequestpath:"id"
formform标签，form 消息体和quertString的值均会被绑定go-zerorequestform:"name"









service块

微服务定义，包含host、port、middleware、路由等信息，goctl会根据此block生成对应的服务

语法格式

@server(
  jwt: $auth
  middleware: $middleware
)
service $name {
  @doc(
    summary: $desc
  )
  @handler $handler
  $httpmethod $path ($request) returns ($response)

  ....
}

字段描述

字段描述示例
$jwt

开启jwt鉴权

Auth
$middleware中间件声明loghandler
$desc路由描述"登录"
$handlerhandler名称user
$httpmethodhttp方法(必须小写)post
$pathhttp路由/user/login
$request请求体,没有可为空UserRequest
($response)响应体,没有则省略returns及其后面语法UserResponse















语法示例

@server(
  jwt: Auth
  middleware: logHandler
)
service user {
  @doc(
    summary: "登录"
  )
  @handler user
  port /user/login (UserRequest) returns (UserResponse)
}

注意事项

TODO: 目前仅支持单行注释，否则会解析出错