PHP Swoole协程微服务实战：从零构建高并发API网关并完成性能调优

一、为什么选择 Swoole 协程

传统 PHP-FPM 模式下，每个请求都会启动一个独立的进程或线程，处理结束后释放所有资源。这种“无共享”架构虽然简单稳定，但面对长连接、实时通信或大量并发请求时，频繁创建和销毁进程会带来巨大的 CPU 与内存开销。

Swoole 通过扩展方式为 PHP 注入了协程能力。协程是用户态的轻量级线程，可以在一个进程内同时运行成千上万个协程，遇到 IO 操作（如数据库查询、HTTP 调用）时自动让出 CPU，实现非阻塞并发。借助 Swoole，我们可以在熟悉的 PHP 语法下编写出与 Node.js、Go 比肩的高性能服务。

本教程将聚焦 Swoole 的 HTTP 服务器与协程 MySQL 客户端，构建一个用户管理的微服务，对外暴露 RESTful API。

二、环境准备与 Swoole 安装

确保你的开发环境满足以下条件：

• PHP 8.0 或更高版本（推荐 PHP 8.2+）
• Linux 系统（生产环境推荐，开发可用 WSL2 或 Docker）
• Composer 包管理器

安装 Swoole 扩展（以 PECL 方式为例）：

pecl install swoole
# 或者启用特定选项，如 --enable-swoole-curl --enable-swoole-json

在 php.ini 中添加：

extension=swoole.so

验证安装成功：

php -m | grep swoole
# 应输出 swoole

创建项目目录并初始化 Composer：

mkdir swoole-microservice
cd swoole-microservice
composer init --name=my/swoole-api --type=project --no-interaction

至此，基础环境已就绪。

三、Swoole 协程基础速览

在构建 HTTP 服务器前，我们需要理解协程的创建与调度。Swoole 中，使用 go() 函数创建协程，其内部可以嵌套使用协程客户端（如 CoMySQL、CoHttpClient），当一个协程遇到 IO 等待时会自动挂起，将执行权交给其他协程。

<?php
use SwooleCoroutine;

// 创建三个并发协程
Coroutinerun(function () {
    go(function () {
        echo "协程1开始n";
        Coroutine::sleep(1);  // 模拟IO等待
        echo "协程1结束n";
    });

    go(function () {
        echo "协程2开始n";
        Coroutine::sleep(0.5);
        echo "协程2结束n";
    });

    echo "主协程等待...n";
});
// 输出顺序：协程1开始 → 协程2开始 → 协程2结束 → 协程1结束

Coroutinerun() 是 Swoole 5.x 推荐的事件循环入口，替代了旧的 SwooleCoroutineScheduler。在真实应用中，HTTP 服务器会自动维护协程容器，无需手动调用 run()。

四、搭建第一个 Swoole HTTP 服务器

我们将创建一个简单的 HTTP 服务器，监听 9501 端口，返回 JSON 响应。

<?php
// server.php
$http = new SwooleHttpServer('0.0.0.0', 9501);

$http->on('request', function ($request, $response) {
    // 设置响应头
    $response->header('Content-Type', 'application/json');
    $response->end(json_encode([
        'code' => 200,
        'message' => 'Hello Swoole',
        'time' => date('Y-m-d H:i:s'),
    ]));
});

$http->start();

运行服务器：

php server.php

访问 http://localhost:9501 即可看到 JSON 响应。此时服务器是同步阻塞模型，每个请求仍按顺序处理。要启用协程，我们需要在服务器配置中设置 enable_coroutine 为 true（Swoole 5 默认开启），并将处理逻辑改为协程风格。

为了构建完整的微服务，我们将引入路由、中间件概念。尽管有 Hyperf 等全栈框架基于 Swoole，但本教程为了展示底层原理，将手写轻量级路由和请求处理。

五、构建用户管理微服务：完整代码实现

我们实现一个支持下列 API 的用户服务：

• GET /users — 获取用户列表（分页）
• GET /users/{id} — 获取单个用户
• POST /users — 创建用户
• PUT /users/{id} — 更新用户
• DELETE /users/{id} — 删除用户

数据库选用 MySQL，使用协程 MySQL 客户端，并实现连接池避免频繁建立连接。

5.1 数据库连接池实现

<?php
// Pool.php
use SwooleCoroutineMySQL;
use SwooleCoroutineChannel;

class MySQLPool
{
    private Channel $pool;
    private array $config;

    public function __construct(array $config, int $size = 10)
    {
        $this->config = $config;
        $this->pool = new Channel($size);
        for ($i = 0; $i pool->push($this->createConnection());
        }
    }

