README

简介

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

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

• 超媒体应用程序语言，简称HAL，用于创建带有超媒体控制的JSON负载。
• HTTP API的问题详细信息，简称API问题，用于报告API问题。

要求

请参阅 composer.json 文件。

安装

运行以下 composer 命令

$ composer require "zfcampus/zf-rest:~1.0-dev"

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

"require": {
    "zfcampus/zf-rest": "~1.0-dev"
}

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

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

return array(
    /* ... */
    'modules' => array(
        /* ... */
        'ZF\Rest',
    ),
    /* ... */
);

配置

用户配置

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

键：控制器服务名称

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

子键：collection_http_methods

在请求集合时允许的HTTP方法数组。

子键：entity_http_methods

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

子键：collection_name

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

子键：collection_query_whitelist（可选）

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

您可能希望白名单的查询字符串参数示例包括“排序”、“筛选”等。

子键：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 实例或其派生实例时使用。

子键：page_size_param（可选）

用于设置每条请求页面大小的查询字符串参数名称。默认情况下未设置；我们建议您有额外的逻辑来确保页面大小的上限，以防止对您的API进行拒绝服务攻击。

用户配置示例

'AddressBook\\V1\\Rest\\Contact\\Controller' => array(
    'listener' => 'AddressBook\\V1\\Rest\\Contact\\ContactResource',
    'route_name' => 'address-book.rest.contact',
    'route_identifier_name' => 'contact_id',
    'collection_name' => 'contact',
    'entity_http_methods' => array(
        0 => 'GET',
        1 => 'PATCH',
        2 => 'PUT',
        3 => 'DELETE',
    ),
    'collection_http_methods' => array(
        0 => 'GET',
        1 => 'POST',
    ),
    'collection_query_whitelist' => array(),
    '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 2应用程序中正常运行。

'service_manager' => array(
    'invokables' => array(
        'ZF\Rest\RestParametersListener' => 'ZF\Rest\Listener\RestParametersListener',
    ),
    'factories' => array(
        'ZF\Rest\OptionsListener' => 'ZF\Rest\Factory\OptionsListenerFactory',
    ),
),

'controllers' => array(
    'abstract_factories' => array(
        'ZF\Rest\Factory\RestControllerFactory'
    )
),

'view_manager' => array(
    // 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实体或集合发起请求，它将返回一个405 Method not allowed响应，并在Allow头部中填充指示哪些请求方法可用的信息。
• 对于OPTIONS请求，它将以200 OK响应和填充了Allow头部的信息进行响应，指示哪些请求方法可以使用。

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 = array()) - 由对资源集合的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服务都将使用此控制器（尽管是单独的实例），除非它们指定了controller_class选项。实例通过ZF\Rest\Factory\RestControllerFactory抽象工厂创建。

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