README

仓库于2019-12-31废弃

此仓库已迁移至laminas-api-tools/api-tools-rest。

简介

此模块提供结构和代码，用于快速实现使用JSON作为传输的RESTful API。

它允许您创建使用以下标准的RESTful JSON API

• Hypermedia Application Language（超媒体应用语言，简称HAL），用于创建包含超媒体控制的JSON有效负载。
• Problem Details for HTTP APIs（HTTP API的问题详情，简称API Problem），用于报告API问题。

要求

请参阅composer.json文件。

安装

运行以下composer命令

$ composer require zfcampus/zf-rest

或者，手动将以下内容添加到您的composer.json文件中的require部分

"require": {
    "zfcampus/zf-rest": "^1.3"
}

然后运行composer update以确保安装了该模块。

最后，将模块名称添加到项目配置的config/application.config.php文件中的modules键下

return [
    /* ... */
    'modules' => [
        /* ... */
        'ZF\Rest',
    ],
    /* ... */
];

zf-component-installer

如果您使用zf-component-installer，该插件将为您将zf-rest作为模块安装。

配置

用户配置

用于配置此模块的最高级键是zf-rest。

键：控制器服务名称

zf-rest下的每个键都是一个控制器服务名称，其值是一个包含以下键之一或多个的数组。

子键：collection_http_methods

允许在向集合发送请求时使用的HTTP方法数组。

子键：entity_http_methods

允许在请求实体时使用的HTTP方法数组。

子键：collection_name

表示集合的嵌入属性的名称。

子键：collection_query_whitelist（可选）

用于收集请求和生成集合链接时的查询字符串参数数组，白名单。这些参数将传递给资源类的 fetchAll() 方法。请求中存在的任何这些参数也将用于生成集合链接。

你可能想要白名单的查询字符串参数示例包括 "sort"，"filter" 等。

从 1.5.0 版本开始：如果存在针对 GET HTTP 方法的输入过滤器，其键将与配置中的键合并。

子键：controller_class（可选）

创建控制器服务时使用的备用控制器类；它 必须 扩展 ZF\Rest\RestController。仅在使用此选项来更改 RestController 中的工作流程时使用。

子键：identifier（可选）

控制器的事件标识符名称。它允许多个控制器实例对不同的共享事件集做出反应。

子键：resource_identifiers（可选）

资源的事件标识符名称或名称数组。

子键：entity_class

用于表示实体的类。主要用于反射（例如在 Apigility Admin UI 中）。

子键：route_name

与此 REST 服务关联的路由名称。当需要在响应中生成链接时使用。

子键：route_identifier_name

路由规范中标识符的参数名称。

子键：listener

将用于处理任何集合或实体请求的资源类。

子键：page_size

每页集合中返回的实体数量。仅在返回的集合是 Zend\Paginator\Paginator 实例或其派生类时使用。

子键：max_page_size（可选）

每页集合中返回的实体最大数量。这与 page_size_param 进行比较。此参数可以设置为帮助防止针对您的 API 的拒绝服务攻击。

子键：min_page_size（可选）

每页集合中返回的实体最小数量。这与 page_size_param 进行比较。

子键：page_size_param（可选）

设置每个请求页面大小的查询字符串参数名称。默认不设置；我们建议具有额外的逻辑来确保页面大小的上限，以防止针对您的 API 的拒绝服务攻击。

用户配置示例

'AddressBook\\V1\\Rest\\Contact\\Controller' => [
    'listener' => 'AddressBook\\V1\\Rest\\Contact\\ContactResource',
    'route_name' => 'address-book.rest.contact',
    'route_identifier_name' => 'contact_id',
    'collection_name' => 'contact',
    'entity_http_methods' => [
        0 => 'GET',
        1 => 'PATCH',
        2 => 'PUT',
        3 => 'DELETE',
    ],
    'collection_http_methods' => [
        0 => 'GET',
        1 => 'POST',
    ],
    'collection_query_whitelist' => [],
    'page_size' => 25,
    'page_size_param' => null,
    'entity_class' => 'AddressBook\\V1\\Rest\\Contact\\ContactEntity',
    'collection_class' => 'AddressBook\\V1\\Rest\\Contact\\ContactCollection',
    'service_name' => 'Contact',
],

系统配置

zf-rest模块提供了以下配置以确保其在Zend Framework应用程序中正确运行。

'service_manager' => [
    'invokables' => [
        'ZF\Rest\RestParametersListener' => 'ZF\Rest\Listener\RestParametersListener',
    ],
    'factories' => [
        'ZF\Rest\OptionsListener' => 'ZF\Rest\Factory\OptionsListenerFactory',
    ],
],

'controllers' => [
    'abstract_factories' => [
        'ZF\Rest\Factory\RestControllerFactory',
    ],
],

'view_manager' => [
    // Enable this in your application configuration in order to get full
    // exception stack traces in your API-Problem responses.
    'display_exceptions' => false,
],

ZF2事件

监听器

ZF\Rest\Listener\OptionsListener

此监听器注册到MvcEvent::EVENT_ROUTE事件，优先级为-100。它有两个目的

• 如果对一个它们不支持方法的REST实体或集合发出请求，它将返回一个包含填充的Allow头，指示哪些请求方法可以使用，的405 Method not allowed响应。
• 对于OPTIONS请求，它将返回一个包含填充的Allow头，指示哪些请求方法可以使用，的200 OK响应。

ZF\Rest\Listener\RestParametersListener

此监听器以优先级100附加到共享的dispatch事件。监听器将请求的查询字符串参数映射到由RestController组合的Resource对象，以及注入RouteMatch。

ZF2服务

模型

ZF\Rest\AbstractResourceListener

此抽象类是Resource监听器的基本实现。由于基于zf-rest的REST服务的分派是事件驱动的，必须构建一个监听器来监听从ZF\Rest\Resource（由RestController调用）触发的事件。以下方法在dispatch()期间根据HTTP方法调用

• create($data) - 由对资源集合的POST请求触发。
• delete($id) - 由对资源实体的DELETE请求触发。
• deleteList($data) - 由对资源集合的DELETE请求触发。
• fetch($id) - 由对资源实体的GET请求触发。
• fetchAll($params = []) - 由对资源集合的GET请求触发。
• patch($id, $data) - 由对资源实体的PATCH请求触发。
• patchList($data) - 由对资源集合的PATCH请求触发。
• update($id, $data) - 由对资源实体的PUT请求触发。
• replaceList($data) - 由对资源集合的PUT请求触发。

ZF\Rest\Resource

Resource对象处理REST请求的业务逻辑分派。它组合一个EventManager实例以将操作委托给附加的监听器。此外，它组合请求信息，例如Request、RouteMatch和MvcEvent对象，以初始化它创建的ResourceEvent并将其传递给监听器以触发事件。

控制器

ZF\Rest\RestController

这是当控制器服务名称与配置的REST服务匹配时使用的基控制器实现。所有由zf-rest管理的REST服务都将使用此控制器（尽管是单独的实例），除非它们指定了控制器类选项。实例通过ZF\Rest\Factory\RestControllerFactory抽象工厂创建。

RestController根据请求的HTTP方法调用ZF\Rest\Resource中的相应方法。在成功时返回HAL有效载荷，在出错时返回API问题响应。