PHP自定义异常注释技巧分享

本文深入解析了PHP自定义异常类的规范化DocBlock注释实践，强调注释的核心价值在于精准传达异常的业务语义与使用契约——不仅要在抛出异常的方法中逐行明确标注带命名空间的`@throws`，更需在异常类本身添加详尽的类级DocBlock，涵盖用途说明、`@see`关联触发场景、`@property`声明携带的业务属性（即使PHP 8.0+已支持属性提升，仍不可省略），以及重写构造函数时对新增参数的`@param`说明；忽视这些细节将导致IDE智能提示失效、静态分析工具无法识别异常意图、团队协作理解偏差，甚至影响单元测试设计与错误处理的健壮性。

PHP自定义异常类怎么写 DocBlock 注释

PHP 自定义异常类本身是 Exception 的子类，注释重点不是“加不加”，而是**是否准确描述了异常语义和抛出上下文**。直接在类定义上方用标准 DocBlock 即可，不需要特殊语法。

常见错误是只写 /** @throws MyCustomException */ 在方法里，却忘了给异常类本身写说明——这会让 IDE 和静态分析工具（如 PHPStan、Psalm）无法理解这个异常代表什么业务含义。

• 必须用 /** ... */ 块注释，不能用 //
• 首行简明说明异常用途，比如“用户余额不足时抛出”
• 推荐补充 @see 指向触发该异常的具体方法或业务流程
• 如果异常携带额外属性（如错误码 $errorCode），需用 @property 明确声明

/**
 * 用户余额不足以完成支付时抛出
 * @see PaymentService::process()
 * @property int $errorCode 错误码，例如 402 表示余额不足
 */
class InsufficientBalanceException extends Exception
{
}

throw new 时要不要在方法里 @throws 注释

要，而且必须对应到具体异常类名。PHP 不强制检查 @throws，但现代 IDE（PhpStorm、VS Code + Intelephense）和类型分析工具依赖它做跳转、提示和未捕获异常检测。

容易踩的坑：@throws Exception 这种宽泛写法等于没写——它掩盖了真实异常契约，导致调用方无法针对性 catch 或写单元测试。

• 每个可能抛出的自定义异常都单独写一行 @throws
• 如果方法既抛 InsufficientBalanceException 又抛 InvalidPaymentMethodException，就写两行
• 不要省略命名空间，如 @throws \App\Exceptions\InsufficientBalanceException

/**
 * @throws \App\Exceptions\InsufficientBalanceException
 * @throws \App\Exceptions\InvalidPaymentMethodException
 */
public function charge(float $amount): void
{
    if ($this->balance <h3>自定义异常构造函数参数要不要注释</h3><p>要，尤其是当重写了 <code>__construct()</code> 并添加了新参数时。PHP 原生 <code>Exception</code> 构造函数签名是 <code>__construct(string $message = "", int $code = 0, ?Throwable $previous = null)</code>，如果你新增了 <code>$context</code> 或 <code>$retryAfter</code>，就必须文档化。</p><p>否则调用方传参会困惑，IDE 也无法提示参数名和类型。</p>

• 用 @param 注释每个新增参数
• 原生参数（$message, $code）可不重复注释，除非你改变了语义（比如把 $code 改成 HTTP 状态码）
• 若仅调用 parent::__construct(...) 且无新增参数，无需重写构造函数，更无需额外注释

/**
 * @param string $message 错误信息
 * @param int $code 业务错误码（非 PHP 异常 code）
 * @param array $context 关联上下文数据，如 ['order_id' => 123]
 */
public function __construct(string $message, int $code, array $context = [])
{
    parent::__construct($message, $code);
    $this->context = $context;
}

PHP 8.0+ 属性提升后，@property 注释还有效吗

仍然有效，而且更关键。PHP 8.0 引入属性提升（promoted properties），比如 public function __construct(public int $errorCode)，此时 $errorCode 是公开属性，但 PHPDoc 不会自动推导其用途和业务含义。

静态分析工具（如 Psalm）默认不信任提升属性的语义，必须靠 @property 显式声明，否则会报 PropertyNotSetInConstructor 或无法识别字段作用。

• 即使用了属性提升，也要在类 DocBlock 中补 @property int $errorCode 业务错误码
• @property-read 或 @property-write 可用于限定访问权限（尽管运行时不受限）
• 别依赖 IDE 自动生成的 @property——它常漏掉描述，或把类型写成 mixed

最易忽略的一点：很多人给异常类写了完整 DocBlock，却在重构时删掉了 @property 行，导致后续团队成员无法快速理解那个 $errorCode 到底是 HTTP 状态码、支付网关返回码，还是内部枚举值。

好了，本文到此结束，带大家了解了《PHP自定义异常注释技巧分享》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！