@soapi/app-server
app-server
是快速的、简单、灵活的用于开发接口平台的service
开发框架。
Install
npm install @soapi/app-server
or use yarn
yarn add @soapi/app-server
Usage
接口平台的service
主要分为 3 个部分,分别是:service
基本信息、interaction
界面插槽定义、hooks
事件响应、app
自定义 koa, 平台 api 调用。
service 基本信息
service 基本信息主要是告诉平台 “我是谁”,可以直接通过对对应字段赋值设置。
import { service, app } from '@soapi/app-server'
service.name = 'your service name'
service.version = 'your service version(must conform to the semver)'
service.changelog = ''
service.mode = 'http'
service.host = '0.0.0.0'
service.port = 8000
// NOTE: 将启动一个server,绑定到上面设定的0.0.0.0:8000端口
service.start()
service.version
必须符合Semantic Versioning规范。
这样平台才可以判断service
是否升级,从而可以进行相应的升级操作。
自定义 koa
通过增加koa
中间件扩展service
功能。
import { service, app } from '@soapi/app-server'
/* 你可以自定义koa中间件,实现service的功能扩展 */
app.use(/* custom koa middleware here */)
service.start()
界面插槽定义
service
可以为操作界面添加一些新的功能。可以添加一个按钮或者输入框,然后响应用户的操作请求(按钮点击或者输入内容)。
这方便服务为用户提供一些快捷操作方式。
import { service, interaction } from '@soapi/app-server'
// ...省略基本信息配置...
const rules = {
name: [{ required: true, message: 'Name 不能为空' }],
url: [{ required: true, message: 'Url 不能为空' }],
}
/**
* 插件的应用配置页面插槽
* 配置页面的插槽没有callback
* 配置信息将被存储到平台数据库
* 当需要的使用的时候,可以通过平台的api接口获取相应的配置信息
* 这保证简单的插件可以做到无状态
*
* 目前插槽只有`application`,其他插槽未开放。
*/
interaction.application = [
{
// 类型
type: 'string',
// 输入框的label
label: 'label',
// 通过api获取配置数据的数据key值(e.g. 通过config.default就能取得用户输入的stirng)
name: 'default',
/* 输入框组件的props */
props: { rules: rules.url },
},
]
service.start()
平台 api 调用
为了减少 request 的沉余数据,ctx 中只包含一些 id,需要更详细的信息要通过 api 接口调用才可以。
import { service, hooks } from '@soapi/app-server'
// ...省略基本信息配置...
hooks.on('applicationUpdated', async ctx => {
ctx.log.info('来源于平台:', ctx.origin)
ctx.log.info(`Id为${ctx.appId}的应用更新啦`)
const config = ctx.api.getConfig(ctx.serviceId)
ctx.log.info(`项目的配置页面的配置信息为:${config}`)
})
service.start()
service.start()
以后,不可以再修改任何配置,否则将导致接口平台的升级检测失败。如果想要修改,请同时修改版本号,然后重启服务
hooks
事件响应
当用户/平台进行某些操作时,将触发一些事件,service 可以监听这些事件,并对此做出响应,我们将此称之为hooks
。
import { service, hooks } from '@soapi/app-server'
// ...省略基本信息配置...
hooks.on('applicationUpdated', async ctx => {
ctx.log.info('来源于平台:', ctx.origin)
ctx.log.info(`Id为${ctx.appId}的应用更新啦`)
})
service.start()
当在接口平台的应用中启动此插件后,每次应用更新后,都会触发记录一条日志。
需要注意的是,hooks 是异步执行的。既,平台通知到service
后,request 请求就结束了。之后的操作相对于平台来说都是异步的。
框架会在 callback 执行完成后,调用end
接口,自动通知平台,service
的任务已经执行完成。
Hooks List
log
接口平台记录 log 时会向插件通知 log 事件。
createApp
创建应用
removeApp
删除应用
updateApp
更新应用信息
createSchema
应用创建新schema
updateSchema
更新schema
内容
removeSchema
删除schema
createRoute
应用创建新route
updateRoute
更新route
信息
removeRoute
删除route
publishAppRelease
应用发布新版本
API LIST
ctx.api.getRoute
获取应用的 route 信息
ctx.api.getSchema
获取应用的 schema 信息
ctx.api.getAppConfig
获取服务在应用中的配置信息
ctx.api.getApplication
获取应用的基本信息
ctx.throwError
通过这个 api 报错,会将错误上报到 接口平台进行记录
ctx.logger
提供ctx.logger.info
, ctx.logger.warn
, ctx.logger.error
, ctx.logger.success
四个等级,输出日志并将错误上报到 server。