koa-hap

koa-hap介绍

koa-hap是基于HAP协议的实现，以文件目录及文件名为目录的约定默认url映射，提供一套koa的中间件，需要注意的是，koa-hap仅支持koa2。

注意，--不支持koa 1.0--

快速开始

安装

npm install koa-hap

使用

// koa app.js

import Koa from 'koa'
import koaHap from 'koa-hap'

const app = new Koa()

//使用中间件
app.use(koaHap('apis', {
  basePath: '/api', // http url path, default is '/api'
  extension: '*.js|*.es6', // string或者RegExp类型
  layoutLoad: false, //是否开启延迟加载，不建议开启
}))

app.listen(3000)
// ...

API

koa-hap只包含一个入口函数 function koaHap(apiPath, options)

参数名|类型|描述 |---|---|---| apiPath|string|api程序文件路径 options|object|配置选项

返回一个koa - middleware 函数，该函数有一个handlers, 该属性存放apiPath映射后的对象，其结构如下：

{
  auth: {
    index: Function, // 验证程序，可以通过 url /api/auth 或者 /api/auth/index 调用
    login: Function, // 用户登录，可以通过 url /api/auth/login调用
    logout: Function // 注销登录，可以通过 url /api/auth/login调用
    // ...
  },
  // ...
}

当启用delayLoad时，该项将为空一个对象{}

options 说明 属性名|类型|默认值|描述 |---|---|---|---| basePath|string|"/api"|http服务中绑定到的url，可以指定到"/"，这样该koa将会被完全占用 extension|string/RegExp|".js"|字符串格式:".js|*.es6"，如果apiPath下有发现不符合hap协议的程序文件，中间件将报错处理。注意：如果您使用了ES6，除非您配置了babel，否则并不会自动转码，将会抛出异常 delayLoad|boolean|false|延迟加载，如果配置了该项，服务将动态查找对应的程序文件执行。这样可以提高服务启动速度。需要注意的是这样并不安全，你还需要严密监测apiPath下的文件变化，并且不会返回映射结构，--除非特殊要求，否则不建议开启此项--

URL映射约定

koa-hap,会将apiPath中的文件，映射到url中，

例如： apiPath参数指定的目录结构

/api
  ├╌ sys  --目录
  ╎  ├╌╌ auth.js   --js文件
  ╎  ╎      ├╌╌ #login   --函数
  ╎  ╎      └╌╌ #logout  --函数
  ╎  └╌╌ access.js
  ╎        ├╌╌ #index  --函数
  ╎        ├╌╌ #valid    --函数
  ╎        └╌╌ #update   --函数
  ├╌ erp  --目录
  ...

将会被映射为以下结构

{
  sys: {
    auth: {
      login: ...,
      logout: ...,
    },
    access(): {      // 通过 url "/api/sys/access" 调用
      valid: ...,    // 通过 url "/api/sys/access/valid" 调用
      update: ...,   // 通过 url "/api/sys/access/update" 调用
    }
  }
}

如果一个目录下面同时有一个程序文件，并且又有另一个同名文件夹，并且其子目录中的存一个与上级目录程序文件相同的文件名，同时还定义了index函数，此时将会导致冲突，koa-hap不允许这种情况该生，程序将抛出异常。需要注意的是另一种情况，当我们启动了延迟加载delayLoad的时候，再访问这个有冲突的函数，这时候不会抛出异常，而是使会优先用较上一层级的程序文件。 例如：

api
  ├╌ sys  --目录
  ╎  ├╌╌ access.js             --文件
  ╎  ╎      ├╌╌ #rights        --函数  冲突
  ╎  ╎      └╌╌ #logout        --函数
  ╎  └╌╌ access                --目录
  ╎        └╌╌ rights.js       --文件
  ╎              ├╌╌ #index    --函数, 冲突
  ╎              └╌╌ #update   --函数
  ...

HAP协议

• 以http的POST方式为提交数据,数据以content提交
• 以json为数据传输格式
• 以url为调用位置描述
• url节(即两个/之间)只允许标识符,验证规则：/^([a-zA-Z]+[0-9]*)+$/，多级使用/划分。
  • 合法url示例: /api/foo/bar, /api/foo#bar
  • 非法url示例: /api/foo-bar, /api/fooBar
• url末端可以使用#划分
  • 例如: /api/auth#login /api/auth#logout
  • /api#auth#login 此url非法.
• hap不规定除以上规定以外的项，即header，cookie,均由用户自行决定。

request content

{
  "arg1": "这是参数1",
  "arg2": { "这是参数2" }
}

response content

{
  //表示此次是否调用成功，如果不成功，则却要
  "success": false,
  // 错误消息，如果调用不成功，应该返回错误信息
  "errMsg": "发生了错误",
  // 错误数据，错误信息类型为任意类型，可以在此项存放错误信息，不用时可以省略
  "errData": {
    "code": "01",
    "stack": "....."
  },
  // 接口返回值，如果没有返回值或者发生了错误，可以省略此项
  "data": undefined
}

• 无论任何情况，服务端应该尽量确保http请求正常返回200，如果遇到错误，则返回一个标准的json对象，并标示错误信息 例：

范例：

request

POST /api/auth/login HTTP/1.1
...
Accept: application/json
Content-Type: application/json;charset=UTF-8
...
------------------body---------------------------
{
  "username": "admin",
  "password": "123"
}

response

HTTP/1.1 200 OK
...
content-type: application/json; charset=utf-8
...
---------------------body----------------------
{
  "success":true,
  "data":
  {
    "username":"admin",
    "loginTime":"2018-03-15T07:34:29.308Z"
  }
}