laravel dingo/api 笔记
使用 Laravel 开发 API，参考了网上一些资料，laravel 默认已经支持了 API 开发，但是因为都没有了解过，打算尝试使用 Dingo API
github 地址：
https://github.com/dingo/api
laravel-china 中文文档：
https://laravel-china.org/docs/dingo-api/2.0.0
文档写的非常详细，翻译的也非常好，但是需要仔细品读，另外 Dingo API 中使用到了其他两个技术，也需要了解下。之前已经写过笔记了，可参考：
fractal - https://blog.csdn.net/beyond__devil/article/details/83870176
jwt-auth - https://blog.csdn.net/beyond__devil/article/details/83827075
这里简单挑几个重点写下：
1.安装
composer require dingo/api
发布配置
php artisan vendor:publish --provider="Dingo\Api\Provider\LaravelServiceProvider"
Facades
Dingo\Api\Facade\API
Dingo\Api\Facade\Route
2.配置信息
3.创建端点(在 API 中，路由一般叫做端点)
1)引用 Dingo API
$api = app('Dingo\Api\Routing\Router');
2)设置版本分组
// 单个分组
$api->version('v1', function($api){
})
// 多个分组
$api->version(['v1', 'v2'], function($api){
})
// 第二个参数，还可以传递一个 『属性数组』
$api->version(['v1', 'v2'], ['middleware' => 'foo'], function($api){
})
注意：
属性数组，是旧版的 Laravel，5.7 版本有些可能不支持
// 其他的和 laravel 的路由没有太大的区分(旧版，新版链式调用不支持)
$api->version('v1', function($api){
$api->group(['middleware' => 'bar'], function($api){
...
});
})
3)创建端点(之前大概看了点源码，忘记了，下面是之前笔记的)
group() - 路由分组
domain() - 子域名路由
namespace() - 命名空间
prefix() - 前缀
name() - 命名前缀，是 as 的别名
as() - 命名前缀
middle() - 中间件
where() - 参数的正则约束
/*
5.7 版本，可以使用这些方法，之前的版本，没有这些方法，使用的是:
group(['prefix' => '', 'namespace' => '', ...], function(){
});
*/
4)命名路由 & 生成路由
$api->get('users/{id}', ['as' => 'users.index', 'uses' => 'Api\V1\UserController@show']);
app('Dingo\Api\Routing\UrlGenerator')->version('v1')->route('users.index');
5)命令行中查看路由
php artisan api::routes
注意：
Laravel 5.7版本，routes/api.php 默认就具备中间件，我们需考虑使用 'Dingo API' 还是 'Laravel 系统默认'
app/Providers/RouteServiceProvider.php
Route::prefix('api')
->middleware('api')
->namespace($this->namespace)
->group(base_path('routes/api.php'));
注意：
如果采用 Ding API，我们可能得取消这里默认的 prefix、middleware、namespace
4.响应
响应生成器，需要使用 'Dingo\Api\Routing\Helpers' trait。我们的 API 控制器基本都要使用它，所以创建一个 『基类控制器』
php artisan make:controller Api/Controller
<?php
namespace App\Http\Controllers\Api;
use Illuminate\Http\Request;
use Dingo\Api\Routing\Helpers;
use App\Http\Controllers\Controller as BaseController;
class Controller extends BaseController
{
use Helpers;
}
关于响应生成器，文档写的很详细，上次可能看了下源码，总结了下，基本和文档一致。
参考源码：Dingo\Api\Http\Response\Factory
1)响应数组
$user = User::findOrFail($id);
$this->response->array($user->toArray()); // 估计只能是数组
// 查看源码：
// array 时，会响应 $parameters[0]
// 『new Response($parameters[0])』
2)响应一个元素
$user = User::findOrFail($id);
$this->response->item($user, new UserTransformer)
3)响应一个元素集合
$users = User::all();
$this->response->collection($user, new UserTransformer)
4)分页响应
$users = User::paginate(25);
$this->response->paginator($user, new UserTransformer)
5)无内容响应
$this->response->noContent();
6)创建了资源的响应
$this->response->created($location = null, $content = null);
location - 会在 header 添加 Location 头部
content - 响应内容
7)accepted() - 同 created() 一样，created() 返回 201，accepted() 返回 202
8)自定义错误内容和状态码
error($message, $statusCode)
9)其他调用 error() 的便捷方法
errorNotFound() - 404
errorBadRequest() - 400
errorForbidden() - 403
errorInternal() - 500
errorUnauthorized() - 401
errorMethodNotAllowed() - 405
10)添加额外的头信息
->withHeader('X-Foo', 'Bar')
11)添加 Meta 信息
->addMeta('foo', 'bar')->addMeta(xx, yy)
->setMeta($meta)
12)设置响应状态码
->setStatusCode(200)
事件：
返回响应之前，会转换响应，如果响应的变化有更多的控制，可以使用以下2个事件
ResponseWasMorphed
ResponseIsMorphing
5.异常处理
API 的开发过程中，对于异常，我们采用直接 throw，然后统一由 Dingo API 来捕获，统一处理
Symfony 内置的异常
Dingo API 内置的资源异常
自定义异常
继承 Symfony\Component\HttpKernel\Exception\HttpException
或
实现 Symfony\Component\HttpKernel\Exception\HttpExceptionInterface
自定义异常响应
app('Dingo\Api\Exception\Handler')->register(function (Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException $exception) {
return Response::make(['error' => 'Hey, 你这是要干嘛!?'], 401);
});
表单请求
定义基础的 API 表单请求类，验证失败，将抛出：
Dingo\Api\Exception\ValidationHttpException
Dingo API 默认的错误格式
'errorFormat' => [
'message' => ':message',
'errors' => ':errors',
'code' => ':code',
'status_code' => ':status_code',
'debug' => ':debug',
],
6.Transformers
使用 transformers 有 2 种方法：
1>为一个指定的类注册一个 transformer，直接从路由中返回这个类，并且通过 transformer 自动运行
app('Dingo\Api\Transformer\Factory')->register('User', 'UserTransformer');
2>使用响应生成器
Fractal
Fractal 是 Dingo API 使用的默认转换层
自动关系预加载
更多配置
定义嵌入关系时，要自定义 'include' 关键词和 '分隔符'，在 'service provider' 或 '启动文件' 中，手动实例化 'Dingo\Api\Transformer\Adapter\Fractal'
$this->app['Dingo\Api\Transformer\Factory']->setAdapter(function ($app) {
// 这里是 'include' 和 ','
return new Dingo\Api\Transformer\Adapter\Fractal(new League\Fractal\Manager, 'include', ',');
});
响应生成器的高级用法
响应生成器的 item()、collection() 和 paginator() 方法，接受额外参数，进一步自定义 Fractal
第三个参数 - 资源键
return $this->item($user, new UserTransformer, ['key' => 'user']);
第四个参数 - 回调函数
return $this->collection($users, new UserTransformer, [], function ($resource, $fractal) {
$resource->setCursor($cursor);
});
回调函数有 2 个参数：
第一个参数：
League\Fractal\Resource\Item 或 League\Fractal\Resource\Collection 实例
第二个参数：
League\Fractal\Manager 实例
不使用 '第三个参数'，也可以省略，直接传递 '第四个参数' 回调函数
自定义转换层
7.API 认证
配置身份验证提供者
内置 3 个身份验证提供者：
HTTP Basic - Dingo\Api\Auth\Provider\Basic
JSON Web Tokens - Dingo\Api\Auth\Provider\JWT
OAuth 2.0 - Dingo\Api\Auth\Provider\OAuth2
默认仅在配置文件中，启用 HTTP 基本身份验证
HTTP 基本验证
服务提供者使用 laravel 内置的默认基本身份验证。需要在 '配置文件' 或 '引导文件' 配置此服务提供者
app('Dingo\Api\Auth\Auth')->extend('basic', function ($app) {
return new Dingo\Api\Auth\Provider\Basic($app['auth'], 'email');
});
JSON Web Tokens(JWT)
使用 tymon/jwt-auth 包
在 '配置文件' 或 '引导文件' 中配置该服务提供者
config.php
'auth' => [
'jwt' => 'Dingo\Api\Auth\Provider\JWT',
],
app('Dingo\Api\Auth\Auth')->extend('jwt', function ($app) {
return new Dingo\Api\Auth\Provider\JWT($app['Tymon\JWTAuth\JWTAuth']);
});
OAuth 2.0
使用 league/oauth2-server 或 lucadegasperi/oauth2-server-laravel 包
需要配置 'provider server - 服务提供者' 或 'bootstrap - 引导文件'(包没有给我们提供 服务提供者，而 basic 和 jwt 都有默认的服务提供者，应该是这样...)
同时，应该还需要配置 config.php 的 auth
自定义身份验证
保护级别
可以使用 'api.auth' 中间件来验证
// 某个版本路由
$api->version(['middleware' => 'api.auth'], function(){});
// 路由组
$api->group( ['middleware' => 'api.auth'], function(){});
// 单个路由
$api->get('user', ['middleware' => 'api.auth'], function(){});
控制器中
$this->middleware('api.auth', ['only' => ['index']]);
只允许特定的身份验证提供者
$api->version(['middleware' => 'api.auth', 'providers' => ['basic', 'oauth']], function(){});
检索经过身份验证的用户
$user = app('Dingo\Api\Auth\Auth')->user();
如果控制器中，使用了 'Dingo\Api\Routing\Helpers'，可以使用 $this->auth 属性
use Dingo\Api\Routing\Helpers; // 引入 trait
class UserController extends Controller
{
use Helpers; // 使用 trait
public function index()
{
$user = $this->auth->user();
return $user;
}
}
不通过中间件来验证，需要手动在需要的地方进行验证
if( !app('Dingo\Api\Auth\Auth')->user()){
return '用户未验证！';
}
8.访问节流限制(rate limiting)
改变节流限速的 key
默认是 "客户端IP"，通过 $request->getClientIp() 获取。
我们可以自定义：
app('Dingo\Api\Http\RateLimit\Handler')->setRateLimiter(function ($app, $request) {
return $app['example']->getRateLimiterKey();
});
回调函数的 2 个参数是：
$app - Ioc 容器
$request - 请求实例
启用节流限速
使用 'api.throttle' 中间件
支持，额外的 2 个选项：
'middleware' => 'api.throttle', 'limit' => 100, 'expires' => 5
limit - 限制次数
expires - 过期时间
自定义阀门(throttle)
继承 Dingo\Api\Contract\Http\RateLimit\Throttle，定义一个 match() 方法，返回 true | false
use Illuminate\Container\Container;
use Dingo\Api\Http\RateLimit\Throttle\Throttle;
class CustomThrottle extends Throttle
{
public function match(Container $app)
{
// 在这里执行一些逻辑并根据是否返回 true 或 false
// 你的条件与阀门匹配。
}
}
注册阀门
api.php
'throttling' => [
'custom' => new CustomThrottle(['limit' => 200, 'expires' => 10])
]
9.内部调用
API 都是外部调用的，但是如果内部某个方法内，也想调用 API 的结果，这样可复用代码
// 构建一个分发器
$dispatcher = app('Dingo\Api\Dispatcher');
// 发起内部请求
$users = $dispatcher->get('api/users');
控制器中，也可使用 'Dingo\Api\Routing\Helpers' trait
use Dingo\Api\Routing\Helpers; // 引用 trait
class HomeController extends Controller
{
use Helpers; // 使用 trait
public function index()
{
$users = $this->api->get('users'); // 调用内部请求
return view('index')->with('users', $users);
}
}
发送数据
$dispatcher->with(['name' => 'Jason', 'location' => 'Australia'])->post('users');
或
$dispatcher->post('users', ['name' => 'Jason', 'location' => 'Australia']);
指定版本的 API
$dispatcher->version('v2')->get('users');
指定的域名
$dispatcher->on('api.example.com')->get('users');
上传附件
1>Symfony\Component\HttpFoundation\File\UploadedFile 实例数组
$dispatcher->attach(Input::files())->post('photos');
2>文件路径数组，数组 key 是文件的下标
$dispatcher->attach(['photo' => 'photos/me.jpg'])->post('photos');
3>文件路径相关的元数据数组(上传时，不会再计算文件 mime 类型和文件大小)
dispatcher->attach([
'photo' => [
'path' => 'photos/me.jpg',
'mime' => 'image/jpeg',
'size' => '49430'
]
])->post('photos');
发送 JSON 数据
$data = ['name' => 'bill', 'password' => 12345];
$dispatcher->json($data)->post('users');
注意：
如果 $data 是一个数组，将会自动被转换为 json。
这个请求的 Content-Type 被设置为 application/json
模拟认证用户
当我们请求的端点(路由)，需要用户认证通过后，才可进行处理，模拟用户
任何后续请求都将视为同一用户
$dispatcher->be(auth()->user())->get('posts');
只为给定的用户模拟一次请求
$dispatcher->be(auth()->user())->once()->get('posts');
获取原始返回对象
// 默认的 API 请求，返回的数据是经过预先转换、格式化
$response = $dispatcher->get('users');
// 要想获取原始查询的数据，添加 raw()
$response = $dispatcher->raw()->get('users');
异常处理
内部调用的 API，会抛出异常，我们如果想处理异常，需要自己捕获。
捕获的异常类需要和抛出的异常类一致
10.OAuth 2.0 认证
Scopes
11.请求你的 API
使用 Postman
使用 CURL
curl -v -H "Accept: application/vnd.YOUR_SUBTYPE.v1+json" http://example.app/users
12.API 文档
资源
/**
* 用户资源标识
*
* @Resource("Users", uri="/users")
*/
行为
@Get、@Post、@Put、@Patch、@Delete
@Versions
@Request
@Response
@Transaction
@Parameters
13.命令行工具
1>生成 API 路由列表
php artisan api:routes
php artisan api:routes --versions v1
php artisan api:routes --scopes read_user_data --scopes write_user_data
2>缓存 API 路由，同时缓存主路由。
php artisan api:cache
切记：
不要执行 laravel 的 route:cache，这样只会缓存主路由，不会缓存 Dingo API 的路由
3>根据标准注释，生成 API 文档
php artisan api:docs
php artisan api:docs --name Example --use-version v2 --output-file /path/to/documentation.md
php artisan api:docs --name Example --use-version v2 > /path/to/documentation.md // 或使用 '>' 标准输出重定向