響應(yīng)格式

當(dāng)處理一個(gè) RESTful API 請(qǐng)求時(shí)， 一個(gè)應(yīng)用程序通常需要如下步驟 來處理響應(yīng)格式：

1. 確定可能影響響應(yīng)格式的各種因素， 例如媒介類型， 語言， 版本， 等等。 這個(gè)過程也被稱為?content negotiation。
2. 資源對(duì)象轉(zhuǎn)換為數(shù)組， 如在?Resources?部分中所描述的。 通過 yii\rest\Serializer 來完成。
3. 通過內(nèi)容協(xié)商步驟將數(shù)組轉(zhuǎn)換成字符串。 [yii\web\ResponseFormatterInterface|response formatters]] 通過 [yii\web\Response::formatters|response]] 應(yīng)用程序組件來注冊(cè)完成。

內(nèi)容協(xié)商

Yii 提供了通過 yii\filters\ContentNegotiator 過濾器支持內(nèi)容協(xié)商。RESTful API 基于 控制器類 yii\rest\Controller 在?contentNegotiator下配備這個(gè)過濾器。 文件管理器提供了涉及的響應(yīng)格式和語言。 例如， 如果一個(gè) RESTful API 請(qǐng)求中包含以下 header，

Accept: application/json; q=1.0, */*; q=0.1

將會(huì)得到JSON格式的響應(yīng)，如下：

$ curl -i -H "Accept: application/json; q=1.0, *

defined('YII_DEBUG') or define('YII_DEBUG', true);

require(__DIR__ . '/vendor/autoload.php');
require(__DIR__ . '/vendor/yiisoft/yii2/Yii.php');

$config = require(__DIR__ . '/config/console.php');

$application = new yii\console\Application($config);
$exitCode = $application->run();
exit($exitCode);

該腳本將被創(chuàng)建為你應(yīng)用程序中的一部分；你可以根據(jù)你的需求來修改它。如果你不需要記錄錯(cuò)誤信息或者希望提高整體性能，YII_DEBUG?常數(shù)應(yīng)定義為?false。 在基本的和高級(jí)的兩個(gè)應(yīng)用程序模板中，控制臺(tái)應(yīng)用程序的入口腳本在默認(rèn)情況下會(huì)啟用調(diào)試模式，以提供給開發(fā)者更好的環(huán)境。

配置

在上面的代碼中可以看到，控制臺(tái)應(yīng)用程序使用它自己的配置文件，名為?console.php?。在該文件里你可以給控制臺(tái)配置各種?應(yīng)用組件和屬性。

如果你的 web 應(yīng)用程序和控制臺(tái)應(yīng)用程序共享大量的配置參數(shù)和值，你可以考慮把這些值放在一個(gè)單獨(dú)的文件中，該文件中包括（ web 和控制臺(tái)）應(yīng)用程序配置。 你可以在“高級(jí)”項(xiàng)目模板中看到一個(gè)例子。

提示：有時(shí)，你可能需要使用一個(gè)與在入口腳本中指定的應(yīng)用程序配置不同的控制臺(tái)命令。例如，你可能想使用?yii migrate?命令來升級(jí)你的測(cè)試數(shù)據(jù)庫，它被配置在每個(gè)測(cè)試套件。要?jiǎng)討B(tài)地更改配置，只需指定一個(gè)自定義應(yīng)用程序的配置文件，通過appconfig選項(xiàng)來執(zhí)行命令：

yii <route> --appconfig=path/to/config.php ...

創(chuàng)建你自己的控制臺(tái)命令

控制臺(tái)的控制器和行為

一個(gè)控制臺(tái)命令繼承自 yii\console\Controller 控制器類。 在控制器類中，定義一個(gè)或多個(gè)與控制器的子命令相對(duì)應(yīng)的動(dòng)作。在每一個(gè)動(dòng)作中，編寫你的代碼實(shí)現(xiàn)特定的子命令的適當(dāng)?shù)娜蝿?wù)。

當(dāng)你運(yùn)行一個(gè)命令時(shí)，你需要指定一個(gè)控制器的路由。例如，路由?migrate/create?調(diào)用子命令對(duì)應(yīng)的yii\console\controllers\MigrateController::actionCreate() 動(dòng)作方法。 如果在執(zhí)行過程中提供的路由不包含路由 ID ，將執(zhí)行默認(rèn)操作（如 web 控制器）。

選項(xiàng)

通過覆蓋在 yii\console\Controller::options() 中的方法，你可以指定可用于控制臺(tái)命令（controller/actionID）選項(xiàng)。這個(gè)方法應(yīng)該返回控制器類的公共屬性的列表。 當(dāng)運(yùn)行一個(gè)命令，你可以指定使用語法?--OptionName=OptionValue?選項(xiàng)的值。 這將分配?OptionValue?到控制器類的?OptionName?屬性。

If the default value of an option is of an array type and you set this option while running the command, the option value will be converted into an array by splitting the input string on any commas.

參數(shù)

除了選項(xiàng)，命令還可以接收參數(shù)。參數(shù)將傳遞給請(qǐng)求的子命令對(duì)應(yīng)的操作方法。第一個(gè)參數(shù)對(duì)應(yīng)第一個(gè)參數(shù)，第二個(gè)參數(shù)對(duì)應(yīng)第二個(gè)參數(shù)，依次類推。 命令被調(diào)用時(shí)，如果沒有足夠的參數(shù)，如果有定義默認(rèn)值的情況下，則相應(yīng)的參數(shù)將采取默認(rèn)聲明的值；如果沒有設(shè)置默認(rèn)值，并且在運(yùn)行時(shí)沒有提供任何值，該命令將以一個(gè)錯(cuò)誤退出。

你可以使用?array?類型提示來指示一個(gè)參數(shù)應(yīng)該被視為一個(gè)數(shù)組。該數(shù)組通過拆分輸入字符串的逗號(hào)來生成。

下面的示例演示如何聲明參數(shù)：

class ExampleController extends \yii\console\Controller{
    // 命令 "yii example/create test" 會(huì)調(diào)用 "actionCreate('test')"
    public function actionCreate($name) { ... }

    // 命令 "yii example/index city" 會(huì)調(diào)用 "actionIndex('city', 'name')"
    // 命令 "yii example/index city id" 會(huì)調(diào)用 "actionIndex('city', 'id')"
    public function actionIndex($category, $order = 'name') { ... }

    // 命令 "yii example/add test" 會(huì)調(diào)用 "actionAdd(['test'])"
    // 命令 "yii example/add test1,test2" 會(huì)調(diào)用 "actionAdd(['test1', 'test2'])"
    public function actionAdd(array $name) { ... }
}

退出代碼

使用退出代碼是控制臺(tái)應(yīng)用程序開發(fā)的最佳做法。通常，執(zhí)行成功的命令會(huì)返回?0。如果命令返回一個(gè)非零數(shù)字，會(huì)認(rèn)為出現(xiàn)錯(cuò)誤。 該返回的數(shù)字作為出錯(cuò)代碼，用以了解錯(cuò)誤的詳細(xì)信息。例如?1?可能代表一個(gè)未知的錯(cuò)誤，所有的代碼都將保留在特定的情況下：輸入錯(cuò)誤，丟失的文件等等。

要讓控制臺(tái)命令返回一個(gè)退出代碼，只需在控制器操作方法中返回一個(gè)整數(shù)：

public function actionIndex(){
    if () {
        echo "A problem occured!\n";
        return 1;
    }
    // do something
    return 0;
}

你可以使用一些預(yù)定義的常數(shù)：

• Controller::EXIT_CODE_NORMAL?值為?0;
• Controller::EXIT_CODE_ERROR?值為?1.

為控制器定義有意義的常量，以防有更多的錯(cuò)誤代碼類型，這會(huì)是一個(gè)很好的實(shí)踐。

格式和顏色

Yii 支持格式化輸出，如果終端運(yùn)行命令不支持的話則會(huì)自動(dòng)退化為非格式化輸出。

要輸出格式的字符串很簡(jiǎn)單。以下展示了如何輸出一些加粗的文字：

$this->stdout("Hello?\n", Console::BOLD);

如果你需要建立字符串動(dòng)態(tài)結(jié)合的多種樣式，最好使用?ansiFormat?：