README

API 管理器

A simple API response formatter and handler for Laravel. Beautify and unify your responses with the least effort possible.

安装

通过 composer

{
     "require": {
         "vinelab/api-manager": "*"
     }
 }

将服务提供者添加到 app/config/app.php 文件中的 providers 数组

'providers' => array(
    ...
    'Vinelab\Api\ApiServiceProvider',

),

配置

发布包配置文件

php artisan config:publish vinelab/api-manager

现在位于 app/config/packages/vinelab/api-manager/api.php

命名空间

映射器是您指定映射器基本命名空间的地方（有关映射器的更多信息，请参阅映射器术语）

'mappers' => 'Lib\Api\Mappers\\',

您可以使用 Api::setMapperNamespace('\New\Namespace\\'); 来覆盖配置的命名空间。

限制

限制是您设置任何端点请求返回的最大数据量。

'limit' => '50',

设置

此包期望为要通过 API 返回的每个模型都拥有 映射器类。

映射器

映射器是一个将任何受支持的数据类型（例如模型）转换为具有您选择的属性的适合 API 响应的数组的类。

默认情况下，Api Manager 将调用给定的映射器上的 map 方法，除非通过传递 [$mapper, $method] 来指示不同，其中 $mapper 是类的实际实例或字符串。

示例

映射器类

class PostMapper {

    public function map(Post $post)
    {
        return [
            'id'        => (int) $post->id,
            'title'     => $post->title,
            'body'      => $post->body,
            'published' => (boolean) $post->published
        ];
    }
}

映射器使用

$post = Post::create([
    'title'     => 'Some Title',
    'body'      => 'Things and spaces',
    'published' => true
]);

$mapper = new PostMapper;
return $mapper->map($post);

映射器示例

以下是实现名为 PostsMapper 的映射器的示例

数组映射

<?php namespace Lib\Api\Mappers;

class PostsMapper implements PostsInterface {

    public function map(array $data)
    {
        return [
            'id'     => (int) $data['id'],
            'title'  => $data['title'],
            'text'   => $data['text'],
            'active' => (boolean) $data['active']
        ];
    }

}

模型映射

<?php namespace Lib\Api\Mappers;

class PostsMapper implements PostsInterface {

    public function map(Post $post)
    {
        return [
            'id'     => (int) $post->id,
            'title'  => $post->title,
            'text'   => $post->text,
            'active' => (boolean) $post->active
        ];
    }

}

使用和响应

从您的控制器中，您可以使用包含这些两个重要功能 respond 和 error 的 Api Facade 类。

数据类型

Api::respond($mapper, $data) 接受以下数据类型用于 $data

数组
Eloquent 模型
Illuminate\Pagination\Paginator，这是调用 paginate() 的结果
Illuminate\Database\Eloquent\Collection 模型对象集合，这是在获取多个记录时，例如 get()

此包返回的响应遵循 json api 的约定以及由书籍 Build APIs You Won't Hate 推荐的标准。

Api::respond($mapper, $data, $total = null, $page = null, $status = 200, $headers = [], $options = 0)

当 $total 和 $page 为 null 时，它们将不会包含在响应中。

分页

return Api::respond('PostsMapper', Post::paginate(3));

响应

{
    "status": 200,
    "total": 3,
    "page": 1,
    "data": [
        {
            "id": 1,
            "title": "Ex veniam et voluptatibus est. Enim provident tempore reiciendis qui qui. Aut soluta ipsum voluptatem repellat quod explicabo.",
            "text": "Voluptatem dolorum eum sequi maiores quo facere dolor. Molestiae corrupti rem quo sed. Quibusdam ut voluptate consequatur.",
            "active": false
        },
        {
            "id": 2,
            "title": "Qui aperiam aut voluptatem repellat est. Minima dolor qui rem sint cum debitis. Ab quia neque quasi laboriosam.",
            "text": "Ea et quae facere fugiat non est eveniet. Veniam quas doloremque repellat esse nihil qui qui voluptas. Laboriosam voluptate rerum et perferendis adipisci deleniti. Quae quam nisi facilis quia dolore.",
            "active": false
        },
        {
            "id": 3,
            "title": "Aspernatur voluptas id ratione rerum et quis. Repellendus dolorem nihil sint maxime. Dolorum ex dolorum sit est recusandae.",
            "text": "Sit voluptatem voluptatem corporis. Excepturi eligendi quia maiores nesciunt quia. Ipsum voluptatem autem aspernatur pariatur.",
            "active": false
        }
    ]
}

