PHP Fiber 优雅协作式多任务
在 PHP Model Context Protocol (MCP) SDK 开发过程中遇到的实际问题，深入探讨了 PHP 纤程（Fibers）这一被低估的强大特性。文章详细展示了如何使用纤程解决复杂的双向通信问题，以及如何构建既优雅又实用的 API。
原文链接 PHP Fiber 优雅协作式多任务
背景
在开发官方 PHP MCP SDK 的客户端通信功能时，开发团队遇到了一个看似无法优雅解决的架构挑战。传统的异步方案、回调模式和状态机都无法在不牺牲代码简洁性的前提下实现需求。最终，PHP 纤程（Fibers）成为了这个问题的完美解决方案。
该功能在 PR #109 中引入，其实现展示了 PHP 纤程最优雅的使用案例之一。但这不仅仅是关于一个问题的故事，更是关于一个自 PHP 8.1 以来一直隐藏在众目睽睽之下、却被大量误解和未充分利用的强大 PHP 特性。
本文将深入探讨：
- PHP 纤程到底是什么（以及它们不是什么）
- 何时以及为何应该使用它们
- 如何理解协作式多任务
- 使用纤程的真实世界实现
- 可以在自己代码中使用的模式
文章较长，建议准备好咖啡慢慢看。
关于纤程的误解
首先要解决房间里的大象：PHP 纤程不是异步 PHP。它们不是并行机制，不是线程，也不是让 PHP 同时运行多个任务。
当 PHP 8.1 在 2021 年 11 月引入纤程支持时，许多开发者都感到困惑。"太好了，又一个异步东西？"大家这样想。这种困惑是可以理解的，因为纤程最显眼的使用场景一直是在 ReactPHP 和 AmPHP 等异步库中。
ReactPHP 甚至有一个名为 async 的包，使用纤程让异步代码看起来像同步代码：
// 纤程之前：回调地狱
$promise->then(function($result) {return anotherAsyncCall($result);
})->then(function($finalResult) {echo $finalResult;
});// 使用纤程：看起来是同步的！
$result = await($promise);
$finalResult = await(anotherAsyncCall($result));
echo $finalResult;
看到这个，很容易认为"纤程 = 异步魔法"。但这忽略了更大的图景。
纤程的本质是协作式多任务。它们赋予代码暂停执行、执行其他操作、然后在完全保留所有变量、调用栈和执行上下文的情况下，精确地回到离开的位置继续执行的能力。
是的，这对异步库非常有用。但在需要受控中断和恢复的纯同步代码中，它同样有用。而这正是大多数 PHP 开发者错过的机会。
纤程采用缓慢的原因不是因为它们不够有用，而是因为大多数开发者不知道何时使用它们。而这正是本文要解决的问题。
理解纤程：基础知识
在深入复杂示例之前，让我们先建立坚实的基础。纤程到底是什么，它如何工作？
什么是协作式多任务？
理解纤程的一个好类比是，将标准 PHP 脚本想象成单轨道上的火车。它从 A 站开到 B 站，通常在到达 B 之前不能停止。纤程允许火车在轨道中间停下来，让乘客下车（或让乘客上洗手间休息），在此期间甚至让另一列火车使用这条轨道，然后在所有行李（变量和内存状态）完好无损的情况下，精确地从停下的地方恢复。
另一个类比是想象你在做饭的同时读书。你读几页书，然后定时器响了，你标记页面，搅拌锅里的东西，再回到刚才读到的地方继续阅读。这就是协作式多任务。
关键词是协作。你（读者/厨师）决定何时切换任务。没有人强行打断你，而是在合适的时候自愿交出控制权。
在编程术语中：
- 抢占式多任务：操作系统强制中断你的代码（线程、进程）
- 协作式多任务：你的代码决定何时交出控制权（协程、纤程）
纤程是 PHP 对协作式多任务的实现。它们让你能够：
- 开始执行一段代码
- 在任何点暂停它（挂起）
- 做其他事情
- 精确地从离开的地方恢复
- 根据需要重复任意多次
纤程的结构
让我们看一个简单的例子：
<?php$fiber = new Fiber(function(): string {echo "1. 纤程启动\n";$value = Fiber::suspend('pause-1');echo "3. 纤程恢复，收到: $value\n";$value2 = Fiber::suspend('pause-2');echo "5. 纤程再次恢复，收到: $value2\n";return 'final-result';
});echo "0. 启动纤程之前\n";$suspended1 = $fiber->start();
echo "2. 纤程挂起，返回: $suspended1\n";$suspended2 = $fiber->resume('data-1');
echo "4. 纤程再次挂起，返回: $suspended2\n";$result = $fiber->resume('data-2');
echo "6. 纤程返回: $result\n";
输出：
0. 启动纤程之前
1. 纤程启动
2. 纤程挂起，返回: pause-1
3. 纤程恢复，收到: data-1
4. 纤程再次挂起，返回: pause-2
5. 纤程再次恢复，收到: data-2
6. 纤程返回: final-result
这里特意包含了数字，以便读者看清执行如何在纤程内外跳转。suspend 让它跳出纤程，resume 让它跳回纤程！为了更清晰，让我们分解一下发生了什么：
- 创建：
new Fiber(function() {...})创建纤程但尚未执行 - 启动：
$fiber->start()开始执行，直到第一个Fiber::suspend() - 挂起：
Fiber::suspend('pause-1')暂停执行并将控制权返回给调用者 - 恢复：
$fiber->resume('data-1')从挂起处继续执行 - 返回：当纤程完成时，
resume()返回最终值
魔法在于执行上下文切换。当纤程挂起时：
- 所有局部变量都被保留
- 调用栈被保存
- 执行跳回到调用
start()或resume()的地方 - 传递给
suspend()的值返回给调用者
当你恢复时：
- 执行跳回纤程内部
- 传递给
resume()的值成为suspend()的返回值 - 一切继续，就像什么都没发生过
一个让纤程变得强大的关键洞察：在纤程内部运行的代码不需要知道它在纤程中。
看看这个：
function processData(int $id): string {$data = fetchData($id); // 这可能会挂起！$result = transform($data); // 这也可能会挂起！return $result;
}// 在纤程内调用
$fiber = new Fiber(fn() => processData(42));
$fiber->start();
从 processData 的角度来看，它只是在调用函数并返回结果。它不知道 fetchData() 和 transform() 可能在幕后挂起纤程。复杂性是隐藏的。
这正是纤程非常适合构建隐藏复杂行为的干净 API 的原因。
异步库中的纤程
现在我们理解了基础知识，让我们看看为什么有些人会将纤程与异步代码联系起来。这也会在我们处理主要问题之前展示一个具体的使用案例。
异步问题
PHP 中的传统异步编程看起来像这样：
// 使用 promises（纤程之前）
function fetchUserData(int $userId): PromiseInterface {return $this->httpClient->getAsync("/users/$userId")->then(function($response) {return json_decode($response->getBody());})->then(function($userData) use ($userId) {return $this->cache->setAsync("user:$userId", $userData);})->then(function() use ($userId) {return "User $userId cached";});
}
这能工作，但很难阅读和理解。使用 catch() 的错误处理会变得混乱。调试很痛苦。而且感觉不像 PHP。
纤程解决方案
有了纤程，像 ReactPHP 这样的库可以提供这样的方式：
// 使用纤程（PHP 8.1 之后）
function fetchUserData(int $userId): string {$response = await($this->httpClient->getAsync("/users/$userId"));$userData = json_decode($response->getBody());await($this->cache->setAsync("user:$userId", $userData));return "User $userId cached";
}
好多了！但 await() 是如何工作的呢？让我们看一个简化版本：
namespace React\Async;function await(PromiseInterface $promise): mixed {// 挂起纤程并注册 promise 回调$result = Fiber::suspend(['type' => 'await','promise' => $promise]);// 恢复时，我们将得到结果或异常if ($result instanceof \Throwable) {throw $result;}return $result;
}
如果你感兴趣，像 PHPStan 这样的工具可以让你添加一些泛型魔法，这样 await() 就能准确知道从你的 Promise 返回什么。这种强大的静态分析感觉就像魔法。多酷啊？
以下是发生的过程：
- 用户代码调用
await($promise)（在纤程内部） await()调用Fiber::suspend()传递 promise- 事件循环看到挂起的纤程和 promise
- 事件循环在纤程挂起时照常继续处理其他事情
- 当 promise 解决时，循环调用
$fiber->resume($value) - 执行在
await()中继续，返回值 - 用户代码得到值，就像它是同步的！
纤程在等待异步操作时挂起，但用户的代码看起来完全是同步的。
更进一步：真正透明的异步
但我们可以走得更远！像 AmPHP 这样的库通过创建围绕异步操作的纤程感知包装器，将其提升到新的水平。你不需要单独的 getAsync() 和 await() 调用，只需要看起来完全同步的方法：
// AmPHP 方法：不需要 await()！
function fetchUserData(int $userId): string {$response = $this->httpClient->get("/users/$userId"); // 看起来同步，实际异步！$userData = json_decode($response->getBody());$this->cache->set("user:$userId", $userData); // 看起来同步，实际异步！return "User $userId cached";
}
等等，什么？没有 await() 调用？这是如何工作的？
魔法在于 get() 和 set() 内部使用纤程。这是一个简化的例子：
class HttpClient {public function get(string $url): Response {// 创建异步操作$promise = $this->performAsyncRequest('GET', $url);// 挂起当前纤程并将 promise 传递给事件循环$response = \Fiber::suspend(['type' => 'await','promise' => $promise]);if ($response instanceof \Throwable) {throw $response;}return $response;}
}
从用户的角度来看，他们只是调用了 get() 并得到了响应。他们完全不知道这是异步的。
这就是纤程的精髓：让异步操作完全透明。用户编写看起来像阻塞的同步 PHP 代码。库使用纤程在幕后处理所有异步复杂性。
比较这些方法
让我们看看演变过程：
// 1. 传统异步与 promises（无纤程）
$promise = $this->httpClient->getAsync("/users/$userId")->then(fn($response) => json_decode($response->getBody()))->then(fn($userData) => $this->cache->setAsync("user:$userId", $userData))->then(fn() => "User $userId cached");// 2. 使用 await() 辅助函数的异步（使用纤程）
$response = await($this->httpClient->getAsync("/users/$userId"));
$userData = json_decode($response->getBody());
await($this->cache->setAsync("user:$userId", $userData));
return "User $userId cached";// 3. 完全透明的异步（纤程隐藏在库中）
$response = $this->httpClient->get("/users/$userId");
$userData = json_decode($response->getBody());
$this->cache->set("user:$userId", $userData);
return "User $userId cached";
注意方法 #3 看起来与同步代码完全一样？这就是正确使用纤程的力量。库开发者处理一次复杂性。每个用户都受益于一个干净的、看起来同步的 API，实际上在底层是异步的。
为什么这导致了误解
因为纤程最显眼的用途是让异步代码看起来同步，开发者假设纤程本身就是异步机制。但纤程本身不做任何异步操作。它们只是提供挂起/恢复机制，使得看起来同步的异步代码成为可能。
事件循环仍在做实际的异步工作。纤程只是让 API 更好用。
这个区别至关重要：纤程是管理执行流的工具，而不是实现并行或异步的工具。
真正的问题：MCP SDK 中的客户端通信
现在让我们进入本文的核心问题。在开发 Model Context Protocol (MCP) 的 PHP 实现时，开发团队遇到了一个似乎无法优雅解决的设计挑战。
什么是 MCP？
Model Context Protocol 是连接 AI 助手（如 Claude）与外部工具和数据源的标准。
一个 MCP 服务器暴露：
- 工具：AI 可以调用的函数（例如："搜索数据库"、"发送邮件"）
- 资源：AI 可以读取的数据（例如："项目文件"、"API 文档"）
- 提示：AI 可以使用的模板
该协议是双向的 JSON-RPC，支持不同的传输方式（STDIO、HTTP + SSE、自定义）。
挑战
MCP 规范包含服务器在请求处理期间与客户端通信的功能：
- 日志记录：向客户端发送日志消息
- 进度更新：更新客户端关于长时间运行操作的进度
- 采样：请求客户端使用其 LLM 生成文本
这些不仅仅是响应类型。不，问题是它们需要在工具执行期间发生。例如：
客户端: "嘿服务器，运行 'analyze_dataset' 工具"
服务器: "开始..." [发送日志]
服务器: "25% 完成" [发送进度]
服务器: "50% 完成" [发送进度]
服务器: "生成摘要，需要你的 LLM" [发送采样请求]
客户端: "这是生成的摘要" [响应采样]
服务器: "完成！这是完整结果" [发送最终响应]
服务器需要：
- 在执行过程中发送消息
- 等待来自客户端的响应
- 在收到响应后继续执行
- 让所有这些感觉起来很自然
API 需求
在 MCP SDK 方面，优先事项之一是使其极其易用。开发团队希望开发者这样编写工具：
$server->addTool(function (string $dataset, ClientGateway $client): array {$client->log(LoggingLevel::Info, "开始分析");foreach ($steps as $step) {$client->progress($progress, 1, $step);doWork($step);}$summary = $client->sample("总结这些数据：...");return ['status' => 'complete', 'summary' => $summary];},name: 'analyze_dataset'
);
看看这段代码。它很漂亮。它很简单。它看起来完全是同步的。没有回调，没有 promises，没有 async/await 语法，没有 yield 生成器。只是普通的 PHP。
但在底层，这需要：
- 向客户端发送 JSON-RPC 通知（日志、进度）
- 发送 JSON-RPC 请求并等待响应（采样）
- 与任何传输方式工作，无论是否阻塞！
- 无论你使用原生 PHP、ReactPHP、Swoole 还是 RoadRunner 都能工作
如何实现？
为什么传统方法行不通
开发团队花了几个小时考虑不同的解决方案：
选项 1：让一切都异步
// 基于 Promise 的方法 - 嵌套且混乱
$server->addTool(function (string $dataset, $client) {return $client->logAsync(LoggingLevel::Info, "开始分析")->then(function() use ($client) {return $client->progressAsync(0.33, 1, "步骤 1");})->then(function() use ($client) {return $client->progressAsync(0.66, 1, "步骤 2");})->then(function() use ($client) {return $client->sampleAsync("总结...");})->then(function($summary) {return ['status' => 'complete', 'summary' => $summary];});
});
回调嵌套很快就会变得笨拙。即使使用 await() 辅助函数来简化：
$server->addTool(function (string $dataset, $client) {await($client->logAsync(LoggingLevel::Info, "开始"));await($client->progressAsync(0.33, 1, "步骤 1"));await($client->progressAsync(0.66, 1, "步骤 2"));$summary = await($client->sampleAsync("总结..."));return ['status' => 'complete', 'summary' => $summary];
});
这强制每个人学习异步 PHP。它使异步库成为核心依赖，并将 SDK 限制在选择的异步运行时。与服务器请求和响应的 PSR-7 不同，PHP 中没有事件循环或异步运行时的标准，因此供应商锁定不是一个选项。对于简单的工具来说，这也是过度杀伤。被拒绝。
选项 2：回调
// 回调地狱警告！
$server->addTool(function (string $dataset, $client) {$client->log(..., function() use ($client) {$client->progress(..., function() use ($client) {$client->sample(..., function($summary) {return ['summary' => $summary];});});});
});
没人想要这个。无需进一步解释。被拒绝。
选项 3：状态机和序列化
如果我们跟踪执行状态并从检查点重新执行处理程序会怎么样？
// 伪代码
if ($state->step === 0) {$client->log(...);$state->step = 1;return $state->serialize();
}
if ($state->step === 1) {$client->progress(...);$state->step = 2;return $state->serialize();
}
// ...以此类推
这非常复杂。即使抽象部分内容并允许用户编写同步代码，跟踪状态也有很多工作要做。如何序列化闭包？如何恢复局部变量？如何处理循环？这将需要完全改变用户编写工具的方式。被拒绝。
选项 4：带 yield 的生成器
$server->addTool(function (string $dataset, $client) {yield $client->log(...);yield $client->progress(...);$summary = yield $client->sample(...);return ['summary' => $summary];
});
这更接近了，但生成器有限制。你不能轻松地从嵌套函数调用中 yield。语法很笨拙。用户需要理解生成器。不理想，但可行。
选项 5：PHP 纤程
如果挂起/恢复是不可见的会怎么样？如果 $client->log() 看起来像一个普通的方法调用，但在幕后它挂起纤程，发送消息，然后恢复呢？
// 用户编写的内容（看起来是同步的！）
$server->addTool(function (string $dataset, $client) {$client->log(...); // 内部挂起$client->progress(...); // 内部挂起$summary = $client->sample(...); // 挂起并等待return ['summary' => $summary];
});
就是这个。这就是解决方案。用户编写普通的 PHP。SDK 处理所有复杂性。
"啊哈！"时刻
当开发团队意识到纤程是答案时，一切都豁然开朗了。以下是它们完美的原因：
- 透明：用户代码不需要知道纤程
- 灵活：适用于任何传输（阻塞或非阻塞）
- 简单：API 只是常规方法调用
- 强大：完全控制执行流
- 通用：适用于同步 PHP、异步 PHP、任何运行时
纤程让开发团队能够在干净的、看起来同步的 API 背后隐藏双向通信的复杂性。用户编写简单的函数。SDK 管理纤程生命周期。传输处理实际的 I/O。
这是完美的关注点分离。
思考过程：为什么纤程在这里有效
让我们深入了解为什么纤程特别适合解决这个问题。
核心挑战
当工具处理程序调用 $client->log() 时，需要：
- 暂停处理程序的执行
- 向客户端发送 JSON-RPC 通知（机制取决于传输）
- 立即恢复处理程序（日志记录不需要等待）
当工具处理程序调用 $client->sample() 时，需要：
- 暂停处理程序的执行
- 向客户端发送 JSON-RPC 请求（机制取决于传输）
- 等待客户端的响应（如何接收响应也取决于传输）
- 使用响应恢复处理程序
关键洞察：需要离开处理程序的执行上下文，做其他事情，然后在特定点返回。而且需要能够多次这样做。这正是纤程提供的功能。
架构
解决方案有三层：
-
ClientGateway（面向用户的 API）
- 提供
log()、progress()、sample()等方法 - 内部调用
Fiber::suspend()传递消息数据 - 恢复时返回响应
- 提供
-
Protocol（编排层）
- 将处理程序执行包装在纤程中
- 检测纤程何时挂起
- 提取挂起的值（通知或请求）
- 将纤程移交给传输层
-
Transport（I/O 层）
- 获取挂起纤程的所有权
- 向客户端发送消息（响应、请求和通知）
- 等待响应（如果需要）
- 准备就绪时恢复纤程
每一层都有明确的职责。魔法在于它们如何协调。
为什么它同时适用于同步和异步
这种方法的美妙之处在于纤程与传输无关。无论你使用的是：
- Stdio（阻塞，单进程）- 官方 SDK 的一部分
- HTTP 与 PHP-FPM（无状态，多进程）- 官方 SDK 的一部分
- ReactPHP（非阻塞，事件驱动）- 展示异步兼容性的外部示例
- Swoole（基于协程）- 使用相同架构可行
挂起/恢复机制都是相同的。传输根据其执行模型决定何时恢复纤程。纤程本身不关心。它只是挂起和等待。
对于阻塞传输，恢复发生在同一进程的循环中。对于非阻塞传输，恢复通过事件循环回调发生。对于多进程传输，当从共享会话中提取响应时恢复发生。纤程不关心这些细节。
实现：架构概述
现在让我们深入实际实现。下面将展示一些来自 PHP MCP SDK 的真实代码，并解释一切如何组合在一起。
三个关键组件
系统有三个主要部分：
用户代码（处理程序）↓
ClientGateway（API）↓Protocol（编排器）↓Transport（I/O）
移交：从 Protocol 到 Transport
这是关键时刻。以下是 Protocol 中的简化流程：
// src/Server/Protocol.php
// Protocol::handleRequest()
public function handleRequest(Request $request, SessionInterface $session): void {$handler = $this->findHandler($request);// 在纤程内执行处理程序！$fiber = new \Fiber(fn() => $handler->handle($request, $session));$result = $fiber->start();if ($fiber->isSuspended()) {// 纤程产生了某些东西！提取它。if ($result['type'] === 'notification') {$this->sendNotification($result['notification'], $session);} elseif ($result['type'] === 'request') {$this->sendRequest($result['request'], $result['timeout'], $session);}// 将纤程交给传输层$this->transport->attachFiberToSession($fiber, $session->getId());} else {// 纤程完成而未挂起$finalResult = $fiber->getReturn();$this->sendResponse($finalResult, $session);}
}
协议启动纤程并检查它是否挂起。如果挂起了，协议提取被挂起的内容（通知或请求），将其排队发送，并将纤程交给传输层。稍后会详细讨论这一点。现在让我们继续。
从这一点开始，传输层拥有纤程的生命周期。进一步的挂起和恢复由传输层处理。
Transport 的职责
每个传输必须：
- 从协议接受纤程
- 向客户端发送排队的消息
- 接收客户端响应
- 在适当的时间恢复纤程
- 处理纤程终止
不同的传输基于其执行模型以不同方式实现这一点。让我们看看每一个。
用户体验：它的外观
在深入传输实现之前，让我们看看从用户角度来看最终结果是什么样的。这很重要，因为它展示了为什么复杂性是值得的。
示例 1：简单的进度更新
这是来自 MCP SDK 文档的真实示例：
// server.php
$server->addTool(function (string $dataset, ClientGateway $client): array {$client->log(LoggingLevel::Info, "对数据集运行质量检查: $dataset");$tasks = ['验证 schema','扫描异常','审查统计摘要',];foreach ($tasks as $index => $task) {$progress = ($index + 1) / count($tasks);$client->progress($progress, 1, $task);usleep(140_000); // 模拟工作}$client->log(LoggingLevel::Info, "数据集 $dataset 通过自动检查");return ['dataset' => $dataset,'status' => 'passed','notes' => '未检测到重大问题',];},name: 'run_dataset_quality_checks',description: '执行带进度更新的数据集质量检查'
);
看看这个工具代码。它只是一个普通函数。它遍历任务。它调用 $client->progress()，就像调用普通方法一样。没有迹象表明这在进行复杂的双向通信。
但实际上发生的是：
- 处理程序启动（在纤程内）
$client->log()挂起纤程- 传输发送日志通知
- 纤程恢复
- 循环开始
- 第一个
$client->progress()挂起纤程 - 传输发送进度通知
- 纤程恢复
usleep()运行（仍在纤程中）- 第二个
$client->progress()再次挂起 - ...以此类推
每次挂起和恢复对用户都是不可见的。代码看起来和表现得像同步 PHP。执行不断在传输的循环（现在是所有者）和工具的处理程序之间来回跳转，每次回到处理程序时，都回到完美的位置并恢复（甚至在 foreach 循环内）。请定义美！！
示例 2：请求 LLM 采样
这是一个更复杂的示例，实际等待响应：
// app/Tools/IncidentCoordinator.php
class IncidentCoordinator implements ClientAwareInterface {use ClientAwareTrait; // 提供 $this->log 和 $this->progress#[McpTool('coordinate_incident_response', '协调事件响应')]public function coordinateIncident(string $incidentTitle): array {$this->log(LoggingLevel::Warning, "事件分类开始: $incidentTitle");$steps = ['收集遥测数据','评估范围','协调响应者',];foreach ($steps as $index => $step) {$progress = ($index + 1) / count($steps);$this->progress($progress, 1, $step);usleep(180_000);}// 请求客户端的 LLM 生成响应策略$prompt = "为事件 \"$incidentTitle\" 提供简洁的响应策略基于: " . implode(', ', $steps);$result = $this->sample($prompt, 350, 90, ['temperature' => 0.5]);$recommendation = $result->content instanceof TextContent? trim($result->content->text): '';$this->log(LoggingLevel::Info, "事件分类完成");return ['incident' => $incidentTitle,'recommended_actions' => $recommendation,'model' => $result->model,];}
}
这更加神奇。sample() 调用：
- 使用采样请求挂起纤程
- 传输向客户端发送请求
- 传输等待客户端响应（响应如何到来取决于传输，这可能需要几秒钟！）
- 当响应到达时，传输使用它恢复纤程
$result包含响应，执行继续
从方法的角度来看，它进行了同步调用并得到了结果。在幕后：
- 纤程被挂起
- 控制权返回到传输的事件循环
- 传输处理其他事情（可能是其他请求）
- 当响应到来时（可能来自另一个 HTTP 请求/进程），纤程恢复
- 方法继续，就像什么都没发生过
这就是协作式多任务的实际应用。编写这个工具的开发者完全不知道这正在发生。
ClientAwareTrait 模式
注意上面示例中的 ClientAwareTrait。这是访问 ClientGateway 的两种方式之一：
方法 1：在处理程序中进行类型提示
#[McpTool('my_tool')]
public function myTool(string $input, ClientGateway $client): string {$client->log(...);return $result;
}
SDK 检测 ClientGateway 参数并自动注入它。
方法 2：实现 ClientAwareInterface
class MyService implements ClientAwareInterface {use ClientAwareTrait; // 提供 setClient() 和辅助方法#[McpTool('my_tool')]public function myTool(string $input): string {$this->log(...); // ClientAwareTrait 提供此方法$this->progress(...);$result = $this->sample(...);return $result;}
}
SDK 在调用处理程序之前调用 setClient()，trait 提供像 log()、progress()、sample() 这样的便捷方法，这些方法内部使用客户端。
两种方法都提供相同的能力。用户根据偏好选择。
底层：ClientGateway
现在让我们剥开第一层，看看 ClientGateway 如何工作。这是用户交互的 API。它出奇地（并不出奇地）简单，但超级强大。
这是实际实现（为清晰起见进行了简化）：
// src/Server/ClientGateway.php
final class ClientGateway {public function __construct(private readonly SessionInterface $session,) {}/*** 向客户端发送通知（即发即忘）。*/public function notify(Notification $notification): void {\Fiber::suspend(['type' => 'notification','notification' => $notification,'session_id' => $this->session->getId()->toRfc4122(),]);}/*** 向客户端发送日志消息。*/public function log(LoggingLevel $level, mixed $data, ?string $logger = null): void {$this->notify(new LoggingMessageNotification($level, $data, $logger));}/*** 向客户端发送进度更新。*/public function progress(float $progress, ?float $total = null, ?string $message = null): void {$meta = $this->session->get(Protocol::SESSION_ACTIVE_REQUEST_META, []);$progressToken = $meta['progressToken'] ?? null;if (null === $progressToken) {// 客户端未请求进度，跳过return;}$this->notify(new ProgressNotification($progressToken, $progress, $total, $message));}/*** 从客户端请求 LLM 采样。*/public function sample(array|Content|string $message,int $maxTokens = 1000,int $timeout = 120,array $options = []): CreateSamplingMessageResult {// 准备消息if (is_string($message)) {$message = new TextContent($message);}if ($message instanceof Content) {$message = [new SamplingMessage(Role::User, $message)];}$request = new CreateSamplingMessageRequest(messages: $message,maxTokens: $maxTokens,preferences: $options['preferences'] ?? null,systemPrompt: $options['systemPrompt'] ?? null,temperature: $options['temperature'] ?? null,// ...其他选项);// 发送请求并等待响应$response = $this->request($request, $timeout);if ($response instanceof Error) {throw new ClientException($response);}return CreateSamplingMessageResult::fromArray($response->result);}/*** 向客户端发送请求并等待响应。*/private function request(Request $request, int $timeout = 120): Response|Error {$response = \Fiber::suspend(['type' => 'request','request' => $request,'session_id' => $this->session->getId()->toRfc4122(),'timeout' => $timeout,]);if (!$response instanceof Response && !$response instanceof Error) {throw new RuntimeException('传输返回了意外的载荷');}return $response;}
}
关键方法
notify() - 最简单的情况：
public function notify(Notification $notification): void {\Fiber::suspend(['type' => 'notification','notification' => $notification,'session_id' => $this->session->getId()->toRfc4122(),]);
}
这会使用一个数据结构挂起当前纤程，该结构指示：
- 这是一个通知（不需要响应）
- 要发送什么通知
- 它属于哪个会话
纤程将在通知排队后立即恢复。
request() - 复杂的情况：
private function request(Request $request, int $timeout = 120): Response|Error {$response = \Fiber::suspend(['type' => 'request','request' => $request,'session_id' => $this->session->getId()->toRfc4122(),'timeout' => $timeout,]);return $response;
}
这会使用一个数据结构挂起纤程，该结构指示：
- 这是一个请求（期望响应）
- 要发送什么请求
- 等待响应多长时间
纤程在以下情况之前不会恢复：
- 客户端发送响应，或
- 超时到期
当恢复时，传递给 $fiber->resume($value) 的值成为 Fiber::suspend() 的返回值。因此 $response 将是 Response 对象（成功）或 Error 对象（失败/超时）。
何时应该使用纤程？
现在你已经看到了纤程的实际应用，什么时候应该在自己的代码中真正使用它们？
纤程使用案例检查清单
在以下情况考虑使用纤程：
✅ 需要暂停和恢复执行 - 核心使用案例。如果你需要离开一个函数，做其他事情，然后回来。
✅ 想要对用户隐藏复杂性 - 如果你正在构建一个库，并希望提供一个干净的 API 来隐藏异步或有状态的行为。
✅ 需要协作式多任务 - 当你希望多个"任务"在没有线程或进程的情况下取得进展。
✅ 正在桥接同步和异步代码 - 当你想让异步操作看起来同步时（如 ReactPHP 的 await）。
✅ 需要维护执行上下文 - 当使用生成器暂停和恢复会受到太多限制时（不能轻松地从嵌套调用中 yield）。
✅ 正在构建基础设施代码 - 库、框架和 SDK 最能从纤程中受益。
何时不使用纤程
在以下情况不要使用纤程：
❌ 简单的回调就足够了 - 不要把事情复杂化。如果回调有效，就使用回调。
❌ 需要真正的并行性 - 纤程是协作的，不是并行的。使用进程、线程或异步 I/O 实现并行性。
❌ 代码简单且线性 - 如果不需要中断或恢复，纤程会增加不必要的复杂性。
❌ 你不控制执行流 - 纤程在库和框架中表现出色，在应用代码中则较少。
❌ 生成器工作正常 - 如果生成器（yield）干净地解决了你的问题，坚持使用它们。纤程更强大但也更复杂。
常见陷阱和注意事项
1. 理解谁控制纤程
关于纤程最基本的理解：当纤程挂起时，它将控制权让回给某人。那个"某人"就是编排器，你需要知道它是谁。
纤程代表一个工作单元。当它调用 Fiber::suspend() 时，执行跳出纤程并返回到调用 $fiber->start() 或 $fiber->resume() 的实体。该实体负责决定何时（以及是否）恢复纤程。
在 MCP 传输中：
- StdioTransport：主循环（
while (!feof($input))）是编排器。它持续处理输入、管理纤程并刷新输出。 - StreamableHttpTransport：SSE 流的阻塞循环在该请求的生命周期内成为编排器。它阻塞整个进程并管理纤程直到完成。
- ReactPHP：事件循环是编排器。我们不阻塞它；相反，我们注册循环管理的定时器。
关键原则：编排器不能被永久阻塞，否则你的纤程永远不会恢复。如果你正在编写挂起纤程的代码，确保接收控制权的实体有机制来恢复它们。
还要注意：纤程可以嵌套。你可以在纤程内部创建纤程。编排器可以是一个中央管理器（如我们的 TaskManager 示例所示），或者父纤程本身可以充当其子纤程的编排器。只需清楚谁在管理谁，并确保编排器不会无限期地被阻塞。
2. 忘记你在纤程中
function myHandler() {$client->sample("生成文本"); // 这会挂起！// 这里的任何代码都在挂起和恢复之后运行
}
记住挂起可能发生在调用栈的深处。始终考虑在挂起期间可能改变的状态。
3. 资源生命周期
$lock = $mutex->acquire();
$client->sample("..."); // 纤程在这里挂起
$lock->release(); // 这会晚得多才运行！
小心跨越挂起点的资源（锁、数据库事务、文件句柄）。纤程可能会挂起几秒钟或几分钟。
4. 跨挂起的异常处理
try {$result = $client->sample("..."); // 挂起
} catch (\Throwable $e) {// 这捕获纤程内部的异常// 不是挂起期间的异常// 除非纤程用 throw() 恢复
}
异常在纤程内正常工作，但挂起/恢复机制本身有单独的错误处理。因此理解异常不会自动跨越纤程和编排器之间的边界至关重要。
如果纤程抛出异常，它会冒泡到编排器（通过 $fiber->start() 或 $fiber->resume()）。如果编排器抛出异常，它不会自动进入纤程（因为异常可能与挂起的纤程相关，也可能无关）。
你必须明确决定如何桥接这个差距。你是希望编排器独立崩溃吗？你想捕获错误并使用失败对象 resume() 吗？还是你想将其 throw() 到纤程中？这些是架构决策，不是默认行为。
5. 全局状态
global $counter;
$counter++;
$client->log("计数：$counter"); // 挂起
$counter++; // 如果另一个纤程在挂起期间修改了 $counter 会怎样？
小心全局状态。其他代码（或其他纤程）可能在你挂起时修改它。
6. 纤程创建开销
创建纤程有少量开销。不要创建数百万个。与线程相比它们是轻量级的，但不是免费的。
结论：理解你的工具的力量
当你学习数据结构和算法时，你不仅仅是记忆定义和语法，你还学习何时使用它们。例如，如果你不认识何时需要在两端快速插入/删除，双向链表就没有用。
这同样适用于语言特性。PHP 自 8.1 以来就有了纤程，但大多数开发者不使用它们，因为他们不认识纤程解决的问题。所以，下次当你面临涉及以下问题时：
- 暂停和恢复执行
- 在干净的 API 背后隐藏复杂性
- 使异步代码感觉同步
- 协作式多任务
问自己："纤程能优雅地解决这个问题吗？"
你可能会惊讶于答案是肯定的频率。
总结
PHP 纤程（Fibers）自 PHP 8.1 引入以来，一直是一个被低估的特性。通过 PHP MCP SDK 的客户端通信功能（PR #109）这个实际案例，我们看到了纤程如何优雅地解决复杂的架构问题。
这个实现的精妙之处不在于其技术复杂度，而在于其设计理念——通过纤程将复杂的双向通信机制隐藏在简洁的同步风格 API 背后，让用户能够编写直观、易读的代码，而无需关心底层的挂起、恢复和状态管理。
关键要点
- 纤程不是异步机制，而是协作式多任务的实现，是管理执行流的工具
- 正确的抽象层次：让复杂性在库层面解决一次，所有用户受益
- 传输无关性：同一套纤程机制可以适配不同的 I/O 模型（阻塞、非阻塞、多进程）
- 用户友好：最好的技术是让问题对用户消失的技术
适用场景
纤程最适合：
- 构建库和框架
- 隐藏异步复杂性
- 需要暂停和恢复执行上下文的场景
- 桥接同步和异步代码
不适用于：
- 简单的线性流程
- 需要真正并行性的场景
- 可以用简单回调或生成器解决的问题
选择正确的工具，理解工具的本质，是构建优雅软件的关键。PHP 纤程正是这样一个被低估但极其强大的工具。
