后端Web框架微服务RPC框架异步编程【免费下载链接】hyperf A coroutine framework that focuses on hyperspeed and flexibility. Building microservice or middleware with ease.项目地址https://gitcode.com/hyperf/hyperf点击查看免费下载本文基于 Hyperf 官方文档 安装指南 撰写并结合仓库内框架源码如 StartServer.php、ScanConfig.php与 composer.json 中的真实依赖约束为开发者提供一份可直接落地的安装与部署手册。读完本文你将掌握 Hyperf 的服务器环境要求、通过 Composer 创建骨架项目、在 Docker 容器中完成开发与启动的完整流程并能独立排查 Swoole 短名未关闭、扫描缓存、兼容性扩展等常见启动故障。一、服务器要求Hyperf 是一个基于协程的常驻内存 CLI 框架对运行环境有明确要求。首先需要明确一个前提当使用 Swoole 网络引擎驱动时Hyperf 仅可运行于 Linux 和 Mac 环境下但由于 Docker 虚拟化技术的发展在 Windows 下也可以通过 Docker for Windows 作为运行环境。通常来说Mac 环境下更推荐本地环境部署以避免 Docker 共享磁盘缓慢导致 Hyperf 启动速度慢的问题。而当您使用Swow网络引擎驱动时则可在 Windows、Linux、Mac 下直接运行。如果不想自行搭建环境官方提供了两条捷径hyperf/hyperf-docker 项目内已经准备好了各种版本的 Dockerfile也可以直接基于已经构建好的 hyperf/hyperf 镜像来运行当您不想采用 Docker 作为运行的环境基础时也可以考虑使用 Box 来作为运行的基础环境。Box 由 Hyperf 团队维护用于管理 PHP 环境与相关依赖支持将 PHP 应用打包为二进制程序并提供反向代理服务来管理和部署 Swoole/Swow 服务。如果您希望自行完成环境搭建则需要确保运行环境达到以下要求依赖项版本要求说明PHP 8.2框架在 composer.json 中以php: 8.2约束Swoole PHP 扩展 5.0网络引擎二选一需关闭Short Name即swoole.use_shortname OffSwow PHP 扩展 1.4网络引擎二选一JSON PHP 扩展—必装Pcntl PHP 扩展—仅在 Swoole 引擎时需要OpenSSL PHP 扩展—如需要使用 HTTPS 时需要PDO PHP 扩展—如需要使用 MySQL 客户端时需要Redis PHP 扩展—如需要使用 Redis 客户端时需要Protobuf PHP 扩展—如需要使用 gRPC 服务端或客户端时需要注意在仓库根目录 composer.json 的require段中同样声明了ext-json、ext-pdo、ext-redis、ext-swoole: 5.0等硬性依赖这与官方文档的服务器要求完全一致说明这些扩展是框架正常安装与运行的前提。Swoole 短名Short Name必须关闭使用 Swoole 引擎时swoole.use_shortname必须设置为Off否则服务无法启动。这一检查在框架的启动命令中有硬性校验在 StartServer.php 的checkEnvironment()方法中框架会读取ini_get_all(swoole)[swoole.use_shortname][local_value]当该值不属于、off、false时会直接输出错误并终止进程[ERROR] Swoole short function names must be disabled before the server starts, please set swoole.use_shortname Off in your php.ini.解决方案有两种在php.ini配置文件中增加swoole.use_shortname Off配置项。注意该配置必须在php.ini内配置无法通过ini_set()函数在运行时重写在执行 PHP 命令时临时关闭php -d swoole.use_shortnameOff bin/hyperf.php start二、通过 Composer 创建项目Hyperf 使用 Composer 来管理项目依赖在使用 Hyperf 之前请确保运行环境已经安装好了 Composer。官方已经准备好了一个骨架项目Skeleton内置了常用的组件、相关配置文件及目录结构是一个可以快速用于业务开发的 Web 项目基础。在安装时您可以根据自身的需求对组件依赖进行选择。在当前所在位置创建骨架项目基于 Swoole 驱动composer create-project hyperf/hyperf-skeleton基于 Swow 驱动composer create-project hyperf/swow-skeleton安装过程中对于自己不清楚的选项请直接使用回车处理避免因自动添加了部分监听器、但又没有正确配置时导致服务无法启动的问题。骨架项目创建完成后即可在项目根目录通过php bin/hyperf.php start启动服务详见后文「启动 Hyperf 服务」一节。三、Docker 下开发假设您的本机环境并不能达到 Hyperf 的环境要求或对环境配置不是那么熟悉那么可以通过 Docker 来运行及开发 Hyperf 项目。Docker 方案的优势在于官方镜像已经预装好 PHP、Swoole/Swow 及所需的扩展无需关心本机环境的差异。1. 启动容器可以根据实际情况把容器内目录映射到宿主机对应的目录以下以/workspace/skeleton为例docker run --name hyperf \ -v /workspace/skeleton:/data/project \ -w /data/project \ -p 9501:9501 -it \ --privileged -u root \ --entrypoint /bin/sh \ hyperf/hyperf:8.1-alpine-v3.18-swoole如果 docker 启动时开启了selinux-enabled选项容器内访问宿主机资源就会受限所以启动容器时可以增加--privileged -u root选项。各参数含义说明--name hyperf为容器命名便于后续管理-v /workspace/skeleton:/data/project将宿主机的/workspace/skeleton目录挂载到容器内的/data/project实现代码共享与持久化-w /data/project设置容器内工作目录-p 9501:9501将容器内的 9501 端口Hyperf HTTP 服务默认端口映射到宿主机-it以交互模式进入容器--entrypoint /bin/sh以 Shell 作为容器入口便于手动执行命令镜像hyperf/hyperf:8.1-alpine-v3.18-swoole基于 Alpine Linux、PHP 8.1、Swoole 引擎的官方镜像。2. 创建项目进入容器交互终端后在工作目录中创建骨架项目composer create-project hyperf/hyperf-skeleton3. 启动项目cd hyperf-skeleton php bin/hyperf.php start接下来就可以在宿主机的/workspace/skeleton/hyperf-skeleton中看到您安装好的代码了。由于 Hyperf 是持久化的 CLI 框架当您修改完代码后需要通过CTRL C终止当前启动的进程实例并重新执行php bin/hyperf.php start启动命令才能使新代码生效。补充在 Docker 环境开发时需注意官方骨架包中的 Dockerfile 默认开启了scan_cacheable详见后文「生产部署优化scan_cacheable」它会导致收集器缓存存在时不再扫描文件从而出现「修改代码不生效」的假象。开发阶段请勿将其设为true。四、启动 Hyperf 服务与代码重载原理1. 启动命令的底层实现由于 Hyperf 内建了协程服务器它将以 CLI 的形式运行。在定义好路由及业务逻辑代码之后需要在项目根目录通过命令行执行php bin/hyperf.php start该命令对应框架源码中的 StartServer.php其核心执行流程为checkEnvironment()校验 Swoole 短名是否关闭、运行环境是否满足要求从容器获取ServerFactory并注入事件分发器与日志组件读取server配置对应config/autoload/server.php若未定义任何 Server 则抛出At least one server should be defined.异常通过Coroutine::set([hook_flags swoole_hook_flags()])设置协程 Hook 标志调用$serverFactory-start()启动协程服务器。启动后服务会监听server.php中配置的地址与端口。默认情况下Hyperf 提供一个首页http://127.0.0.1:9501/。当Console界面显示服务启动后便可通过cURL或浏览器对服务正常发起访问。关于路由、控制器定义的完整示例请参阅 快速入门 文档。2. 为什么修改代码后必须重启Hyperf 是持久化的 CLI 应用一旦进程启动已解析的 PHP 代码会持久化在进程中因此启动服务后再修改的 PHP 代码不会改变已启动的服务。如希望服务重新加载修改后的代码需要在启动的Console中键入CTRL C终止服务再重新执行启动命令php bin/hyperf.php start。Tips您也可以将启动 Server 的命令配置在 IDE 上通过 IDE 的「启动 / 停止」操作快捷完成服务的启动与重启非视图开发时可以采用 TDD测试驱动开发进行开发这样不仅可以省略服务重启和频繁切换窗口的麻烦还可保证接口数据的正确性在文档 协程组件库 一章中提供了多种由社区开发者支持的热更新 / 热重载解决方案如 watcher 组件如希望采用热更新方案可再深入了解。3. 常见启动相关配置速查结合仓库内 常见问题 文档这里整理几个与启动直接相关的排查要点场景处理方式内存限制太小导致项目无法运行PHP 默认memory_limit只有 128M可执行php -d memory_limit-1 bin/hyperf.php start或修改php.ini先用php --ini查看配置文件位置语法错误导致服务无法启动报错形如Fatal error: Uncaught PhpParser\Error: Syntax error...时可执行composer analyse对项目进行静态检测定位问题代码段环境版本不一致导致服务无法启动报错形如Hyperf\Engine\Channel::push(...) must be compatible with Swoole\Coroutine\Channel::push(...)时说明实际运行时的 Swoole 版本与安装框架/组件时的版本不一致使用相同版本即可解决代码不生效执行composer dump-autoload -o开发阶段不要设置scan_cacheable为true五、生产部署优化开启 scan_cacheable以下内容整理自 编程须知 与 ScanConfig.php 源码。官方 Dockerfile 已默认完成以下操作。线上代码部署时请务必开启scan_cacheable。开启此配置后首次扫描时会生成代理类和注解缓存再次启动时可以直接使用缓存极大优化内存使用率和启动速度。在源码层面ScanConfig.php 的initConfigByFile()方法会从项目config/config.php中读取该配置并遵循以下规则$appEnv $configContent[app_env] ?? dev; $cacheable value($configContent[scan_cacheable] ?? $appEnv prod);也就是说scan_cacheable默认为false开发模式dev当app_env为prod时自动启用也可以在config/config.php中显式指定scan_cacheable true。由于开启缓存后会跳过扫描阶段因此会依赖 Composer Class Map故必须执行--optimize-autoloader优化索引。综上线上更新代码、重启项目前需要执行以下命令# 优化 Composer 索引 composer dump-autoload -o # 生成代理类和注解缓存 php bin/hyperf.php注意当环境变量存在SCAN_CACHEABLE时.env中无法修改这个配置环境变量优先级更高。六、存在兼容性问题的扩展由于 Hyperf 基于 Swoole 协程实现而 Swoole 4 带来的协程功能是 PHP 前所未有的所以与不少扩展仍存在兼容性问题。以下扩展包括但不限于都会造成一定的兼容性问题不能与 Hyperf 共用或共存xhprofxdebug当 PHP 版本 8.2 且 Swoole 版本大于等于 5.0.2 时可用blackfiretraceuopz七、版本规则与升级Hyperf 采用x.y.z的版本号规则命名各个版本例如1.2.3中 1 为 x2 为 y3 为 z您可以根据该规则制定更新计划x重大版本。当核心进行大量重构或存在大量破坏性 API 变更时发布通常无法与之前的 x 版本完全兼容具体以对应版本的升级指南为准y主要功能迭代版本。当一些公开 API 进行了破坏性变更包括公开 API 的变更和删除导致前置版本可能无法兼容时发布z完全兼容的修复版本。当对各个组件的已有功能进行 BUG 修复或安全修复时发布z 版本也可能包括一些不影响此前代码使用的新增功能或组件。当您希望升级 Hyperf 版本时对x 和 y 版本的升级请根据 版本升级指南对应版本目录下的升级指南进行操作对z 版本的升级可直接在项目根目录执行composer update hyperf来更新依赖包。不建议单独升级某一个组件而是统一升级所有组件以获得更加一致的体验。八、快速开始您的第一个 Hyperf 服务安装完成并启动服务后您可以参考 快速入门 文档通过定义路由、控制器、依赖注入来完成第一个 HTTP 服务。核心步骤如下在config/routes.php中通过Router::get()等方法定义路由或使用#[AutoController]/#[Controller]注解定义控制器路由通过构造函数注入或#[Inject]注解注入获得业务服务类执行php bin/hyperf.php start启动服务访问http://127.0.0.1:9501/验证效果若需多端口监听可通过 server.php 配置 中的servers数组配置多个 Server并在依赖关系config/autoload/dependencies.php中重新定义 Server 以保证对象隔离。至此您已经完成了从环境准备、项目创建、容器化开发到生产部署优化的完整安装闭环可以正式开始基于 Hyperf 的业务开发了。赞分享后端Web框架微服务RPC框架异步编程【免费下载链接】hyperf A coroutine framework that focuses on hyperspeed and flexibility. Building microservice or middleware with ease.项目地址https://gitcode.com/hyperf/hyperf点击查看免费下载相关推荐Hyperf 安装指南环境要求、Composer 创建项目与 Docker 开发部署Hyperf 安装指南环境要求、Composer 创建项目与 Docker 开发部署 本篇指南完整覆盖 Hyperf 协程框架的安装与初始化流程从 PHP后端Web框架微服务RPC框架异步编程Hyperf 安装部署指南环境要求、Composer 快速创建与 Docker 开发实战Hyperf 安装部署指南环境要求、Composer 快速创建与 Docker 开发实战 Hyperf 是一个基于 Swoole/Swow 协程的高性能 PH后端Web框架微服务RPC框架异步编程Hyperf 安装指南环境要求、Composer 骨架项目创建与 Docker 开发部署全流程Hyperf 安装指南环境要求、Composer 骨架项目创建与 Docker 开发部署全流程 本指南以 Hyperf 官方安装文档为主体完整覆盖从运行环境后端微服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考