CodeIgniter4 API 響應(yīng)特性

現(xiàn)代化的 PHP開(kāi)發(fā)都需要構(gòu)建 API ，不管它只是為了給 javascript 單頁(yè)應(yīng)用提供數(shù)據(jù)還是作為獨(dú)立的產(chǎn)品。CodeIgniter 提供了一個(gè)API響應(yīng)特性，可用于任何控制器，使公共響應(yīng)類(lèi)型簡(jiǎn)單，無(wú)需記住它的 HTTP 狀態(tài)代碼應(yīng)返回的響應(yīng)類(lèi)型。

使用示例

下面的示例顯示了控制器中常見(jiàn)的使用模式。

<?php namespace App\Controllers;


class Users extends \CodeIgniter\Controller
{
    use CodeIgniter\API\ResponseTrait;


    public function createUser()
    {
        $model = new UserModel();
        $user = $model->save($this->request->getPost());


        // 響應(yīng) 201 狀態(tài)碼
        return $this->respondCreated();
    }
}

在這個(gè)例子中，響應(yīng)了 201 的HTTP狀態(tài)碼，并使用“創(chuàng)建”的通用狀態(tài)消息返回。方法存在于最常見(jiàn)的用例中

// 通用響應(yīng)方式
respond($data, 200);
// 通用錯(cuò)誤響應(yīng)
fail($errors, 400);
// 項(xiàng)目創(chuàng)建響應(yīng)
respondCreated($data);
// 項(xiàng)目成功刪除
respondDeleted($data);
// 客戶(hù)端未授權(quán)
failUnauthorized($description);
// 禁止動(dòng)作
failForbidden($description);
// 找不到資源
failNotFound($description);
// Data 數(shù)據(jù)沒(méi)有驗(yàn)證
failValidationError($description);
// 資源已存在
failResourceExists($description);
// 資源早已被刪除
failResourceGone($description);
// 客戶(hù)端請(qǐng)求數(shù)過(guò)多
failTooManyRequests($description);

處理響應(yīng)類(lèi)型

當(dāng)您通過(guò)以下任何一種方法傳遞數(shù)據(jù)時(shí)，它們將決定基于數(shù)據(jù)類(lèi)型來(lái)格式化結(jié)果:

• 如果 $data 是一個(gè)字符串，它將被當(dāng)作 HTML 發(fā)送回客戶(hù)端。
• 如果 $data 是一個(gè)數(shù)組，它將嘗試請(qǐng)求內(nèi)容類(lèi)型與客戶(hù)端進(jìn)行協(xié)商，默認(rèn)為 JSON。如果沒(méi)有在 ConfigAPI.php 中配置內(nèi)容。默認(rèn)使用 $supportedResponseFormats 屬性。

需要使用格式化，請(qǐng)修改 Config/Format.php 文件配置。$supportedResponseFormats 包含了一個(gè)格式化響應(yīng)類(lèi)型列表。默認(rèn)情況下，系統(tǒng)將會(huì)自動(dòng)判斷并響應(yīng) XML 和 JSON 格式:

public $supportedResponseFormats = [
    'application/json',
    'application/xml'
];

這是在 Content Negotiation 中使用的數(shù)組，以確定返回的響應(yīng)類(lèi)型。如果在客戶(hù)端請(qǐng)求的內(nèi)容和您支持的內(nèi)容之間沒(méi)有匹配，則返回第一個(gè)該數(shù)組中的格式。

接下來(lái)，需要定義用于格式化數(shù)據(jù)數(shù)組的類(lèi)。這必須是一個(gè)完全合格的類(lèi)名，類(lèi)名必須實(shí)現(xiàn) CodeIgniterAPIFormatterInterface。格式化支持 JSON 和 XML

public $formatters = [
    'application/json' => \CodeIgniter\API\JSONFormatter::class,
    'application/xml'  => \CodeIgniter\API\XMLFormatter::class
];

因此，如果您的請(qǐng)求在 Accept 頭中請(qǐng)求 JSON 格式的數(shù)據(jù)，那么您傳遞的數(shù)據(jù)數(shù)組就可以通過(guò)其中任何一個(gè) respond* 或 fail* 方法將由 CodeIgniterAPIJSONFormatter 格式化。由此產(chǎn)生的 JSON 數(shù)據(jù)將被發(fā)送回客戶(hù)端。

引用類(lèi)

respond($data[, $statusCode=200[, $message='']])

這是該特征中所有其他方法用于將響應(yīng)返回給客戶(hù)端的方法。

$data 元素可以是字符串或數(shù)組。 默認(rèn)情況下，一個(gè)字符串將作為 HTML 返回，而數(shù)組將通過(guò) json_encode 運(yùn)行并返回為 JSON，除非 Content Negotiation 確定它應(yīng)該以不同的格式返回。

