README

这是一个简单易用的版本控制系统，允许根据API请求动态调整资源，弃用或注入。它为API提供了一套完全可配置的访问控制列表（ACL），以帮助应用开发者和根据设备允许的功能进行公开访问。

因此，这是一个很好的工具，可以在不牺牲设备兼容性的情况下，保持API的生命周期更新。它也是一种强制移动设备应用程序更新的好方法，因为它可以拒绝对特定版本或最低版本的请求。

该工具在这方面不提供任何安全功能，这意味着请求设备必须自行提供信息。不要将其用作安全系统，而应将其用作兼容性/弃用系统。

入门

要安装包，请运行

composer require imageplus/apivcs

您还应该发布配置以允许您进一步自定义设置。

php artisan vendor:publish  --tag=imageplus-api-vcs-config

通过在您的环境变量中添加 VCS_ENABLED=true 来启用此功能。

请求参数

headers: [
    ...
    Device-Type: ios,
    Device-Version: 1.32.1-rc_final
]

设置全局API版本

此包可以配置为使用全局API版本（例如 /api/v1/...，/api/v6/...）。要增加版本，只需更新您的环境变量以包含以下键值，其中值是您的API的最新版本，例如：3

VCS_API_VERSION=3

如果您想删除旧版本，请参阅以下阻塞版本。

全局API版本只能为整数，且请求必须包含 /api/v{version_number}/{uri} 来使用它们。如果URL上未指定版本号，则默认为环境变量 VCS_API_DEFAULT_VERSION。

注意：您无需指定您的API路由以接受版本控制。

警告：如果您使用全局版本，请勿在API内部进行重定向，否则您的请求将丢失提交的API版本。

设置设备和版本

在发布的配置文件中，您将能够配置您打算进行版本控制的设备。

'devices' => [
    'android' => 'Android',
    'ps5' => 'Playstation 5'
]

一旦添加了设备，您需要在配置文件或使用环境变量覆盖（见以下ENV覆盖）中提供该设备的最低版本。

'minimum_version' => [
    'android' => '2.1.0',
    'ps5' => '1.0.0'
],

默认情况下，必须提供设备类型和版本才能访问API。您可以使用 VCS_ALLOW_DEVICELESS_ACCESS 环境标志来更改此设置。

功能

如果您想将特定功能限制在特定的设备或版本数量上，您可以使用以下方式配置您的功能

'my_feature_key' => [
    'android' => '2.7.0',
    'ps5' => '1.0.0|!1.3.*'
],
'no_android_access' => [
    'ps5' => '1.0.0'
]

通过使用版本助手，您可以标记特定版本或特定设备的最低版本。如果特定设备未在功能上设置，则它将无法访问该功能。

用法

外观

APIVersionValidator

这是一个版本比较器，主要用于辅助。它允许您比较给定版本，并可以作为ACL检查器。

APIVersionControl

此外观将帮助您根据请求中注册的设备创建条件。例如，假设您想根据设备提供json或XML资源。您可以使用以下方式

if (APIVersionControl::hasAccess('XML'))
    return Response::makeXML($resource);

return Response::makeJSON($resource);

或向资源添加特定设备的其他属性

APIVersionControl::onlyDeviceVersion('ios', '!1.2.*', function () use ($resource) {
    $resource->valid_version = true;
});

中间件

有三个路由中间件可以帮助您进一步自定义ACL。在您的 api.php 文件中，您可以使用这些中间件来阻止特定路由。

FeatureVersionMiddleware：仅允许具有访问指定功能的设备

//Only devices that support notifications
Route::group([
    'name' => 'Notifications routes',
    'prefix' => 'api/notifications',
    'as' => 'notifications.',
    
    'middleware' => 'feature:notifications'
], function (){

    //All notification routes
    
});

APIVersionMiddleware：使用版本助手来阻止或仅允许访问特定API版本

//This route only works on API version 1
Route::get('/api/user', [
    'as' => 'user.index',
    'uses' => 'UsersController@index'
])->middleware('api_version:=1');

//This route works on any API version above or equal 2
Route::get('/api/profile', [
    'as' => 'profile',
    'uses' => 'ProfileController@index'
])->middleware('api_version:2');

DeviceVersionMiddleware：使用版本助手来阻止或仅允许访问特定设备和版本

//This route only works on ios
Route::get('/api/blob', [
    'as' => 'blob',
    'uses' => 'BlobController@index'
])->middleware('device_version:ios,2.8.0');

//This route works on any version for playstation but only after 2.9.0 for iOS
Route::get('/api/blobs', [
    'as' => 'blobs',
    'uses' => 'BlobController@all'
])->middleware([
    'device_version:ps5,any',
    'device_version:ios,2.9.0'
]);

阻止特定版本

您还可以使用配置中的locked_versions来阻止特定设备版本或全局API版本。

'locked_versions' => [
    'global' => env('VCS_GLOBAL_BLOCK_VERSION', '2'),
    'ios' => env('VCS_IOS_BLOCK_VERSION', '2.1.2, 2.1.6'),
]

这些版本之间用,分隔，并且需要指定如上所示的精确版本。

环境覆盖

当配置文件中的env_override为true时，大多数配置都可以在您的env文件中覆盖。如果您缓存了配置，则此设置不会生效。以下是支持覆盖的正确语法：

VCS_{device_type}_MINIMUM_VERSION //Sets the minimum version for {device_type}

VCS_{device_type}_LOCKED_VERSION //Defines (and replaces) the locked versions for {device_type} Use GLOBAL for global api version

命令助手

您可以使用提供的命令来模拟特定设备的访问。

php artisan api:has-access --device=ios --device_ver=1.0.0-pre-alpha2

php artisan api:has-access --device=ps5 --device_ver=1.0.1-rcA --feature=profile

php artisan api:has-access --device=ios --device_ver=1.42.12 --api_ver=4

imageplus / apivcs

维护者

详细信息