Skip to content

18. 实践练习——第 8 版

我们将重新审视示例应用——第 5 版(及其由 JSON 文件配置的第 7 版)——并把它改造成客户端/服务器应用。这将使我们能够把上一章学到的有关 Web 服务的知识付诸实践。

18.1. 简介

第 5 版的架构如下:

Image

  • 名为 [dao] (Data Access Objects,数据访问对象)的层负责与 MySQL 数据库和本地文件系统的交互;
  • 名为 [business] 的层执行税额计算;
  • 主脚本充当协调者:它实例化 [dao] 和 [business] 层,然后与 [business] 层通信以执行必要的任务。

我们将把这个架构迁移为如下客户端/服务器架构:

Image

  • 在 [2] 中,我们将重用第 5 版的 [dao] 层,去掉访问本地文件系统的方法。这些方法将被迁移到 [dao] 层,即 [6, 7] 客户端的层;
  • 在 [3] 中,[business] 层将与第 5 版中保持一致,只是去掉了它的 [executeBatchTaxes] 方法,该方法被迁移到客户端的 [business] 和 [8] 层中;
  • 在 [4] 中,必须编写服务器脚本;它需要:
    • 创建 [business]、[dao] 和 [3, 2] 层;
    • 与客户端脚本 [5, 7] 通信;
  • 在 [7] 中,必须编写客户端的 [dao] 层:
    • 它将是服务器脚本 [4, 5] 的 HTTP 客户端;
    • 它将接管第 5 版 [dao] 层中访问本地文件系统的方法;
  • 在 [8] 中,客户端的 [business] 层将提供与第 5 版的 [InterfaceBusiness] 接口相同的方法。不过,其实现将有所不同。在第 5 版中,[business] 层执行税额计算。而这里,由服务器的 [business] 层执行这一计算。因此,客户端的 [business] 层将调用 [dao] 和 [7] 层来与服务器通信,并请求它计算税额;
  • 在 [9] 中,控制台脚本需要实例化客户端的 [dao, business] 层并启动它们的执行。

服务器是一个 Web 脚本:它位于 [scripts-web/tax/version-08] 文件夹中,由 [Laragon] 中的 Apache 服务器执行。客户端是一个控制台脚本:它位于 [scripts-console/tax/version-08] 文件夹中,在终端中执行。

18.2. 服务器

我们先关注应用的服务器端。

Image

这个架构将由如下文件来实现:

scripts-web/tax/version-08
├── Business
│   ├── InterfaceServerBusiness.php
│   └── ServerBusiness.php
├── Dao
│   ├── InterfaceServerDao.php
│   └── ServerDao.php
├── Data
│   ├── .htaccess
│   ├── config-server.json
│   ├── database-mysql.json
│   └── database-pgsql.json
├── Tests
│   ├── ServerBusinessTest.php
│   └── ServerDaoTest.php
└── tax-server.php

18.2.1. 层之间交换的实体

层之间交换的实体就是第 5 版中的那些:[TaxException] 异常、税务管理部门的数据 [TaxAdminData],以及数据库描述 [Database]。服务器还使用第 5 版的类 [Utilities],其方法 [readJsonFile] 被类 [Database] 使用。PHP 7 课程过去会把这些文件复制到服务器文件夹中。我们现在直接从 [scripts-console/tax/version-05] 文件夹加载它们:这样可以确保每个类只存在一个实例,并且在第 5 版中所做的任何修正都会惠及使用它的所有版本。

18.2.2. [dao] 层

[dao] 层实现如下 [InterfaceServerDao] 接口:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 服务器 [dao] 层的接口
interface InterfaceServerDao
{
    // 读取税务管理部门的数据
    // 出错时抛出 [TaxException] 异常
    public function getTaxAdminData(): TaxAdminData;
}
  • 第 13 行:[getTaxAdminData] 方法从税务机关的数据库中获取数据。

[InterfaceServerDao] 接口由如下 [ServerDao] 类实现:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 服务器的 [dao] 层:它在数据库中查找税务管理部门的数据
// 它是版本 5 的 [DaoTaxWithTaxAdminDataInDatabase] 类,去掉了
// 处理纳税人 JSON 文件的方法
class ServerDao implements InterfaceServerDao
{
    // 数据库的描述
    private readonly Database $database;
    // 包含税务管理部门数据的 [TaxAdminData] 对象
    // [protected]:派生类可以初始化它
    protected readonly TaxAdminData $taxAdminData;

    // 构造函数
    public function __construct(string $databaseFilename)
    {
        // 数据库的描述 - 可能抛出 [TaxException] 异常
        $this->database = Database::fromJsonFile($databaseFilename);
        $database = $this->database;
        try {
            // 打开数据库连接
            // 读取的行将以关联数组 [列 => 值] 的形式返回
            $connection = \PDO::connect(
                $database->dsn,
                $database->id,
                $database->pwd,
                [\PDO::ATTR_DEFAULT_FETCH_MODE => \PDO::FETCH_ASSOC]
            );
            // 开始一个事务
            $connection->beginTransaction();
            // 读取税率档表
            $brackets = $this->getBrackets($connection);
            // 读取常量表
            $constants = $this->getConstants($connection);
            // 成功结束事务
            $connection->commit();
        } catch (\PDOException $ex) {
            // 是否有正在进行的事务?
            if (isset($connection) && $connection->inTransaction()) {
                // 失败结束事务
                $connection->rollBack();
            }
            // 将错误以 [TaxException] 异常的形式向上传递给调用代码
            throw new TaxException("Database access error ({$ex->getMessage()})", 30, $ex);
        }
        // 构建 [TaxAdminData] 对象:对读取的数据进行检查
        $this->taxAdminData = TaxAdminData::fromArray([...$brackets, ...$constants]);
    }

这是第 5 版中 [DaoTaxWithTaxAdminDataInDatabase] 类的代码(在第 13 章中介绍过),去掉了提供读写纳税人 JSON 文件方法的 [TraitDao] 功能。随后的私有方法 [getBrackets] 和 [getConstants] (此处未列出)保持不变。只有一处不同:

