五分鐘入門 Dingo API

GraceDevelopment發表於2019-03-03

基於 https://laravel-china.org/docs/dingo-api/2.0.0 文件更簡潔的描述Dingo,直戳重點,注重實踐

概述

Dingo API幫助您輕鬆快速地構建自己的API。雖然這個方案的目標是儘可能保持靈活性,但它仍然不能涵蓋所有情況並解決所有問題。

安裝

將以下程式碼加入到composer.json中,並執行composer update 或 composer install

"require": {
    "dingo/api": "2.0.0-alpha1"
}
複製程式碼

Laravel

釋出配置檔案,執行此命令後會在config目錄下生成api.php配置檔案

php artisan vendor:publish --provider="DingoApiProviderLaravelServiceProvider"
Lumen
複製程式碼

Lumen

如果是你使用的lumen,因lumen沒有vendor命令,請開啟 bootstrap/app.php 並註冊服務提供者:

$app->register(DingoApiProviderLumenServiceProvider::class);
複製程式碼

Facade

API 自帶了兩個 Facade,你可以酌情使用。

DingoApiFacadeAPI
複製程式碼

這個是排程器的 Facade ,並提供了一些好用的輔助方法。

DingoApiFacadeRoute
複製程式碼

你可以使用這個 Facade 來獲取 API 的當前路由、請求、檢查當前路由的名稱等。

你可以在config/app.php aliases陣列內註冊Facade

`aliases` => [
	...
	`API`          => DingoApiFacadeAPI::class,
	`ApiRoute`     => DingoApiFacadeRoute::class,
],
複製程式碼

配置

在.env檔案中配置你的Dingo API

  • API_STANDARDS_TREE
  • API_SUBTYPE
  • API_PREFIX
  • API_VERSION
  • API_NAME
  • API_CONDITIONAL_REQUEST
  • API_STRICT
  • API_DEBUG
  • API_DEFAULT_FORMAT

API_STANDARDS_TREE

Standards Tree 標準樹

  • 未註冊的樹(x)主要表示本地和私有環境
  • 私有樹(prs)主要表示沒有商業釋出的專案
  • 供應商樹(vnd)主要表示公開發布的專案
    是一種概念上的東西,類似與git的分支,如果正常開發就按照 x,prs,vnd 的描述來填寫即可。

API_SUBTYPE

在請求header中需要用到他

API_PREFIX

地址的字首,如果不需要請填寫 `/`

API_VERSION

介面的版本,填寫後是預設訪問的版本

API_NAME

介面的名稱,用於生成api文件,其他地方不使用

API_CONDITIONAL_REQUEST

條件請求預設為開啟狀態,這有利於客戶端的快取機制在可能的情況下快取 API 請求。

API_STRICT

強制每次請求必須帶版本,既

Accept:application/vnd.{API_SUBTYPE}.v2+json
複製程式碼

API_DEBUG

是否開啟除錯,開啟後訪問api會看到

API_DEFAULT_FORMAT

返回的型別,一般都是json

一個栗子

API_STANDARDS_TREE=vnd
API_SUBTYPE=catering
API_PREFIX=/
API_VERSION=v1
API_NAME="My API"
API_CONDITIONAL_REQUEST=false
API_STRICT=false
API_DEBUG=true
API_DEFAULT_FORMAT=json
複製程式碼

使用

這裡與實際業務結合來講解

表結構

member

CREATE TABLE `member` (
  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
  `tel` bigint(20) DEFAULT NULL COMMENT `手機號碼`,
  `password` varchar(255) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT `登入密碼`,
  `status` tinyint(4) NOT NULL DEFAULT `0` COMMENT `賬號狀態 0:正常`,
  `created_at` timestamp NULL DEFAULT NULL,
  `updated_at` timestamp NULL DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `member_tel_unique` (`tel`),
  KEY `member_tel_status_index` (`tel`,`status`)
) ENGINE=InnoDB AUTO_INCREMENT=4 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
複製程式碼

member_data

