企业官网建设流程全解析

• 后端
• Web框架
• 微服务
• RPC框架
• 异步编程

本文围绕 Hyperf 官方生态中的hyperf/nano组件展开，它是 Hyperf 的一个"极简发行版"：无需脚手架（Skeleton）、零配置，仅用一个 PHP 文件即可启动一个完整的 Hyperf 应用。本文将完整讲解它的安装方式、快速开始流程、闭包风格 API 以及路由、DI 容器、中间件、异常处理、命令行、事件监听、自定义进程、定时任务、Hyperf 组件集成等全部实战用法，并结合本仓库中的相关源码（如 DB 组件、StdoutLoggerInterface 等）说明其底层原理。读完本文，你将掌握用 Nano 在几十行代码内搭建协程 Web 服务、命令行工具与后台任务的能力。

什么是 hyperf/nano

hyperf/nano将整个 Hyperf 框架"压缩"到单个 PHP 文件中。在传统 Hyperf 项目中，你需要通过骨架（Skeleton）创建包含config/、app/、bin/等目录的完整工程，并维护大量配置文件；而使用 Nano 时，你只需一个index.php，在其中通过Hyperf\Nano\Factory\AppFactory创建应用实例，用闭包风格注册路由与各种能力，最后调用$app->run()启动即可。

它非常适合以下场景：

• 快速原型验证（PoC）与脚本化服务；
• 微服务中的轻量边缘服务、健康检查端点；
• 演示、教学与测试环境；
• 希望把应用打包为 Phar 单文件的部署场景。

特性一览

Nano 官方文档明确列出的特性如下：

其中"支持注解外的全部 Hyperf 功能"是关键约束：Nano 以闭包替代注解驱动的路由、AOP 切面注册等能力，因此基于注解的控制器风格在 Nano 中不适用，但组件级能力（数据库、缓存、队列、事件等）不受影响。

安装 hyperf/nano

在已初始化 Composer 的项目目录中执行：

composer require hyperf/nano

安装完成后，项目下会生成vendor/autoload.php。Nano 是独立分发的包，可安装到任意 PHP 8.0+（以当前 Composer 依赖约束为准）且已安装 Swoole 扩展的环境中。安装后即可直接编写单文件应用，无需执行composer install之外的任何初始化命令。

快速开始：第一个单文件应用

创建index.php，内容如下（完整保留自官方文档）：

<?php // index.php use Hyperf\Nano\Factory\AppFactory; require_once __DIR__ . '/vendor/autoload.php'; $app = AppFactory::create('0.0.0.0', 9051); $app->get('/', function () { $user = $this->request->input('user', 'nano'); $method = $this->request->getMethod(); return [ 'message' => "hello {$user}", 'method' => $method, ]; }); $app->run();

启动服务：

php index.php start

简洁如此——一个可运行的 Hyperf HTTP 服务就诞生了。随后访问http://127.0.0.1:9051/?user=hyperf，将得到：

{"message": "hello hyperf", "method": "GET"}

对这段代码做几点拆解：

• AppFactory::create('0.0.0.0', 9051)：创建应用实例，前两个参数为监听地址与端口；从官方其余示例可见AppFactory::create()也可以不传参数，直接使用默认地址与端口。
• $app->get('/path', Closure)：以闭包注册 HTTP 路由处理器。
• 闭包内的$this被绑定为Hyperf\Nano\ContainerProxy（详见下文 DI 容器一节），因此可以直接通过$this->request访问当前 PSR-7 请求对象：input()读取查询参数并支持默认值，getMethod()获取 HTTP 方法。
• 闭包直接返回数组，Nano 会自动将其序列化为 JSON 响应。
• $app->run()：启动应用并阻塞运行。start是 Nano 提供的服务器管理命令（与 Swoole 常驻进程的管理方式一致），此外还支持stop、restart等常规命令。

更多实战示例

1. 路由：集成 Hyperf 路由器的全部方法

$app集成了 Hyperf 路由器（Router）的所有方法，包括get、post、put、delete、addRoute、addGroup等。下面演示路由分组与带正则约束的参数路由：

<?php use Hyperf\Nano\Factory\AppFactory; require_once __DIR__ . '/vendor/autoload.php'; $app = AppFactory::create(); $app->addGroup('/nano', function () use ($app) { $app->addRoute(['GET', 'POST'], '/{id:\d+}', function($id) { return '/nano/'.$id; }); $app->put('/{name:.+}', function($name) { return '/nano/'.$name; }); }); $app->run();

要点说明：

• addGroup('/nano', Closure)为一组路由添加统一前缀；
• addRoute(['GET', 'POST'], '/{id:\d+}', ...)表示该路径同时接受 GET 与 POST 方法，{id:\d+}使用正则约束参数只能为数字，路由参数会自动注入闭包形参$id；
• put('/{name:.+}', ...)演示了 PUT 方法与通配正则参数{name:.+}；
• 路由匹配失败会落入 404 响应，这与完整版 Hyperf 的路由行为一致。