  • 第 17 行:属性 [taxAdminData] 被声明为 [protected] 而不是 [private]。第 9 版将派生 [ServerDao] 类,派生类必须能够初始化这个属性。从 PHP 8.4 开始,只要继承的 [readonly] 属性不是私有的,派生类就可以对其初始化。

18.2.3. [business] 层

[business] 层实现如下 [InterfaceServerBusiness] 接口:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 服务器 [business] 层的接口
interface InterfaceServerBusiness
{
    // 计算纳税人的税款
    // 返回数组 [tax, surcharge, discount, reduction, rate]
    public function calculateTax(string $married, int $children, int $salary): array;
}

[InterfaceServerBusiness] 接口由如下 [ServerBusiness] 类实现:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 服务器的 [business] 层:版本 5 的 [Business] 类,去掉了 [executeBatchTax] 方法
class ServerBusiness implements InterfaceServerBusiness
{
    // 税务管理部门的数据
    private readonly TaxAdminData $taxAdminData;

    // [dao] 层由构造函数注入
    public function __construct(private readonly InterfaceServerDao $dao)
    {
        // 我们获取用于计算税款的数据
        // [getTaxAdminData] 方法可能抛出 [TaxException] 异常
        // 我们随后让它向上传播给调用代码
        $this->taxAdminData = $this->dao->getTaxAdminData();
    }

