使用 Dingo API 扩展包快速构建 Laravel RESTful API（一） —— 安装配置篇

注：本系列教程适用于 Laravel/Lumen 5.5+ 版本。

Dingo API 提供了一整套 工具 以便帮助开发者快速构建遵循 REST 规范的 API 接口。这些工具包括：

• 内容协商
• 多种认证适配器
• API 版本
• 访问频率限制
• 响应数据格式转化
• 错误及异常处理
• 内部请求
• 生成 API 文档

1、安装

安装该扩展包之前需要保证已经安装以下程序：

• Laravel/Lumen 5.5+
• PHP 7.1+

然后在 Laravel/Lumen 项目根目录通过如下 Composer 命令安装扩展包：

composer require dingo/api:^2

安装完成后的操作取决于你使用的是哪个框架。

Laravel

Laravel 5.5+ 版本支持该扩展包的自动发现，所以无需注册对应服务器提供者，如果你想要自定义扩展包配置可以通过如下 Artisan 命令将其发布到 config 目录下：

php artisan vendor:publish --provider="Dingo\Api\Provider\LaravelServiceProvider"

上述命令会将 Dingo API 扩展包中的配置文件 api.php 发布到项目根目录下的 config 目录中。

Lumen

打开 bootstrap/app.php 注册需要的服务提供者：

$app->register(Dingo\Api\Provider\LumenServiceProvider::class);

门面

有两个门面可用来处理这个扩展包，你可以添加任意一个：

Dingo\Api\Facade\API
Dingo\Api\Facade\Route

2、配置

扩展包安装之后，基本上所有功能都已经预先配置好，所以不需要什么改动就可以开始构建 API 接口。你可以使用 .env 环境配置文件进行大部分配置，对于一些细小的地方需要发布配置文件（Laravel）进行微调或者在 bootstrap/app.php （Lumen）中配置，你还可以使用 AppServiceProvider 的 boot 方法进行运行时配置。

学院君注：在开始配置之前建议先速读一下 config/api.php 配置文件中的配置项，以便对 Dingo 配置有一个总体的认识。

标准树

标准树（Standard tree）是一个 HTTP 协议层面的术语，Web 资源的内容类型（即 MIME 类型，由 Content-Type 字段指定）都是通过 IANA （互联网号码分配局）注册的，MIME 类型一般分为类型和子类型，比如 text/html ， text 是类型， html 是子类型，为了保证注册流程的灵活性与效率，子类型被归进了一个树结构的分类中。树结构信息被放在了子类型名的最前面，以 . 与其它部分分隔。现在，常见的几种树如下所示：

• 标准树（Standards Tree）：标准树中的子类型名不需要树结构信息，如 application/json 、 image/png 、 text/css 、 text/html ，这些我们平时所见的 MIME 类型都是属于标准树。
• 厂商树（Vendor Tree）：子类型使用 vnd. 前缀 + 厂商名称 + 子类型名来标识，如 .deb 文件的 MIME 类型是 application/vnd.debian.binary-package ；
• 个人树（Personal or Vanity Tree）：个人树中包含试验性或者不会以商业形式公开的子类型，个人树中的子类型名的前缀是 prs. ；
• 非标准的以 x. 为前缀的树：以 x. 为第一前缀的子类型名仅能够在私人的、本地的环境中使用。此类型的子类型不能被注册，只能在相互间同意的各方中传输使用。

Dingo 借助了 HTTP 协议的标准树概念来解决 API 接口中内容协商和自定义 MIME 类型的版本控制，你可以基于自己所开发的项目使用不同的标准树，系统支持三个不同的树 —— x 、 prs 和 vnd ，它们各自的用途如下（和 MIME 类型的用途对应）：

x
prs
vnd

Dingo 默认使用的是未注册树 x ，你可以在 .env 文件中配置项目所使用的标准树：

API_STANDARDS_TREE=vnd

如果你不知道怎么用，使用默认值即可。

子类型

子类型（Subtype）通常是应用或项目的简称，或小写格式。和上面介绍的 MIME 的子类型一样，该配置项和标准树结合起来使用，可以在请求头中通过 Accept 字段与服务器进行内容协商，比如 application/x.SUBTYPE.v1+json ，该配置值默认为空，你也可以在 .env 中进行自定义配置：

API_SUBTYPE=myapp

前缀和子域名

