README

仓库弃用时间：2019-12-31

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

简介

此模块提供 API-Problem 格式的数据结构和渲染。

HTTP API 的问题详情，用于报告 API 问题。

要求

请参阅 composer.json 文件。

安装

运行以下 composer 命令

$ composer require zfcampus/zf-api-problem

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

"require": {
    "zfcampus/zf-api-problem": "^1.2"
}

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

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

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

zf-component-installer

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

配置

用户配置

此模块用户配置的最高级配置键为 zf-api-problem。

键：accept_filters

一个数组，包含匹配 Accept 头媒体类型的值，当匹配时，将导致 ApiProblemListener 处理 MvcEvent::EVENT_RENDER_ERROR 事件。

键：render_error_controllers

一个数组，包含匹配 MVC RouteMatch 中的 controller 参数的控制器服务名称，如果匹配，将导致 ApiProblemListener 处理 MvcEvent::EVENT_RENDER_ERROR 事件。

系统配置

以下配置提供在 config/module.config.php 中，以启用模块功能

'service_manager' => [
    'aliases'   => [
        'ZF\ApiProblem\ApiProblemListener'  => 'ZF\ApiProblem\Listener\ApiProblemListener',
        'ZF\ApiProblem\RenderErrorListener' => 'ZF\ApiProblem\Listener\RenderErrorListener',
        'ZF\ApiProblem\ApiProblemRenderer'  => 'ZF\ApiProblem\View\ApiProblemRenderer',
        'ZF\ApiProblem\ApiProblemStrategy'  => 'ZF\ApiProblem\View\ApiProblemStrategy',
    ],
    'factories' => [
        'ZF\ApiProblem\Listener\ApiProblemListener'             => 'ZF\ApiProblem\Factory\ApiProblemListenerFactory',
        'ZF\ApiProblem\Listener\RenderErrorListener'            => 'ZF\ApiProblem\Factory\RenderErrorListenerFactory',
        'ZF\ApiProblem\Listener\SendApiProblemResponseListener' => 'ZF\ApiProblem\Factory\SendApiProblemResponseListenerFactory',
        'ZF\ApiProblem\View\ApiProblemRenderer'                 => 'ZF\ApiProblem\Factory\ApiProblemRendererFactory',
        'ZF\ApiProblem\View\ApiProblemStrategy'                 => 'ZF\ApiProblem\Factory\ApiProblemStrategyFactory',
    ],
],
'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\ApiProblem\Listener\ApiProblemListener

ApiProblemListener 会附加到 MVC 生命周期的三个事件中

MvcEvent::EVENT_DISPATCH，作为一个具有优先级 100 的共享监听器附加到 Zend\Stdlib\DispatchableInterface。
MvcEvent::EVENT_DISPATCH_ERROR，具有优先级 100。
MvcEvent::EVENT_RENDER，具有优先级 1000。

如果当前的 Accept 媒体类型与配置的 API-Problem 媒体类型不匹配（默认情况下，这些是 application/json 和 application/*+json），则此监听器将返回而不采取任何操作。

当此监听器采取行动时，其目的有三

在调度之前，将咨询 render_error_controllers 配置值，以确定是否应该附加 ZF\ApiProblem\Listener\RenderErrorListener；有关更多信息，请参阅RenderErrorListener。
在调度之后，检测控制器返回的响应类型；如果是 ApiProblem 模型，则继续不做任何操作。如果在调度期间抛出异常，则将响应转换为包含异常信息的 API-Problem 响应。
如果发生调度错误，并且 Accept 类型在为 API-Problems 定义的集合中，则尝试将调度异常转换为 API-Problem 响应。

`ZF\ApiProblem\Listener\RenderErrorListener`

此监听器在优先级 100 下附加到 MvcEvent::EVENT_RENDER_ERROR。此监听器由 ZF\ApiProblem\Listener\ApiProblemListener 条件性地附加到需要 API Problem 响应的控制器。具有 100 的优先级确保在此事件上在此监听器之前运行默认的 ZF2 监听器。在它确实运行的情况下，它将异常转换为 API-问题响应。

`ZF\ApiProblem\Listener\SendApiProblemResponseListener`

此监听器在优先级 -500 下附加到 SendResponseEvent::EVENT_SEND_RESPONSE。此监听器的主要目的是，在检测到 API-Problem 响应时，发送适当的头信息和问题详细信息作为内容主体。如果 view_manager 的 display_exceptions 设置启用，则监听器将确定 API-Problem 是否表示应用程序异常，如果是这样，则将异常跟踪作为序列化响应的一部分注入。

ZF2 服务

事件服务

ZF\ApiProblem\Listener\ApiProblemListener
ZF\ApiProblem\Listener\RenderErrorListener
ZF\ApiProblem\Listener\SendApiProblemResponseListener

视图服务

`ZF\ApiProblem\View\ApiProblemRenderer`

此服务扩展了来自 ZF2 MVC 层的 JsonRenderer 服务。其主要责任是装饰 JSON 渲染，并具有可选输出堆栈跟踪的能力。

`ZF\ApiProblem\View\ApiProblemStrategy`

此服务是一种视图策略，它检测到 ZF\ApiProblem\View\ApiProblemModel；当检测到时，它选择 ApiProblemRender，并将响应注入带有包含 application/problem+json 媒体类型的 Content-Type 头信息。这类似于 Zend Framework 2 的 JsonStrategy。

模型

`ZF\ApiProblem\ApiProblem`

ZF\ApiProblem\ApiProblem 的实例用于建模遇到的问题类型。通常，ApiProblem 的实例会被包裹在 ApiProblemResponse 中。大部分信息都可以传递给构造函数。

class ApiProblem
{
    public function __construct(
        $status,
        $detail,
        $type = null,
        $title = null,
        array $additional = []
    ) {
        /* ... */
    }
}

例如：

new ApiProblem(404, 'Entity not found');

// or

new ApiProblem(424, $exceptionInstance);

`ZF\ApiProblem\ApiProblemResponse`

ZF\ApiProblem\ApiProblemResponse 的实例可以从任何控制器服务或 ZF2 MVC 事件中返回，以中断 MVC 生命周期并立即返回响应。在这种情况下，响应将被转换为 API-Problem 的正确 JSON 结构，并且 Content-Type 头将被设置为 application/problem+json 媒体类型。

例如：

use Zend\Mvc\Controller\AbstractActionController;
use ZF\ApiProblem\ApiProblem;
use ZF\ApiProblem\ApiProblemResponse;

class MyController extends AbstractActionController
{
    /* ... */
    public function fetch($id)
    {
        $entity = $this->model->fetch($id);
        if (! $entity) {
            return new ApiProblemResponse(new ApiProblem(404, 'Entity not found'));
        }
        return $entity;
    }
}

zfcampus / zf-api-problem

维护者

详细信息