2.2. 配置信息

优质

小牛编辑

138浏览

2023-12-01

大部分的配置信息都是预先配置好了的，为的是让你能快速上手你的 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 标准树

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

未注册的树（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