PHP注解标记服务元数据需借助doctrine/annotations等库解析DocBlock，定义带@Target的注解类，通过AnnotationReader提取元数据，并结合反射动态生成调用逻辑，依赖opcache且需类已加载。
PHP 注解怎么标记服务调用的元数据
PHP 本身不原生支持注解（annotation），所谓“用注解标记服务元数据”，实际是借助第三方库（如 phpdocumentor/reflection-docblock 或 doctrine/annotations）解析 DocBlock 中的自定义标签，再配合反射提取信息。不是语法级特性，而是约定 + 工具链。
关键点在于：注解只是字符串，真正起作用的是你写的解析逻辑。没解析，@Service 就是一行普通注释。
- 必须启用
opcache.enable=1（Doctrine 注解依赖 opcache 缓存反射信息） - 类必须已加载（自动加载需正常工作），否则
ReflectionClass找不到目标 - 注解内容不能含未转义的
@、{、}，否则解析器可能截断或报错
用 doctrine/annotations 提取 @Rpc 或 @Http 元数据
这是目前最主流的做法：定义业务相关的注解类，用 Doctrine 的 AnnotationReader 解析。
例如想标记一个方法要走 HTTP 调用：
立即学习“PHP免费学习笔记（深入）”；
/**
* @Http(host="api.example.com", path="/v1/users", method="POST")
*/
public function createUser(array $data): array
{
// ...
}
对应需定义 Http 注解类（带 @Annotation 和 @Target("METHOD")）；然后用 $reader->getMethodAnnotations($method) 拿到实例。注意：
-
@Target必须明确指定是"CLASS"、"METHOD"还是"PROPERTY"，否则运行时报Invalid target - 注解类的属性名必须与 DocBlock 中键名完全一致（区分大小写），且需声明为
public - 数组值写法是
headers={"Content-Type": "application/json"}，不是 JSON 格式，是 PHP 字面量语法
为什么不用 phpstan/phpdoc-parser 或正则直接读注释
能读，但不推荐。原因很实际：
- 正则匹配
@Foo(...)容易被多行参数、嵌套括号、注释内代码块干扰，稳定性和可维护性差 -
phpstan/phpdoc-parser是为静态分析设计的，不提供运行时反射集成，你要自己把解析结果和类/方法对齐，成本高 -
doctrine/annotations已处理好缓存、命名空间映射、类型转换（如int、bool自动 cast），省掉大量边界 case
除非你项目已禁用 opcache 或无法引入新包，否则没必要绕开成熟方案。
注解元数据怎么传给服务调用器（如 Guzzle / Swoole RPC 客户端）
典型做法是封装一层「代理工厂」：根据目标方法的反射信息 + 注解元数据，动态生成调用逻辑。
例如：
$meta = $this->reader->getMethodAnnotations($method)[0] ?? null;
if ($meta instanceof Http) {
return $this->httpClient->request(
$meta->method,
'https://' . $meta->host . $meta->path,
['json' => $args]
);
}
这里容易漏掉的是错误兜底：
- 注解缺失时没默认值 → 抛出
InvalidArgumentException比静默失败更利于排查 - 注解字段类型错误（如
method=GETT）→ 应在解析阶段校验，而非等到发请求才报 405 - 多个同名注解（如两个
@Timeout）→ Doctrine 默认只取第一个，需显式用@Annotation\Attributes({@Annotation\Attribute("allowMultiple"=true)})
注解不是魔法，它只是把配置从 YAML 搬到了类文件里；一旦元数据变复杂，很快会遇到维护成本反超收益的问题。真要支撑上百个服务接口，建议注解只管路由和协议，超时、重试、熔断这些交给统一配置中心或注解+外部配置混合管理。