2. DI 容器：$this即 ContainerProxy

Nano 管理的所有闭包回调（包括中间件、异常处理器等）中，$this都被绑定到Hyperf\Nano\ContainerProxy。这意味着你可以在闭包内直接使用容器能力：

<?php use Hyperf\Nano\ContainerProxy; use Hyperf\Nano\Factory\AppFactory; require_once __DIR__ . '/vendor/autoload.php'; class Foo { public function bar() { return 'bar'; } } $app = AppFactory::create(); $app->getContainer()->set(Foo::class, new Foo()); $app->get('/', function () { /** @var ContainerProxy $this */ $foo = $this->get(Foo::class); return $foo->bar(); }); $app->run();

• $app->getContainer()返回 Hyperf 的 DI 容器实例，可调用set()手动注册对象（对应完整版 Hyperf 中 DI 组件 的能力）；
• 闭包内$this->get(Foo::class)即从容器解析依赖；ContainerProxy还代理了容器与request、response等上下文对象，所以前文的$this->request才能直接使用；
• 借助容器，你可以像在完整 Hyperf 中一样面向接口编程、按需装配服务。

3. 中间件：PSR-7 请求/响应管道

通过addMiddleware注册中间件，闭包签名为function ($request, $handler)，返回$handler->handle($request)的结果以继续管道：

<?php use Hyperf\Nano\Factory\AppFactory; require_once __DIR__ . '/vendor/autoload.php'; $app = AppFactory::create(); $app->get('/', function () { return $this->request->getAttribute('key'); }); $app->addMiddleware(function ($request, $handler) { $request = $request->withAttribute('key', 'value'); return $handler->handle($request); }); $app->run();

访问/将得到value，说明请求对象在中间件中携带的属性被传递到了路由闭包。

这里有一条通用规则：除了闭包之外，所有$app->addXXX()方法（addMiddleware、addExceptionHandler、addListener、addProcess等）同样接受类名作为参数，可以传入任意对应的 Hyperf 类（如标准的中间件类），让 Nano 应用复用现有类库。

4. 异常处理：自定义异常响应

通过addExceptionHandler注册全局异常处理器，闭包签名为function ($throwable, $response)：

<?php use Hyperf\HttpMessage\Stream\SwooleStream; use Hyperf\Nano\Factory\AppFactory; require_once __DIR__ . '/vendor/autoload.php'; $app = AppFactory::create(); $app->get('/', function () { throw new \Exception(); }); $app->addExceptionHandler(function ($throwable, $response) { return $response->withStatus('418') ->withBody(new SwooleStream('I\'m a teapot')); }); $app->run();

• 路由闭包抛出\Exception后，由异常处理器接管；
• 处理器基于 PSR-7 响应对象重建响应：withStatus('418')设置 HTTP 状态码（418 "I'm a teapot" 为 HTTP 协议中的趣味状态码），withBody(new SwooleStream(...))用 SwooleStream 包装响应体——该流实现在本仓库 http-message 组件 中，是 Hyperf 标准 HTTP 消息层的一部分；
• 多个异常处理器按注册顺序构成处理链，这一点与完整版 Hyperf 的异常处理机制（exception-handler 组件）一致。

5. 命令行：注册自定义命令

用addCommand注册命令，命令名作为第一个参数：

<?php use Hyperf\Contract\StdoutLoggerInterface; use Hyperf\Nano\Factory\AppFactory; require_once __DIR__ . '/vendor/autoload.php'; $app = AppFactory::create(); $app->addCommand('echo', function(){ $this->get(StdoutLoggerInterface::class)->info('A new command called echo!'); }); $app->run();

执行命令：

php index.php echo

• 命令闭包内同样通过$this->get(StdoutLoggerInterface::class)从容器取出标准输出日志器——StdoutLoggerInterface 定义在 contract 组件 中，继承自 PSR-3LoggerInterface，其info()等方法可直接打印带颜色的终端日志；
• 在 Nano 应用中，php index.php start启动服务、php index.php echo执行命令，命令与服务器管理命令共享同一入口。

6. 事件监听：订阅框架生命周期事件

用addListener监听 Hyperf 事件，事件类与闭包一一对应：

<?php use Hyperf\Contract\StdoutLoggerInterface; use Hyperf\Framework\Event\BootApplication; use Hyperf\Nano\Factory\AppFactory; require_once __DIR__ . '/vendor/autoload.php'; $app = AppFactory::create(); $app->addListener(BootApplication::class, function($event){ $this->get(StdoutLoggerInterface::class)->info('App started'); }); $app->run();

启动应用时终端会输出 "App started"。其中 BootApplication 是 framework 组件 中定义的应用启动事件，在框架引导完成、应用即将运行时触发。你可以把初始化逻辑（如预热缓存、注册资源）放在该监听器闭包中。

