安装

Dingo 能为Laravel提供一整套包括从路由，到认证的RESTful API开发工具

Dingoapi的安装命令

composer require dingo/api

有时候会有内存限制，同时内存不足，就可以使用临时提高内存命令

COMPOSRT MEMORY_LIMIT=-1

由于在laravel安装的插件都会放到vendor目录中，而且这个目录是对外不可见的，所以，需要使用命令将API的配置文件发布到config下

php artisan vendor:publish --provider="DingoApiProviderLaravelServiceProvider"

然后就会在config目录下生成一个API类

配置信息
可以通过 ·env 文件来自定义大部分配置
但是发现，好像并没有关于这个的配置，可以自己添加的
例如：添加一个前缀和子域

API_PREFIX=api

还可以使用域名的方式

API_DOMAIN=api.myapp.com

版本号

这个版本号是你的 API 的默认版本号，并且会在一些未提供版本号的情况下作为回调的默认值使用。在生成 API
文档时也会使用这个版本号作为默认值

API_VERSION=v1

名称

你的 API 的名称只会在你使用 API Blueprint
命令生成文档的时候使用。使用此名称可以避免你每次生成文档的时候都必须手动定义名称

API_NAME=show

条件请求

『条件请求』默认为开启状态，这有利于客户端的缓存机制在可能的情况下缓存 API 请求

一般在生产阶段可以开启，但是在开发阶段就没有必要开启了

API_CONDITIONAL_REQUEST=false

严格模式

严格模式要求客户端发送 Accept 头，代替配置文件中配置的默认版本。这意味着你将不能通过浏览器直接访问你的 API

API_STRICT=false

响应格式
默认的响应格式是 JSON，并有一个 JSON 响应格式是被默认注册。

API_DEFAULT_FORMAT=json

创建端点

一个端点是一个路由的另一种说法。当讨论 API 的时候，很多人把访问的路由称作为一个端点

版本组

为了避免与你主要的项目路由冲突，dingo/api 将会使用其专属的路由实例。要创建端点，我们首先需要获得一个 API 路由的实例

$api = app('DingoApiRoutingRouter');

因为API是支持多个版本的，所以，可以定义一个版本分组

$api->version('v1', function ($api) {

});

然后，可以有多个版本分组

$api->version('v2', function ($api) {

});

还可以让一个分组支持多个版本

$api->version(['v1', 'v2'], function ($api) {

});

例如：v1版本里面的API有两个路由

$api = app('DingoApiRoutingRouter');
$api->version('v1', function ($api) {
    $api->get('test', [AppHttpControllersTestController::class, 'index']);
    $api->get('name',['as'=>'test.name','user'=>'AppHttpControllersTestController@name']);
});

在命令行中查看路由

php artisan api:routes

查到了路由，就可以运行了

命名路由和生成 URLs

在控制器中生成一个路由

dd(app('DingoApiRoutingUrlGenerator')->version('v1')->route('test.name'));

响应

一个可用的 API 简单来说就是通过接受请求并将易处理的响应返回给客户端，一般来说， API 有多种易处理的方式返回响应，例如 JSON

例如：

public function index()
    {
        return User::all();
    }

这个包将会自动的格式化响应为 JSON，并设置 Content-Type 头为 application/json

响应生成器

响应生成器提供了一个流畅的接口去方便的建立一个更定制化的响应

要利用响应生成器，你的控制器需要使用 DingoApiRoutingHelpers
为了每一个控制器都可以使用这个响应，可以在基类的controller中去引入

值得注意的是，有一些响应之间的状态码是不同的，下面会下出来

响应一个数组

有数据的响应码为200

public function index()
    {
        $user = User::findOrFail(1);
        return $this->response->array($user->toArray());
    }

无内容响应

无内容的响应码为204

return $this->response->noContent();

创建了资源的响应

空的资源响应码为201

return $this->response->created();

错误响应

有很多不同的方式创建错误响应，可以快速的生成一个错误响应
定义自定义消息和状态码的普通错误

// 一个自定义消息和状态码的普通错误。
        return $this->response->error('发生了一个错误', 404);

