# 安装
$ composer require dingo/api:3.0.x@dev
# 1.在 api.php 中编写接口
# 2.在响应构建器中使用转化器构建JSON 响应
# 1.
$api = app(\Dingo\Api\Routing\Router::class); # 获取对应的 API 路由器实例
$api->version('v1', function ($api) {
//
}); # 版本分组
# .env中：
API_SUBTYPE= # 子类型，默认为空
API_PREFIX=dingoapi # 配置路由前缀
API_DOMAIN=api.myapp.com # 子域名，和前缀二选一进行配置
API_VERSION=v1 # 版本
API_NAME= # 名字
API_CONDITIONAL_REQUEST=false # 带条件的请求
API_STRICT=false # Strict 模式
# 完整的 Accept 字段值格式
# Accept: application/API_STANDARDS_TREE.API_SUBTYPE.API_VERSION+json
# 2.
# app\Http\Controller 下创建新的 API 基类控制器
php artisan make:controller ApiController
# 内容：
class ApiController extends Controller
{
use Helpers;
}
# 定义一个继承自该控制器的子控制器
php artisan make:controller Api/TaskController --resource
# 返回 JSON 响应示例：
$task = Task::findOrFail($id);
return $this->response->array($task->toArray());
# API 路由示例：
$api->version('v3', function ($api) {
$api->resource('tasks', \App\Http\Controllers\Api\TaskController::class);
});
# 三种序列化器
$fractal->setSerializer(new \League\Fractal\Serializer\ArraySerializer());
$fractal->setSerializer(new \League\Fractal\Serializer\DataArraySerializer()); # 默认
$fractal->setSerializer(new \League\Fractal\Serializer\JsonApiSerializer());
# 转化器
# 新建 app/Transformers/TaskTransformer 转化器，初始化代码：
namespace App\Transformers;
use App\Task;
use League\Fractal\TransformerAbstract;
class TaskTransformer extends TransformerAbstract
{
public function transform(Task $task)
{
return [
'id' => $task->id,
'text' => $task->text,
'completed' => $task->is_completed ? 'yes' : 'no',
'link' => route('tasks.show', ['id' => $task->id])
];
}
}
# 单个资源：
$task = Task::findOrFail($id);
return $this->response->item($task, new TaskTransformer());
# 资源集合：
$tasks = Task::all();
return $this->response->collection($tasks, new TaskTransformer());
# 添加额外的响应头
return $this->response->item($task, new TaskTransformer)->withHeader('Foo', 'Bar');
# 添加 cookie, 必须要是实例
$cookie = new \Symfony\Component\HttpFoundation\Cookie('foo', 'bar');
...->withCookie($cookie);
# 设置响应状态码
...->setStatusCode(200);
# 添加元数据
...->addMeta('foo', 'bar');
API 认证
HTTP基本认证
# 1.注册驱动，在 AuthServiceProvider 的 boot 方法中注册基本认证
# 2.在相应的 API 路由中认证中间件
# 3.访问 （添加Basic Auth / 不添加）
# 这里的认证信息是首页注册时的原邮箱和原密码
# 1.
use Dingo\Api\Auth\Auth;
use Dingo\Api\Auth\Provider\Basic;
public function boot()
{
// Dingo 认证驱动注册
$this->app->make(Auth::class)->extend('basic', function ($app) {
return new Basic($app['auth'], 'email');
});
}
# 2.
$api->version('v3', ['middleware' => 'api.auth'], function ($api) {
$api->resource('tasks', \App\Http\Controllers\Api\TaskController::class);
});
# or，在指定路由上应用该中间件
$api->version('v3', function ($api) {
$api->resource('tasks', \App\Http\Controllers\Api\TaskController::class, [
'middleware' => 'api.auth'
]);
});
JWT认证
# 准备工作：
$ composer require tymon/jwt-auth
$ php artisan vendor:publish --provider="Tymon\JWTAuth\Providers\JWTAuthServiceProvider"
$ php artisan jwt:secret
# 让用于认证的 User 模型类实现 JWTSubject 接口
class User extends Authenticatable implements JWTSubject {
public function getJWTIdentifier()
{
return $this->getKey();
}
public function getJWTCustomClaims()
{
return [];
}
}
# 1.注册驱动，可以在 config/api.php 中注册对应的认证驱动，也可以和 HTTP 一样
# 2.获取 JWT 令牌
# 3.基于 JWT 认证访问 API
# 1. config/api/php:
'auth' => [
'jwt' => \Dingo\Api\Auth\Provider\JWT::class,
],
# 2.
$api->version('v3', function ($api) {
$api->post('user/auth', function () {
$credentials = app('request')->only('email', 'password');
try {
if (! $token = \Tymon\JWTAuth\Facades\JWTAuth::attempt($credentials)) {
throw new \Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException('Invalid credentials');
}
} catch (\Tymon\JWTAuth\Exceptions\JWTException $e) {
throw new \Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException('Create token failed');
}
return compact('token');
});
}); # 访问即可获取到 Token 值
# 3.代码保持和 HTTP 基本认证一样，设置认证类型为 Bearer Token，写入获取到的 Token 值
OAuth 2.0 认证
1.安装配置 Passport
$ composer require laravel/passport # 安装
# php artisan migrate # 生成用于存放客户端和访问令牌的数据表
$ php artisan passport:install # 创建生成安全访问令牌（token）所需的加密键
# 添加 Laravel\Passport\HasApiTokens trait 到 App\User 模型
namespace App;
use Laravel\Passport\HasApiTokens;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;
class User extends Authenticatable
{
use HasApiTokens, Notifiable;
}
# 在 AuthServiceProvider 的 boot 方法中调用 Passport::routes 方法
class AuthServiceProvider extends ServiceProvider
{
protected $policies = [
'App\Model' => 'App\Policies\ModelPolicy',
];
public function boot()
{
$this->registerPolicies();
Passport::routes();
}
}
# 修改配置文件 config/auth.php
'api' => [
'driver' => 'passport',
'provider' => 'users',
],
2.设置认证中间件
# Api\TaskController.php:
public function __construct()
{
$this->middleware('auth:api');
}
3.通过密码授权令牌访问认证 API
# 1.获取CLIENT_ID和CLIENT_SECRET，配置到 .env 中
# 2.在 routes/api.php 中定义一个用于获取授权令牌的路由
# 3.将获取到的access_token（认证 API 时的令牌）设置到类型为 Bearer 的 Authorization 字段，请求 tasks.index 路由
# 1.
$ php artisan passport:client --password
# 2.
$api->version('v3', function ($api) {
$api->post('user/token', function () {
app('request')->validate([
'email' => 'required|string',
'password' => 'required|string',
]);
$http = new \GuzzleHttp\Client();
// 发送相关字段到后端应用获取授权令牌
$response = $http->post(route('passport.token'), [
'form_params' => [
'grant_type' => 'password',
'client_id' => env('CLIENT_ID'),
'client_secret' => env('CLIENT_SECRET'),
'username' => app('request')->input('email'), // 这里传递的是邮箱
'password' => app('request')->input('password'), // 传递密码信息
'scope' => '*'
],
]);
return response()->json($response->getBody()->getContents());
});
$api->resource('tasks', \App\Http\Controllers\Api\TaskController::class);
});
php 内置的 http server 是 block 的，一次只能处理一个请求，这里将项目部署到wamp中。
访问频率限制
通过 Laravel 自带的节流中间件 - throttle
'throttle:60,1', # 默认1 分钟内可以对应用该中间件的路由发起 60 次请求
$api->post('user/token', ['middleware' => 'throttle:3,1', function () {
//
}]); # 通过传递参数到该中间件来手动设置时间范围和请求次数
# 响应头中通过 X-RateLimit-* 字段获取频率限制相关数值:
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1557801344
通过 Dingo 实现的节流中间件
$api->post('user/token', ['middleware' => 'api.throttle', 'limit' => 3, 'expires' => 1, function () {
//
}
自定义节流器
# 创建自定义节流器 app/Throttles/CustomThrottle.php:
namespace App\Throttles;
use Dingo\Api\Contract\Http\RateLimit\HasRateLimiter;
use Dingo\Api\Http\RateLimit\Throttle\Throttle;
use Dingo\Api\Http\Request;
use Illuminate\Container\Container;
class CustomThrottle extends Throttle implements HasRateLimiter
{
protected $options = ['limit' => 5, 'expires' => 1];
public function match(Container $container)
{
return ! $container['api.auth']->check();
}
// 通过域名+IP识别客户端
public function getRateLimiter(Container $app, Request $request)
{
return $request->route()->getDomain() . '|' . $request->getClientIp();
}
}
# 在 routes/api.php 中通过 throttle 参数指定 user/token 路由使用该自定义节流器
$api->post('user/token', ['middleware' => 'api.throttle', 'throttle' => 'App\Throttles\CustomThrottle', function () {
...
}]);