README

信息

- master

此包为您提供处理API多个版本的方法。请参阅 用法 部分了解如何使用此包

安装

步骤 1：下载包

打开命令行，进入项目目录，并执行以下命令以下载此包的最新稳定版本

$ composer require xurudragon/api-versioning-bundle

此命令要求您全局安装了Composer，如Composer文档中的安装章节所述。

步骤 2：启用包

然后，通过将其添加到注册的包列表中启用该包。如果您使用的是 Symfony 3.*，请查看您的项目中的 app/AppKernel.php 文件。

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new XuruDragon\ApiVersioningBundle\XuruDragonApiVersioningBundle(),
        );

        // ...
    }

    // ...
}

如果您使用的是 Symfony 4.*，请查看您的项目中的 config/bundles.php 文件。

<?php

//config/bundles.php

return [
    // ....
    XuruDragon\ApiVersioningBundle\XuruDragonApiVersioningBundle::class => ['all' => true],
];

步骤 3：配置

这里没有特别的事情要做。除非您想更改发送到API的头名称以处理版本变更。您可以将这些条目添加到您的配置文件中

xurudragon_versioning:
    # Header name that should be sent to the api to processing versioning changes
    header_name: X-Accept-Version #Header name

用法

简介

您的API响应必须始终与API的最新版本匹配。

为了支持多个版本，您必须为每个破坏向后兼容性的API版本创建一个变更类，继承自以下抽象类：XuruDragon\ApiVersioningBundle\Changes\AbstractChanges

在配置文件中添加对应于之前创建的类的条目
我们建议您使用以下结构

创建一个名为 ApiChanges 的文件夹

将您的类命名为 ApiChangesXYZ，其中 X 表示 主 版本，Y 表示 次 版本，Z 表示 修订 版本
我们假设您了解语义化版本控制系统

创建变更类

这是 0.9.0 类版本，它假定您的API版本至少为 0.9.1 。

您现在应该使用自己的逻辑实现apply和supports方法。

<?php
// ../ApiChanges/ApiChanges090.php

namespace Your\Bundle\ApiChanges;

use XuruDragon\ApiVersioningBundle\Changes\AbstractChanges,

class ApiChanges090 extends AbstractChanges
{

    /**
     * Apply version changes for current request.
     *
     * @param array $data
     *
     * @return null|array
     */
    public function apply(array $data = [])
    {
        return $data;
    }

    /**
     * Returns true if this version changes is supported for current request.
     *
     * @param array $data
     *
     * @return null|bool
     */
    public function supports(array $data = [])
    {
        return true;
    }
    // ...
}

supports 应该返回 true 或 false，根据此版本变更是否支持您最新API版本返回的实际数据。

apply 应执行您想要将实际数据转换为与该API版本对应的任何操作。返回的数组将编码为JSON并返回给发起请求的API客户端。

####示例假设您的API 1.0.0版本在调用服务的JSON输出中添加了一个条目。这个条目是返回的最新API版本的数据数组中的 "location"。

您必须删除此数据条目，以便请求的版本 0.9.0 与调用客户端期望的匹配。

$data = [
    'results' => [
        'firstname' => 'John',
        'lastname' => 'Doe',
        'location' => '4, Privet Drive, Little Whinging, Surey', 
    ],
];

您可以通过修改之前创建的类来实现这一点，如下面的代码所示

当然，这里只是一个删除一个条目的简单示例，处理可能更复杂。

<?php
// ../ApiChanges/ApiChanges090.php

namespace Your\Bundle\ApiChanges;

use XuruDragon\ApiVersioningBundle\Changes\AbstractChanges,

/**
 * Class ApiChanges090.
 */
class ApiChanges090 extends AbstractChanges
{
    /**
     * {@inheritdoc}
     */
    public function apply(array $data = [])
    {
        //short example, but can be more more complex
        unset($data['results']['location']);

        return $data;
    }

    /**
     * {@inheritdoc}
     */
    public function supports(array $data = [])
    {
        //check for the entry column "location" in the results sub-array of $data
        return isset($data['results']) && array_search('location', array_keys($data['results']), true);
    }
    // ...
}

当然，这里是一个删除一个条目的简单示例，处理可能更复杂。

在配置中注册版本变更类

    # Array of version changes that breaks backward compatibility
    # The array should be `desc` ordered.
    # The newest version should be the first and the oldest the last one
    versions:
        # version 0.9.0
        - { version_number: "0.9.0", changes_class: "Your\Bundle\ApiChanges\ApiChanges090"}

这就完成了，不再需要配置。

xurudragon / api-versioning-bundle

维护者

详细信息