    private function createConnection(): MySQL
    {
        $mysql = new MySQL();
        $connected = $mysql->connect($this->config);
        if (!$connected) {
            throw new RuntimeException("MySQL连接失败: {$mysql->connect_error}");
        }
        return $mysql;
    }

    public function get(): MySQL
    {
        return $this->pool->pop(); // 协程挂起等待直到有可用连接
    }

    public function put(MySQL $mysql): void
    {
        $this->pool->push($mysql);
    }

    // 使用连接执行查询（自动回收）
    public function execute(callable $callback)
    {
        $mysql = $this->get();
        try {
            return $callback($mysql);
        } finally {
            $this->put($mysql);
        }
    }
}

5.2 HTTP 服务器与路由分发

<?php
// server.php
require __DIR__ . '/vendor/autoload.php';

$pool = new MySQLPool([
    'host' => '127.0.0.1',
    'port' => 3306,
    'user' => 'root',
    'password' => 'secret',
    'database' => 'swoole_api',
    'charset' => 'utf8mb4',
], 20); // 20个连接

$http = new SwooleHttpServer('0.0.0.0', 9501);
$http->set([
    'worker_num' => 4,          // 多个Worker进程
    'enable_coroutine' => true, // 自动创建协程
]);

$http->on('request', function ($req, $res) use ($pool) {
    // 解析 URI
    $uri = $req->server['request_uri'];
    $method = $req->server['request_method'];

    // 简单路由匹配：支持 /users 和 /users/{id}
    $pattern = '#^/users(?:/(d+))?$#';
    if (!preg_match($pattern, $uri, $matches)) {
        $res->status(404);
        $res->end(json_encode(['error' => 'Not Found']));
        return;
    }

    $userId = $matches[1] ?? null; // 可能为数字或空

    // 根据方法分发
    switch ($method) {
        case 'GET':
            if ($userId) {
                getUser($res, $pool, (int)$userId);
            } else {
                listUsers($res, $pool);
            }
            break;
        case 'POST':
            createUser($res, $pool, json_decode($req->rawContent(), true) ?? []);
            break;
        case 'PUT':
            if ($userId) updateUser($res, $pool, (int)$userId, json_decode($req->rawContent(), true) ?? []);
            else sendError($res, 400, '缺少用户ID');
            break;
        case 'DELETE':
            if ($userId) deleteUser($res, $pool, (int)$userId);
            else sendError($res, 400, '缺少用户ID');
            break;
        default:
            $res->status(405);
            $res->end(json_encode(['error' => 'Method Not Allowed']));
    }
});

$http->start();

5.3 业务处理函数（协程内执行）

<?php
function sendJson(SwooleHttpResponse $res, array $data, int $code = 200) {
    $res->status($code);
    $res->header('Content-Type', 'application/json');
    $res->end(json_encode($data, JSON_UNESCAPED_UNICODE));
}

function sendError(SwooleHttpResponse $res, int $code, string $message) {
    sendJson($res, ['error' => $message], $code);
}

function listUsers(SwooleHttpResponse $res, MySQLPool $pool) {
    $page = (int)($_GET['page'] ?? 1);
    $limit = 10;
    $offset = ($page - 1) * $limit;

    $pool->execute(function (MySQL $db) use ($res, $offset, $limit) {
        $result = $db->query("SELECT id, name, email, created_at FROM users LIMIT $offset, $limit");
        if ($result === false) {
            sendError($res, 500, '查询失败');
            return;
        }
        sendJson($res, ['data' => $result, 'page' => $page]);
    });
}

function getUser(SwooleHttpResponse $res, MySQLPool $pool, int $id) {
    $pool->execute(function (MySQL $db) use ($res, $id) {
        $stmt = $db->prepare("SELECT id, name, email, created_at FROM users WHERE id = ?");
        $result = $stmt->execute([$id]);
        if (empty($result)) {
            sendError($res, 404, '用户不存在');
            return;
        }
        sendJson($res, $result[0]);
    });
}

function createUser(SwooleHttpResponse $res, MySQLPool $pool, array $data) {
    // 简单验证
    if (empty($data['name']) || empty($data['email'])) {
        sendError($res, 422, '姓名和邮箱为必填项');
        return;
    }
    $pool->execute(function (MySQL $db) use ($res, $data) {
        $stmt = $db->prepare("INSERT INTO users (name, email) VALUES (?, ?)");
        $result = $stmt->execute([$data['name'], $data['email']]);
        if ($result === false) {
            sendError($res, 500, '创建失败');
            return;
        }
        $newId = $db->insert_id;
        sendJson($res, ['id' => $newId, 'message' => '创建成功'], 201);
    });
}

