hyperf 3.1.66 新增 grpc 多客户端负载均衡、pool 全量刷新、guzzle 持久化 cookie 及数据库 json 包含键查询四大核心优化，均需显式配置与精准适配方可生效。
Hyperf 3.1.66 不是小修小补，它把 gRPC 客户端负载均衡和连接池刷新机制从“能用”推进到了“可靠高并发可用”的级别。如果你正在用 Hyperf 做微服务网关、跨语言调用或高频内部 RPC，这个版本值得立刻升级。
gRPC 多客户端负载均衡怎么配才生效
Hyperf 3.1.66 新增了 GrpcClientPool 的多实例负载能力，但默认不启用——它依赖你显式配置多个 endpoint 并启用策略。
- 必须在
config/autoload/grpc.php中定义多个endpoints，且每个 endpoint 的host和port不能重复（哪怕只是不同域名指向同一 IP） - 负载策略由
load_balancer配置项控制，默认是round_robin；若要改用random或自定义策略，需实现Hyperf\Grpc\LoadBalancer\LoadBalancerInterface - 注意：gRPC 连接复用仍基于 HTTP/2 单连接多路复用，所以即使配置了 3 个 endpoint，每个 endpoint 实际只维持一个底层
ManagedChannel，负载发生在请求分发层，而非连接层 - 验证是否生效：调用
GrpcClientFactory::get()获取 client 后，连续发起 10 次UnaryCall，检查日志中endpoint字段是否轮转
Pool 连接池全量刷新的触发条件与副作用
此前连接池异常连接只能靠 max_idle_time 被被动淘汰，3.1.66 引入了主动全量刷新机制，但它不是“一键刷新”，而是有明确触发边界。
- 刷新仅对
Hyperf\Pool\Pool及其子类（如Hyperf\Database\Pool、Hyperf\Redis\Pool）生效，gRPC 的GrpcClientPool不在此列 - 触发方式只有两种：
Pool::refresh()手动调用，或配置refresh_interval（单位秒）后由定时器自动触发；没有“连接失败自动刷新”逻辑 - 刷新期间，新请求会阻塞等待，直到刷新完成——这意味着如果你设了 30 秒刷新间隔，而某次刷新因网络抖动耗时 5 秒，这 5 秒内所有获取连接的协程都会挂起
-
refresh_interval建议设为大于max_lifetime（如后者是 3600，前者至少设 3700），否则可能刚创建就刷新，浪费资源
Guzzle 持久化 Cookie 的实际影响范围
这个特性常被误读为“全局 Cookie 共享”，其实它只作用于同一个 GuzzleHttp\Client 实例内的请求链路，且受协程隔离约束。
- Cookie 持久化由
cookie_jar配置开启：'cookie_jar' => true，此时 client 内部会使用GuzzleHttp\Cookie\CookieJar实例 - 关键限制：协程间不共享 CookieJar —— 即使你在
Di中单例注册了 client，每个协程拿到的仍是独立 jar 实例（Hyperf 的协程上下文隔离机制决定的） - 若需跨协程传递登录态，必须显式序列化
CookieJar::toArray()并注入下游请求，或改用 token + header 透传 - 对性能的影响极小，但要注意：开启后每次请求都会执行 cookie 匹配逻辑，若 cookie 数量超 50 条，建议关闭或手动管理
数据库 JSON 包含键查询的写法陷阱
json_contains 在 Hyperf 3.1.66 中支持原生语法，但 ORM 层封装容易掩盖底层差异，导致线上查不到数据。
- MySQL 8.0+ 才支持标准
JSON_CONTAINS函数；低版本需用JSON_EXTRACT+ 字符串匹配，Hyperf 不自动降级 - 使用 QueryBuilder 时，必须写成
$query->whereRaw('JSON_CONTAINS(?, ?)', [$jsonColumn, $searchValue])，不能用where方法传数组，否则会被当成普通字段比较 - 注意参数顺序：
JSON_CONTAINS(json_col, search_value)，第二个参数是待搜索的值（字符串或 JSON），不是路径 - 如果
$searchValue是 PHP 数组，需先json_encode()，且确保编码后不含多余空格（建议加JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES）
这些优化点都不是开箱即用的魔法开关，它们都依赖你理解底层协议（HTTP/2 流控）、协程生命周期（Cookie 隔离）、SQL 引擎能力（JSON 函数版本）——跳过这些细节直接套配置，反而更容易在线上出问题。
