Autos

Autos 数据校验中间件

Autos 内置了对接口调用前端传参、后端数据返回是否符合接口文档约定的校验功能，可通过 http-proxy-middleware 中间件的形式使用。

1.1 特性

校验 query, path, postJSON, post form 参数是否符合约定
校验 response json 是否符合约定

1.2 TODO

不能正确校验 websocket 请求参数是否符合约定
不能正确校验文件上传请求参数是否符合约定
可能不能正确校验 headers 内参数是否符合约定
未校验非 json 响应数据格式是否符合约定

2. API

xxxxxxxxxx
 
const { createProxyMiddleware } = require('http-proxy-middleware');
const { proxyHandle } = require('auto-service/lib/validate');
​
proxyHandle(proxies: proxyConfig || proxyConfig[], config: IProxyHandleConfig)

2.1 IProxyHandleConfig

IProxyHandleConfig 用以配置校验中间件的相关行为。

loadSwagger

(url: string) => swaggerjson

required

获取 swagger 文件

onValidate

((e: { message: string; code: number; result?: smvalidateinfo | undefined; }) => void) | undefined

校验结束后的回调

formatBodyBeforeValidate

(<j, o extends {}>(data: j) => o) | undefined

格式化响应 body

2.2 ISMValidateInfo

send

Smajaxconfig | undefined

receive

{ body?: any; status: number; }

required

req

Incomingmessage

required

res

Smabstractresponse

required

2.3 ISMAjaxConfig

method

required

url

String

required

data

Any

form

Any

query

Any

header

Any

path

Any

body

Any

2.4 ISMAbstractResponse

httpVersion

String

required

httpVersionMajor

Number

required

httpVersionMinor

Number

required

connection

Socket

required

headers

Incominghttpheaders

required

rawHeaders

String[]

required

trailers

{ [key: string]: string | undefined; }

required

rawTrailers

String[]

required

setTimeout

((msecs: number, callback: () => void) => incomingmessage) | ((msecs: number, callback?: (() => void) | undefined) => serverresponse)

required

method

String | undefined

Only valid for request obtained from http.Server.

url

String | undefined

Only valid for request obtained from http.Server.

statusCode

Number | undefined

Only valid for response obtained from http.ClientRequest.

statusMessage

String | undefined

Only valid for response obtained from http.ClientRequest.

socket

Socket

required

destroy

((error?: error | undefined) => void) | ((error: error) => void)

required

readable

Boolean

required

_read

(size: number) => void

required

read

(size?: number | undefined) => any

required

setEncoding

(encoding: string) => incomingmessage

required

pause

() => incomingmessage

required

resume

() => incomingmessage

required

isPaused

() => boolean

required

unpipe

<t extends writablestream>(destination?: t | undefined) => incomingmessage

required

unshift

(chunk: any) => void

required

wrap

(oldstream: readablestream) => incomingmessage

required

push

(chunk: any, encoding?: string | undefined) => boolean

required

_destroy

((err: error, callback: function) => void) | ((err: error, callback: function) => void)

required

addListener

