发布时间2019-06-20 10:08:18
18
0
0

状态码表

  • 200 OK - 对成功的 GET、PUT、PATCH 或 DELETE 操作进行响应。也可以被用在不创建新资源的 POST 操作上
  • 201 Created - 对创建新资源的 POST 操作进行响应。应该带着指向新资源地址的 Location 头
  • 202 Accepted - 服务器接受了请求,但是还未处理,响应中应该包含相应的指示信息,告诉客户端该去哪里查询关于本次请求的信息
  • 204 No Content - 对不会返回响应体的成功请求进行响应(比如 DELETE 请求)
  • 304 Not Modified - HTTP 缓存 header 生效的时候用
  • 400 Bad Request - 请求异常,比如请求中的 body 无法解析
  • 401 Unauthorized - 没有进行认证或者认证非法
  • 403 Forbidden - 服务器已经理解请求,但是拒绝执行它
  • 404 Not Found - 请求一个不存在的资源
  • 405 Method Not Allowed - 所请求的 HTTP 方法不允许当前认证用户访问
  • 410 Gone - 表示当前请求的资源不再可用。当调用老版本 API 的时候很有用
  • 415 Unsupported Media Type - 如果请求中的内容类型是错误的
  • 422 Unprocessable Entity - 用来表示校验错误
  • 429 Too Many Requests - 由于请求频次达到上限而被拒绝访问

Dingo 错误响应

//的错误响应,包含错误消息和状态码
return $this->response->error('404 not found',404);

//404 响应,等同于上述返回 404 状态码的错误响应
return $this->response->errorNotFound();

//401 响应,等同于 error('Bad Request',401);
return $this->response->errorBadRequest();

//403 Forbidden 响应,等同于 error('Forbidden',403)
return $this->response->errorForbidden();

//500 Internal Error,=> error('Internal Error',500)
return $this->response->errorInternal();

//401 Unauthorized 响应,等同于 error('Unauthorized',401);
return $this->response->errorUnauthorized();

//405 Method Not Aoolwed,比如在 get 路由上发起 POST 请求会报这个错误
return $this->response->errorMethodNotAllowed();

异常响应

在构建 API 的时候处理异常是一件痛苦的事,在 Dingo API 中,你不需要手动构建异常响应,只需要抛出一个继承自 Symfony\Component\HttpKernel\Exception\HttpException 的异常,Dingo API 就会自动为你处理这个响应。

状态码     异常
403     Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException
400     Symfony\Component\HttpKernel\Exception\BadRequestHttpException
409     Symfony\Component\HttpKernel\Exception\ConflictHttpException
410     Symfony\Component\HttpKernel\Exception\GoneHttpException
500     Symfony\Component\HttpKernel\Exception\HttpException
411     Symfony\Component\HttpKernel\Exception\LengthRequiredHttpException
405     Symfony\Component\HttpKernel\Exception\MethodNotAllowedHttpException
406     Symfony\Component\HttpKernel\Exception\NotAcceptableHttpException
404     Symfony\Component\HttpKernel\Exception\NotFoundHttpException
412     Symfony\Component\HttpKernel\Exception\PreconditionFailedHttpException
428     Symfony\Component\HttpKernel\Exception\PreconditionRequiredHttpException
503     Symfony\Component\HttpKernel\Exception\ServiceUnavailableHttpException
429     Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException
401     Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException
415     Symfony\Component\HttpKernel\Exception\UnsupportedMediaTypeHttpException

下面是一个示例,当我们尝试更新一条已经被别人更新过的记录时抛出一个 ConflictHttpException 异常:

$api->version('v1', function ($api) {
    $api->put('task/{id}', function ($id) {
        $task = \App\Task::find($id);

        if ($task->updated_at > app('request')->get('last_updated')) {
            throw new \Symfony\Component\HttpKernel\Exception\ConflictHttpException('Task was updated prior to your request.');
        }

        // No error, we can continue to update the user as per usual.
    });
});

Dingo API 会自动捕获抛出的异常并将其转化为 JSON 格式,响应的 HTTP 状态码也会相应更改以匹配这个异常,ConflictHttpException 对应的 HTTP 状态码是 409。

资源异常

资源异常,每个异常都会返回 422 状态码:

Dingo\Api\Exception\DeleteResourceFailedException
Dingo\Api\Exception\ResourceException
Dingo\Api\Exception\StoreResourceFailedException
Dingo\Api\Exception\UpdateResourceFailedException

这些异常的特殊之处在于你可以将创建、更新或者删除资源时遇到的验证错误传递到这些异常中。

下面我们就来看一个创建新用户验证失败抛出 StoreResourceFailedException 异常的例子:

$api->version('v1', function ($api) {
    $api->post('tasks', function () {
        $rules = [
            'text' => ['required', 'string'],
            'is_completed' => ['required', 'boolean']
        ];

        $payload = app('request')->only('text', 'is_completed');

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

        if ($validator->fails()) {
            throw new \Dingo\Api\Exception\StoreResourceFailedException('Could not create new task.', $validator->errors());
        }

        // Create user as per usual.
    });
});

Dingo API 会自动捕获抛出的异常并将其转化为 JSON 格式,响应的 HTTP 状态码也会更改为与异常相匹配的值,资源异常会返回 422 状态码以及如下 JSON 格式错误信息: 异常

自定义异常

除了 Dingo 内置支持的异常类之外,你可以创建自定义的 HTTP 异常,前提是它们继承自Symfony\Component\HttpKernel\Exception\HttpException 基类或者实现了Symfony\Component\HttpKernel\Exception\HttpExceptionInterface 接口。

如果你需要自定义异常返回的响应可以注册一个异常处理器(你可以在某个服务提供者如 AppServiceProvider 的 boot 方法中添加这段代码):

app(\Dingo\Api\Exception\Handler::class)->register(function (\Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException $exception) {
    return \Illuminate\Support\Facades\Response::make(['error' => 'Hey, what do you think you are doing!?'], 401);
});

现在如果认证失败(抛出 UnauthorizedHttpException 异常)就会返回如下 JSON 格式信息:

{
    "error": "Hey, what do you think you are doing!?"
}