如果一個(gè) $message 字符串被傳遞，它將被用來(lái)替代標(biāo)準(zhǔn)的 IANA 標(biāo)準(zhǔn)碼回應(yīng)狀態(tài)。但不是每個(gè)客戶(hù)端都會(huì)遵守自定義代碼，并將使用 IANA 標(biāo)準(zhǔn)匹配狀態(tài)碼。

注解

由于它在活動(dòng)的響應(yīng)實(shí)例上設(shè)置狀態(tài)碼和正文，所以應(yīng)該一直作為腳本執(zhí)行中的最終方法。

fail($messages[, int $status=400[, string $code=null[, string $message='']]])

這是用于表示失敗的響應(yīng)的通用方法，并被所有其他“fail”方法使用。

該 $messages 元素可以是字符串或字符串?dāng)?shù)組。 該 $status 參數(shù)是應(yīng)返回的HTTP狀態(tài)碼。

由于使用自定義錯(cuò)誤代碼更好地提供了許多 API，因此可以在第三個(gè)參數(shù)中傳遞自定義錯(cuò)誤代碼。如果沒(méi)有值，它將是一樣的 $status 【狀態(tài)碼】。

如果一個(gè) $message 字符串被傳遞，它將被用于代替響應(yīng)狀態(tài)的標(biāo)準(zhǔn) IANA 碼。不是每個(gè)客戶(hù)端都會(huì)遵守自定義代碼，并且將使用與狀態(tài)代碼相匹配的 IANA 標(biāo)準(zhǔn)。

這個(gè)響應(yīng)是一個(gè)包含兩個(gè)元素的數(shù)組： error 和 messages 。 error 元素包含錯(cuò)誤的狀態(tài)代碼。messages 元素包含一組錯(cuò)誤消息。它看起來(lái)像:

$response = [
    'status' => 400,
    'code' => '321a',
    'messages' => [
        'Error message 1',
        'Error message 2'
    ]
];

respondCreated($data[, string $message = ''])

設(shè)置創(chuàng)建新資源時(shí)使用的相應(yīng)狀態(tài)代碼，通常為201:

$user = $userModel->insert($data);
return $this->respondCreated($user);

respondDeleted($data[, string $message = ''])

設(shè)置當(dāng)通過(guò)此API調(diào)用的結(jié)果刪除新資源時(shí)使用的相應(yīng)狀態(tài)代碼（通常為200）。

$user = $userModel->delete($id);
return $this->respondDeleted(['id' => $id]);

failUnauthorized(string $description[, string $code=null[, string $message = '']])

設(shè)置當(dāng)用戶(hù)未被授權(quán)或授權(quán)不正確時(shí)使用的相應(yīng)狀態(tài)代碼。狀態(tài)碼為401。

return $this->failUnauthorized('Invalid Auth token');

failForbidden(string $description[, string $code=null[, string $message = '']])

不像 failUnauthorized，當(dāng)請(qǐng)求 API 路徑?jīng)Q不允許采用這種方法。未經(jīng)授權(quán)意味著客戶(hù)端被鼓勵(lì)再次嘗試使用不同的憑據(jù)。禁止意味著客戶(hù)端不應(yīng)該再次嘗試，因?yàn)樗粫?huì)有幫助。狀態(tài)碼為403。

return $this->failForbidden('Invalid API endpoint.');

failNotFound(string $description[, string $code=null[, string $message = '']])

設(shè)置于在找不到請(qǐng)求的資源時(shí)使用的狀態(tài)碼。狀態(tài)碼為404。

return $this->failNotFound('User 13 cannot be found.');

failValidationError(string $description[, string $code=null[, string $message = '']])

設(shè)置于客戶(hù)端發(fā)送的數(shù)據(jù)未通過(guò)驗(yàn)證規(guī)則時(shí)使用的狀態(tài)碼。狀態(tài)碼通常為400。

return $this->failValidationError($validation->getErrors());

failResourceExists(string $description[, string $code=null[, string $message = '']])

設(shè)置于當(dāng)客戶(hù)端嘗試創(chuàng)建的資源已經(jīng)存在時(shí)使用的狀態(tài)碼。狀態(tài)碼通常為409。

return $this->failResourceExists('A user already exists with that email.');

failResourceGone(string $description[, string $code=null[, string $message = '']])

設(shè)置于當(dāng)請(qǐng)求的資源先前被刪除并且不再使用時(shí)使用的狀態(tài)碼。狀態(tài)碼通常為410。

return $this->failResourceGone('That user has been previously deleted.');

failTooManyRequests(string $description[, string $code=null[, string $message = '']])

設(shè)置于當(dāng)客戶(hù)端調(diào)用 API路徑次數(shù)過(guò)多時(shí)使用的狀態(tài)碼。這可能是由于某種形式的節(jié)流或速率限制。狀態(tài)碼通常為400。

return $this->failTooManyRequests('You must wait 15 seconds before making another request.');

failServerError(string $description[, string $code = null[, string $message = '']])

設(shè)置于當(dāng)存在服務(wù)器錯(cuò)誤時(shí)使用的狀態(tài)碼。

return $this->failServerError('Server error.');