Laravel Dingo API

提供一系列工具幫助你輕鬆構建本身的可拓展的API

提供工具集

• 內容協商
• 多種認證適配
• API版本號
• 訪問限制與限流
• 輸出數據轉換
• 錯誤和異常處理
• 內部請求
• API文檔

安裝

composer require dingo/api:1.0.*@dev

# 服務註冊
- Lumen下：
	#在`bootstrap/app`中註冊
	$app->register(Dingo\Api\Provider\LumenServiceProvider::class);
- Laravel下：
	#在`config/app.php`中註冊
	`Dingo\Api\Provider\LaravelServiceProvider::class`
	#發佈配置
	php artisan vendor:publish --provider="Dingo\Api\Provider\LaravelServiceProvider"

# Facad註冊
- Dingo\Api\Facade\API
- Dingo\Api\Facade\Route

env配置

• API_STANDARDS_TREE 標準樹
  • x未註冊樹 - 用於本地開發（建議值）
  • prs私有樹 - 用於非商業交付項目
  • vnd第三方樹 - 用於公開交付項目
• API_SUBTYPE 項目簡稱（小寫）
• API_PREFIX 前綴（建議值 api）
• API_DOMAIN 子域名（建議值 api.myapp.com）
• API_VERSION 默認版本號（建議值 v1）
• API_NAME api名稱（用於生成文檔）
• API_CONDITIONAL_REQUEST 條件請求（用於客戶端緩存api，默認true）
• API_STRICT 嚴格模式（強制要求客戶端提供Accept頭指定版本號，默認false）
• API_DEFAULT_FORMAT 響應格式（默認json）
• API_DEBUG debug信息追加到異常跟蹤棧上（默認false）

路由接管

$router = app('Dingo\Api\Routing\Router');
$api->version('v1', function ($api) {
	$api->get(路徑, 'MyController@MyAction');
	
    $api->group(['middleware' => 'foo'], function ($api) {
    });
});

響應

響應模式

1. 直接返回集合或對象（自動處理爲json）
2. 響應構建器
   • 響應輸出前morph變形流程 response > transformers > formatters > 輸出
   • 基類控制器引入響應構建器
     • Trait：use Dingo\Api\Routing\Helpers;
     • 使用：$this->response或者$this->response()
   • 正常響應
     • return $this->response->array($arrayData)
     • return $this->response->item($obj, $transfomrer)
     • return $this->response->collection($objs, $transfomrer)
     • return $this->response->paginator($paginatedObjs, $transfomrer)
     • return $this->response->noContent()
     • return $this->response->created([$uri])
   • 異常響應
     • return $this->response->error($msg, $statusCode)
     • return $this->response->errorNotFound([$msg])
     • return $this->response->errorBadRequest([$msg])
     • return $this->response->errorForbidden([$msg])
     • return $this->response->errorInternal([$msg])
     • return $this->response->errorUnauthorized([$msg])
   • 增長Http頭部 $this->response->withHeader($name, $value)
   • 增長元數據 $this->response->addMeta($name, $value)|setMeta([$name,=>$value])
   • 設置狀態碼 $this->response->setStatusCode($statuCode)

響應變形

• 監聽可選事件 ResponseIsMorphing、ResponseWasMorphed並handle響應

錯誤處理

• 錯誤時直接拋出相應的HTTP異常，dingo會自動設置json輸出及匹配的狀態碼

Transformer

默認使用Fractal Transfomer

調用模式

• 預先註冊好，輸出時直接返回對象：app('Dingo\Api\Transformer\Factory')->register('‘MyModel, 'MyModelTransformer')
• 預先未註冊，輸出對象前手動轉換：return $this->response->item($obj, $transfomrer)

認證

內置支持的認證適配器

• HTTP Basic (Dingo\Api\Auth\Provider\Basic)
• JSON Web Tokens (Dingo\Api\Auth\Provider\JWT)
• OAuth 2.0 (Dingo\Api\Auth\Provider\OAuth2)

調試請求

• 頭部必須帶上 Accept: application/vnd.YOUR_SUBTYPE.v1+json

限流

• 針對限定的每一個路由單獨生效限流
• 默認是按ip去限流的，可修改區別鍵

App('Dingo\Api\Http\RateLimit\Handler')->setRateLimiter(function ($app, $request) {
    return 惟一鍵名；
});

• 路由配置： 'middleware' => 'api.throttle', 'limit' => 次數, 'expires' => 分鐘數