050. Api 开发工具包 —— dingo/api(基础安装)

Api 开发工具包 —— dingo/api(基础安装)

dingo/api 是一个 Lumen 和 Laravel 都可用的 RestFul 工具包,帮助我们快速的开始构建 RestFul Api,在我看来,以下几个功能为 API 的开发带来的很大的方便:

  • 通过 HTTP Accept 头来切换 API 版本;
  • 可以快速配置 jwt-auth 完成用户认证;
  • 很好的整合了 league/fractal 做数据层转换,同时解决了预加载的问题;
  • 捕获错误和异常,以一个统一的格式返回;

这节课我们在一个 5.5 的全新项目中,完成基础的安装以及配置,快速的了解一下这个扩展包。更加深入的内容,例如配合 jwt-auth 以及 fractal 会在后面的课程中继续讲解。

安装

$ composer require dingo/api:^2.0.0-alpha2

file

现在报错了,分析一下报错的原因,注意到 dingo 依赖了一个扩展包 dingo/blueprint 是用来生成接口文档的,依赖了 phpdocumentor/reflection-docblock^3.1 的版本,使用 composer info 等命令查看一下 phpdocumentor/reflection-docblock 现在的情况

file

所以 phpunit 也依赖了 phpdocumentor/reflection-docblock ,不过现在安装了 4.* 的版本,这样两个版本就冲突了,所以问题出在了 dingo/blueprint 这个扩展包的依赖上其实 dingo/blueprint 已经在开发版本中解决了这个问题,但是还没有发布一个新版本,所以我们可以修改一下 composer.json 当存在版本冲突时,允许使用 dev 版本的依赖。

composer.json

.
.
.
    "config": {
        "preferred-install": "dist",
        "sort-packages": true,
        "optimize-autoloader": true
    },
    "minimum-stability" : "dev",
    "prefer-stable" : true
.
.
.

增加了两句:

  • "minimum-stability" : "dev" ——设定的最低稳定性的版本为 dev ,也就是可以依赖开发版本的扩展包;
  • "prefer-stable" : true —— Composer 还是优先使用更稳定的包版本。

这样设置后,有限使用稳定版本的依赖,但是当有冲突存在时,允许使用 dev 版本。这样最后安装时,就会安装 dev-master 版本的 dingo/blueprint

file

发布配置文件:

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

file

使用

配置

发布完成了,要想开始使用这个扩展包,还需要进行一些相关的配置,这里有几个非常重要的配置,必须要了解:

  • API_STANDARDS_TREE ——API 接口性质,三个值可选;
    • x —— 本地开发的或私有环境的;
    • prs —— 未对外发布的,提供给公司 APP,单页应用,桌面应用等;
    • vnd —— 对外发布的,开放给所有用户。
  • API_SUBTYPE —— 项目的简称;
  • API_PREFIX —— 与 API_DOMAIN 二选一,路由的前缀,例如设置为 api,接口路由为 www.larabbs.com/api
  • API_DOMAIN ——与 API_PREFIX 二选一,路由域名,例如 api.larabbs.com
  • API_VERSION——接口版本;
  • API_DEBUG—— Debug 模式,输出完整的 Debug 信息。

可以方便的配置到 .env 文件中,最后我们会配置成如下这样:

.env

.
.
.
# dingo
API_STANDARDS_TREE=prs
API_SUBTYPE=package
API_PREFIX=api
API_VERSION=v1
API_DEBUG=true

这几个配置非常的重要, API 版本的切换会利用到这些配置,不配置是会报错的。

添加接口

现在就可以添加一下接口了,需要注意的是,我们要想使用 dingo/api 那么就必须让它接管整个 api 的路由,也就是需要使用 dingo 提供的方式来注册路由:

routes/api.php

.
.
.
$api = app('Dingo\Api\Routing\Router');

$api->version('v1', function($api) {
    $api->get('version', function() {
        return response('this is version v1');
    });
});

$api 同我们使用的 Route 的使用方法一致,group,middleware,namespace,你平时怎么用现在也怎么用,只是换了一个对象而已,唯一增加的方法是 version ,用于定义一个 API 的版本,上面我们定义了一个 v1 的版本。

这时候需要明确一件事,因为路由交给 dingo 了,默认的 RouteServiceProvider 中的配置就不会起作用了,这段代码的作用只是告诉框架需要加载一个路由文件 api.php,其他关于中间件,命名空间,prefix 的设置都不起作用。这也就意味着当你需要用到某些东西的时候,需要去路由中再注册一遍。

app/Providers/RouteServiceProvider.php

.
.
.
    protected function mapApiRoutes()
    {
        Route::prefix('api')
             ->middleware('api')
             ->namespace($this->namespace)
             ->group(base_path('routes/api.php'));
    }
.
.
.

file

使用 PostMan 访问一下 package.test/api/version ,所有的接口必须增加 api 的前缀,配置中默认当前是 v1 版本,所以会直接访问到 v1 中的 verison 接口。

切换版本

想要切换版本需要增加一个 Accept 的头,格式是 Accept: application/prs.package.v2+json

routes/api.php

.
.
.
$api->version('v2', function($api) {
    $api->get('version', function() {
        return response('this is version v2');
    });
});

file

统一错误信息

如果请求成功,也就是状态码是 200 系列,那么接口应该返回数据,如果是 400 或 500 有报错,dingo 会帮助我们统一错误信息,可以看一下配置:

config/api.php

.
.
.
    'errorFormat' => [
        'message' => ':message',
        'errors' => ':errors',
        'code' => ':code',
        'status_code' => ':status_code',
        'debug' => ':debug',
    ],
.
.
.
  • message —— 错误信息;
  • errors ——通过表单验证类验证请求出现错误时的信息;
  • code——异常的错误码;
  • status_code——状态码;
  • debug ——具体的 debug 信息。

随便访问一个 404 的地址:

file

随便写个路由,抛出异常:

.
.
.
$api->version('v2', function($api) {
    $api->get('version', function() {
        return response('this is version v2');
    });

    $api->get('exception', function() {
        throw new Exception('test exception', 1001);
    });
});

file

我们自己抛出一个异常,同时定义一个自定义的错误码,这时返回的状态码是 500,同时也增加了 code 信息。

代码版本控制

$ git add -A
$ git commit -m 'dingo/api'

本文章首发在 LearnKu.com 网站上。

上一篇 下一篇
《L01 基础入门》
我们将带你从零开发一个项目并部署到线上,本课程教授 Web 开发中专业、实用的技能,如 Git 工作流、Laravel Mix 前端工作流等。
《L03 构架 API 服务器》
你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程,JWT 概念及使用 和 API 开发相关的进阶知识。
贡献者:2