第九章 请求与响应组件
请求与响应组件是 WangStruct Framework 处理 HTTP 通信的基础组件,负责接收外部客户端发送的 HTTP 请求,将请求数据组织为统一的请求对象,并根据应用程序的处理结果构建 HTTP 响应内容,最终通过统一的响应对象输出给客户端。
在传统 PHP 程序中,开发者通常直接通过 $_GET、$_POST、$_SERVER 和 $_FILES 等全局变量获取请求数据,再通过 header()、echo 和 http_response_code() 等方式输出响应。这种方式虽然能够完成基本的 HTTP 处理,但当应用程序规模扩大时,各个控制器和业务程序容易形成不同的请求读取方式和响应输出方式,造成程序之间的处理逻辑不统一。
因此,WangStruct Framework 需要建立独立的请求与响应组件,将 HTTP 请求数据的获取、解析、管理和响应输出集中组织。应用程序通过请求对象读取外部数据,通过响应对象设置返回内容,不直接承担底层 HTTP 数据处理工作。
本章围绕请求对象、响应对象、请求管理程序和响应管理程序展开工程设计,明确请求参数获取、请求类型识别、响应状态码设置、响应头管理、内容输出和数据格式处理等接口,使框架能够形成统一的 HTTP 请求处理与响应输出机制。
9.1 请求与响应组件的工程定位
请求与响应组件位于 HTTP 外部通信与框架内部应用程序之间,是框架接收外部请求和输出处理结果的基础接口层。
请求对象负责描述一次 HTTP 请求所携带的信息,包括请求方法、请求地址、查询参数、表单数据、请求头、Cookie、上传文件和请求体等内容。响应对象负责组织应用程序需要返回的数据,包括响应状态码、响应头、响应内容和数据格式。
请求与响应组件不负责执行业务功能,也不负责决定应用程序应该返回什么业务结果。它只负责将外部请求转换为框架内部统一的数据对象,并将应用程序生成的响应数据转换为符合 HTTP 协议的输出内容。
组件整体关系如下:
请求与响应组件由请求对象、响应对象以及相应的管理程序组成。请求管理程序负责创建和管理请求对象,响应管理程序负责组织响应输出。应用程序通过统一接口与这两个对象交互,从而避免直接依赖 PHP 全局变量和分散的响应输出代码。
9.2 请求与响应组件的目录结构
请求与响应组件需要分别管理请求数据和响应数据,同时设置必要的管理程序,使请求对象和响应对象能够由框架统一创建和调用。
本章采用以下工程目录结构:
WangStruct/
│
├── framework/ # 框架核心程序目录
│ │
│ ├── Http/ # HTTP请求与响应组件目录
│ │ ├── Request.php # HTTP请求对象
│ │ ├── Response.php # HTTP响应对象
│ │ ├── RequestManager.php # 请求对象管理程序
│ │ └── ResponseManager.php # 响应对象管理程序
│ │
│ └── Core/ # 框架核心类目录
│ └── Application.php # 应用运行管理类
│
├── app/ # 应用程序目录
│ └── Controller/ # 应用控制器目录
│ └── IndexController.php # 默认控制器
│
└── public/ # Web访问入口目录
└── index.php # 框架启动入口
framework/Http 用于组织 HTTP 请求与响应相关程序。Request.php 负责请求数据管理,Response.php 负责响应数据管理,RequestManager.php 和 ResponseManager.php 分别负责请求对象与响应对象的创建和管理。
Application.php 负责协调框架运行过程,将请求处理和响应输出纳入统一的应用生命周期。
上述目录属于本章的工程设计结构,实际工程实现时应与前面章节的目录组织和自动加载规则保持一致,不应重复创建已有的核心程序文件。
9.3 HTTP 请求对象设计
请求对象是请求与响应组件的核心数据对象,用于统一保存一次 HTTP 请求所包含的信息。
PHP 在接收到 HTTP 请求时,会将部分请求信息放入超全局变量中。例如,查询参数保存在 $_GET 中,表单参数保存在 $_POST 中,请求头和服务器信息可以从 $_SERVER 中获取,上传文件信息保存在 $_FILES 中。
请求对象需要将这些分散的数据集中组织,使应用程序不必直接读取 PHP 超全局变量。
请求对象可以采用以下数据结构:
其中,\(M\) 表示请求方法,\(U\) 表示请求地址,\(Q\) 表示查询参数,\(P\) 表示表单参数,\(H\) 表示请求头,\(C\) 表示 Cookie,\(F\) 表示上传文件,\(B\) 表示原始请求体,\(S\) 表示服务器环境信息。
请求对象文件为:
framework/Http/Request.php
基础实现如下:
<?php
namespace WangStruct\Framework\Http;
class Request
{
protected $method;
protected $uri;
protected $query;
protected $post;
protected $server;
protected $headers;
protected $cookies;
protected $files;
protected $body;
/**
* 初始化请求对象
*/
public function __construct(
$method,
$uri,
$query,
$post,
$server,
$headers,
$cookies,
$files,
$body
) {
$this->method = strtoupper($method);
$this->uri = $uri;
$this->query = $query;
$this->post = $post;
$this->server = $server;
$this->headers = $headers;
$this->cookies = $cookies;
$this->files = $files;
$this->body = $body;
}
/**
* 获取请求方法
*/
public function method()
{
return $this->method;
}
/**
* 获取请求地址
*/
public function uri()
{
return $this->uri;
}
/**
* 获取查询参数
*/
public function query($name = null, $default = null)
{
if ($name === null) {
return $this->query;
}
return isset($this->query[$name])
? $this->query[$name]
: $default;
}
/**
* 获取表单参数
*/
public function post($name = null, $default = null)
{
if ($name === null) {
return $this->post;
}
return isset($this->post[$name])
? $this->post[$name]
: $default;
}
/**
* 获取请求头
*/
public function header($name, $default = null)
{
$name = strtolower($name);
return isset($this->headers[$name])
? $this->headers[$name]
: $default;
}
/**
* 获取Cookie
*/
public function cookie($name, $default = null)
{
return isset($this->cookies[$name])
? $this->cookies[$name]
: $default;
}
/**
* 获取上传文件
*/
public function file($name)
{
return isset($this->files[$name])
? $this->files[$name]
: null;
}
/**
* 获取原始请求体
*/
public function body()
{
return $this->body;
}
/**
* 获取服务器信息
*/
public function server($name, $default = null)
{
return isset($this->server[$name])
? $this->server[$name]
: $default;
}
/**
* 判断请求方法
*/
public function isMethod($method)
{
return $this->method === strtoupper($method);
}
}
该请求对象将不同来源的 HTTP 请求数据保存为独立属性,并通过统一方法提供访问接口。
例如:
$request->method();
$request->query('id');
$request->post('username');
$request->header('content-type');
$request->cookie('session_id');
$request->file('upload');
$request->body();
需要注意,查询参数、表单参数和原始请求体是不同的数据来源,不能将它们混为同一个参数集合。对于 JSON 请求,数据通常位于原始请求体中,需要根据请求头声明的数据格式进行解析,不能假设所有 JSON 数据都会自动出现在 $_POST 中。
9.4 请求管理程序设计
请求管理程序负责从 PHP 当前 HTTP 运行环境中收集请求数据,并创建统一的请求对象。
请求对象只负责保存和提供请求数据,不能直接承担读取 PHP 超全局变量的职责。请求管理程序则负责与 PHP 运行环境交互,将不同来源的数据组织起来,再交给请求对象。
请求管理程序文件为:
framework/Http/RequestManager.php
基础实现如下:
<?php
namespace WangStruct\Framework\Http;
class RequestManager
{
/**
* 创建当前HTTP请求对象
*/
public function createFromGlobals()
{
$method = isset($_SERVER['REQUEST_METHOD'])
? $_SERVER['REQUEST_METHOD']
: 'GET';
$uri = isset($_SERVER['REQUEST_URI'])
? $_SERVER['REQUEST_URI']
: '/';
$query = $_GET;
$post = $_POST;
$server = $_SERVER;
$cookies = $_COOKIE;
$files = $_FILES;
$headers = $this->getHeaders();
$body = file_get_contents('php://input');
return new Request(
$method,
$uri,
$query,
$post,
$server,
$headers,
$cookies,
$files,
$body
);
}
/**
* 获取HTTP请求头
*/
protected function getHeaders()
{
$headers = array();
foreach ($_SERVER as $name => $value) {
if (strpos($name, 'HTTP_') === 0) {
$headerName = strtolower(
str_replace(
'_',
'-',
substr($name, 5)
)
);
$headers[$headerName] = $value;
}
}
if (isset($_SERVER['CONTENT_TYPE'])) {
$headers['content-type'] =
$_SERVER['CONTENT_TYPE'];
}
if (isset($_SERVER['CONTENT_LENGTH'])) {
$headers['content-length'] =
$_SERVER['CONTENT_LENGTH'];
}
return $headers;
}
}
createFromGlobals() 方法负责从当前 PHP HTTP 运行环境获取请求信息,并创建 Request 对象。
getHeaders() 方法负责整理 PHP 环境中可以获取的请求头信息,将请求头名称统一转换为小写形式,并使用连字符组织名称。
该实现是基础请求采集示例。实际工程还需要结合 PHP 运行环境和服务器配置处理代理转发头、请求体读取失败、上传文件错误以及请求数据大小限制等情况。特别是代理提供的客户端 IP、原始协议和主机信息不能直接视为可信数据,需要根据受信任代理配置进行判断。
9.5 HTTP 请求类型识别
HTTP 请求方法用于说明客户端希望服务器对目标资源执行何种操作。请求与响应组件需要统一识别请求方法,使应用程序能够通过请求对象判断当前请求类型。
常见 HTTP 请求方法包括:
GET 用于获取资源,POST 用于提交数据,PUT 用于提交目标资源的完整更新内容,PATCH 用于提交部分更新内容,DELETE 用于请求删除目标资源,HEAD 用于获取响应头而不返回响应主体,OPTIONS 用于查询目标资源支持的通信选项。
请求对象已经通过 method() 方法提供请求方法读取接口,通过 isMethod() 方法提供请求类型判断接口。
例如:
if ($request->isMethod('GET')) {
// GET请求处理
}
if ($request->isMethod('POST')) {
// POST请求处理
}
if ($request->isMethod('DELETE')) {
// DELETE请求处理
}
请求类型识别只负责判断 HTTP 请求方法,不负责决定业务操作是否合法。请求是否允许访问某个资源,还需要由路由、权限和业务处理程序共同判断。
对于不受框架支持的请求方法,应当按照 HTTP 请求处理规则返回相应错误,而不能将所有未知请求都默认为 GET 请求。
9.6 请求参数获取与数据处理
请求参数获取是请求对象的重要职责。不同请求方式携带的数据可能位于不同位置,因此请求组件需要保留参数来源,使应用程序能够明确读取所需数据。
GET 请求参数通常位于 URL 查询字符串中,PHP 将其解析为 $_GET。POST 表单数据通常由 PHP 解析到 $_POST。JSON 请求则需要通过 php://input 获取原始请求体,再使用 JSON 解析程序转换为 PHP 数据结构。
例如,客户端发送:
POST /api/user HTTP/1.1
Content-Type: application/json
{"username":"Wang","age":30}
请求管理程序获取原始请求体后,可以通过 JSON 解码形成数据结构:
$data = json_decode(
$request->body(),
true
);
对于 JSON 解析结果,需要检查解析是否成功,不能将解析失败的数据直接作为有效业务参数。
请求数据处理可以表示为:
其中,\(D_r\) 表示解析后的请求数据,\(B\) 表示原始请求体,\(H\) 表示请求头。解析程序根据请求头中的 Content-Type 判断数据格式,再使用相应解析方式处理。
请求参数获取与数据验证也需要分开。请求对象负责获取参数,数据验证程序负责检查参数类型、长度、格式和业务约束。不能因为参数能够被读取,就认为参数内容可信或符合业务要求。
9.7 HTTP 响应对象设计
响应对象负责组织应用程序需要返回给客户端的数据。应用程序完成处理后,可以通过响应对象设置状态码、响应头、响应内容和数据格式,再由响应管理程序统一输出。
响应对象的数据模型可以表示为:
其中,\(C\) 表示 HTTP 状态码,\(H\) 表示响应头,\(B\) 表示响应主体,\(F\) 表示响应数据格式。
响应对象文件为:
framework/Http/Response.php
基础实现如下:
<?php
namespace WangStruct\Framework\Http;
class Response
{
protected $statusCode = 200;
protected $headers = array();
protected $content = '';
/**
* 设置HTTP状态码
*/
public function setStatusCode($code)
{
$code = (int) $code;
if ($code < 100 || $code > 599) {
throw new \InvalidArgumentException(
'Invalid HTTP status code.'
);
}
$this->statusCode = $code;
return $this;
}
/**
* 获取HTTP状态码
*/
public function getStatusCode()
{
return $this->statusCode;
}
/**
* 设置响应头
*/
public function setHeader($name, $value)
{
$this->headers[$name] = $value;
return $this;
}
/**
* 获取响应头
*/
public function getHeaders()
{
return $this->headers;
}
/**
* 设置响应内容
*/
public function setContent($content)
{
$this->content = (string) $content;
return $this;
}
/**
* 获取响应内容
*/
public function getContent()
{
return $this->content;
}
}
响应对象提供状态码、响应头和响应内容的统一管理接口。
例如:
$response
->setStatusCode(200)
->setHeader('Content-Type', 'text/html; charset=UTF-8')
->setContent('<h1>WangStruct</h1>');
通过这种方式,应用程序只负责设置响应数据,不需要在业务代码中直接输出 HTTP 响应头和内容。
在完整工程中,响应头名称和值还需要经过格式检查,防止非法字符进入 HTTP 响应头,避免响应头注入问题。响应主体也需要根据实际数据类型确定编码方式。
9.8 响应管理程序设计
响应管理程序负责将响应对象保存的数据转换为实际 HTTP 输出。
响应对象只管理响应数据,响应管理程序负责调用 PHP 输出接口,将状态码、响应头和响应内容发送给客户端。
响应管理程序文件为:
framework/Http/ResponseManager.php
基础实现如下:
<?php
namespace WangStruct\Framework\Http;
class ResponseManager
{
/**
* 输出HTTP响应
*/
public function send(Response $response)
{
if (headers_sent()) {
throw new \RuntimeException(
'HTTP headers have already been sent.'
);
}
http_response_code(
$response->getStatusCode()
);
foreach ($response->getHeaders() as $name => $value) {
header(
$name . ': ' . $value,
true
);
}
echo $response->getContent();
}
}
send() 方法接收响应对象,首先检查 HTTP 响应头是否已经发送,然后设置状态码和响应头,最后输出响应主体。
响应输出必须发生在 HTTP 响应头尚未发送的阶段。若此前已经输出空格、HTML 或其他内容,PHP 就可能无法继续正确设置响应头。因此,框架需要统一管理响应输出时机,避免控制器和业务程序提前直接输出内容。
对于文件下载、流式输出和大文件响应,还需要扩展专门的输出处理机制,不能简单地将所有响应内容都保存为一个字符串后一次性输出。
9.9 响应状态码与响应头管理
HTTP 状态码用于表示服务器对当前请求的处理结果。响应对象需要提供统一的状态码设置接口,使应用程序能够根据处理结果返回适当的 HTTP 状态。
常见状态码包括:
| 状态码 | 含义 |
|---|---|
| 200 | 请求成功 |
| 201 | 资源创建成功 |
| 204 | 请求成功,无响应主体 |
| 301 | 永久重定向 |
| 302 | 临时重定向 |
| 400 | 请求数据错误 |
| 401 | 未通过身份认证 |
| 403 | 禁止访问 |
| 404 | 目标资源不存在 |
| 405 | 请求方法不被允许 |
| 500 | 服务器内部错误 |
响应头用于向客户端描述响应数据的属性和处理方式。例如,Content-Type 用于声明响应主体的数据格式,Cache-Control 用于表达缓存控制要求,Location 可以用于重定向响应。
响应对象通过 setHeader() 设置响应头。完整工程还应支持响应头删除、查询和多值处理,并对响应头名称和值执行合法性检查。
响应状态码与响应内容需要保持一致。例如,204 响应不应包含响应主体;重定向响应通常需要设置相应的 Location 响应头。响应管理程序应根据 HTTP 协议约束处理这些特殊情况。
9.10 响应数据格式处理
应用程序可能需要返回 HTML、JSON、纯文本或其他类型的数据。响应对象应当通过统一接口管理响应内容及其数据格式,避免应用程序在不同位置重复编写格式转换和响应头设置代码。
HTML 响应通常使用:
$response
->setHeader(
'Content-Type',
'text/html; charset=UTF-8'
)
->setContent('<h1>Welcome</h1>');
JSON 响应需要将 PHP 数据结构转换为 JSON 字符串:
$data = array(
'code' => 200,
'message' => 'success',
'data' => array(
'name' => 'WangStruct'
)
);
$json = json_encode(
$data,
JSON_UNESCAPED_UNICODE
);
if ($json === false) {
throw new RuntimeException(
'JSON encoding failed.'
);
}
$response
->setHeader(
'Content-Type',
'application/json; charset=UTF-8'
)
->setContent($json);
纯文本响应可以设置为:
$response
->setHeader(
'Content-Type',
'text/plain; charset=UTF-8'
)
->setContent('WangStruct Framework');
不同格式的响应具有不同的内容类型。响应管理程序负责输出最终内容,格式转换则应由对应的序列化程序或响应构建方法完成。
对于 JSON 数据,需要处理编码失败和无效数据。对于 HTML 内容,需要根据数据来源和输出位置执行适当的转义处理。不能因为响应对象能够输出字符串,就认为所有字符串都可以直接作为安全的 HTML 内容输出。
9.11 请求与响应组件的协同运行
请求对象和响应对象分别管理输入与输出,两者通过框架应用运行程序连接起来。
应用程序启动时,请求管理程序创建当前 HTTP 请求对象,并将其交给应用运行程序。应用运行程序根据请求信息组织后续处理,将请求对象传递给相应控制器。控制器完成处理后,返回或设置响应对象,最后由响应管理程序统一输出。
完整处理过程如下:
在这一过程中,请求对象与响应对象分别承担输入数据和输出数据的管理职责。应用运行程序负责组织调用关系,控制器负责处理具体请求,响应管理程序负责最终输出。
这样可以避免控制器直接读取大量 PHP 全局变量,也可以避免多个控制器分别使用 header() 和 echo 输出响应。
9.12 请求与响应组件的工程验证
请求与响应组件完成实现后,需要分别验证请求数据采集、请求对象访问、请求类型识别、响应数据组织和 HTTP 输出等过程。
请求对象验证需要检查请求方法、请求地址、查询参数、表单参数、请求头、Cookie、上传文件和原始请求体能否正确读取。不同来源的请求数据应当保持独立,不能出现查询参数和表单参数相互覆盖的情况。
请求类型验证需要分别发送 GET、POST、PUT、PATCH、DELETE、HEAD 和 OPTIONS 等请求,检查请求对象返回的请求方法是否正确。对于框架没有实现处理机制的请求方法,应验证其是否得到明确的错误响应。
请求数据格式验证需要分别使用表单数据和 JSON 数据进行测试,检查请求头识别、原始请求体读取和数据解析结果。对于格式错误的 JSON 数据,应能够识别解析失败,而不能将其作为有效数据继续传递。
响应对象验证需要检查状态码、响应头和响应主体的设置与读取过程。响应管理程序验证需要检查实际 HTTP 输出结果,包括状态码是否正确、响应头是否正确发送、响应主体是否完整。
还需要检查响应头已经发送时的异常处理,以及响应输出之前是否存在意外内容。对于 JSON 响应,需要验证输出内容是否符合 JSON 格式;对于 HTML 响应,需要检查字符编码和输出转义。
最后,将请求与响应组件纳入完整框架启动流程,验证外部请求能否经过请求管理程序进入应用程序,并由响应管理程序正确返回结果。
以上代码为工程实现示例。只有在实际文件创建、PHP 语法检查、请求测试和服务器运行验证完成后,才能确认组件达到对应的工程验收要求。
9.13 请求与响应组件的工程边界
请求与响应组件负责 HTTP 请求数据的采集、组织、访问和响应输出,不负责应用业务逻辑,也不负责完整的请求调度过程。
请求对象能够读取请求参数,不代表参数已经通过安全验证。请求参数是否符合业务要求,需要由后续数据验证程序负责。请求方法能够被识别,也不代表当前用户拥有执行对应操作的权限。访问权限需要由身份认证和权限管理机制处理。
响应对象能够设置状态码和响应内容,也不代表业务处理已经成功。应用程序需要根据实际处理结果决定响应状态,不能简单地将所有响应都设置为 200。
请求与响应组件也不负责路由匹配。请求对象提供请求地址和请求方法,路由组件根据这些信息确定目标处理程序。两者通过请求对象建立数据联系,但职责不能混淆。
对于文件上传、文件下载、流式响应、长连接和大文件传输等特殊 HTTP 场景,还需要根据具体工程需求扩展相应处理机制,不能将普通字符串响应接口视为所有 HTTP 通信场景的完整实现。
通过本章的工程设计,WangStruct Framework 建立了由 Request 请求对象、Response 响应对象、RequestManager 请求管理程序和 ResponseManager 响应管理程序组成的 HTTP 请求与响应处理基础结构,使外部请求能够通过统一对象进入框架,应用程序也能够通过统一响应接口返回处理结果,为后续路由管理、控制器调度和中间件机制提供基础。