没有找到资源的错误

// 一个没有找到资源的错误，第一个参数可以传递自定义消息。
        return $this->response->errorNotFound('没有找到资源');

还有好多错误响应

// 一个自定义消息和状态码的普通错误。
return $this->response->error('This is an error.', 404);

// 一个没有找到资源的错误，第一个参数可以传递自定义消息。
return $this->response->errorNotFound();

// 一个 bad request 错误，第一个参数可以传递自定义消息。
return $this->response->errorBadRequest();

// 一个服务器拒绝错误，第一个参数可以传递自定义消息。
return $this->response->errorForbidden();

// 一个内部错误，第一个参数可以传递自定义消息。
return $this->response->errorInternal();

// 一个未认证错误，第一个参数可以传递自定义消息。
return $this->response->errorUnauthorized();

错误异常和错误响应

就是说可以把错误抛到一个继承了 SymfonyComponentHttpKernelExceptionHttpException 的异常，API 会自动的处理响应

例如：

throw new 
SymfonyComponentHttpKernelExceptionBadRequestHttpException('发生了请求错误.');

BadRequestHttpException这个包会自动的捕捉异常，然后转换为 JSON。响应的 HTTP 状态码也会根据异常而改变。如果你没有改变默认的错误格式， ConflictHttpException 异常将默认返回的结果为，HTTP
409 状态码和响应的 JSON 表述

还有很多异常，可以在https://learnku.com/docs/dingo-api/2.0.0/Errors-And-Error-Responses/1447查看

资源异常

下面是通用的资源异常的列表，它们都会返回 HTTP 422 状态码

DingoApiExceptionDeleteResourceFailedException
DingoApiExceptionResourceException
DingoApiExceptionStoreResourceFailedException
DingoApiExceptionUpdateResourceFailedException

这些异常是特殊的，因为它们允许你传递任何验证错误，当你尝试去创建、更新或者删除资源的时候。

举一个例子，当你尝试验证新用户的创建时遇到错误时，你可能会抛出 StoreResourceFailedException
例如：

$rules = [
            'username' => ['required', 'alpha'],
            'password' => ['required', 'min:7']
        ];

        $payload = app('request')->only('username', 'password');

        $validator = app('validator')->make($payload, $rules);

        if ($validator->fails()) {
            throw new DingoApiExceptionStoreResourceFailedException('注册异常', $validator->errors());
        }

在发生验证错误时，就会抛出所有异常

Transformers

Transformers 允许你便捷地、始终如一地将对象转换为一个数组。通过使用一个 transformer 你可以对整数和布尔值，包括分页结果和嵌套关系进行类型转换

简单点来说，就是 transformer 是一个类，它会获取原始数据并将返回一个格式化之后的标准数组

使用 Transformers
使用响应生成器来使用Transformers

响应数组 --item

这是没有使用Transformers格式化前的数据

来使用Transformers后
首先，创建一个appTransformersUserTransformer.php类

public function transform(User $user)
    {
        return [
            'id' => $user->id,
            'name' => $user->name,
            'email' => $user->email
        ];
    }

然后，

 $user = User::find(1);
 return $this->response->item($user, new UserTransformer);

这种方式是最常见的

响应集合–collection

还是和响应数组一样去使用，只不过响应集合是响应多个数据

 public function index()
    {
        $user = User::all();
        return $this->response->collection($user, new UserTransformer);
    }

分页响应 --paginator

$user = User::paginate(1);
        return $this->response->paginator($user, new UserTransformer);

分页响应会带上和分类相关的数据

添加额外的头信息

如果已经使用了Transformer，那么就可以在后面使用添加额外的头信息

return $this->response->item($user, new UserTransformer)->withHeader('X-Foo', 'Bar');

添加 Meta 信息

使用了Transformer后还可以去添加meta元数据，

return $this->response->item($user, new UserTransformer)->addMeta('foo', 'bar');

还可以设置元数据数组，而不是链接多个方法调用

return $this->response->item($user, new UserTransformer)->setMeta($meta);

设置响应状态码

return $this->response->paginator($user, new UserTransformer)