Downloads
Stars
Version
系统间接口调用是开发中经常遇到的场景, 安全, 客户端发起请求方便, 服务端处理请求方便, 灵活的配置等都是设计时候考量的因素.
安全 :
系统间接口交互通常都是基于 HMAC (消息认证码)的方式来保证安全, HMAC 有哈希, 有密匙, 密匙保存在服务端, 所以很适合系统间接口的安全验证.
Laravel Request Guard 使用 sha256
哈希函数, sha256目前足够安全(相对于sha1
md5
) 快速(相对于sha3
).
Laravel Request Guard 使用 nonce
+ timestamp
来防止重放攻击.
请求 :
Laravel Request Guard 依赖并使用 guzzle/guzzle
来完成请求发起, 参数设置和 guzzle/guzzle
保持一致,
同时在使用上运用了 Laravel Manager 的语法糖, 构建请求方便灵活, 详情看下方 请求
部分.
响应 :
每次请求总会返回 \Mitoop\ApiSignature\SignatureResponse
对象(即使服务端发生了异常), 该对象提供了简洁有力的方法来告别try catch
. 详情看下方 响应
部分.
配置 :
配置支持多客户端, 并且支持同时充当客户端和服务端.
须知 :
只支持 Laravel.
composer require mitoop/laravel-signature-guard
1 . 安装过后运行 php artisan vendor:publish --provider="Mitoop\Signature\ServiceProvider"
,会生成 config/api-clients.php
配置文件.
2 . 如果需要使用 Facade
'aliases' => [
// ...
'Client' => Mitoop\Signature\Facades\Client::class,
]
3 . api-clients.php
配置说明
'default' => 'client-one', // 默认的客户端 作为发起方时, 默认连接的客户端
'clients' => [ // 客户端组
'client-one' => [ // 一个客户端
'app_id' => env('SIGN_CLIENT_ONE_APP_ID', 'app id'), // 客户端的 app id [必填]
'app_secret' => env('SIGN_CLIENT_ONE_APP_SECRET', 'app secret'),// 客户端的密匙 [必填]
'scheme' => env('SIGN_CLIENT_ONE_SCHEME', 'http'),// 客户端的 scheme 支持 http, https [必填]
'host' => env('SIGN_CLIENT_ONE_HOST', ''),// 客户端的 基础host 例如 : baidu.com 或者 192.168.11.11 [必填]
'ip' => env('SIGN_CLIENT_ONE_IP', ''),// 客户端的 host 对应的ip [选填]
'port' => env('SIGN_CLIENT_ONE_PORT', 80),// 客户端的 host 使用的端口 [必填]
'https_cert_pem' => env('SIGN_CLIENT_ONE_HTTPS_CERT_PEM', false),// 发起 https 请求时候用到的证书 [选填]
// 可选值 :
// false : 关闭证书验证
// true : 开启 SSL 验证, 并使用系统的 CA 来处理
// 自定义证书路径 : 开启 SSL 验证, 并使用自定义的 CA 来处理
'enable_log' => true, // 开启请求日志 true 或者 false 推荐 true
// 可以把请求的地址数组放在这里 actions 不是固定的 可以自定义
'actions' => [
'foo' => '/foo/abr',
'hello' => 'hello/world'
]
],
'another-client' => [ // 另一个客户端
'app_id' => env('SIGN_ANOTHER_CLIENT_APP_ID', 'app id'),
'app_secret' => env('SIGN_ANOTHER_CLIENT_APP_SECRET', 'app secret'),
'scheme' => env('SIGN_ANOTHER_CLIENT_SCHEME', 'http'),
'host' => env('SIGN_ANOTHER_CLIENT_HOST', ''),
'ip' => env('SIGN_ANOTHER_CLIENT_IP', ''),
'port' => env('SIGN_ANOTHER_CLIENT_PORT', 80),
'https_cert_pem' => env('SIGN_ANOTHER_CLIENT_HTTPS_CERT_PEM', false),
'enable_log' => true,
],
//... more clients
],
'identity' => 'mitoop-dev-server', // 当前系统身份标识 作为发起方时使用, 标识当前请求来源于该系统
请求支持 get
, post
, put
, delete
四种方法. 下面以 post
方法为例. 假如设置了alias
为 Client
// 向默认客户端发起请求 配置中 client-one 为默认客户端, 这里就是直接向 client-one 发起请求
Client::post('/api/demo', ['请求参数数组']);
向其他客户端发起请求 这个时候需要指定 connect
的客户端
Client::connect('any-client')->post('/api/demo', ['请求参数数组']);
// 容器模式
$client = app(\Mitoop\Signature\Client::class);
$client->connect('any-client')->post('/api/demo', ['请求参数数组']);
// 请求参数说明 请求参数遵从于 `guzzle`
[
'query' => [
'foo' => 'bar'
],
'form_params' => [
'foo' => 'bar'
],
'json' => [
'foo' => 'bar'
],
]
// query 是典型的 `get` 请求传参方式, 等同于 url 后的问号参数
// form_params 是典型的 `post` 请求传参方式, 这应该是最常见的 POST 提交数据的方式, 最终就会以 application/x-www-form-urlencoded 方式提交数据
// json JSON 格式支持比键值对复杂得多的结构化数据,这一点很有用, 最终就会以 application/json 方式提交数据
// !!! 请不要 form_params 和 json 同时使用, query 可以和两者之一同时使用
每次请求总会返回 \Mitoop\Signature\SignatureResponse
对象(即使服务端发生了异常),
该对象提供了简洁有力的方法来告别try catch
.
$signatureResponse->isSuccess(); // 请求是否成功
$signatureResponse->isOk(); // isSuccess别名方法
$signatureResponse->body(); // 获取原始输出信息
$signatureResponse->json(); // 获取json格式的数据
// 典型用法如 :
if($signatureResponse->isOk()) {
if($json = $signatureResponse->json()) {
// 处理自己的业务代码
}
}
// 告别处理响应时 try catch 冗长的处理
更多使用方法参考 这里
requesting 和 requested 是请求前和请求后的事件,可以方便地对请求进行额外的处理.
Client::requesting(function (\Mitoop\Signature\Client $client) {
// 请求发起之前
});
Client::requested(function (\Mitoop\Signature\Client $client) {
// 请求发起之后
});
Laravel Request Guard 使用 Laravel 本身提供的 guard
机制来完成身份验证.
首先需要配置一个 guard :
'guards' => [
//...
'server-api' => [ // 这里的 `server-api` 是 `guard` 名称, 可以自定义
'driver' => 'signature', // 指定驱动为 `signature`
],
],
其次定义路由中间件, Laravel Request Guard 本身提供了一个中间件 \Mitoop\Signature\Middleware\RequestGuardAuth
假如你使用该中间件 那么在 \App\Http\Kernel
的 $routeMiddleware
上配置 :
//...
'auth.signature' => \Mitoop\Signature\Middleware\RequestGuardAuth::class,
\Mitoop\Signature\Middleware\RequestGuardAuth
中间件非常简单, 你也可以自己定义一个中间件.
public function handle($request, Closure $next, $guard)
{
Auth::guard($guard)->check(); // 对请求进行验证, 如果验证错误抛出 `\Mitoop\Signature\Exception\InvalidSignatureException` 异常
return $next($request);
}
最后在路由里使用 auth.signature:server-api
中间件就可以了
// 现在 `/test` 请求必需通过验证才能访问的到
Route::post('/test', function () {
dd(request()->all());
})->middleware('auth.signature:server-api');
// 本机测试
Route::get('/tt', function () {
// 向 `tuning` 客户端发起请求 `tuning` 客户端可以配置为当前项目的 host
$response = Client::connect('tuning')->post('test', [
'form_params' => [
'foo' => 'bar',
],
'query' => [
'hello' => 'world',
],
]);
return $response->body();
});
// tuning 配置参考
'tuning' => [
'app_id' => '100001',
'app_secret' => 'tuning',
'scheme' => 'http',
'host' => 'foobar.test', // 本地项目域名
'ip' => '127.0.0.1',
'port' => 80,
'https_cert_pem' => false,
'enable_log' => true,
],
其他可用的 Auth 方法
Auth::guard('server-api')->check();
Auth::guard('server-api')->id();
Auth::guard('server-api')->user();
// 检查是否通过验证
Auth::guard('server-api')->check();
// 返回发起方的 config 里的 app_id
$appId = Auth::guard('server-api')->id();
// 返回 `\Mitoop\Signature\ClientUser` 实例. 里面包含了发起方的 config 信息(不包含密匙)
$user = Auth::guard('server-api')->user();
// 还可以从 ClientUser 实例上获取每一项配置
$appId = $user->app_id;
$host = $user->host;
//...