Yii框架请求组件使用教程

本文深入解析了 Yii 框架中 Request 组件的核心用法与常见陷阱，强调它专用于安全、可靠地封装和读取当前 HTTP 请求信息（而非发起请求），涵盖获取完整 URL 的正确方式（getAbsoluteUrl()）、读取请求头的规范方法（getHeaders()->get()）、安全提取 GET/POST 参数的最佳实践（自动过滤与类型转换），以及精准识别 AJAX 和 JSON 请求的双重判断策略（isAjax + getContentType）；同时重点提醒反向代理配置（trustedHosts/secureHeaders）、Web 服务器兼容性（如 Apache 过滤下划线 Header）、CLI 环境限制等易被忽视的关键细节，帮助开发者避开高频坑点，写出更健壮、可维护的请求处理逻辑。

Yii 的 Request 组件不是用来发 HTTP 请求的，而是封装当前进来的 HTTP 请求信息——它不等价于 cURL 或 Guzzle，别往客户端方向想。

怎么拿到当前请求的完整 URL

用 Yii::$app->request->getAbsoluteUrl()，这是唯一推荐方式。它自动拼协议（https 还是 http）、域名、端口、子目录路径和查询参数，比如返回 https://api.example.com/v1/users?id=123。

常见错误：

• 用 $_SERVER['REQUEST_URI'] 拼接，会漏掉协议和 host，且在反向代理下可能返回错误的端口或协议
• 用 Yii::$app->request->url，只返回路径部分（如 /user/index），不含域名和查询参数
• 自己拼 $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI']，不处理 HTTPS 检测、端口省略逻辑，也不兼容 CLI 环境

注意：如果用了 Nginx 反向代理，必须配置 trustedHosts 和 secureHeaders，否则 getAbsoluteUrl() 可能误判为 HTTP。

怎么读取自定义请求头

统一走 getHeaders()->get('X-Api-Key')，大小写不敏感，但建议按标准写法传入全大写带连字符的键名。

使用场景：

• 鉴权（X-Api-Key、Authorization）
• 调试标识（X-Request-ID）
• 前端透传字段（X-Forwarded-For，但注意信任链配置）

容易踩的坑：

• 没配 trustedHosts 时，X-Forwarded-For 等头会被忽略
• Apache 默认会过滤掉带下划线的 Header（如 X_Api_Token），改用连字符或启用 mod_headers
• getHeaders() 返回的是 yii\web\HeaderCollection 对象，不能直接当数组用

GET/POST 参数怎么安全获取

用 get() 和 post() 方法，它们自动做过滤和类型转换（比如 get('id', 0, 'int')）。

关键细节：

• get() 只读 URL 查询参数，不管 Content-Type；post() 只读 application/x-www-form-urlencoded 或 multipart/form-data 提交的数据
• JSON 请求体要用 getRawBody() + json_decode() 手动解析，post() 拿不到
• 路由后缀（如 .html）会影响 get() 解析，因为 Yii 先做路由匹配再拆参数，一般建议关闭后缀或统一用无后缀路由
• 如果启用了 enableCsrfValidation，post() 会校验 CSRF token，失败直接 400，不是参数读不到

如何判断请求是否为 AJAX 或 JSON API

靠 isAjax 属性和 getContentType() 判断，而不是检查 URL 后缀或手动读 header。

示例逻辑：

if (Yii::$app->request->isAjax) {
    // 处理 X-Requested-With: XMLHttpRequest
}
if (strpos(Yii::$app->request->getContentType(), 'application/json') === 0) {
    // 处理 JSON 请求体
}

注意点：

• isAjax 依赖 X-Requested-With header，可被伪造，仅作辅助判断
• getContentType() 返回的是解析后的 MIME 类型（如 application/json），不是原始 header 字符串
• 某些前端库（如 axios）默认不带 X-Requested-With，此时 isAjax 为 false，得靠 getContentType() 或自定义 header

反向代理和 CLI 环境下，这些属性行为可能异常，尤其 isAjax 在 CLI 中恒为 false，但 getContentType() 会返回 null —— 别假设它们总有效。

文中关于Yii框架的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Yii框架请求组件使用教程》文章吧，也可关注golang学习网公众号了解相关技术文章。