Menu

2.2. 配置信息

大部分的配置信息都是预先配置好了的,为的是让你能快速上手你的 API 项目。你可以通过 ·env 文件来自定义大部分配置。但是,有一些配置微调需要你发布配置文件(Laravel)或者在 bootstrap/app.php 文件中配置 (Lumen)。你也可以使用 AppServiceProvider 中的 boot 方法来做设置。

重要: 如果你正在使用 Laravel 5 你必须发布配置文件或者是使用服务提供者,不能使用 bootstrap/app.php 文件,这种方式是 Lumen 框架专属的。

如果你正在使用 Laravel 你可以使用下面的 Artisan 命令来发布配置文件:

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

Standards Tree 标准树

这有三个不同的树: xprsvnd。你使用的标准树需要取决于你开发的项目

  • 未注册的树(x)主要表示本地和私有环境
  • 私有树(prs)主要表示没有商业发布的项目
  • 供应商树(vnd)主要表示公开发布的项目

子类型使用私有和供应商树在技术上意味着在 IANA 上注册,但是并不强制要求。

最后,如果你不确定该如何选择,x 树或者说未注册树都是安全的。

你可以配置在.env文件中。

API_STANDARDS_TREE=vnd

子类型

子类型通常是应用程序或项目的短名称,都是小写的。

你可以在你的 .env 文件中配置这个。

API_SUBTYPE=myapp

前缀和子域

如果你曾经使用过 API 你就会知道大多数服务都来自子域或前缀。前缀或子域是必须的,但只需要一个。请避免使用版本号作为你的前缀或子域,因为版本控制是通过 header 头 Accept 处理的。

你可以在你的 .env 文件中配置这个。

API_PREFIX=api

当然你也可以使用域名。

API_DOMAIN=api.myapp.com

版本号

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

你可以在你的 .env 文件中这么配置它。

API_VERSION=v1

名称

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

你可以在你的 .env 文件中这么配置它。

API_NAME=My API

你可能需要把它用引号包起来。

API_NAME="My API"

条件请求

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

你可以在你的 .env 文件中将其配置为关闭:

API_CONDITIONAL_REQUEST=false

严格模式

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

如果开启严格模式,发送非法的 Acceept 标头会抛出一个未处理的异常 Symfony\Component\HttpKernel\Exception\BadRequestHttpException ,你需要自己处理这个异常。

你可以在你的 .env 文件中配置。

API_STRICT=false

认证服务

默认的只有 basic 认证是开启的。在后面的章节中会有详细的介绍。

更多复杂的配置你需要配置在一个 service provider 或者启动文件中。

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

访问节流

默认情况下『访问节流』是关闭的。你可以注册你自定义的阀门,或者使用已经存在的认证的和非认证的阀门。

更多复杂的配置你需要配置在一个 service provider 或者启动文件中。

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

响应转换

Fractal 是默认的转换规则。

你可以在 .env 文件中进行配置,可你还是需要在服务提供器或者 bootstrap 文件中进行更加复杂的配置。

$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);
});

响应格式

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

你可以在 .env 文件中配置默认的响应格式。更进一步的响应格式配置需要在一个 published 的配置文件,服务提供器,或是 bootstrap 文件中。

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

错误格式

当包遇到错误时,它会尝试生成一个通用的错误响应,而不是将异常转储给用户。 它使用的错误格式可以根据自己的喜好进行配置。

您必须在已发布的配置文件或引导程序文件中对其进行配置。

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

调试模式

该包处理的通用错误包括一个 debug 键,当启用这个键时,将会填充堆栈跟踪详细信息。

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

API_DEBUG=true

本文章首发在 Laravel China 社区
上一篇 下一篇
讨论数量: 0
发起讨论


暂无话题~
刻意练习,每日精进。
15
点赞
5000
浏览
0
讨论
译者