CREATE TABLE `member_data` (
  `member_id` bigint(20) NOT NULL COMMENT `使用者編碼`,
  `sex` enum(`0`,`1`,`2`) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT `性別 0=>女生 1=>男生 2=>未知`,
  `nick_name` varchar(255) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT `姓名/暱稱`,
  `img` varchar(255) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT `使用者頭像`,
  `created_at` timestamp NULL DEFAULT NULL,
  `updated_at` timestamp NULL DEFAULT NULL,
  UNIQUE KEY `member_data_member_id_unique` (`member_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
複製程式碼

新建一個路由

$api = app (`DingoApiRoutingRouter`);
$api->post (`user/register`, `AppApiControllersUserController@register`);
});
複製程式碼

建立自定義響應

<?php

    namespace AppApi;
	
	class Response
	{
		public static function success($data)
		{
			return [
				`status_code` => 200,
				`data`        => $data,
			];
		}
		
		public static function error($message = ``)
		{
			return [
				`status_code` => 0,
				`message`     => $message,
			];
		}
		
		public static function return($statusCode, $message, $data = [])
		{
			return [
				`status_code` => $statusCode,
				`message`     => $message,
				`data`        => $data,
			];
		}
	}
複製程式碼

建立控制器

<?php
	namespace AppApiControllers;
	
	use AppApiDingoController;
	use AppApiResponse;
	use AppApiServicesUserService;
	use IlluminateHttpRequest;
	
	class UserController extends DingoController
	{
		public $request;
		
		protected $userService;
		
		public function __construct(Request $request, UserService $userService)
		{
			$this->request = $request;
			
			$this->userService = $userService;
		}
		
		public function register()
		{
			$result = $this->userService->register ($this->request->all ());
			
			if ($result[`status_code`] == 200) {
				return $this->response->array (Response::return (200, `註冊成功`, [
					`user_id` => $result[`data`],
				]));
			}
			
			return $this->response->error ($result[`message`], 500);
		}
	}
複製程式碼

建立服務

<?php
	namespace AppApiServices;
	
	use AppApiActionsCreateUser;
	use AppApiResponse;
	use AppModelsMember;
	
	class UserService
	{
		public $member;
		
		public function __construct(Member $member)
		{
			$this->member = $member;
		}
		
		public function register($data)
		{
			try {
				return Response::success ((new CreateUser())->execute ($data));
			} catch (Exception $e) {
				return Response::error ($e->getMessage ());
			}
		}
	}
複製程式碼

建立動作

<?php
	namespace AppApiActions;
	
	use AppModelsMember;
	use AppModelsMemberData;
	
	class CreateUser
	{
		/**
		 * @param array $data
		 *
		 * @return mixed
		 * @throws Exception
		 */
		public function execute(array $data)
		{
			
			$member           = new Member();
			$member->tel      = $data[`tel`];
			$member->password = md5 ($data[`password`]);
			$result           = $member->save ();
			
			if (!$result) {
				throw new Exception(`註冊失敗`);
			}
			
			$memberData            = new MemberData();
			$memberData->member_id = $member->id;
			$memberData->sex       = "2";
			$memberData->nick_name = "";
			$memberData->img       = "";
			$memberData->save ();
			
			return $member->id;
		}
	}
複製程式碼

請求

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "http://api.c.com/user/register",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001
Content-Disposition: form-data; name="tel"

18510362698
-----011000010111000001101001
Content-Disposition: form-data; name="password"

zjk1221
-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => array(
    "accept: application/vnd.catering.v1+json",
    "cache-control: no-cache",
    "content-type: multipart/form-data; boundary=---011000010111000001101001",
    "postman-token: e7cf665f-3698-217a-cd71-35c3a44f42bc"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
複製程式碼

疑難雜症

列出一些常見問題及解決方案

版本區分後如何訪問

API_VERSION 設定的版本只是預設訪問版本,如果想訪問其他版本,需在header內新增

Accept:application/vnd.{API_SUBTYPE}.v2+json
複製程式碼

不想新增字首怎麼辦

API_PREFIX=/
複製程式碼

API_PREFIX不能為空,必須填寫內容,那理所當然的/一定是正確的

致謝

感謝你看到這裡,以上為個人研究開發的總結以及程式碼,如果可以幫到你,我很高興。如果有什麼問題或者文章有哪些錯誤,請在評論區回覆,及時阻止我誤導他人。謝謝

相關文章