Yii2框架web.php中urlManager的patterns数组如何正确配置？

我有一个Yii2应用，尝试在web.php的urlManager中添加patterns数组配置REST路由，查阅相关文档后仍未解决问题。

初始可正常工作的配置 #

当使用如下配置时，Postman调用http://localhost:8080/v1/user/login的POST请求正常：

'urlManager' => [
    'enablePrettyUrl' => true,
    'showScriptName' => false,
    
    'rules' =>  [
        'class' => 'yii\rest\UrlRule', 
        'controller' => 'v1/user', 
        'POST' => 'v1/user/signup',
        'POST' => 'v1/user/login',
    ],                          
],

改用patterns数组后的错误配置 #

尝试改用patterns数组配置（同时需要支持OPTIONS请求，适配React前端调用）：

'urlManager' => [
    'enablePrettyUrl' => true,
    'showScriptName' => false,
    
    'rules' =>  [
        'class' => 'yii\rest\UrlRule', 
        'controller' => 'v1/user', 
        'patterns' => [
            'POST' => 'signup',
            'POST login' => 'login',
            'OPTIONS login' => 'options',                    
        ],
    ],                          
],

完整配置及报错信息 #

完整web.php配置如下：

<?php
// phpcs:ignoreFile

$params = require __DIR__ . '/params.php';
$db = require __DIR__ . '/db.php';

$config = [
    'id' => 'basic',
    'name' => 'internetsuite 2.0',
    'basePath' => dirname(__DIR__),
    'bootstrap' => ['log'],
    'aliases' => [
        '@bower' => '@vendor/bower-asset',
        '@npm'   => '@vendor/npm-asset',
    ],
    'modules' => [
        'v1' => [
            'class' => 'app\modules\v1\Module',
        ],
    ],
    'components' => [
        'request' => [
            'parsers' => [
                'application/json' => 'yii\web\JsonParser',
            ],
            'cookieValidationKey' => 'OEtCunrAfQNETtmUSDnZw1JPHTB44i3A',
        ],
        'cache' => [
            'class' => 'yii\caching\FileCache',
        ],
        'user' => [
            'identityClass' => 'app\models\User',
            'enableAutoLogin' => true,
        ],
        'errorHandler' => [
            'errorAction' => 'site/error',
        ],
        'mailer' => [
            'class' => \yii\symfonymailer\Mailer::class,
            'viewPath' => '@app/mail',
            'useFileTransport' => true,
        ],
        'log' => [
            'traceLevel' => YII_DEBUG ? 3 : 0,
            'targets' => [
                [
                    'class' => 'yii\log\FileTarget',
                    'levels' => ['error', 'warning'],
                ],
            ],
        ],
        'db' => $db,
        'urlManager' => [
            'enablePrettyUrl' => true,
            'showScriptName' => false,
            'enableStrictParsing' => true,
            
            'rules' =>  [[
                'class' => 'yii\rest\UrlRule', 
                'controller' => 'v1/user', 
                'pluralize' => false,
                ],
                'extraPatterns' => [
                    'OPTIONS {login}' => 'options',                    
                    'POST signup' => 'signup',
                    'POST login' => 'login',
                ],
            ],                          
        ],
    ],
    'params' => $params,
];

if (YII_ENV_DEV) {
    $config['bootstrap'][] = 'debug';
    $config['modules']['debug'] = [
        'class' => 'yii\debug\Module',
    ];

    $config['bootstrap'][] = 'gii';
    $config['modules']['gii'] = [
        'class' => 'yii\gii\Module',
    ];
}

return $config;

运行后出现错误：

Unknown Property – yii\base\UnknownPropertyException
Setting unknown property: yii\web\UrlRule::POST

正确的配置方案 #

错误核心是rules数组结构错误：extraPatterns是yii\rest\UrlRule的专属属性，必须嵌套在该规则的配置数组内，不能和规则数组同级，否则Yii会将其当作独立的yii\web\UrlRule规则处理，触发属性不存在的错误。另外，patterns会覆盖默认REST路由，建议用extraPatterns追加自定义路由，避免影响原有REST行为。

正确的urlManager配置如下：

'urlManager' => [
    'enablePrettyUrl' => true,
    'showScriptName' => false,
    'enableStrictParsing' => true,
    
    'rules' =>  [
        [
            'class' => 'yii\rest\UrlRule', 
            'controller' => 'v1/user', 
            'pluralize' => false,
            'extraPatterns' => [
                // 处理login接口的跨域预检请求
                'OPTIONS login' => 'options',
                // 自定义POST路由
                'POST signup' => 'signup',
                'POST login' => 'login',
            ],
        ],
    ],                          
],

关键说明 #

• pluralize设为false，避免自动生成复数形式的路由（比如users）。
• OPTIONS路由配置专门用于支持React等前端的跨域预检请求，确保前端能正常调用API。

内容的提问来源于stack exchange，提问作者mightycode Newton