7. 自定义进程：常驻后台任务

用addProcess注册自定义常驻进程，闭包内是进程主循环：

<?php use Hyperf\Contract\StdoutLoggerInterface; use Hyperf\Nano\Factory\AppFactory; require_once __DIR__ . '/vendor/autoload.php'; $app = AppFactory::create(); $app->addProcess(function(){ while (true) { sleep(1); $this->get(StdoutLoggerInterface::class)->info('Processing...'); } }); $app->run();

• 该进程由 Swoole 管理，随应用一同启动、常驻运行，每秒输出一次日志；
• 适合承载轮询、消费、定时上报等后台任务；此能力对应完整版 Hyperf 的 process 组件。

8. 定时任务：Cron 表达式调度

用addCrontab注册定时任务，第一个参数为 Cron 表达式：

<?php use Hyperf\Contract\StdoutLoggerInterface; use Hyperf\Nano\Factory\AppFactory; require_once __DIR__ . '/vendor/autoload.php'; $app = AppFactory::create(); $app->addCrontab('* * * * * *', function(){ $this->get(StdoutLoggerInterface::class)->info('execute every second!'); }); $app->run();

• * * * * * *为六段式 Cron 表达式（秒 分 时 日 月 周），与完整版 Hyperf 的 crontab 组件 规则一致，因此这里表示每秒执行一次；
• 定时任务同样运行在常驻进程中，由 Nano 内部按 Cron 规则调度闭包。

9. 使用 Hyperf 组件：以数据库为例

Nano 与全部 Hyperf 组件兼容。以 db 组件 为例：先通过$app->config([...])注入组件所需的配置，再直接使用静态门面Hyperf\DB\DB：

<?php use Hyperf\DB\DB; use Hyperf\Nano\Factory\AppFactory; require_once __DIR__ . '/vendor/autoload.php'; $app = AppFactory::create(); $app->config([ 'db.default' => [ 'host' => env('DB_HOST', 'localhost'), 'port' => env('DB_PORT', 3306), 'database' => env('DB_DATABASE', 'hyperf'), 'username' => env('DB_USERNAME', 'root'), 'password' => env('DB_PASSWORD', ''), ] ]); $app->get('/', function(){ return DB::query('SELECT * FROM `user` WHERE gender = ?;', [1]); }); $app->run();

说明：

• $app->config(['db.default' => [...]])以键值对形式注入配置，db.default即数据库连接池default池的配置段；配置项可通过env()辅助函数读取环境变量并设置默认值，这一点与完整版 Hyperf 的配置规范一致（参见 config 组件 与 db-connection 组件）；
• DB::query()是静态调用。从 DB 类实现 可以看到，DB通过__callStatic/__call将调用代理到连接池中的真实连接（PoolFactory管理连接、支持事务beginTransaction/commit/rollback等方法，详见 DB 门面类 的@method注释），并对连接做了协程上下文管理与释放，因此查询天然支持协程化；
• 这意味着 Nano 应用可以直接享用 Hyperf 生态的组件能力：Redis、缓存、AMQP、gRPC 客户端等皆可按同样的"注入配置 + 使用门面"模式接入。

适用场景与注意事项

综合以上内容，使用 Nano 时有几点值得注意：

1. 注解体系不可用：Nano 定位是闭包风格，不支持注解（Annotation）驱动的控制器、AOP 注解切面等。需要注解能力的复杂业务模块，应使用标准 Hyperf 骨架工程。
2. 组件能力完整：除注解外，Hyperf 的事件、中间件、进程、定时任务、DI、配置等机制在 Nano 中均可通过$app->addXXX()闭包形式获得，组件兼容性有官方文档背书。
3. Phar 友好：由于应用是单文件、无额外配置目录，便于用 Phar 打包后直接分发运行。
4. 依赖前提：运行环境需满足 Hyperf 的基本要求（Swoole 扩展、Composer 依赖等）；AppFactory::create()不传参时使用默认监听地址与端口（具体默认值以hyperf/nano包内实现为准）。
5. 快速验证路径：从 README 对 Nano 的定位（"zero-config, no skeleton, minimal Hyperf distribution"）可以看出，Nano 是 Hyperf 官方提供给开发者的一把"轻量钥匙"，适合快速搭建单文件服务，而重型业务仍建议回归完整骨架。

小结

hyperf/nano用最小的成本呈现了 Hyperf 的核心运行模型：单文件入口、闭包注册、ContainerProxy 绑定、PSR-7 消息管道、事件与进程机制，以及组件化能力。本文从安装、快速开始到九个实战示例完整复现了官方文档的用法，并对照本仓库的 DB、StdoutLoggerInterface、BootApplication、SwooleStream 等源码说明了底层实现。当你需要"几行代码跑起一个 Hyperf 服务"时，Nano 就是最直接的答案。

• 后端
• Web框架
• 微服务
• RPC框架
• 异步编程