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
现在报错了，分析一下报错的原因，注意到 dingo 依赖了一个扩展包 dingo/blueprint 是用来生成接口文档的，依赖了 phpdocumentor/reflection-docblock 的 ^3.1 的版本，使用 composer info 等命令查看一下 phpdocumentor/reflection-docblock 现在的情况
所以 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。
发布配置文件：
$ php artisan vendor:publish --provider="Dingo\Api\Provider\LaravelServiceProvider"
使用
配置
发布完成了，要想开始使用这个扩展包，还需要进行一些相关的配置，这里有几个非常重要的配置，必须要了解：
- 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'));
}
.
.
.
使用 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');
});
});
统一错误信息
如果请求成功，也就是状态码是 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 的地址：
随便写个路由，抛出异常：
.
.
.
$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);
});
});
我们自己抛出一个异常，同时定义一个自定义的错误码，这时返回的状态码是 500，同时也增加了 code 信息。
代码版本控制
$ git add -A
$ git commit -m 'dingo/api'
关于 LearnKu
粤公网安备 44030502004330号