hapi-api-version, hapi的API版本插件

维护者：Tim Costa

onwards的API版本插件 onwards 。

特性/目标

• 支持通过 accept 和定制 header ( 默认 api-version ) 进行版本控制，如 troyhunt.com 所描述
• 100%测试覆盖
• 易于使用和灵活
• 遵循 hapi代码规范。
• 允许遵循干燥原则

要求

运行 node> =8和 hapi> =17，测试 Travis CI 。

安装

npm install --save hapi-api-version

用法

将它的注册到服务器：

'use strict';constHapi=require('hapi');constinit=asyncfunction () {
 try {
 constserver=newHapi.server({ port:3000 });
 awaitserver.register({
 register:require('hapi-api-version'),
 options: {
 validVersions: [1, 2],
 defaultVersion:2,
 vendorName:'mysuperapi' }
 })
 awaitserver.start();
 console.log('Server running at:', server.info.uri);
 } 
 catch (err) {
 console.error(err);
 process.exit(1);
 }
}init();

是时候添加一些路线了。

通常，这个插件设计了两个通用的用例来解决这个问题。

这是永远不改变api版本的路由类型。 路由定义和处理程序保持相同。

server.route({
 method:'GET',
 path:'/loginStatus',
 handler:function (request, h) {
 constloggedIn=...;
 return {
 loggedIn: loggedIn
 );
 }
});

这就是实际改变的路线。

在简单的情况下，只要处理程序不同，就可以使用这种方法。

constusersVersion1= [{
 name:'Peter Miller'}];constusersVersion2= [{
 firtname:'Peter',
 lastname:'Miller'}];server.route({
 method:'GET',
 path:'/users',
 handler:function (request, h) {
 constversion=request.pre.apiVersion;
 if (version ===1) {
 return usersVersion1;
 }
 return usersVersion2;
 }
});

有时需要更改处理器本身，而不仅仅改变路由定义本身。

constusersVersion1= [{
 name:'Peter Miller'}];constusersVersion2= [{
 firtname:'Peter',
 lastname:'Miller'}];server.route({
 method:'GET',
 path:'/v1/users',
 handler:function (request, h) {
 return usersVersion1;
 },
 config: {
 response: {
 schema:Joi.array().items(
 Joi.object({
 name:Joi.string().required()
 })
 )
 }
 }
});server.route({
 method:'GET',
 path:'/v2/users',
 handler:function (request, h) {
 return usersVersion2;
 },
 config: {
 response: {
 schema:Joi.array().items(
 Joi.object({
 firtname:Joi.string().required(),
 lastname:Joi.string().required()
 })
 )
 }
 }
});

请注意这里的响应验证的不同模式。

用户仍然向 /users 发送一个请求，插件会根据请求的版本在内部将它的重写为 /v1/users 或者 /v2/users 。

示例

可以在 example 文件夹中找到带有路由的完整工作示例。

文档

hapi-api-version 在内部工作，可以重写 url 。 这个过程非常简单：

• 检查 accept header 或者自定义 header ( 默认 api-version ) 是否存在并提取版本
• 如果提取了版本，检查是否有效，否则使用状态代码 400 进行响应
• 如果未提取任何版本( 比如 。 没有发送标题) 使用默认版本
• 检查版本化的路由( 像 /v2/users ) 是否存在- 如果将url重写为 /v2/users，则将url重写为，否则执行

命令行选项

插件的选项在插件注册中验证。

• validVersions ( 必选) 是整数值的array 。 指定你支持的所有有效的api版本。 其他任何东西都被认为无效，插件用状态代码 400 响应。
• defaultVersion ( 必选) 是一个包含在 validVersions 中的整数。 定义没有发送标题时要使用的版本。
• vendorName ( 必选) 是一个字符串。 定义在 accept 标头中使用的供应商 NAME 。
• versionHeader ( 可选) 是一个字符串。 定义要使用的自定义 header的NAME 。 默认情况下，这是 api-version 。
• passiveMode ( 可选) 是一个布尔值。 允许在没有提供标题时绕过。 当你提供其他内容如文档和减少处理这些内容的开销时有用。
• basePath ( 可选) 是一个字符串。 如果我们有一个与 / 不同的基路径( 例如： /api/ ) 默认情况下，这是 / 。

在处理程序中获取请求的API版本

你可以在处理程序中获得用户( 或者，如果未请求任何内容，则可能为默认版本) 请求的API版本。 它存储在 request.pre.apiVersion 中。

头

标题必须有一个特定的格式才能被插件正确识别和处理。

Accept: application/vnd.mysuperapi.v2+json

在这里，mysuperapi 是选项中指定的vendorName 。 如果供应商 NAME 没有 MATCH，则将使用默认版本。

api-version: 2

这里 api-version 是自定义 header的默认 NAME 。 它可以通过 versionHeader的选项来指定。

正在运行测试

实验室用于所有测试。 在运行测试之前，请确保将它的全局安装：

npm install -g lab

现在执行测试：

npm test

若要查看html中的覆盖率报告，请执行以下操作：

npm run test-coverage

在这之后，可以在 coverage/coverage.html 中找到 html 。

许可证

Apache-2.0