模型

return Api::respond('PostsMapper',Post::first());

响应

{
    "status": 200,
    "data": {
        "id": 1,
        "title": "Ex veniam et voluptatibus est. Enim provident tempore reiciendis qui qui. Aut soluta ipsum voluptatem repellat quod explicabo.",
        "text": "Voluptatem dolorum eum sequi maiores quo facere dolor. Molestiae corrupti rem quo sed. Quibusdam ut voluptate consequatur.",
        "active": false
    }
}

集合

$data = Post::where('active', '0')->get();
$total = $data->count();
$page = 2;

return Api::respond('PostsMapper', $data, $total, $page);

响应

{
    "status": 200,
    "total": 15,
    "page": 2,
    "data": [
        {
            "id": 1,
            "title": "Ex veniam et voluptatibus est. Enim provident tempore reiciendis qui qui. Aut soluta ipsum voluptatem repellat quod explicabo.",
            "text": "Voluptatem dolorum eum sequi maiores quo facere dolor. Molestiae corrupti rem quo sed. Quibusdam ut voluptate consequatur.",
            "active": false
        },
        {
            "id": 2,
            "title": "Qui aperiam aut voluptatem repellat est. Minima dolor qui rem sint cum debitis. Ab quia neque quasi laboriosam.",
            "text": "Ea et quae facere fugiat non est eveniet. Veniam quas doloremque repellat esse nihil qui qui voluptas. Laboriosam voluptate rerum et perferendis adipisci deleniti. Quae quam nisi facilis quia dolore.",
            "active": false
        },
        {
            "id": 14,
            "title": "Illo quia minima ut est praesentium assumenda explicabo. Facilis ipsam minus et rerum perspiciatis illo. Voluptas distinctio et possimus non iste doloremque dolor.",
            "text": "Corporis quos dignissimos voluptas tempora quo perspiciatis nesciunt. Corrupti soluta ad eos tenetur debitis. Aut quia atque molestiae delectus et.",
            "active": false
        },
        {
            "id": 15,
            "title": "Labore sequi molestiae quisquam nostrum. Esse nisi in non aut praesentium occaecati. Suscipit exercitationem necessitatibus eos quis nulla. Necessitatibus nisi nostrum non ducimus aspernatur quod.",
            "text": "Officiis odio cumque est expedita. Qui atque veniam eos saepe. Architecto corrupti quis quia modi voluptatem.",
            "active": false
        }
    ]
}

请求数据限制

API 的一部分是您想要对请求您的 API 的客户端实施的限制。为了使其更简单和集中，您可以使用 Api 来设置和获取限制值，并配置一个上限（最大）值，该值不能被请求客户端超过。

此值从 limit 查询参数中读取。例如 http://api.com/?limit=20

要获取请求的限制，请使用 Api::limit()，它将自动验证请求的限制是否超过您指定的最大限制值。

要覆盖代码中的限制值（配置的限制），您可以使用 Api::setLimit(100)。

错误处理

对于错误响应，请使用 Api::error 函数。

Api::error($exception, $code = 0, $status = 500, $headers = [], $options = 0);

$exception 可以是 字符串（异常消息）或继承自 Exception 或 RuntimeException 的任何继承类

使用异常的错误

try {
    throw WhateverCustomException('You deserve it, this is your fault.', 1001);
} catch (WhateverCustomException $e)
{
	return Api::error($e, $e->getCode(), 401);
}

401 将是 HTTP 响应代码

1001 是错误代码（特定于 API）

响应

{
    "status": 401,
    "error": {
        "code": 1001,
        "message": "You deserve it, this is your fault."
    }
}

使用消息的错误

return Api::error('Something is wrong!!!', 1000, 505);

响应

{
    "status": 505,
    "error": {
        "code": 1000,
        "message": "Something is wrong!!!"
    }
}

贡献

请参阅CONTRIBUTING以获取详细信息。

许可证

本软件包是开源软件，使用MIT许可证授权。

vinelab / api-manager

维护者

详细信息