PHP灰度发布需统一收口至PSR-15中间件，通过请求上下文挂载灰度标识，优先取Nginx注入的X-USER-ID哈希分桶，规则须来自Apollo/Nacos配置中心，全链路透传并保持决策一致。
PHP 本身不提供 A/B 测试或灰度发布的内置能力，所有有效方案都依赖「请求上下文 + 外部规则 + 统一决策点」三者配合。关键不是写多少分支逻辑，而是让 shouldEnterGray() 这个判断在每次请求中稳定、快速、可追溯。
灰度判断必须收口到 PSR-15 或框架中间件里
把灰度逻辑塞进每个 Controller 方法里，会导致重复计算、漏判、难以统一开关；放在 __construct() 或 Service Provider 中初始化，则可能因配置中心未就绪而加载空规则。
- 用 PSR-15 中间件，在
process()开头调用分流器，例如$this->grayRouter->shouldEnterGray($request) - 分流结果（如
gray_bucket或is_gray）必须挂载到请求对象上，比如$request->attributes->set('gray_bucket', $bucket)，供后续任意层级读取 - Hyperf 用户直接用
$request->withAttribute('is_gray', true)；Laravel 用户用$request->attributes->set()；Swoole/RR 环境严禁用static或全局变量存桶号
用户标识取值顺序和哈希方式直接影响分流稳定性
用 IP 做依据在 NAT/CDN 下完全不可靠；用 cookie 或 session 容易被篡改或丢失；直接取模（$uid % 100）扩容时全量重分——这三类错误会直接导致埋点错乱、缓存击穿、状态不一致。
- 优先取
$_SERVER['HTTP_X_USER_ID']（由 Nginx 注入），为空再降级到$_REQUEST['uid']，并记录告警 - 哈希必须用
crc32((string)$uid)，强制转 string 防截断，再abs() % 100得桶号；不要用md5或siphash（PHP 8.1+ 才有，兼容性差） - 未登录用户不能硬编码为
0，否则全部挤进同一桶；建议用设备指纹（如 UA + IP 哈希）做 fallback，但需注明“非强一致性”
规则来源必须是配置中心，不能读环境变量或本地 JSON
getenv('GRAY_RULE') 或 file_get_contents('gray.json') 会导致规则延迟生效、多实例不一致、无法实时回滚——这不是灰度，是赌运气。
立即学习“PHP免费学习笔记（深入）”；
- 接入
ApolloPHP或nacos-php-sdk，别自己封装 HTTP 轮询；设置超时timeout=3，失败时 fallback 到内存缓存的上一版规则 - 配置项只保留三个字段：
gray.enabled（bool）、gray.percentage（int）、gray.users（array），扁平结构，避免嵌套解析失败 - 轮询间隔设为
10s，而非1s；高优服务建议配合 webhook 或长连接推送，减少配置中心压力
业务代码里只读不判，且必须覆盖全链路
灰度不是只改接口返回，而是要让 DAO、模板渲染、异常处理、甚至日志上报都感知当前是否处于灰度路径。否则新旧逻辑混用会掩盖真实问题。
- Controller 层根据
$request->attributes->get('gray_bucket') < 5决定调用newFeatureService()还是legacyService() - DAO 层查库前检查是否灰度，决定走新表名、新索引或新分库策略；模板层用
@if($request->attributes->get('is_gray'))控制区块展示 - 记录灰度决策日志，字段至少含：
uid、rule_version、hit_gray、reason（如"percentage: 5%"）
最容易被忽略的是：灰度流量在一次完整请求链路中必须保持决策一致。比如用户命中灰度后，其后续子请求（RPC、消息、定时任务触发）如果没透传或复现桶号，就会出现“前端看到新功能，后端日志却是老逻辑”的断裂现象。