如果你曾经开发过 API 应该知道大部分 API 都是以子域名（或某个域名前缀）形式提供服务，域名前缀或子域名是必须的，并且同时只有一个（即要么配置域名前缀，要么配置子域名），不要将版本号作为前缀或子域名，因为版本号通常通过 Accept 请求头进行处理。你可以在 .env 文件中配置域名前缀：

API_PREFIX=api

或子域名：

API_DOMAIN=api.myapp.com

版本

这里的版本指的是 API 的默认版本，可以在没有提供版本号的时候使用这个版本，或者作为生成 API 文档时的默认版本。

你可以在 .env 文件中配置它：

API_VERSION=v1

名字

API 的名字只有在使用 Dingo 提供的 API Blueprint 命令生成文档的时候才用到，这个名字作为 API 的默认名字以免生成文档时需要手动指定名字。

你可以在 .env 文件中配置它：

API_NAME="My API"

带条件的请求

由于缓存 API 请求的时候会使用客户端缓存功能，所以默认开启了带条件的请求，你可以在配置文件 .env 中配置该选项：

API_CONDITIONAL_REQUEST=false

Strict 模式

Strict 模式要求客户端发送 Accept 请求头而不是默认在配置文件中指定的版本，这意味着你不能通过 Web 浏览器访问 API。 如果 Strict 模式开启并且使用了无效的 Accept 头，API 会抛出一个 Symfony\Component\HttpKernel\Exception\BadRequestHttpException 异常。

你可以在 .env 中配置这个选项：

API_STRICT=false

认证提供者

Dingo 默认只开启了 basic 认证，如果要对认证进行更复杂的配置，需要在服务提供者（Laravel）或启动文件（Lumen）设置：

$app['Dingo\Api\Auth\Auth']->extend('oauth', function ($app) {
   return new Dingo\Api\Auth\Provider\JWT($app['Tymon\JWTAuth\JWTAuth']);
});

后面介绍 Dingo 中 API 认证实现的时候还会详细介绍这一块。

访问频率限制

默认访问频率限制是被禁用的，你可以注册自定义的带有频率限制的节流器或者使用已经存在的认证/取消认证节流器。

要进行更加复杂的配置，同样需要在服务提供者（Laravel）或启动文件（Lumen）中操作：

$app['Dingo\Api\Http\RateLimit\Handler']->extend(function ($app) {
    return new Dingo\Api\Http\RateLimit\Throttle\Authenticated;
});

响应转化器

Dingo 默认使用 Fractal 作为响应转化器：

'transformer' => env('API_TRANSFORMER', Dingo\Api\Transformer\Adapter\Fractal::class),

你可以在 .env 中配置，但如果要实现更加复杂的配置还是需要在服务提供者（Laravel）或启动文件（Lumen）中操作：

$app['Dingo\Api\Transformer\Factory']->setAdapter(function ($app) {
    $fractal = new League\Fractal\Manager;

    $fractal->setSerializer(new League\Fractal\Serializer\JsonApiSerializer);

    return new Dingo\Api\Transformer\Adapter\Fractal($fractal);
});

响应数据格式

Dingo 默认的响应数据格式是 JSON，你可以在配置文件 .env 中配置默认的响应数据格式：

API_DEFAULT_FORMAT=json

更加高级的格式配置需要发布配置文件到 config 目录或者在服务提供者（Laravel）及启动文件（Lumen）中操作：

Dingo\Api\Http\Response::addFormatter('json', new Dingo\Api\Http\Response\Format\Jsonp);

错误格式

如果 Dingo 遇到错误将会尝试生成错误响应而不是将异常抛给用户，错误格式可以进行自定义配置。该配置必须在 config 目录下对应的配置文件（Laravel）：

'errorFormat' => [
    'message' => ':message',
    'errors' => ':errors',
    'code' => ':code',
    'status_code' => ':status_code',
    'debug' => ':debug',
],

或启动文件（Lumen）中实现：

$app['Dingo\Api\Exception\Handler']->setErrorFormat([
    'error' => [
        'message' => ':message',
        'errors' => ':errors',
        'code' => ':code',
        'status_code' => ':status_code',
        'debug' => ':debug'
    ]
]);

调试模式

如果开启了调试模式的话，生成的错误信息会被 Dingo 放到 debug 键中，并与堆栈跟踪信息一起显示出来。

你可以在配置文件 .env 中配置是否开启：

API_DEBUG=true