帮酷LOGO
  • 显示原文与译文双语对照的内容
An API versioning plugin for hapi.

  • 源代码名称:hapi-api-version
  • 源代码网址:http://www.github.com/p-meier/hapi-api-version
  • hapi-api-version源代码文档
  • hapi-api-version源代码下载
  • Git URL:
    git://www.github.com/p-meier/hapi-api-version.git
  • Git Clone代码到本地:
    git clone http://www.github.com/p-meier/hapi-api-version
  • Subversion代码到本地:
    $ svn co --depth empty http://www.github.com/p-meier/hapi-api-version
    Checked out revision 1.
    $ cd repo
    $ svn up trunk
  • hapi-api-version

    维护者:Tim Costa

    Build Status

    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 中。

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

    接受 header
    Accept: application/vnd.mysuperapi.v2+json

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

    自定义 header
    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




    Copyright © 2011 HelpLib All rights reserved.    知识分享协议 京ICP备05059198号-3  |  如果智培  |  酷兔英语