{ (event: string, listener: (...args: any[]) => void): incomingmessage; (event: "close", listener: () => void): incomingmessage; (event: "data", listener: (chunk: string | buffer) => void): incomingmessage; (event: "end", listener: () => void): incomingmessage; (event: "readable", listener: () => void): incomingmess...

required

Event emitter The defined events on documents including: 1. close 2. data 3. end 4. readable 5. error Event emitter The defined events on documents including: 1. close 2. drain 3. error 4. finish 5. pipe 6. unpipe

emit

{ (event: string | symbol, ...args: any[]): boolean; (event: "close"): boolean; (event: "data", chunk: string | buffer): boolean; (event: "end"): boolean; (event: "readable"): boolean; (event: "error", err: error): boolean; } | { ...; }

required

once

required

prependListener

required

prependOnceListener

required

removeListener

required

pipe

(<t extends writablestream>(destination: t, options?: { end?: boolean | undefined; } | undefined) => t) | (<t extends writablestream>(destination: t, options?: { end?: boolean | undefined; } | undefined) => t)

required

removeAllListeners

required

setMaxListeners

((n: number) => incomingmessage) | ((n: number) => serverresponse)

required

getMaxListeners

() => number

required

listeners

((event: string | symbol) => function[]) | ((event: string | symbol) => function[])

required

eventNames

(() => (string | symbol)[]) | (() => (string | symbol)[])

required

listenerCount

((type: string | symbol) => number) | ((type: string | symbol) => number)

required

assignSocket

(socket: socket) => void

required

detachSocket

(socket: socket) => void

required

writeContinue

(callback?: (() => void) | undefined) => void

required

writeHead

{ (statuscode: number, reasonphrase?: string | undefined, headers?: outgoinghttpheaders | undefined): void; (statuscode: number, headers?: outgoinghttpheaders | undefined): void; }

required

upgrading

Boolean

required

chunkedEncoding

Boolean

required

shouldKeepAlive

Boolean

required

useChunkedEncodingByDefault

Boolean

required

sendDate

Boolean

required

finished

Boolean

required

headersSent

Boolean

required

setHeader

(name: string, value: string | number | string[]) => void

required

getHeader

(name: string) => string | number | string[] | undefined

required

getHeaders

() => outgoinghttpheaders

required

getHeaderNames

() => string[]

required

hasHeader

(name: string) => boolean

required

removeHeader

(name: string) => void

required

addTrailers

(headers: outgoinghttpheaders | [string, string][]) => void

required

flushHeaders

() => void

required

writable

Boolean

required

_write

(chunk: any, encoding: string, callback: (err?: error | undefined) => void) => void

required

_writev

((chunks: { chunk: any; encoding: string; }[], callback: (err?: error | undefined) => void) => void) | undefined

_final

(callback: function) => void

required

write

{ (chunk: any, cb?: function | undefined): boolean; (chunk: any, encoding?: string | undefined, cb?: function | undefined): boolean; }

required

setDefaultEncoding

(encoding: string) => serverresponse

required

end

{ (cb?: function | undefined): void; (chunk: any, cb?: function | undefined): void; (chunk: any, encoding?: string | undefined, cb?: function | undefined): void; }

required

cork

() => void

required

uncork

() => void

required

2.5 IIncomingMessage

httpVersion

String

required

httpVersionMajor

Number

required

httpVersionMinor

Number

required

connection

Socket

required

headers

Incominghttpheaders

required

rawHeaders

String[]

required

trailers

{ [key: string]: string | undefined; }

required

rawTrailers

String[]

required

setTimeout

(msecs: number, callback: () => void) => incomingmessage

required

method

String | undefined

Only valid for request obtained from http.Server.

url

String | undefined

Only valid for request obtained from http.Server.

statusCode

Number | undefined

Only valid for response obtained from http.ClientRequest.

statusMessage

String | undefined

Only valid for response obtained from http.ClientRequest.

socket

Socket

required

destroy

(error?: error | undefined) => void

required

readable

Boolean

required

_read

(size: number) => void

required

read

(size?: number | undefined) => any

required

setEncoding

(encoding: string) => incomingmessage

required

pause

() => incomingmessage

required

resume

() => incomingmessage

required

isPaused

() => boolean

required

unpipe

<t extends writablestream>(destination?: t | undefined) => incomingmessage

required

unshift

(chunk: any) => void

required

wrap

(oldstream: readablestream) => incomingmessage

required

push

(chunk: any, encoding?: string | undefined) => boolean

required

_destroy

(err: error, callback: function) => void

required

addListener

required

Event emitter The defined events on documents including: 1. close 2. data 3. end 4. readable 5. error

emit

required

once

required

prependListener

required

prependOnceListener

required

removeListener

required

pipe

<t extends writablestream>(destination: t, options?: { end?: boolean | undefined; } | undefined) => t

required

removeAllListeners

(event?: string | symbol | undefined) => incomingmessage

required

setMaxListeners

(n: number) => incomingmessage

required

getMaxListeners

() => number

required

listeners

(event: string | symbol) => function[]

required

eventNames

() => (string | symbol)[]

required

listenerCount

(type: string | symbol) => number

required

3 快速上手 - 面向前端 FE

适用于前后端联调阶段，提升联调效率。

3.1 配置 proxy

配置 webpack proxy，如 cra 标配的 src/setupProxy.js：

xxxxxxxxxx
 
const { createProxyMiddleware } = require('http-proxy-middleware');
/**
 * @typedef { import('auto-service/lib/consts').ProxyHandleConfig } ProxyHandleConfig
 */
const { proxyHandle } = require('auto-service/lib/validate');
​
module.exports = function (app) {
  app.use(
    '/test/api',
    createProxyMiddleware({
      ...proxyHandle(
        {},
        /** @type {ProxyHandleConfig} 配置 */
        {
          // 加载本地 swagger 文档的逻辑
          loadSwagger: () => require('../swagger.json'),
          // 返回接口返回的 result 字段
          formatBodyBeforeValidate: (data) => data.result,
          // 自定义校验信息显示逻辑
          onValidate: (res) => {
            const { code, result: { receive, send } = {}, message } = res;
            if (code) {
              // do something
            }
          }
      )[0],
      target: PROXY_TARGET,
      changeOrigin: true
    })
  )
};

3.2 默认 onValidate

当传参或数据返回不符合文档约定时，默认 onValidate 配置会打出如下信息：

xxxxxxxxxx
 
  接口 /mix/{id}/ 参数不符合约定: data.body.id should be number
  接口 /mix/{id}/ 数据返回不符合约定: data.code should be number
  接口 /mix/{id}/ 参数不符合约定: data.body.id should be number
  接口 /mix/{id}/ 数据返回不符合约定: data.code should be number

你可以配置在 onValidate 内配置任意的处理逻辑，例如向与你联调的 RD 发送 IM 消息。

4. 快速上手 - 面向测试 QA

TODO

自动测试并校验