README

Laravel API 构建器旨在提供一种快速、标准化的方式来创建 API。当您使用此包创建资源 API 时，您将获得标准的 CRUD 端点，并且足够灵活，可以适应您的业务逻辑需求。

安装

您可以通过 composer 安装此包

composer require coreproc/api-builder

使用方法

要开始使用 API 构建器，只需创建一个控制器，使其扩展 ApiBuilderController 类，然后定义有关资源的必要信息。以下是一个基本控制器示例

<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use App\Transformers\PostTransformer;
use CoreProc\ApiBuilder\Http\Controllers\ApiBuilderController;

class PostsController extends ApiBuilderController
{
    public static $model = Post::class;

    public static $transformer = PostTransformer::class;

    protected $allowedParams = [
        'user_id',
        'title',
        'short_description',
        'content',
        'published_at',
    ];
}

此控制器假设您有一个 Post 模型和 PostTransformer 转换器。如果您不了解转换器，可以在 这里 找到更多信息。

现在，为了使上述控制器可用，我们只需要在 routes/api.php 中定义路由。

Route::apiResource('posts', 'Api\PostsController');

一旦在路由中定义，您将获得以下端点

GET     /api/posts          Get a paginated list of the posts in your database
POST    /api/posts          Create a new Post entry
GET     /api/posts/{id}     Get the details of the specified Post resource
PUT     /api/posts/{id}     Update the Post resource
DEL     /api/posts/{id}     Delete the Post resource

查询/过滤

此包的一个主要优点是具有强大的查询/过滤功能，使 API 用户能够完全控制他们正在查找的内容。

受 GraphQL 启发，参数中添加操作数的方式相同。

例如，如果您想查询特定用户 ID 的所有帖子，您可以这样操作

GET /api/posts?user_id=1

但如果您想查询用户 ID 大于 5 的所有帖子（例如），您可以这样做

GET /api/posts?user_id_gt=5

对于控制器中定义的 $allowedParams 变量中的所有参数，都将应用此方法。如果您想使用此功能，则需要定义哪些参数可以通过查询传递。

以下是一个示例。如果您想获取标题包含“test”一词的帖子，您可以这样做

GET /api/posts?title_contains=test

以下是您可以使用的完整操作数列表

not                 Not equal
lt                  Less than
lte                 Less than or equal to
gt                  Greater than
gte                 Greater than or equal to
contains            Uses LIKE with wildcard on both sides of the query value
not_contains        Inverse of contains
starts_with         Uses LIKE with wildcard at the end of the query value
not_starts_with     Inverse of starts_with
ends_with           Uses LIKE with wildcard at the beginning of the query value
not_ends_with       Inverse of ends_with
in                  Where IN given a set of values. This must be passed as an array.
not_in              Where NOT IN given a set of values. This must be pased as an array.

现在，如果您想在默认情况下通过索引资源时修改/应用过滤器，可以通过在控制器中覆盖 indexQuery() 方法来实现

class PostsController extends ApiBuilderController {

    ...
    
    protected static function indexQuery(Request $request, Builder $query)
    {
        return $query->where('user_id', $request->user()->id);
    }

通过以上操作，索引资源将仅返回当前登录用户的用户 ID 的结果。您还可以在此处执行其他逻辑。

日期

允许查询/过滤日期，并且可以使用操作数。但是，您必须定义日期字段

class PostsController extends ApiBuilderController {

    ...
    
    protected $dates = [
        'published_at',
    ];

定义后，您可以传递任何 Carbon::parse() 可以解析的值。例如

GET /api/posts?published_at_gte=Mar1

排序

在索引资源时也可以进行排序。以下是一个示例

GET /api/posts?sort=published_at

这将按发布日期升序对所有帖子进行排序。要更改排序方向，请像这样传递 desc 值

GET /api/posts?sort=published_at,desc

请注意，此包将保留 sort 关键字用于其排序功能。（路线图：使其可配置）

空值

要传递空值，此包将保留 null 值用于查询值。所有传递的 null 字符串都将转换为后端中的 NULL 值。以下是如何使用它的示例

GET /api/posts?published_at_not=null

限制结果

您还可以通过传递 limit 参数来限制结果。

GET /api/posts?limit=1

分页

默认情况下，资源的索引返回分页结果。每页默认结果数量为 15。（路线图：使其可配置）

要增加每页的结果数量，您可以传递 per_page 参数

GET /api/posts?per_page=100

可以通过定义页码来浏览页面

GET /api/posts?page=2

创建资源

// TODO

创建规则

// TODO

查看资源

// TODO

更新资源

// TODO

更新规则

// TODO

删除资源

// TODO

授权

// TODO

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全

如果您发现任何与安全相关的问题，请发送电子邮件至chris.bautista@coreproc.ph，而不是使用问题跟踪器。

关于 CoreProc

CoreProc 是一家软件开发公司，为初创公司、数字/广告机构和企业提供软件开发服务。

在我们的网站上了解更多关于我们的信息。

鸣谢

• Chris Bautista
• 所有贡献者

许可证

MIT 许可证（MIT）。有关更多信息，请参阅许可证文件。