Hyperf 是微服务落地载体而非单体升级插件，需重构服务边界、通信方式与部署模型；直接替换组件或复用单体结构会导致伪微服务、协程污染与分布式单体。
Hyperf 不是单体架构的“升级插件”，而是需要重构服务边界、通信方式和部署模型的微服务落地载体——直接在原有单体里加 Hyperf 组件，大概率会陷入“伪微服务”陷阱。
Hyperf 不能直接替换 Spring Boot 单体应用
很多团队误以为把 @SpringBootApplication 换成 Hyperf\HttpServer\Server 就完成了迁移。实际根本行不通：Spring Boot 单体通常共享一个数据库连接池、事务上下文和全局缓存实例，而 Hyperf 的协程调度模型要求每个服务持有独立的数据源、独立的事务边界、独立的配置加载路径。
- 直接复用旧数据库连接池会导致协程间状态污染，出现
MySQL server has gone away或脏读 - 沿用单体的
ApplicationContext注入逻辑，会让Hyperf\Di\Container无法正确管理生命周期，@Inject失效或注入错实例 - 未拆分的业务代码仍调用
OrderService::create()这类本地方法，绕过gRPC或JSON-RPC通信层，等于没解耦
服务拆分必须从领域模型开始，而非代码目录
常见错误是按 MVC 层机械切分：把所有 controller/ 提成网关，service/ 提成 RPC 服务，dao/ 提成数据服务。这只会制造出更难维护的分布式单体。
- 真正起点是识别限界上下文（Bounded Context），例如电商系统中，“订单创建”和“库存扣减”属于不同上下文——前者含用户、地址、优惠券；后者依赖仓储、SKU、批次库存，二者数据模型、一致性要求、扩展节奏完全不同
- 每个上下文对应一个
Hyperf项目，独立composer.json、独立config/autoload/、独立docker-compose.yml - 跨上下文调用必须走接口契约，禁止直接引用对方的
App\Service\*类，用Hyperf\RpcClient或Hyperf\Contract\RpcClientInterface封装
协程安全不是加 go() 就完事
Hyperf 的性能优势来自协程非阻塞，但默认 PHP 扩展（如 pdo_mysql、redis）不是协程安全的——直接在 go() 里调用会引发段错误或数据错乱。
- 必须启用
Swoole\Runtime::enableCoroutine()并替换原生扩展：用hyperf/database替代原生PDO，用hyperf/redis替代phpredis - 第三方 SDK（如微信支付、阿里云 OSS）需确认是否支持协程，否则要用
Hyperf\Coroutine\Waiter包裹成同步调用，避免阻塞整个 Worker - 全局变量（
$_SERVER、static $cache）在协程间共享，必须改用Co::getcid()+Channel或ApplicationContext存储上下文数据
配置中心与服务发现不能靠 .env 文件硬编码
单体时代把数据库地址写进 .env 没问题，但在 Hyperf 微服务集群里，每个服务实例的注册地址、超时策略、熔断阈值都可能动态变化。
-
consul或nacos是必备组件，Hyperf\ServiceGovernance必须启用，禁用config/autoload/services.php中的静态服务地址 - 配置项如
database.default.pool.min_connections需通过配置中心下发，而不是写死在config/autoload/databases.php - 服务间调用必须开启
load_balancer策略（如random或roundrobin），否则所有请求打到同一实例，失去水平扩展意义
最难的不是写 go(function () { ... })，而是让每个服务真正拥有自己的数据边界、故障域和发布节奏——一旦某个服务的 composer update 影响了其他服务的 vendor/，说明还没脱离单体思维。
