后端微服务【免费下载链接】hyperf A coroutine framework that focuses on hyperspeed and flexibility. Building microservice or middleware with ease.项目地址https://gitcode.com/gh_mirrors/hy/hyperf点击查看免费下载Hyperf 作为一款基于 Swoole 的协程框架内置了对 TCP/UDP 服务的开箱即用支持开发者只需编写一个事件回调类、在server.php配置中声明一个监听端口即可启动一个高性能的 TCP/UDP Socket 服务无需关心底层的事件循环与协程调度。本文将以官方文档docs/en/tcp-server.md为核心脉络结合仓库中src/server与src/contract的源码实现完整讲解 TCP 服务与 UDP 服务的搭建步骤、核心事件模型、底层 Server 构建原理以及多端口混合监听的实战技巧帮助你快速掌握用 Hyperf 承载自定义二进制协议、物联网长连接或 UDP 数据采集服务的方法。一、整体认知Hyperf 的 TCP/UDP 服务能力Hyperf 默认就具备创建 TCP/UDP 服务的能力。与 HTTP 服务类似TCP/UDP 服务同样基于 Swoole 的Swoole\Server构建因此天然继承 Swoole 的异步事件驱动、多 Worker 进程模型与协程调度能力。你只需要完成两件事编写一个回调类实现框架约定的回调接口如OnReceiveInterface、OnPacketInterface在对应方法中处理业务逻辑编写一段配置在项目的config/autoload/server.php中声明一个servers节点指定监听地址、端口、Socket 类型与事件回调。框架会在启动时根据配置自动完成底层 Server 的创建、事件注册与生命周期管理让开发者把精力完全集中在业务回调上。在深入配置之前先理解 Server 的类型体系。在 ServerInterface 中定义了三种服务类型常量常量值说明ServerInterface::SERVER_HTTP1HTTP 服务ServerInterface::SERVER_WEBSOCKET2WebSocket 服务ServerInterface::SERVER_BASE3基础 TCP/UDP 服务TCP 与 UDP 服务使用的正是SERVER_BASE类型。在 Server::makeServer 中可以看到当type为SERVER_BASE时框架会直接new SwooleServer($host, $port, $mode, $sockType)即创建一个纯 Swoole 基础 Server不附带任何 HTTP/WebSocket 协议解析能力数据以原始字节流形式交给回调处理。二、搭建 TCP 服务2.1 创建 TcpServer 回调类首先创建一个处理 TCP 数据收发的类实现Hyperf\Contract\OnReceiveInterface接口?php declare(strict_types1); namespace App\Controller; use Hyperf\Contract\OnReceiveInterface; class TcpServer implements OnReceiveInterface { public function onReceive($server, int $fd, int $reactorId, string $data): void { $server-send($fd, recv: . $data); } }OnReceiveInterface的定义位于 src/contract/src/OnReceiveInterface.php其方法签名约束如下$server当前 Swoole Server 实例类型可能为Swoole\Server、协程风格的Swoole\Coroutine\Server\Connection或Hyperf\Server\Connection与运行模式相关可直接调用其send()等方法向客户端回写数据$fd客户端连接的文件描述符用于标识一条 TCP 连接$reactorIdReactor 线程 ID在 BASE 模式下通常为 0 或-1$data收到的原始数据内容二进制或文本均可Swoole 默认不解析协议交给回调自行处理。上述示例的业务逻辑非常简单收到任何数据后向该连接回写recv:前缀加上原始数据实现一个回声 前缀的迷你服务。2.2 创建对应的服务配置接着在config/autoload/server.php的servers数组中增加一个节点以下仅展示与本服务相关的配置项其余无关配置已省略?php declare(strict_types1); use Hyperf\Server\Server; use Hyperf\Server\Event; return [ // The following has removed other irrelevant configuration items servers [ [ name tcp, type Server::SERVER_BASE, host 0.0.0.0, port 9504, sock_type SWOOLE_SOCK_TCP, callbacks [ Event::ON_RECEIVE [App\Controller\TcpServer::class, onReceive], ], settings [ // Configure on demand ], ], ], ];各配置项含义与底层映射如下name服务名称用于在ServerManager中注册与区分多个服务。如果不显式设置框架在 ServerConfig 中会尝试用数组键作为服务名当键为非数字时type服务类型这里必须是Server::SERVER_BASE等价于ServerInterface::SERVER_BASE 3host监听地址0.0.0.0表示监听本机所有网卡若仅需本机访问可填127.0.0.1。Port类的默认 host 为0.0.0.0见 Portport监听端口示例为9504注意避免与系统已占用端口冲突sock_typeSocket 类型TCP 服务使用 Swoole 常量SWOOLE_SOCK_TCPUDP 服务使用SWOOLE_SOCK_UDPcallbacks事件回调映射Event::ON_RECEIVE [类名, 方法名]声明收到数据时调用哪个类的哪个方法settingsSwoole Server 运行参数如worker_num、open_length_check等按需配置留空数组即可。一个容易被忽略的细节当type为SERVER_BASE时Port::filter 会自动向 settings 中合并两个默认值——open_http2_protocol false与open_http_protocol false确保基础 TCP/UDP 端口不会被意外解析为 HTTP 协议。该行为在 PortTest 中有对应的单元测试验证。2.3 编写客户端进行联调配置完成后启动服务php bin/hyperf.php start即可用一个最朴素的 Swoole 客户端验证服务是否工作?php $client new \Swoole\Client(SWOOLE_SOCK_TCP); $client-connect(127.0.0.1, 9504); $client-send(Hello World.); $ret $client-recv(); // recv:Hello World.当服务端收到Hello World.后回调onReceive会执行$server-send($fd, recv:Hello World.)因此客户端recv()拿到的返回值即为recv:Hello World.与预期完全一致。除了Swoole\Client你同样可以使用系统自带的nc -v 127.0.0.1 9504、telnet 127.0.0.1 9504等命令行工具进行冒烟测试或者用任意语言的 Socket 客户端发送原始字节流。三、搭建 UDP 服务UDP 是面向无连接的数据报协议服务端通常以收到一个数据包 → 处理 → 回发一个数据包的方式工作。Hyperf 对 UDP 的支持同样简洁。3.1 创建 UdpServer 回调类?php declare(strict_types1); namespace App\Controller; use Hyperf\Contract\OnPacketInterface; class UdpServer implements OnPacketInterface { public function onPacket($server, $data, $clientInfo): void { var_dump($clientInfo); $server-sendto($clientInfo[address], $clientInfo[port], Server: . $data); } }注意官方文档特别说明——如果项目中不存在OnPacketInterface接口文件例如未安装hyperf/contract的早期版本可以不实现该接口只要配置正确运行结果与实现了接口完全一致。也就是说UDP 回调类的编写非常灵活接口实现并非硬性约束。OnPacketInterface的定义位于 src/contract/src/OnPacketInterface.php回调参数含义如下$serverSwoole Server 实例$data收到的 UDP 数据包内容$clientInfo客户端信息数组包含address客户端 IP、port客户端端口等字段可用于定位发送方并决定回包目标。示例逻辑中先var_dump($clientInfo)打印客户端信息方便观察联调时的来源地址再通过$server-sendto($clientInfo[address], $clientInfo[port], Server: . $data)向客户端回写一个带Server:前缀的数据包。3.2 创建对应的服务配置?php declare(strict_types1); use Hyperf\Server\Server; use Hyperf\Server\Event; return [ // The following has removed other irrelevant configuration items servers [ [ name udp, type Server::SERVER_BASE, host 0.0.0.0, port 9505, sock_type SWOOLE_SOCK_UDP, callbacks [ Event::ON_PACKET [App\Controller\UdpServer::class, onPacket], ], settings [ // Configure on demand ], ], ], ];与 TCP 配置相比仅有两处不同sock_type改为SWOOLE_SOCK_UDP回调事件由Event::ON_RECEIVE改为Event::ON_PACKET。3.3 UDP 客户端联调启动服务后可用Swoole\Client的 UDP 模式或nc -u 127.0.0.1 9505发送数据包验证?php $client new \Swoole\Client(SWOOLE_SOCK_UDP); $client-connect(127.0.0.1, 9505); $client-send(Hello UDP.); $ret $client-recv(); // Server:Hello UDP.由于 UDP 无连接特性connect()在这里只是绑定对端地址send()发送数据报后服务端onPacket回调会收到数据与客户端信息并通过sendto()回包。四、事件模型TCP/UDP 服务的回调事件总览配置中的callbacks项本质上是事件名 → 回调的映射。框架在 Server::registerSwooleEvents 中遍历该映射对每个合法 Swoole 事件调用$server-on($event, $callback)完成注册若回调是[类名, 方法名]数组形式框架会通过容器解析该类从而获得完整的依赖注入与 AOP 能力并自动调用initCoreMiddleware初始化核心中间件若类实现了MiddlewareInitializerInterface。与 TCP/UDP 服务直接相关的核心事件定义在 src/server/src/Event.php 中汇总如下事件常量常量值触发时机说明Event::ON_CONNECTconnect新客户端连接建立监听连接进入事件可用于连接鉴权、计数或初始化连接上下文Event::ON_RECEIVEreceive收到 TCP 数据监听数据接收事件TCP 业务的核心入口Event::ON_CLOSEclose客户端连接关闭监听连接关闭事件用于清理连接资源、下线通知等Event::ON_PACKETpacket收到 UDP 数据报UDP 数据接收事件UDP 业务的核心入口Event类还定义了start、workerStart、workerStop、managerStart、shutdown、pipeMessage等进程级事件供defaultCallbacks见 Server::defaultCallbacks自动注册以完成框架自身的引导流程如启动协程运行时、初始化配置中心等。因此即使你的callbacks只写了ON_RECEIVE一个事件框架的生命周期引导也由内部默认回调保证。一个更完整的 TCP 服务配置示例同时注册连接进入与关闭事件方便做在线状态管理callbacks [ Event::ON_CONNECT [App\Controller\TcpServer::class, onConnect], Event::ON_RECEIVE [App\Controller\TcpServer::class, onReceive], Event::ON_CLOSE [App\Controller\TcpServer::class, onClose], ],对应的回调类方法实现方式与onReceive相同按接口约定实现即可public function onConnect($server, int $fd): void { // 连接建立可记录 fd、客户端地址或下发欢迎消息 $server-send($fd, Welcome!); } public function onClose($server, int $fd): void { // 连接关闭清理该 fd 对应的会话状态 }五、源码级原理TCP/UDP Server 是如何被构建出来的理解底层构建链路有助于你在遇到多端口、多协议混跑场景时做出正确配置。整个启动流程由 Server 驱动关键节点如下配置解析ServerConfig构造函数校验servers节点必须存在否则抛出InvalidArgumentException(Config server.servers not exist.)见 ServerConfig随后将每个子项通过Port::build()构造成Port对象见 Port::build。端口排序sortServers()会优先将 WebSocket/HTTP 端口排在最前普通 TCP/UDP 端口追加在末尾保证 HTTP 相关 Server 作为主 Server 创建见 Server::sortServers。主 Server 创建initServers()遍历排序后的端口列表——第一个端口调用makeServer()依据type创建主 Swoole ServerSERVER_BASE对应Swoole\Server见 Server::makeServer后续端口调用addlistener()挂载为额外监听端口见 Server::initServers。这意味着你可以在同一进程内同时监听多个 TCP/UDP 端口甚至与 HTTP/WebSocket 服务共存——只需在servers数组中追加多个节点即可。事件注册与参数合并callbacks经容器解析后注册到 Swoolesettings采用全局 settings 与端口级 settings 合并端口级优先的规则array_replace。注册到 ServerManager每个服务以name为键注册进 ServerManager业务代码可通过ServerManager::get($name)在任意协程内取回对应端口的 Server 实例用于主动推送等场景。多服务共存示例若你想让一个进程同时提供 HTTP API9501与 TCP 长连接9504只需在servers数组中同时保留 HTTP 节点与上述 TCP 节点。框架会自动把 HTTP 端口作为主 ServerTCP 端口作为附加监听端口。六、进阶实践建议自定义协议解析TCP 是基于字节流的onReceive拿到的数据可能不是完整的一帧。可通过settings配置 Swoole 的协议选项如open_length_check、package_length_offset、package_body_offset、package_max_length开启自动分包或在回调中自行实现粘包拆包逻辑。连接资源管理大量长连接场景下务必在ON_CLOSE中清理该fd对应的内存状态避免连接泄漏可用Coroutine\Channel或 Redis 记录在线 fd 列表。UDP 大数据包UDP 单个数据报有 MTU 限制通常 1472 字节左右业务设计时需控制单包大小或自行实现分片与重组协议。性能调优在settings中按需设置worker_num、open_tcp_nodelay、backlog等参数多 Worker 下注意fd归属与进程间通信必要时使用sendMessage进行pipeMessage跨进程消息传递。结合框架生态TCP/UDP 回调类是经由容器解析的因此可以在回调方法中通过构造函数注入任意 Hyperf 组件如 Redis、数据库连接池、Logger无缝复用框架能力。七、小结通过docs/en/tcp-server.md这份文档可以总结出 Hyperf TCP/UDP 服务的四步套路实现回调接口 → 编写回调方法 → 在server.php中声明SERVER_BASE类型端口 → 启动并联调。底层由 Server 统一完成 Swoole Server 的创建、事件注册与容器化回调绑定配合 Event 中的ON_CONNECT/ON_RECEIVE/ON_CLOSE/ON_PACKET四个核心事件足以覆盖绝大多数自定义 Socket 协议服务的开发需求。同时由于支持多端口混合监听TCP/UDP 服务可以很自然地与 HTTP/WebSocket 服务共存于同一 Hyperf 应用之中是构建物联网网关、即时通讯、游戏服务端或二进制协议网关时的可靠选择。赞分享后端微服务【免费下载链接】hyperf A coroutine framework that focuses on hyperspeed and flexibility. Building microservice or middleware with ease.项目地址https://gitcode.com/gh_mirrors/hy/hyperf点击查看免费下载相关推荐Hyperf 协程框架 TCP/UDP 服务开发实战指南Hyperf 协程框架 TCP/UDP 服务开发实战指南 Hyperf 框架开箱即用地提供了基于 Swoole 的 TCP/UDP 网络服务能力你不需要额外引后端微服务Hyperf TCP/UDP 服务开发指南从零搭建自定义网络协议服务Hyperf TCP/UDP 服务开发指南从零搭建自定义网络协议服务 Hyperf 协程框架默认内置了基于 Swoole 的 TCP/UDP 服务创建能力只后端Web框架微服务RPC框架异步编程pysheeet 实战指南用 Python socket 构建 TCP/UDP 服务器从 Echo 到零拷贝 sendfilepysheeet 实战指南用 Python socket 构建 TCP/UDP 服务器从 Echo 到零拷贝 sendfile 本篇指南基于 pyshee文档教程开发工具上一篇如何利用AIRealNet在10分钟内搭建AI图像检测系统完整教程下一篇ParlAI 对话矛盾检测实战DECODE 数据集加载、JSONL 格式解析与矛盾判定创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考