查看 代码示例

编写 API 接口 JSON 描述文件，将其放置在应用 apis 目录中，运行 yao start 命令启动服务时，引擎将按接口描述的定义，生成 RESTFul API 接口。 Yao 当前支持 RESTFul API 描述 MQTT、Socket、WEB Socket API ; 用于数据归集对接、即时通信、IoT 等类型的项目。

业务接口描述文件是以 小写英文字母 + .协议名称 + .json 扩展名命名的 JSON 文本文件, <name>.<protocol>.json;

一个 http 协议的接口(API)文档，可以定义一组 API，可以在每个 API 中绑定一个处理器(process), 系统自动调用处理器，返回处理器调用结果；

API 将通过路由 /api/<group>/<path>访问, 请求成功响应 out 中定义的状态码、Content-Type 和处理器(process)返回值， 请求失败响应异常状态码和 JSON 格式的错误消息 查看异常规范。

in 中定义的参数表，将作为处理器的输入参数。支持使用 :param 、 :payload 、$param.字段名称 等变量，绑定请求参数。

Object File 数据结构

{
  "code": 500,
  "message": "ID=12的数据不存在",
  "context": {
    "field": "id"
  }
}

返回状态与错误码一致，如 HTTP Response 状态码为 400~599 则视为程序处理异常。

错误码含义，基本与 HTTP 协议状态码含义一致，便于 RESTFul API 编写、统一异常处理和工程师理解错误码含义。

在请求 api 中使用 gurad，类似于使用中间件过滤请求，拦截一些不满足条件的请求，在定义 api 的时候指定 guard 字段所使用的处理器即可

指定整个分组 api 都要验证登录

{
  "name": "下拉搜索",
  "version": "1.0.0",
  "description": "下拉搜索",
  "guard": "bearer-jwt",
  "group": "select",
  "paths": [
    {
      "path": "/category",
      "method": "GET",
      "process": "flows.category",
      "in": [],
      "out": {
        "status": 200,
        "type": "application/json"
      }
    }
  ]
}

单独指定一个接口需要验证登录

{
  "name": "下拉搜索",
  "version": "1.0.0",
  "description": "下拉搜索",
  "group": "select",
  "paths": [
    {
      "path": "/category",
      "method": "GET",
      "guard": "bearer-jwt",
      "process": "flows.category",
      "in": [],
      "out": {
        "status": 200,
        "type": "application/json"
      }
    }
  ]
}

{
  "name": "下拉搜索",
  "version": "1.0.0",
  "description": "下拉搜索",
  "guard": "-",
  "group": "select",
  "paths": [
    {
      "path": "/category",
      "method": "GET",
      "process": "flows.category",
      "in": [],
      "out": {
        "status": 200,
        "type": "application/json"
      }
    }
  ]
}

新建flows/category.flow.yao文件:

{
  "label": "类目树",
  "version": "1.0.0",
  "description": "类目树",
  "nodes": [
    {
      "name": "类目",
      "engine": "xiang",
      "query": {
        "select": ["id", "name", "name as label", "id as value", "parent_id"],
        "wheres": [{ ":deleted_at": "删除", "=": null }],
        "from": "category",
        "limit": 1000
      }
    },
    {
      "name": "类目树",
      "process": "xiang.helper.ArrayTree",
      "args": ["{{$res.类目}}", { "parent": "parent_id" }]
    }
  ],
  "output": "{{$res.类目树}}"
}

调用 127.0.0.1/api/select/category