function updateUser(SwooleHttpResponse $res, MySQLPool $pool, int $id, array $data) {
    $updates = [];
    $params = [];
    if (isset($data['name'])) {
        $updates[] = 'name = ?';
        $params[] = $data['name'];
    }
    if (isset($data['email'])) {
        $updates[] = 'email = ?';
        $params[] = $data['email'];
    }
    if (empty($updates)) {
        sendError($res, 400, '没有要更新的字段');
        return;
    }
    $params[] = $id;
    $pool->execute(function (MySQL $db) use ($res, $id, $updates, $params) {
        $sql = "UPDATE users SET " . implode(', ', $updates) . " WHERE id = ?";
        $stmt = $db->prepare($sql);
        $result = $stmt->execute($params);
        if ($db->affected_rows === 0) {
            sendError($res, 404, '用户不存在或未修改');
            return;
        }
        sendJson($res, ['message' => '更新成功']);
    });
}

function deleteUser(SwooleHttpResponse $res, MySQLPool $pool, int $id) {
    $pool->execute(function (MySQL $db) use ($res, $id) {
        $stmt = $db->prepare("DELETE FROM users WHERE id = ?");
        $stmt->execute([$id]);
        if ($db->affected_rows === 0) {
            sendError($res, 404, '用户不存在');
            return;
        }
        sendJson($res, ['message' => '删除成功']);
    });
}

5.4 数据库表结构

CREATE TABLE `users` (
    `id` INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    `name` VARCHAR(100) NOT NULL,
    `email` VARCHAR(150) NOT NULL UNIQUE,
    `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

现在启动服务器，即可通过 curl 或 API 工具测试完整的用户 CRUD 接口。所有数据库操作都在协程中非阻塞执行，这意味着即使有多个请求同时到来，服务器也不会因为某个慢查询而阻塞其他请求。

六、压力测试与性能分析

我们使用 wrk 或 ab 对服务进行压力测试，并对比简单 PHP-FPM 实现（假设相同的 CRUD 逻辑但无协程连接池）。

启动 Swoole 服务：

php server.php

在另一终端执行 wrk -t4 -c200 -d30s http://127.0.0.1:9501/users：

Running 30s test @ http://127.0.0.1:9501/users
  4 threads and 200 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency    45.32ms   12.11ms 210.45ms   85.67%
    Req/Sec     1.12k   132.42     1.45k    72.33%
  134000 requests in 30.02s, 25.54MB read
Requests/sec:   4463.55

而典型的 PHP-FPM + MySQL 直连（无连接池）在同样的并发下很容易因为数据库连接数耗尽而大量超时，吞吐量可能仅有几百 QPS。Swoole 的连接池复用使得 QPS 提升数倍至数十倍，延迟也更稳定。

七、部署与生产环境调优

将 Swoole 服务部署到生产环境时，建议采取以下优化：

• 守护进程化：设置 daemonize => 1 让服务器后台运行，配合 log_file 记录日志。
• Worker 进程数：设置为 CPU 核心数的 1-2 倍，充分利用多核。
• 协程连接池大小：根据数据库最大连接数合理设置，一般 20-50 足够。
• 平滑重启：使用 kill -USR2 信号重启 Worker 进程，不中断对外服务。
• Nginx 反向代理：在前端放置 Nginx 处理静态资源、SSL 终止和负载均衡，将动态请求代理到 Swoole 服务器。

一个典型的 Nginx 配置片段：

upstream swoole_upstream {
    server 127.0.0.1:9501;
    keepalive 200;
}
server {
    listen 80;
    location /api/ {
        proxy_pass http://swoole_upstream/;
        proxy_http_version 1.1;
        proxy_set_header Connection "keep-alive";
    }
}

另外，建议结合 Supervisor 或 systemd 守护进程监控 Swoole 服务，确保意外退出后自动拉起。

八、总结与扩展

通过本实战教程，我们从零构建了一个基于 Swoole 协程的 PHP 微服务，完整实现了用户 CRUD API，并引入协程连接池大幅提升数据库交互效率。这个架构轻松支撑了每秒四千以上的并发请求，证明了 PHP 在协程加持下完全可以胜任高并发场景。

你可以在此基础上扩展更多功能：

• 引入 中间件 处理鉴权、日志、跨域等。
• 集成 Redis 协程客户端 实现缓存和会话管理。
• 利用 定时任务 和 WebSocket 构建实时应用。
• 使用 Hyperf 或 Swoft 框架获得更完备的企业级功能。

Swoole 让 PHP 突破了原有的边界，但编写协程代码时仍需注意避免阻塞调用（如原生 file_get_contents），务必使用协程化客户端。随着 PHP 生态的持续协程化，越来越多的库开始原生支持 Swoole，这使得 PHP 在高性能服务领域拥有了更强的竞争力。