    // 税款计算
    // --------------------------------------------------------------------------
    #[\Override]
    public function calculateTax(string $married, int $children, int $salary): array
  • 第 9 行:类 [ServerBusiness] 就是第 5 版的类 [Business] ,只是去掉了它的方法 [executeBatchTaxes];
  • 第 15 行:构造函数接收一个类型为 [dao] 层的引用,其类型为 [InterfaceServerDao];
  • 第 26 行:[calculateTax] 方法及其使用的私有方法保持不变。该算法从第 1 版开始就已经讨论和解释过,其面向对象版本在第 13 章中介绍。

18.2.4. 服务器脚本

服务器脚本 [tax-server.php] 实现 [web] 和 [4] 层。它由如下 JSON 文件 [Data/config-server.json] 配置:

{
    "databaseFilename": "Data/database-mysql.json",
    "dependencies": [
        "../../../scripts-console/tax/version-05/Entities/TaxException.php",
        "../../../scripts-console/tax/version-05/Entities/TaxAdminData.php",
        "../../../scripts-console/tax/version-05/Entities/Database.php",
        "../../../scripts-console/tax/version-05/Utilities/Utilities.php",
        "Dao/InterfaceServerDao.php",
        "Dao/ServerDao.php",
        "Business/InterfaceServerBusiness.php",
        "Business/ServerBusiness.php"
    ],
    "users": [
        {
            "login": "admin",
            "passwd": "admin"
        }
    ]
}
  • 第 2 行:MySQL 数据库的 JSON 配置文件。这是第 7 版的 [database-mysql.json] 文件。[Data] 文件夹中还包含用于 PostgreSQL 数据库的 [database-pgsql.json] 文件:只需修改这一行,服务器就可以使用 PostgreSQL 工作;
  • 第 3–12 行:应用的 PHP 文件,其路径相对于服务器上的 [version-08] 文件夹。前四个来自第 5 版;
  • 第 13–18 行:授权使用该应用的用户列表。

与第 7 版一样,[rootDirectory] 键不再存在:脚本基于常量 [__DIR__] 计算自己的根文件夹。同样也不再有 [absoluteDependencies] 键,它曾提供 [vendor/autoload.php] 文件(来自 [Composer])的绝对路径:现在它是基于 [__DIR__] 确定的。

文件 [config-server.json] 位于服务器上的 [Data] 文件夹中,因此处于网站的目录结构之内:如果不采取预防措施,任何人都可以通过 URL [http://localhost/php8-oct-2026/scripts-web/tax/version-08/Data/config-server.json] 下载它并读取用户凭据。包含数据库密码的文件 [database-mysql.json],也是如此。因此,[Data] 文件夹中包含一个名为 [.htaccess] 的文件:

# [Data] 文件夹包含密码:Apache 拒绝提供其中的文件
Require all denied

名为 [.htaccess] 的文件包含 Apache 服务器配置指令,这些指令适用于包含它的文件夹及其子文件夹。[Require all denied] 指令拒绝访问该文件夹:对于 [Data] 文件夹中文件的任何请求,Apache 都会以 [403 Forbidden] 响应。而 PHP 脚本则直接从磁盘读取这些文件,不经过 Apache,因此不受影响。

脚本 [tax-server.php] 如下实现 [web] 层:

<?php

// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);

// 命名空间
namespace Application;

// Symfony 依赖
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

// 服务器的根文件夹:配置文件的路径相对于此文件夹
const ROOT_DIRECTORY = __DIR__;
// 配置文件的路径
const CONFIG_FILENAME = ROOT_DIRECTORY . "/Data/config-server.json";

// 获取配置
$config = json_decode(file_get_contents(CONFIG_FILENAME), true, flags: JSON_THROW_ON_ERROR);

// 引入脚本所需的依赖
require_once ROOT_DIRECTORY . "/../../../vendor/autoload.php";
foreach ($config["dependencies"] as $dependency) {
    require_once ROOT_DIRECTORY . "/$dependency";
}

// 准备服务器的 JSON 响应
$response = new JsonResponse();
// 重音字符和 / 不转义,浮点数始终带小数点写出 (0.0)
$response->setEncodingOptions(JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_PRESERVE_ZERO_FRACTION);

// 我们获取当前请求
$request = Request::createFromGlobals();
// 身份验证:客户端发送的凭据(如果它没有发送则为 null)
$requestUser = $request->getUser();
$requestPassword = $request->getPassword();
// 该用户是授权用户之一吗?
$found = $requestUser !== null && $requestPassword !== null
    && array_any(
        $config["users"],
        fn(array $user): bool => $user["login"] === $requestUser && hash_equals($user["passwd"], $requestPassword)
    );
if (!$found) {
    // 未找到 - 代码 401
    $response->setStatusCode(Response::HTTP_UNAUTHORIZED);
    $response->headers->set("WWW-Authenticate", 'Basic realm="Tax calculation server"');
    // 错误消息
    $response->setData(["response" => ["error" => "Authentication failed [$requestUser]"]]);
    $response->send();
    // 结束
    exit;
}

// 我们有了有效的用户 - 检查收到的参数
$errors = [];
// 必须是带三个参数的 GET 请求
if ($request->getMethod() !== "GET" || $request->query->count() !== 3) {
    $errors[] = "GET method required with only the parameters [married, children, salary]";
}
// 婚姻状况
if (!$request->query->has("married")) {
    $errors[] = "missing married parameter";
} else {
    $married = strtolower(trim($request->query->getString("married")));
    if (!in_array($married, ["yes", "no"], true)) {
        $errors[] = "invalid married parameter [$married]";
    }
}
// 子女数和工资:整数 >= 0
$values = [];
foreach (["children", "salary"] as $parameter) {
    if (!$request->query->has($parameter)) {
        $errors[] = "missing $parameter parameter";
        continue;
    }
    $value = trim($request->query->getString($parameter));
    if (preg_match('/^\d+$/', $value) !== 1) {
        $errors[] = "invalid $parameter parameter [$value]";
    } else {
        $values[$parameter] = (int) $value;
    }
}
// 请求中还有其他参数吗?
foreach (array_diff(array_keys($request->query->all()), ["married", "children", "salary"]) as $parameter) {
    $errors[] = "invalid parameter [$parameter]";
}
// 有错误吗?
if ($errors !== []) {
    // 我们向客户端发送 400 错误代码
    $response->setStatusCode(Response::HTTP_BAD_REQUEST);
    $response->setData(["response" => ["errors" => $errors]]);
    $response->send();
    exit;
}

// 我们已具备工作所需的一切
// 构建服务器的架构
try {
    // 创建 [dao] 层
    $dao = new ServerDao(ROOT_DIRECTORY . "/" . $config["databaseFilename"]);
    // 创建 [business] 层
    $business = new ServerBusiness($dao);
} catch (TaxException $ex) {
    // DBMS 驱动的错误消息可能不是 UTF-8 编码(Windows 上是 Windows-1252)
    $message = $ex->getMessage();
    if (!mb_check_encoding($message, "UTF-8")) {
        $message = mb_convert_encoding($message, "UTF-8", "Windows-1252");
    }
    // 我们向客户端发送 500 错误代码
    $response->setStatusCode(Response::HTTP_INTERNAL_SERVER_ERROR);
    $response->setData(["response" => ["error" => $message]]);
    $response->send();
    exit;
}
// 税款计算
$result = $business->calculateTax($married, $values["children"], $values["salary"]);
// 我们返回响应
$response->setData(["response" => $result]);
$response->send();

说明

  • 第 10–12 行:声明将要使用的 [HttpFoundation] 库中的类;
  • 第 15 行:服务器的根目录就是脚本所在的目录;
  • 第 20 行:加载配置文件;
  • 第 23–26 行:我们加载 [Composer] 的类加载器,然后加载应用的所有文件;
  • 第 29 行:我们准备一个 JSON 响应。[JsonResponse] 类是 [Response] 的子类:它的 [setData] 方法把传给它的数组编码为 JSON,并将其用作响应主体。它还设置 HTTP 头 [Content-Type: application/json];
  • 第 31 行:函数 [json_encode] 的选项,由 [setData] 使用。使用 [JSON_UNESCAPED_UNICODE] 时,带重音的字符不会被编码为 [\uXXXX]。使用 [JSON_PRESERVE_ZERO_FRACTION] 时,实际税率 [0.0] 会写成 [0.0] 而不是 [0]:客户端会把它解码为浮点数(float)而不是整数;
  • 第 36–37 行:与上一章一样,我们获取客户端发送的标识符;
  • 第 39–43 行:我们验证该用户确实是授权用户之一。如果数组 [array_any] 函数(PHP 8.4)中至少有一个元素满足传给它的箭头函数所表达的条件,它就返回 [true] ——这里的数组是 [$config["users"]] 。它取代了 PHP 7 脚本中的 [while] 循环。密码使用 [hash_equals] 进行比较;
  • 第 44–52 行:如果不是这样,就发送 HTTP 状态码 [401 Unauthorized],表示访问被拒绝。浏览器收到这个状态码和 HTTP 头 [WWW-Authenticate: Basic realm=…] 后,会显示一个身份验证窗口,提示用户进行身份验证;
  • 第 49 行:服务器的 JSON 响应说明了错误的原因。所有服务器响应都将是数组 [["response" => something]] 的 JSON 字符串。PHP 7 的脚本会把被拒绝的用户名和密码返回给客户端。密码绝不能返回,也不能写入日志:我们只返回用户名;
  • 第 56–88 行:我们验证请求的有效性:
    • 一个恰好带有三个参数的 GET 请求;
    • 参数 [married] 的值必须是 [yes] 或 [no];
    • 参数 [children],其值必须是 >= 0 的整数;
    • 参数 [salary],其值必须是大于或等于 0 的整数;
    • 没有其他参数;
  • 第 59 行:每检测到一个错误,就向数组 [$errors] 中添加一条错误消息;
  • 第 65 行:对象 [$request->query] 的方法 [getString] 以字符串形式返回参数值;
  • 第 72 行:参数 [children] 和 [salary] 遵循相同的规则:它们在同一个循环中检查。它们转换为整数的值被放入数组 [$values] 中;
  • 第 85 行:函数 [array_diff] 返回收到的参数中不在列表 [married, children, salary] 中的参数名称;
  • 第 89 行:如果发生错误,就向客户端发送 HTTP 状态码 [400 Bad Request]。JSON 响应包含错误列表;
  • 第 99–104 行:从这里开始,查询已经通过了验证。可以实例化 [dao, business] 层了。这种实例化会带来开销(读取数据库),因此只有在确定查询有效时才应执行。构造 [dao] 层可能会抛出 [TaxException] 类型的异常;
  • 第 106–108 行:错误消息往往来自数据库管理系统的 PDO 驱动程序。在 Windows 上,它有时可能是以 Windows-1252 而不是 UTF-8 编码的。然而,[json_encode] 函数只接受 UTF-8 字符串:此时 [JsonResponse] 会抛出异常。[mb_check_encoding] 函数检查字符串的编码,[mb_convert_encoding] 函数在必要时对其进行转换。PHP 7 的脚本使用的是函数 [utf8_encode],它自 PHP 8.2 起已被弃用;
  • 第 111 行:如果发生了异常,就向客户端发送 HTTP 状态码 [500 Internal Server Error]。这个状态码表示服务器无法处理一个有效的请求。响应中说明了错误的原因;
  • 第 117 行:税额计算委托给 [business] 层;
  • 第 119–120 行:发送响应,使用默认状态码 [200 OK]。

让我们测试这个脚本。在浏览器中,请求 URL [http://localhost/php8-oct-2026/scripts-web/tax/version-08/tax-server.php?married=yes&children=2&salary=55555]。浏览器会显示其身份验证窗口,在其中输入 [admin] 和 [admin]。然后它会显示服务器的响应:JSON。如果服务器拒绝这些凭据,请参见上一章中的“当服务器始终响应 401 时”一节。

18.2.4.1. 为什么用 [http] 而不是 [https]?

客户端会发送其凭据:严格来说,URL 应当是安全的([https]),正如我们在上一章中看到的。但现代浏览器([Chrome]、[Edge]、[Firefox])只有在服务器证书由它们信任的证书颁发机构签发时,才会接受 HTTPS 页面。[Laragon] 为 [localhost] 生成的证书是自签名的:没有任何人为它担保。根据浏览器版本及其缓存状态的不同,浏览器要么显示带有链接([Proceed to localhost (unsafe)])的警告,要么拒绝加载页面而不提供继续的选项。当浏览器已记录 [localhost] 必须始终使用有效证书提供服务(HSTS 机制),或者认为该证书不合规时,就会发生这种情况。上一章中介绍的解决办法(把 [Laragon] 证书添加到 [Windows] 证书存储、删除 HSTS 规则)并不总是足够。

因此我们在浏览器中使用未加密的 URL [http://localhost/...]。这在这里并不是安全疏漏:发往 [localhost] 的请求永远不会离开本机(它经过内部网络接口,称为“回环”接口),任何间谍软件都无法在网络上截获它。顺便说一句,Web 浏览器也知道这一点:它们把 [http://localhost] 视为可信来源。另一方面,一旦服务器可以从网络访问——尤其是在生产环境中——就必须使用 HTTPS 协议,并配备由公认机构签发的有效证书(例如由 [Let's Encrypt] 免费签发)。

不过,我们编写的客户端并不是浏览器:[curl] 命令(选项 [-k])和 Symfony 客户端 [HttpClient](选项 [verify_peer] 通过 [false])可以接受 [Laragon] 的自签名证书。然而,这要求已在 [Laragon] 中启用 HTTPS 协议([Apache / SSL / Enabled] 菜单),而默认情况下并未启用,并且这个证书在该机器上必须可用。为了确保这些示例在任何 [Laragon] 安装上都能运行,我们因此在本章和后续各章中始终使用 URL [http://localhost/...]:在浏览器中、在 [curl] 命令中,以及在客户端配置文件中([urlServer] 键)。要切换到 HTTPS,只需在这些 URL 中把 [http] 替换为 [https] ,并将 [-k] 选项加入 [curl] 命令:客户端配置文件中已经包含了必要的选项 [verify_peer] 和 [verify_host],在与 [http] 一起使用时它们不起作用。两种方案的结果相同。

让我们用 [curl] 运行同样的查询。URL 中的非 ASCII 字符必须经过编码:例如,字符 [é] 被编码为 [%C3%A9](它按 UTF-8 编码的两个字节)。浏览器会自行完成这种编码:

> curl -i -u admin:admin "http://localhost/php8-oct-2026/scripts-web/tax/version-08/tax-server.php?married=yes&children=2&salary=55555"
HTTP/1.0 200 OK
Date: Fri, 02 Oct 2026 12:29:49 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json

{"response":{"tax":2814,"surcharge":0,"discount":0,"reduction":0,"rate":0.14}}
  • 第 2 行:状态码 [200 OK];
  • 第 8 行:由类 [Content-Type: application/json] 定义的 HTTP 头 [JsonResponse];
  • 第 10 行:服务器的 JSON 响应。

没有凭据时(没有 [-u] 选项),返回状态码 [401 Unauthorized]:

> curl -i "http://localhost/php8-oct-2026/scripts-web/tax/version-08/tax-server.php?married=yes&children=2&salary=55555"
HTTP/1.0 401 Unauthorized
Date: Fri, 02 Oct 2026 12:29:49 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
WWW-Authenticate: Basic realm="Tax calculation server"
Connection: close
Content-Type: application/json

{"response":{"error":"Authentication failed []"}}

让我们运行几个错误测试。我们请求 URL [http://localhost/php8-oct-2026/scripts-web/tax/version-08/tax-server.php?married=x&children=x&salary=x&w=x]:

> curl -i -u admin:admin "http://localhost/php8-oct-2026/scripts-web/tax/version-08/tax-server.php?married=x&children=x&salary=x&w=x"
HTTP/1.0 400 Bad Request
Date: Fri, 02 Oct 2026 12:29:49 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json

{"response":{"errors":["GET method required with only the parameters [married, children, salary]","invalid married parameter [x]","invalid children parameter [x]","invalid salary parameter [x]","invalid parameter [w]"]}}

不带参数的 POST 请求([curl] 的选项 [-X POST] ):

> curl -i -u admin:admin -X POST "http://localhost/php8-oct-2026/scripts-web/tax/version-08/tax-server.php"
HTTP/1.0 400 Bad Request
Date: Fri, 02 Oct 2026 12:29:49 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json

{"response":{"errors":["GET method required with only the parameters [married, children, salary]","missing married parameter","missing children parameter","missing salary parameter"]}}

现在让我们模拟数据库管理系统的故障。我们可以在 [Laragon] 窗口中停止 MySQL。我们改为把 [database-mysql.json] 文件中的 DSN 条目修改为 [mysql:host=127.0.0.1;port=3307;dbname=dbtaxes-2019;charset=utf8mb4]:没有数据库管理系统在 3307 端口上监听,连接被拒绝,就像 MySQL 已停止时一样:

> curl -i -u admin:admin "http://localhost/php8-oct-2026/scripts-web/tax/version-08/tax-server.php?married=yes&children=3&salary=60000"
HTTP/1.0 500 Internal Server Error
Date: Fri, 02 Oct 2026 12:29:50 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json

{"response":{"error":"Database access error (SQLSTATE[HY000] [2002] Connection refused)"}}
  • 第 2 行:状态码 [500 Internal Server Error];
  • 第 10 行:异常消息 [TaxException] 由 [dao] 层抛出。在 Windows 上,驱动程序的消息是法语的:[Aucune connexion n'a pu être établie car l'ordinateur cible l'a expressément refusée]。

然后恢复原来的 DSN。

18.2.5. [PHPUnit] 测试

每次构建服务器的新版本时,我们都会像从第 4 版以来所做的那样测试 [dao] 和 [business] 层。这些测试不经过 Web 服务器:它们像服务器脚本那样构建 [dao] 和 [business] 层,并直接对其进行测试。它们位于服务器上的 [Tests] 文件夹中。PHP 7 课程使用的是 [Codeception] 测试框架;我们则像前面各章一样使用 [PHPUnit]。

18.2.5.1. [dao] 层测试

[Tests/ServerDaoTest.php] 测试如下:

<?php

// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);

// 测试的命名空间
namespace Application\Tests;

// 被测试的类
use Application\ServerDao;
// PHPUnit 的类
use PHPUnit\Framework\TestCase;

final class ServerDaoTest extends TestCase
{
    // 服务器的根文件夹
    private const string ROOT_DIRECTORY = __DIR__ . "/..";
    // 服务器的配置
    private static array $config;

    // 在类的第一个测试之前执行一次
    #[\Override]
    public static function setUpBeforeClass(): void
    {
        // 我们获取服务器的配置
        self::$config = json_decode(file_get_contents(self::ROOT_DIRECTORY . "/Data/config-server.json"), true, flags: JSON_THROW_ON_ERROR);
        // 我们引入服务器的依赖
        foreach (self::$config["dependencies"] as $dependency) {
            require_once self::ROOT_DIRECTORY . "/$dependency";
        }
    }

    // 从数据库读取的税务管理部门数据
    public function testTaxAdminData(): void
    {
        // 像在服务器脚本中那样创建 [dao] 层
        $dao = new ServerDao(self::ROOT_DIRECTORY . "/" . self::$config["databaseFilename"]);
        $taxAdminData = $dao->getTaxAdminData();
        // 计算常量
        $this->assertSame(1551.0, $taxAdminData->halfShareQfCeiling);
        $this->assertSame(21037.0, $taxAdminData->singleIncomeCeilingForReduction);

说明

  • 第 23–31 行:我们建立与服务器脚本 [tax-server.php] 中相同的工作环境:读取配置文件并加载应用文件。无需加载 [Composer] 的类加载器:[PHPUnit] 已经加载了它;
  • 第 37 行:我们像服务器脚本中那样,创建待测试的 [dao] 层的一个实例;
  • 从这里开始,条件与服务器脚本中相同:[testTaxAdminData] 方法的其余部分(此处未列出)与第 5 至第 7 版的 [DaoTest] 测试相同。

18.2.5.2. [business] 层的测试

[Tests/ServerBusinessTest.php] 测试如下:

<?php

// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);

// 测试的命名空间
namespace Application\Tests;

// 被测试的类
use Application\InterfaceServerBusiness;
use Application\ServerDao;
use Application\ServerBusiness;
// PHPUnit 的类
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;

final class ServerBusinessTest extends TestCase
{
    // 服务器的根文件夹
    private const string ROOT_DIRECTORY = __DIR__ . "/..";
    // 服务器的配置
    private static array $config;
    // 被测试的 [business] 层
    private InterfaceServerBusiness $business;

    // 在类的第一个测试之前执行一次
    #[\Override]
    public static function setUpBeforeClass(): void
    {
        // 我们获取服务器的配置
        self::$config = json_decode(file_get_contents(self::ROOT_DIRECTORY . "/Data/config-server.json"), true, flags: JSON_THROW_ON_ERROR);
        // 我们引入服务器的依赖
        foreach (self::$config["dependencies"] as $dependency) {
            require_once self::ROOT_DIRECTORY . "/$dependency";
        }
    }

    // 在每个测试之前执行
    #[\Override]
    protected function setUp(): void
    {
        // 像在服务器脚本中那样创建 [dao] 层和 [business] 层
        $dao = new ServerDao(self::ROOT_DIRECTORY . "/" . self::$config["databaseFilename"]);
        $this->business = new ServerBusiness($dao);
    }

    // 官方数据表中的纳税人
    public static function taxpayers(): array

说明

  • 第 28–36 行:我们建立与服务器脚本中相同的工作环境;
  • 第 40–44 行:在每个测试之前,像服务器脚本中那样创建待测试的 [business] 层的一个实例;
  • 测试的其余部分(此处未列出)与第 4 至第 7 版的 [BusinessTest] 测试相同:一个包含官方数据表中 11 位纳税人的 [taxpayers] 数据提供者,以及 [testCalculateTax] 方法。

测试结果如下(MySQL 数据库管理系统必须处于运行状态):

> php vendor/bin/phpunit scripts-web/tax/version-08/Tests --testdox
PHPUnit 12.5.37 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.5.11
Configuration: .../php8-oct-2026/phpunit.xml

............                                                      12 / 12 (100%)

Time: 00:00.014, Memory: 16.00 MB

Server Business (Application\Tests\ServerBusiness)
 ✔ Calculate tax with data set "couple, 2 children, 55555"
 ✔ Calculate tax with data set "couple, 2 children, 50000"
 ✔ Calculate tax with data set "couple, 3 children, 50000"
 ✔ Calculate tax with data set "single, 2 children, 100000"
 ✔ Calculate tax with data set "single, 3 children, 100000"
 ✔ Calculate tax with data set "couple, 3 children, 100000"
 ✔ Calculate tax with data set "couple, 5 children, 100000"
 ✔ Calculate tax with data set "single, 0 children, 100000"
 ✔ Calculate tax with data set "couple, 2 children, 30000"
 ✔ Calculate tax with data set "single, 0 children, 200000"
 ✔ Calculate tax with data set "couple, 3 children, 200000"

Server Dao (Application\Tests\ServerDao)
 ✔ Tax admin data

OK (12 tests, 35 assertions)

18.3. 客户端

我们接下来关注应用的客户端。

Image

这个架构将由如下文件来实现:

scripts-console/tax/version-08
├── Business
│   ├── ClientBusiness.php
│   └── InterfaceClientBusiness.php
├── Dao
│   ├── ClientDao.php
│   └── InterfaceClientDao.php
├── Data
│   ├── config-client-ko.json
│   ├── config-client-unreachable.json
│   ├── config-client.json
│   ├── errors.json
│   ├── results.json
│   └── taxpayersdata.json
├── Main
│   └── MainTaxClient.php
└── Tests
    └── ClientBusinessTest.php

18.3.1. 层之间交换的实体

客户端的实体都已经介绍过,并且已在第 5 版中使用:

  • 异常 [TaxException];
  • 纳税人数据 [TaxPayerData]。

与服务器一样,客户端也从第 5 版的文件夹中加载它们,同时加载类 [Utilities] 和 trait [TraitDao]。

18.3.2. [dao] 层

[dao] 层实现如下 [InterfaceClientDao] 接口:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 客户端 [dao] 层的接口
// 出错时所有方法都会抛出 [TaxException] 异常
interface InterfaceClientDao
{
    // 读取纳税人数据
    // 不正确的数据会报告到 JSON 文件 [$errorsFilename] 中
    /** @return TaxPayerData[] */
    public function getTaxPayersData(string $taxPayersFilename, string $errorsFilename): array;

    // 由服务器计算纳税人的税款
    // 返回数组 [tax, surcharge, discount, reduction, rate]
    public function calculateTax(string $married, int $children, int $salary): array;

    // 保存结果
    /** @param TaxPayerData[] $taxPayersData */
    public function saveResults(string $resultsFilename, array $taxPayersData): void;
}
  • 第 15 行:[getTaxPayersData] 方法把纳税人数据从 JSON 文件 [$taxPayersFilename] 加载到内存中。如果有任何错误,它们会被记录到 JSON 文件 [$errorsFilename] 中;
  • 第 19 行:[calculateTax] 方法计算某位纳税人的税额;
  • 第 23 行:方法 [saveResults] 把表 [$taxPayersData]——代表若干次税额计算的结果——中的数据保存到文件 [$resultsFilename] 中。

方法 [getTaxPayersData] 和 [saveResults] 属于第 5 版中的 [InterfaceDao] 接口。[InterfaceClientDao] 接口由如下 [ClientDao] 类实现:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// Symfony 依赖
use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;
use Symfony\Contracts\HttpClient\HttpClientInterface;

// 客户端的 [dao] 层:税款计算服务器的 HTTP 客户端
class ClientDao implements InterfaceClientDao
{
    // 版本 5 的 trait 实现了接口的 [getTaxPayersData] 和 [saveResults] 方法
    use TraitDao;

    // HTTP 客户端
    private readonly HttpClientInterface $httpClient;

    // 构造函数
    // $urlServer:税款计算服务器的 URL
    // $user:发出请求的用户,数组 [login, passwd]
    // $httpClientOptions:HTTP 客户端的附加选项(verify_peer、verify_host……)
    public function __construct(
        private readonly string $urlServer,
        #[\SensitiveParameter] array $user,
        array $httpClientOptions = [],
    ) {
        // HTTP 客户端:用户的凭据将随每个请求一起发送
        $this->httpClient = HttpClient::create([
            ...$httpClientOptions,
            "auth_basic" => [$user["login"], $user["passwd"]],
        ]);
    }

    // 由服务器计算税款
    #[\Override]
    public function calculateTax(string $married, int $children, int $salary): array
    {
        try {
            // 我们向服务器发出请求
            $response = $this->httpClient->request("GET", $this->urlServer, [
                "query" => [
                    "married" => $married,
                    "children" => $children,
                    "salary" => $salary,
                ],
            ]);
            // 响应的状态
            $statusCode = $response->getStatusCode();
            // 响应的 JSON 文档,即使状态是错误代码也是如此(参数 false)
            $json = $response->getContent(false);
        } catch (ExceptionInterface $ex) {
            // 无法连接到服务器
            throw new TaxException("Error communicating with the server ({$ex->getMessage()})", 40, $ex);
        }
        // 日志
        // print "$json\n";
        // 服务器发送数组 ["response" => something] 的 JSON 字符串
        try {
            $serverResponse = json_decode($json, true, flags: JSON_THROW_ON_ERROR)["response"] ?? null;
        } catch (\JsonException $ex) {
            $serverResponse = null;
        }
        if (!is_array($serverResponse)) {
            throw new TaxException("Invalid server response [$json]", 41);
        }
        // 出错?
        if ($statusCode !== 200) {
            // 我们抛出一个异常,其消息是服务器的响应并补充其 HTTP 状态
            $message = json_encode(
                ["HTTP status" => $statusCode] + $serverResponse,
                JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR
            );
            throw new TaxException($message, 42);
        }
        // 我们返回响应:数组 [tax, surcharge, discount, reduction, rate]
        return $serverResponse;
    }
}

说明

  • 第 17 行:我们引入第 5 版的 [TraitDao] 类,它实现了 [getTaxPayersData] 和 [saveResults] 方法。这样就只剩下 [calculateTax] 方法需要实现;
  • 第 20 行:[Symfony] 的 HTTP 客户端,其类型为接口 [HttpClientInterface];
  • 第 26–30 行:[ClientDao] 类的构造函数接受三个参数:
    • 税额计算服务器的 URL [$urlServer] 。这是一个被提升为属性的参数(构造函数属性提升);
    • 数组 [$user] ,其键为 [login] 和 [passwd],它定义了发出请求的用户。属性(注解)[#[\SensitiveParameter]] (PHP 8.2)指示 PHP 在出错时显示的堆栈跟踪中隐藏该参数的值:密码不会出现在其中;
    • HTTP 客户端的附加选项;
  • 第 32–35 行:HTTP 客户端只创建一次,使用接收到的选项,并补充选项 [auth_basic]:用户的凭据将随每个请求发送。运算符 [...] 把数组 [$httpClientOptions] 中的元素复制到选项数组中。PHP 7 的客户端会为每个请求创建一个新的 HTTP 客户端;
  • 第 40 行:[calculateTax] 方法接收要发送给税额计算服务器的三个参数;
  • 第 44–50 行:用服务器所期望的三个参数向其发起查询。[query] 选项在对这些参数编码之后把它们添加到 URL 中;
  • 第 54 行:从服务器获取 JSON 响应。如果没有把参数 [false] 传给方法 [getContent],那么当服务器响应状态表示错误(3xx–5xx 状态码)时,HTTP 客户端一旦尝试获取响应内容就会抛出异常。这里,无论响应的 HTTP 状态如何,我们都想访问其内容,这就是传入该参数的原因;
  • 第 55–57 行:如果无法连接到服务器,HTTP 客户端会抛出 [ExceptionInterface] 异常。我们把它转换为 [TaxException] 异常:这样,客户端的上层只需处理一种异常类型;
  • 第 60 行:在开发模式下,可以显示服务器的 JSON 响应;
  • 第 63–68 行:服务器的响应是数组 [["response" => something]] 的 JSON 字符串。我们取出 [something]。如果收到的文档不是 JSON(例如 Apache 的 HTML 错误页面),我们就抛出 [TaxException] 异常;
  • 第 71–77 行:如果 HTTP 状态码不是 200,则说明服务器遇到了问题。此时会抛出 [TaxException] 类型的异常,其消息由服务器的 JSON 响应再加上 HTTP 响应码构成。运算符 [+] 用于合并两个关联数组;
  • 第 80 行:结果以关联数组的形式返回,其键为 [tax, surcharge, discount, reduction, rate]。

18.3.3. [business] 层

[business] [8] 层实现如下 [InterfaceClientBusiness] 接口:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 客户端 [business] 层的接口
interface InterfaceClientBusiness
{
    // 计算一位纳税人的税款
    // 返回数组 [tax, surcharge, discount, reduction, rate]
    public function calculateTax(string $married, int $children, int $salary): array;

    // 批处理模式下的税款计算
    // 可能抛出来自 [dao] 层并向上传递的 [TaxException] 异常
    public function executeBatchTaxes(string $taxPayersFileName, string $resultsFileName, string $errorsFileName): void;
}
  • 第 13 行:[calculateTax] 方法计算税额;
  • 第 17 行:[executeBatchTaxes] 方法为数据位于 [$taxPayersFileName] 文件中的纳税人计算税额,把结果写入 [$resultsFileName] 文件,并把遇到的任何错误写入 [$errorsFileName] 文件。

这是第 5 版中 [InterfaceBusiness] 接口的两个方法。[InterfaceClientBusiness] 接口由如下 [ClientBusiness] 类实现:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 客户端的 [business] 层:税款计算由服务器完成
class ClientBusiness implements InterfaceClientBusiness
{
    // [dao] 层由构造函数注入
    public function __construct(private readonly InterfaceClientDao $clientDao)
    {
    }

    // 税款计算:委托给向服务器发起查询的 [dao] 层
    #[\Override]
    public function calculateTax(string $married, int $children, int $salary): array
    {
        return $this->clientDao->calculateTax($married, $children, $salary);
    }

    // 批处理模式下的税款计算
    #[\Override]
    public function executeBatchTaxes(string $taxPayersFileName, string $resultsFileName, string $errorsFileName): void
    {
        // 我们让来自 [dao] 层的异常向上传递
        // 我们获取纳税人数据
        $taxPayersData = $this->clientDao->getTaxPayersData($taxPayersFileName, $errorsFileName);
        // 我们计算每位纳税人的税款
        $results = array_map(
            fn(TaxPayerData $taxPayerData): TaxPayerData => $taxPayerData->withResults(
                $this->calculateTax($taxPayerData->married, $taxPayerData->children, $taxPayerData->salary)
            ),
            $taxPayersData
        );
        // 保存结果
        $this->clientDao->saveResults($resultsFileName, $results);
    }
}

说明

  • 第 12 行:[ClientBusiness] 类的构造函数接收一个对 [dao] 层的引用作为参数;
  • 第 18–20 行:税额计算委托给 [dao] 层;
  • 第 25–38 行:方法 [executeBatchTaxes] 就是第 5 版中 [Business] 类的那个方法。

18.3.4. 主脚本

客户端脚本 [Main/MainTaxClient.php] 实现 [console] 和 [9]层。它由如下 JSON 文件 [Data/config-client.json] 配置:

{
    "urlServer": "http://localhost/php8-oct-2026/scripts-web/tax/version-08/tax-server.php",
    "user": {
        "login": "admin",
        "passwd": "admin"
    },
    "httpClientOptions": {
        "verify_peer": false,
        "verify_host": false
    },
    "taxPayersDataFilename": "Data/taxpayersdata.json",
    "resultsFilename": "Data/results.json",
    "errorsFilename": "Data/errors.json",
    "dependencies": [
        "../version-05/Entities/TaxException.php",
        "../version-05/Entities/TaxPayerData.php",
        "../version-05/Utilities/Utilities.php",
        "../version-05/Dao/TraitDao.php",
        "Dao/InterfaceClientDao.php",
        "Dao/ClientDao.php",
        "Business/InterfaceClientBusiness.php",
        "Business/ClientBusiness.php"
    ]
}
  • 第 2 行:税额计算服务器的 URL。它使用 [http] 方案:我们在前面已经看到了原因;
  • 第 3–6 行:向税额计算服务器发送请求的用户;
  • 第 7–9 行:HTTP 客户端选项。它们只在使用 URL 或 [https] 时才会用到:与上一章一样,它们指示客户端不验证服务器的自签名证书。当与 URL 或 [http] 一起使用时,这些选项会被忽略;
  • 第 11–13 行:包含纳税人数据、结果和错误的 JSON 文件;
  • 第 14–23 行:客户端的各个 PHP 文件。前四个是第 5 版的文件。

脚本 [MainTaxClient.php] 的代码如下:

<?php

// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);

// 命名空间
namespace Application;

// 客户端的根文件夹:配置文件的路径相对于此文件夹
const ROOT_DIRECTORY = __DIR__ . "/..";
// [Data] 文件夹的配置文件:命令行的第 1 个参数(如果存在)
$configFilename = ROOT_DIRECTORY . "/Data/" . ($argv[1] ?? "config-client.json");

// 获取配置
$config = json_decode(file_get_contents($configFilename), true, flags: JSON_THROW_ON_ERROR);

// 我们引入脚本所需的依赖:第三方库 (Symfony),然后是应用程序文件
require_once ROOT_DIRECTORY . "/../../../vendor/autoload.php";
foreach ($config["dependencies"] as $dependency) {
    require_once ROOT_DIRECTORY . "/$dependency";
}

// 数据文件的路径
$taxPayersDataFilename = ROOT_DIRECTORY . "/" . $config["taxPayersDataFilename"];
$resultsFilename = ROOT_DIRECTORY . "/" . $config["resultsFilename"];
$errorsFilename = ROOT_DIRECTORY . "/" . $config["errorsFilename"];

// 创建 [dao] 层
$clientDao = new ClientDao($config["urlServer"], $config["user"], $config["httpClientOptions"]);
// 创建 [business] 层
$clientBusiness = new ClientBusiness($clientDao);

// 批处理模式下的税款计算
try {
    $clientBusiness->executeBatchTaxes($taxPayersDataFilename, $resultsFilename, $errorsFilename);
    print "The results have been saved in the file [{$config["resultsFilename"]}]\n";
} catch (TaxException $ex) {
    // 我们显示错误
    print "Error no. {$ex->getCode()}: {$ex->getMessage()}\n";
}
// 结束
print "Done\n";

说明

  • 第 10 行:客户端的根文件夹是 [Main] 文件夹的父文件夹;
  • 第 12 行:配置文件,位于 [Data] 文件夹中。其名称可以作为参数传递给脚本([php MainTaxClient.php config-client-ko.json])。否则,默认使用 [config-client.json] 文件。我们将用这个选项来做错误测试;
  • 第 18–21 行:加载依赖项:用于 Symfony [HttpClient] 库的 [Composer] 类加载器,然后是客户端文件;
  • 第 29 行:创建 [dao] 层。我们向它传递该层构造函数所期望的信息:
    • 税额计算服务器的 URL;
    • 将发出请求的用户的凭据;
    • HTTP 客户端的选项;
  • 第 31 行:创建 [business] 层。把刚刚创建的 [dao] 层的引用传递给该层的构造函数;
  • 第 35 行:指示 [business] 层:
    • 计算文件 [taxpayersdata.json] 中所有纳税人的税额;
    • 把结果写入文件 [results.json];
    • 把错误写入文件 [errors.json];
  • 第 37–39 行:所有客户端错误,包括与服务器的通信错误,都以 [TaxException] 异常的形式出现,并显示其错误码和消息。

在 Apache 服务器和 MySQL 数据库管理系统正在运行的情况下,让我们在 [Main] 文件夹中打开的终端里运行客户端:

1
2
3
> php MainTaxClient.php
The results have been saved in the file [Data/results.json]
Done

运行客户端会产生与以前版本相同的结果。请检查如下文件:

  • [Data/taxpayersdata.json]:需要计算税额的纳税人的数据;
  • [Data/results.json]:文件 [Data/taxpayersdata.json] 中各位纳税人的结果。这个文件与第 7 版的 [results.json] 文件相同;
  • [Data/errors.json]:处理文件 [Data/taxpayersdata.json] 时可能发生的错误。

让我们来看看可能的错误情形。首先是服务器不可达。你可以停止 [Laragon] 的 Apache 服务器。我们改为使用配置文件 [config-client-unreachable.json],它与文件 [config-client.json] 除 URL 之外完全相同:这个文件指定 [localhost] 机器上的 4443 端口,没有任何服务器在该端口上监听请求([http://localhost:4443/php8-oct-2026/...])。客户端控制台中的结果如下:

1
2
3
> php MainTaxClient.php config-client-unreachable.json
Error no. 40: Error communicating with the server (Failed to connect to localhost port 4443 after 0 ms: Couldn't connect to server for "http://localhost:4443/php8-oct-2026/scripts-web/tax/version-08/tax-server.php?married=yes&children=2&salary=55555".)
Done

Symfony HTTP 客户端抛出的异常被 [dao] 层转换为错误码为 40 的 [TaxException] 异常。

现在,让我们像之前用 [curl] 所做的那样,模拟 MySQL 数据库管理系统的故障。客户端控制台中的结果如下:

1
2
3
> php MainTaxClient.php
Error no. 42: {"HTTP status":500,"error":"Database access error (SQLSTATE[HY000] [2002] Connection refused)"}
Done

让我们恢复数据库管理系统,然后使用配置文件 [config-client-ko.json],其中登录的用户对服务器来说是未知的:

1
2
3
4
    "user": {
        "login": "x",
        "passwd": "x"
    },

客户端控制台中的结果随后如下:

1
2
3
> php MainTaxClient.php config-client-ko.json
Error no. 42: {"HTTP status":401,"error":"Authentication failed [x]"}
Done

18.3.5. [PHPUnit] 测试

与前面各版本一样,我们将为客户端的 [business] 层编写一个 [PHPUnit] 测试。[Tests/ClientBusinessTest.php] 测试如下:

<?php

// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);

// 测试的命名空间
namespace Application\Tests;

// 被测试的类
use Application\ClientDao;
use Application\ClientBusiness;
use Application\InterfaceClientBusiness;
// PHPUnit 的类
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;

// 测试客户端的 [business] 层:服务器必须处于运行状态
final class ClientBusinessTest extends TestCase
{
    // 客户端的根文件夹
    private const string ROOT_DIRECTORY = __DIR__ . "/..";
    // 客户端的配置
    private static array $config;
    // 被测试的 [business] 层
    private InterfaceClientBusiness $business;

    // 在类的第一个测试之前执行一次
    #[\Override]
    public static function setUpBeforeClass(): void
    {
        // 我们获取客户端的配置
        self::$config = json_decode(file_get_contents(self::ROOT_DIRECTORY . "/Data/config-client.json"), true, flags: JSON_THROW_ON_ERROR);
        // 我们引入客户端的依赖(Composer 自动加载器已由 PHPUnit 加载)
        foreach (self::$config["dependencies"] as $dependency) {
            require_once self::ROOT_DIRECTORY . "/$dependency";
        }
    }

    // 在每个测试之前执行
    #[\Override]
    protected function setUp(): void
    {
        // 像在主脚本中那样创建 [dao] 层和 [business] 层
        $clientDao = new ClientDao(self::$config["urlServer"], self::$config["user"], self::$config["httpClientOptions"]);
        $this->business = new ClientBusiness($clientDao);
    }

说明

  • 第 29–37 行:定义测试环境。我们使用与主脚本 [MainTaxClient.php] 中相同的环境;
  • 第 41–45 行:在每个测试之前创建 [dao] 和 [business] 层。属性 [$this->business] 引用 [business] 层;
  • 测试的其余部分(此处未列出)与前面的版本相同:官方数据表中的 11 位纳税人以及 [testCalculateTax] 方法。请注意,[assertSame] 断言要求服务器返回的值具有完全符合预期的类型:税额、附加税、减免额和扣减额为整数;税率为实数。这由服务器的 [JSON_PRESERVE_ZERO_FRACTION] 选项来保证。

这个测试检查客户端,同时也通过它检查服务器:Apache 服务器和 MySQL 数据库管理系统必须处于运行状态。测试结果如下:

> php vendor/bin/phpunit scripts-console/tax/version-08/Tests --testdox
PHPUnit 12.5.37 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.5.11
Configuration: .../php8-oct-2026/phpunit.xml

...........                                                       11 / 11 (100%)

Time: 00:00.070, Memory: 16.00 MB

Client Business (Application\Tests\ClientBusiness)
 ✔ Calculate tax with data set "couple, 2 children, 55555"
 ✔ Calculate tax with data set "couple, 2 children, 50000"
 ✔ Calculate tax with data set "couple, 3 children, 50000"
 ✔ Calculate tax with data set "single, 2 children, 100000"
 ✔ Calculate tax with data set "single, 3 children, 100000"
 ✔ Calculate tax with data set "couple, 3 children, 100000"
 ✔ Calculate tax with data set "couple, 5 children, 100000"
 ✔ Calculate tax with data set "single, 0 children, 100000"
 ✔ Calculate tax with data set "couple, 2 children, 30000"
 ✔ Calculate tax with data set "single, 0 children, 200000"
 ✔ Calculate tax with data set "couple, 3 children, 200000"

OK (11 tests, 22 assertions)

现在我们有了一个客户端/服务器应用。在下一个版本中,我们将改进服务器:它将使用会话,记录其操作日志,并在出现问题时通过电子邮件通知管理员。