第十一章 控制器组件
控制器组件是应用程序运行过程中的功能组织与调用环节,负责接收路由管理组件传递的请求信息,协调请求对象、模型、视图及应用服务,组织应用程序的执行过程,并将处理结果返回给框架响应组件。
在 WangStruct Framework 中,控制器不是独立于框架运行的业务程序,而是按照统一规范组织起来的应用功能入口。框架通过控制器基础类、控制器加载机制和统一调用接口,建立控制器与其他应用组件之间的协作关系。
本章围绕控制器的基础结构、继承机制、创建方式、加载过程、方法调用、参数传递及结果返回展开设计,建立控制器与请求、模型、视图和应用服务之间的调用关系,使开发者能够按照统一的工程规范组织应用功能程序。
11.1 控制器组件的工程定位
在 Web 应用中,用户访问某个 URL 后,路由管理组件负责确定目标控制器和执行方法。控制器接收路由解析结果,结合当前请求信息,调用相应的数据模型、视图程序或应用服务,完成当前请求对应的功能处理。
例如,用户访问用户资料页面时,整个执行过程可以分为以下几个环节:
-
请求组件获取客户端提交的 HTTP 请求信息。
-
路由组件根据 URL 找到目标控制器和执行方法。
-
应用运行程序加载并调用目标控制器。
-
控制器获取请求参数。
-
控制器调用模型或应用服务处理相关数据。
-
控制器将处理结果交给视图组件,或者直接返回数据。
-
应用运行程序将结果交给响应组件输出。
控制器处于路由调度与应用功能执行之间,其主要职责是组织调用关系,而不是承担所有具体业务处理。
从工程结构上看,控制器组件需要建立以下几个方面的机制:
-
控制器基础类:定义应用控制器共同使用的基础接口。
-
控制器继承机制:使应用控制器能够继承框架提供的基础能力。
-
控制器创建机制:根据路由解析结果创建对应的控制器对象。
-
控制器加载机制:通过自动加载组件定位控制器类文件。
-
控制器调用机制:根据路由指定的方法执行相应程序。
-
组件调用机制:建立控制器与请求、模型、视图及应用服务之间的联系。
-
结果返回机制:统一处理控制器方法的执行结果。
控制器组件与其他框架组件之间的关系如下:
其中,模型、视图和应用服务属于控制器可以调用的应用层组件。本章重点建立调用关系,不提前限定这些组件内部的数据结构和具体实现方式。
11.2 控制器组件目录结构
控制器基础类属于框架核心程序,具体应用控制器则属于应用程序。两者应当分开组织,避免框架公共能力与应用业务程序混合。
本章涉及的工程目录结构如下:
WangStruct/
├── framework/ # 框架核心程序目录
│ ├── Controller/ # 控制器基础组件目录
│ │ └── Controller.php # 控制器基础类
│ ├── Core/ # 框架核心类目录
│ │ └── Application.php # 应用运行管理类
│ ├── Http/ # HTTP请求与响应组件目录
│ │ ├── Request.php # HTTP请求对象
│ │ └── Response.php # HTTP响应对象
│ ├── Router/ # 路由管理组件目录
│ │ └── Router.php # 路由注册与解析管理类
│ └── View/ # 视图组件目录
│ └── View.php # 视图管理类
├── app/ # 应用程序目录
│ ├── Controller/ # 应用控制器目录
│ │ ├── IndexController.php # 默认首页控制器
│ │ └── UserController.php # 用户功能控制器
│ ├── Model/ # 应用数据模型目录
│ │ └── UserModel.php # 用户数据模型
│ └── Service/ # 应用服务目录
│ └── UserService.php # 用户应用服务
└── public/ # Web访问入口目录
└── index.php # 框架启动入口
其中,framework/Controller/Controller.php 负责定义控制器基础能力;app/Controller/ 用于存放具体应用控制器;模型、视图和应用服务分别由对应组件或应用目录管理。
上述目录用于说明本章控制器组件与其他组件之间的组织关系。视图、模型和应用服务的内部结构及实现方式,应由相应章节分别确定。
11.3 控制器基础类设计
控制器基础类是应用控制器继承的公共父类,负责提供控制器运行过程中需要使用的基础接口。
应用开发者创建控制器时,不需要重复编写请求获取、视图调用和结果返回等公共操作,而是通过继承基础控制器类获得统一的调用入口。
控制器基础类主要承担以下职责:
-
保存当前请求对象。
-
提供请求对象访问接口。
-
提供视图调用接口。
-
提供控制器结果返回接口。
-
为模型和应用服务调用预留统一的组织方式。
-
为具体应用控制器提供共同的继承基础。
控制器基础类不应直接包含某个具体业务的处理代码。例如,用户登录、文章管理和订单处理等功能,应当分别由应用控制器及其调用的应用组件完成。
11.3.1 控制器基础类结构
控制器基础类可以采用 PHP 面向对象方式实现。
基础示例:
<?php
class Controller
{
protected $request;
protected $view;
public function __construct(
Request $request,
View $view
) {
$this->request = $request;
$this->view = $view;
}
public function getRequest()
{
return $this->request;
}
public function getView()
{
return $this->view;
}
public function assign($name, $value)
{
$this->view->assign($name, $value);
return $this;
}
public function render($template, $data = array())
{
return $this->view->render(
$template,
$data
);
}
public function response($content)
{
return $content;
}
}
该基础类通过构造方法接收请求对象和视图对象,并保存为控制器实例的成员属性。
getRequest() 用于获取当前请求对象,getView() 用于获取视图对象,assign() 用于向视图传递数据,render() 用于调用视图管理程序,response() 用于返回控制器处理结果。
这里的 View 和 Request 是前面及相关章节所设计的组件接口。实际工程中应当依据这些组件最终确定的接口实现进行衔接,不能仅凭示例假设它们已经具备所有方法。
11.4 控制器继承机制
控制器继承机制用于建立框架基础控制器与应用控制器之间的父子类关系。
框架提供公共基础类,应用程序根据具体功能创建不同的控制器类,并继承框架基础类。
例如:
<?php
class IndexController extends Controller
{
public function index()
{
return $this->render(
'index/index'
);
}
}
IndexController 通过 extends Controller 继承基础控制器的公共接口,因此不需要在每个应用控制器中重新定义请求对象和视图对象的基本访问方式。
对于用户功能,可以创建独立的控制器:
<?php
class UserController extends Controller
{
public function profile()
{
$id = $this->request->query('id');
return $this->render(
'user/profile',
array(
'userId' => $id
)
);
}
}
不同控制器可以分别组织自己的功能方法,但共同继承框架基础控制器。
控制器继承关系可以表示为:
这种继承关系使控制器公共能力集中在框架核心层,应用层只需要实现具体功能方法。
需要注意,继承机制用于复用公共接口,不意味着所有应用控制器都必须通过继承不断增加业务逻辑。控制器之间应保持相对独立,具体业务功能可以通过模型和应用服务进行组织。
11.5 控制器创建与加载机制
控制器创建与加载是将路由解析结果转换为控制器对象的过程。
路由管理组件返回的结果包含目标控制器名称和执行方法。应用运行程序根据这些信息定位控制器类,通过自动加载组件加载对应文件,再创建控制器实例。
例如,路由解析结果为:
$routeResult = array(
'controller' => 'UserController',
'action' => 'profile',
'params' => array()
);
应用运行程序需要完成以下处理:
-
读取控制器类名称。
-
根据应用控制器目录定位类文件。
-
通过自动加载机制加载类。
-
检查目标类是否存在。
-
创建控制器对象。
-
将请求对象及所需组件传入构造方法。
-
准备调用目标执行方法。
控制器类文件的加载由第八章设计的自动加载与类管理组件承担,控制器组件不应重复实现一套独立的文件加载机制。
11.5.1 控制器对象创建
控制器对象需要由应用运行程序统一创建,以保证控制器使用的请求对象和其他依赖组件来自当前应用运行环境。
基础创建示例:
<?php
$controllerClass = 'UserController';
$controller = new $controllerClass(
$request,
$view
);
这里的 $request 和 $view 分别代表当前应用运行过程中已经创建的请求对象和视图对象。
实际工程中,控制器类名必须经过框架定义的命名空间和应用目录映射规则处理,不能直接允许外部请求参数决定任意 PHP 类名。
11.5.2 控制器类加载
控制器加载依赖自动加载组件。
例如:
应用控制器名称:UserController
控制器文件路径:app/Controller/UserController.php
当应用运行程序创建 UserController 对象时,自动加载程序根据已经注册的命名空间与目录映射关系查找文件。
控制器加载过程可以表示为:
通过这种方式,控制器组件只负责定义控制器的对象规范和调用方式,类文件的查找及加载仍由自动加载组件负责。
11.6 控制器方法调用机制
控制器方法是应用功能的具体执行入口。一个控制器可以包含多个公共方法,每个方法对应一种应用操作。
例如:
<?php
class UserController extends Controller
{
public function index()
{
return $this->render('user/index');
}
public function profile()
{
return $this->render('user/profile');
}
public function detail()
{
return $this->render('user/detail');
}
}
路由管理组件负责确定调用哪个控制器和方法,应用运行程序负责执行实际调用。
例如:
/user/index → UserController::index()
/user/profile → UserController::profile()
/user/detail → UserController::detail()
控制器方法调用需要遵循统一规范:
-
目标控制器必须是框架允许加载的应用控制器。
-
目标方法必须存在。
-
目标方法必须符合框架定义的可调用规则。
-
外部请求参数不能直接作为任意类方法的调用依据。
-
方法执行结果应返回给应用运行程序统一处理。
11.6.1 控制器方法调用
基础调用示例:
<?php
$action = 'profile';
if (!method_exists($controller, $action)) {
throw new BadMethodCallException(
'Controller action not found.'
);
}
$reflection = new ReflectionMethod(
$controller,
$action
);
if (!$reflection->isPublic() || $reflection->isStatic()) {
throw new BadMethodCallException(
'Controller action is not callable.'
);
}
$result = $controller->$action();
这里使用反射检查目标方法是否为公开的非静态方法,避免将控制器内部的保护方法或私有方法作为外部访问入口。
实际工程还需要明确构造方法、析构方法及框架内部保留方法的访问限制,并由应用运行程序统一执行调用检查。
11.6.2 控制器参数传递
控制器方法可以根据路由规则接收动态路径参数。
例如:
<?php
class UserController extends Controller
{
public function detail($id)
{
return $this->render(
'user/detail',
array(
'userId' => $id
)
);
}
}
对应路由:
/user/{id} → UserController::detail($id)
客户端访问:
/user/1001
路由匹配程序提取参数:
$params = array(
'id' => '1001'
);
应用运行程序再根据已经确定的调用规范,将路由参数传递给控制器方法。
参数传递不能仅依赖数组顺序随意调用,还应当保证路由参数与目标方法参数之间具有明确的对应关系。
11.7 控制器与请求组件的调用关系
请求组件负责获取和管理客户端提交的 HTTP 请求信息,控制器通过请求对象读取当前请求的数据。
控制器不应直接在每个业务方法中重复访问 PHP 超全局变量,例如 $_GET、$_POST 和 $_SERVER。统一使用请求对象,可以使请求信息的读取方式保持一致。
例如:
<?php
class UserController extends Controller
{
public function login()
{
$username = $this->request->post(
'username'
);
$password = $this->request->post(
'password'
);
// 后续处理由应用服务负责
return array(
'username' => $username
);
}
}
这里控制器只负责取得当前请求参数,并组织后续调用。
请求对象的参数读取、请求方法识别和请求数据处理,仍由第九章的请求组件负责。
控制器与请求组件之间的关系可以表示为:
控制器通过请求对象获得数据,不直接承担底层 HTTP 请求采集工作。
11.8 控制器与模型组件的调用关系
模型组件负责组织应用数据及其相关操作。控制器可以根据当前功能需要调用模型,取得或处理相应的数据。
例如,用户资料控制器需要读取用户信息时,可以调用用户模型:
<?php
class UserController extends Controller
{
protected $userModel;
public function __construct(
Request $request,
View $view,
UserModel $userModel
) {
parent::__construct(
$request,
$view
);
$this->userModel = $userModel;
}
public function profile($id)
{
$user = $this->userModel->findById($id);
return $this->render(
'user/profile',
array(
'user' => $user
)
);
}
}
在这个调用关系中:
-
控制器接收路由传递的用户标识。
-
模型根据标识执行数据查询。
-
模型将查询结果返回给控制器。
-
控制器将数据传递给视图。
-
视图负责组织最终展示内容。
控制器负责组织调用顺序,模型负责处理其定义的数据操作。具体的数据查询规则和模型接口应当由模型组件设计确定。
11.9 控制器与视图组件的调用关系
视图组件负责将控制器提供的数据组织成最终展示内容。控制器可以调用视图管理程序,将数据传递给指定模板。
例如:
<?php
class IndexController extends Controller
{
public function index()
{
$data = array(
'title' => 'WangStruct Framework',
'description' => 'Framework application'
);
return $this->render(
'index/index',
$data
);
}
}
控制器通过 render() 调用视图组件,将模板名称和数据传递给视图管理程序。
其调用关系可以表示为:
控制器负责选择需要使用的模板并提供数据,视图组件负责模板加载、变量传递和内容渲染。
如果控制器需要返回 JSON 或普通文本数据,则不一定需要调用视图组件,可以直接将数据交给应用运行程序,由响应组件根据结果类型进行处理。
11.10 控制器与应用服务的调用关系
当某项应用功能涉及多个处理步骤时,可以通过应用服务组织具体操作,避免将大量功能处理代码集中写入控制器。
例如,用户注册可能涉及用户数据处理、数据保存及相关业务操作。控制器可以调用用户应用服务:
<?php
class UserController extends Controller
{
protected $userService;
public function __construct(
Request $request,
View $view,
UserService $userService
) {
parent::__construct(
$request,
$view
);
$this->userService = $userService;
}
public function register()
{
$data = array(
'username' => $this->request->post('username'),
'email' => $this->request->post('email')
);
$result = $this->userService->register(
$data
);
return $result;
}
}
控制器只负责获取请求数据、调用应用服务并接收执行结果。
应用服务负责其自身定义的应用功能处理。服务内部是否调用模型、其他服务或外部资源,由应用服务的工程设计确定。
控制器与应用服务之间的关系可以表示为:
该关系表示一种常见的调用组织方式,并不意味着所有控制器方法都必须经过应用服务。简单功能可以直接调用模型,具体调用层次应当根据应用程序的实际结构确定。
11.11 控制器返回结果管理
控制器方法执行完成后,需要将结果返回给应用运行程序。应用运行程序再根据结果类型,将其交给响应组件处理。
控制器返回结果可以分为以下几种常见类型:
| 返回结果 | 用途 |
|---|---|
| 字符串 | 返回普通文本内容 |
| 数组 | 返回结构化数据 |
| 视图渲染结果 | 返回模板生成的页面内容 |
| 响应对象 | 返回已经组织好的 HTTP 响应 |
例如,控制器可以返回普通文本:
public function hello()
{
return 'Hello WangStruct';
}
也可以返回结构化数据:
public function detail()
{
return array(
'id' => 1001,
'name' => 'Example User'
);
}
还可以返回视图渲染结果:
public function index()
{
return $this->render(
'index/index',
array(
'title' => '首页'
)
);
}
控制器不应直接在业务方法中混合输出内容、设置 HTTP 状态码和发送响应头。统一的响应处理应由响应组件负责。
控制器返回结果与响应组件之间的关系如下:
具体如何根据结果类型确定响应格式,应由应用运行程序与响应组件之间的接口规范确定。本章只建立控制器返回结果的基本组织方式。
11.12 控制器组件与应用运行程序的协同机制
控制器组件不能独立完成完整的请求执行过程,需要由应用运行程序统一组织控制器的创建、加载、调用和结果返回。
应用运行程序负责连接路由组件、自动加载组件、请求组件、控制器组件和响应组件。
整体运行过程如下:
从工程实现角度看,应用运行程序需要完成以下工作:
首先,接收路由管理组件返回的解析结果,确定目标控制器、方法和参数。
其次,调用自动加载组件加载目标控制器类,并检查类是否符合控制器调用规范。
然后,根据框架已经建立的组件创建机制准备请求对象、视图对象以及控制器需要的其他依赖对象。
接下来,创建控制器实例,检查目标方法的可调用状态,将路由参数传递给对应方法。
最后,接收控制器执行结果,交给响应组件统一处理。
这种组织方式使控制器只承担应用功能的组织职责,应用运行程序则负责控制器生命周期和组件之间的运行调度。
11.13 控制器组件的工程验证
控制器组件完成工程实现后,需要围绕基础类、继承关系、类加载、对象创建、方法调用、参数传递及结果返回开展验证。
11.13.1 基础类验证
检查控制器基础类是否能够正常加载,构造方法是否能够接收请求对象和视图对象,公共接口是否能够正常调用。
11.13.2 继承机制验证
创建一个继承基础控制器的应用控制器,检查父类方法是否能够正常访问,子类是否能够按照规范定义自己的功能方法。
11.13.3 控制器加载验证
通过路由管理组件提供的控制器名称,检查自动加载程序是否能够定位正确的控制器文件,并完成类加载。
同时检查不存在的控制器类是否能够被识别,避免加载失败后继续执行后续调用。
11.13.4 控制器方法调用验证
检查应用运行程序能否根据路由解析结果调用正确的方法,并验证不存在的方法、非公开方法和不符合调用规范的方法是否会被阻止。
11.13.5 参数传递验证
分别测试无参数方法和带动态路由参数的方法,检查路由参数与控制器方法参数之间的对应关系是否正确。
11.13.6 组件调用验证
检查控制器能否正确使用请求对象、模型、视图和应用服务,确认各组件返回的数据能够按照接口规范传递。
11.13.7 返回结果验证
分别测试普通文本、数组和视图渲染结果,检查应用运行程序能否正确接收控制器返回值,并交给响应组件处理。
实际工程验证应遵循统一开发流程:需求确认、检查实际文件、实施代码、本地 PHP 语法检查、适用的本地功能测试、同步服务器、服务器运行验证、修复复测及最终验收。代码示例和设计说明不代表实际工程已经完成实现或验证。
11.14 控制器组件的工程边界
控制器组件负责组织应用功能程序的执行过程,但不应取代其他组件的职责。
控制器基础类负责提供公共控制器接口,不负责实现具体应用业务。
控制器继承机制负责建立框架基础类与应用控制器之间的关系,不负责控制器文件的查找和加载。
控制器加载依赖自动加载组件,不应重复建设独立的类文件加载机制。
控制器方法调用依赖路由解析结果和应用运行程序,不允许外部 URL 直接决定任意 PHP 类或方法的执行。
控制器通过请求对象获取 HTTP 请求数据,不直接承担底层请求采集。
控制器可以调用模型处理应用数据,但不替代模型的数据管理职责。
控制器可以调用视图组织展示内容,但不替代视图组件的模板加载和渲染职责。
控制器可以调用应用服务组织功能处理,但不应将所有应用服务的处理逻辑集中到控制器中。
控制器返回执行结果,由应用运行程序和响应组件完成后续处理,不直接取代 HTTP 响应管理机制。
通过上述职责划分,控制器组件建立了路由管理、请求处理、模型操作、视图展示、应用服务和响应输出之间的统一调用关系。
本章完成了控制器基础类、继承机制、创建与加载、方法调用、参数传递及结果返回等工程设计,为 WangStruct Framework 的应用功能组织建立统一的控制器规范。




