Add Annotation for Sentry Safe Caller

[xuanyanwow]

Summary by CodeRabbit

发布说明

• 新功能
  • 新增“安全调用器”注解，允许为方法配置自定义异常处理器与默认返回值，提升容错与异常处理灵活性。
  • 将对应的切面集成到运行时，以自动在被注解的方法周围应用该异常处理机制。
  • 配置已更新以启用该切面。

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Warning

Rate limit exceeded

@huangdijia has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 24 minutes and 40 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 15d6323 and a637c47.

📒 Files selected for processing (3)

• src/sentry/src/Annotation/Graceful.php (1 hunks)
• src/sentry/src/Aspect/GracefulAspect.php (1 hunks)
• src/sentry/src/ConfigProvider.php (1 hunks)

Walkthrough

新增 SafeCaller 注解类与 SafeCallerAspect 切面，并在 ConfigProvider 中注册该切面。切面在被注解的方法执行时捕获异常，调用可选的自定义异常处理器并按需将异常上报到 Sentry，最终返回注解指定的默认值或异常处理结果。

Changes

Cohort / File(s)	变更摘要
注解：SafeCaller src/sentry/src/Annotation/SafeCaller.php	新增 PHP 8 属性类 SafeCaller（命名空间 FriendsOfHyperf\Sentry\Annotation），构造器使用属性提升 public mixed $default = null，并接受可选 ?callable $exceptionHandler，用于指定默认返回值与自定义异常处理回调。
切面：SafeCallerAspect src/sentry/src/Aspect/SafeCallerAspect.php	新增 AOP 切面类 SafeCallerAspect，添加 public array $annotations，实现 process(ProceedingJoinPoint $proceedingJoinPoint): mixed，在方法执行时捕获异常、调用 exceptionHandler（若存在）、按条件上报至 Sentry 并返回注解的默认值或处理结果。
配置注册 src/sentry/src/ConfigProvider.php	在返回的配置数组中将 Aspect\SafeCallerAspect::class 添加至 aspects 列表，启用该切面。

Sequence Diagram(s)

sequenceDiagram
    participant Caller as 调用方
    participant Aspect as SafeCallerAspect
    participant Target as 被装饰方法
    participant Handler as exceptionHandler (可选)
    participant Sentry as Sentry SDK

    Caller->>Aspect: 调用被 `#[SafeCaller]` 装饰的方法
    Aspect->>Target: proceed()
    alt 正常返回
        Target-->>Aspect: 返回结果
        Aspect-->>Caller: 返回结果
    else 抛出异常
        Target-->>Aspect: throw Exception
        alt 有自定义 exceptionHandler
            Aspect->>Handler: 调用 exceptionHandler(Throwable)
            Handler-->>Aspect: 返回值（可用于是否上报）
            alt 根据 handler 返回需上报
                Aspect->>Sentry: 上报异常
                Sentry-->>Aspect: 上报完成
            end
        else 无 handler
            Aspect->>Sentry: 上报异常
            Sentry-->>Aspect: 上报完成
        end
        Aspect-->>Caller: 返回注解中 `$default` 或 handler 指定值
    end

Loading

Estimated code review effort

🎯 3 (中等) | ⏱️ ~20 分钟

• 重点查看 SafeCallerAspect::process 中异常分支、exceptionHandler 返回值的判定逻辑与上报条件。
• 校验注解类构造器的类型与可见性（属性提升与 callable 接收）。
• 确认 ConfigProvider 中 aspects 注册位置与格式符合现有约定。

Suggested reviewers

• huangdijia

Poem

🐰 我跳过一行又一行，
注入守护的 SafeCaller 翩翩来访，
异常落地不再慌，
Sentry 轻声记下每一桩，
小兔微笑，代码更安康。 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	标题准确总结了PR的主要变更：添加SafeCaller注解及其相关的方面类和配置

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/sentry/src/Annotation/SafeCaller.php (1)

20-31: 考虑为属性声明添加说明性注释

$exceptionHandler 属性没有类型声明，而 $default 使用了构造器属性提升。这是因为 PHP 不支持将 callable 用作类型化属性，只能使用未类型化的属性。

虽然当前实现是正确的，但建议添加一个注释说明这个设计决策，以提高代码可读性。

🔎 查看建议的改进

+    /**
+     * @var null|callable 异常处理函数（注：由于 PHP 限制，callable 不能用作类型化属性）
+     */
     public $exceptionHandler;

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ec76f5b and b909671.

📒 Files selected for processing (3)

• src/sentry/src/Annotation/SafeCaller.php (1 hunks)
• src/sentry/src/Aspect/SafeCallerAspect.php (1 hunks)
• src/sentry/src/ConfigProvider.php (1 hunks)

🧰 Additional context used

📓 Path-based instructions (6)

**/*.php

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

**/*.php: All PHP files must include declare(strict_types=1) at the top
Use PSR-12 coding standards for PHP code formatting
Use 4-space indentation with short array syntax in PHP code
Use .php-cs-fixer.php configuration for PHP code formatting

All PHP files must include a strict_types declaration at the top

**/*.php: Follow project PHP coding standard enforced by php-cs-fixer with PSR-12 style, 4-space indentation, and short array syntax
Maintain type coverage by updating or adding tests when public APIs change; ensure composer test:types stays green before pushing

Files:

• src/sentry/src/ConfigProvider.php
• src/sentry/src/Annotation/SafeCaller.php
• src/sentry/src/Aspect/SafeCallerAspect.php

src/**/src/**/*.php

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use namespace pattern FriendsOfHyperf\{ComponentName} for all component classes

Files:

• src/sentry/src/ConfigProvider.php
• src/sentry/src/Annotation/SafeCaller.php
• src/sentry/src/Aspect/SafeCallerAspect.php

src/*/src/ConfigProvider.php

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Each component must include a ConfigProvider.php file that defines dependencies, commands, listeners, and annotations

Files:

• src/sentry/src/ConfigProvider.php

**/src/ConfigProvider.php

📄 CodeRabbit inference engine (CLAUDE.md)

**/src/ConfigProvider.php: Use Hyperf's ConfigProvider pattern for auto-discovery in components, defining dependencies, commands, listeners, aspects, and annotations
Components can publish config files and migrations to user applications through ConfigProvider's publish array

Files:

• src/sentry/src/ConfigProvider.php

src/*/src/**/*.php

📄 CodeRabbit inference engine (CLAUDE.md)

src/*/src/**/*.php: Namespace convention for components must follow FriendsOfHyperf{ComponentName}
All code must be coroutine-safe and avoid global state without proper context management, blocking I/O operations, and non-coroutine-safe third-party libraries without wrappers
Use Hyperf's Context API for request-scoped data instead of global state
Follows PSR-12 coding standards and use PHP-CS-Fixer for automatic formatting
Use PHPStan at maximum level for static analysis
Ensure component namespace doesn't conflict with existing Hyperf components or other packages in the ecosystem
Integrate deeply with Hyperf's Dependency Injection container for service registration
Leverage Hyperf's AOP (Aspect-Oriented Programming) for cross-cutting concerns via aspects defined in ConfigProvider
Use Hyperf's Event System to register listeners for framework events in components
All code must support coroutine-based concurrency using Swoole/Swow compatibility

Files:

• src/sentry/src/ConfigProvider.php
• src/sentry/src/Annotation/SafeCaller.php
• src/sentry/src/Aspect/SafeCallerAspect.php

src/**/*.php

📄 CodeRabbit inference engine (AGENTS.md)

Each component lives in its own subdirectory with PSR-4 namespaces matching FriendsOfHyperf\*

Files:

• src/sentry/src/ConfigProvider.php
• src/sentry/src/Annotation/SafeCaller.php
• src/sentry/src/Aspect/SafeCallerAspect.php

🧠 Learnings (2)

📚 Learning: 2025-12-12T05:33:43.947Z

Learnt from: CR
Repo: friendsofhyperf/components PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-12T05:33:43.947Z
Learning: Applies to src/*/src/**/*.php : Leverage Hyperf's AOP (Aspect-Oriented Programming) for cross-cutting concerns via aspects defined in ConfigProvider

Applied to files:

• src/sentry/src/ConfigProvider.php
• src/sentry/src/Aspect/SafeCallerAspect.php

📚 Learning: 2025-12-12T05:33:43.947Z

Learnt from: CR
Repo: friendsofhyperf/components PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-12T05:33:43.947Z
Learning: Applies to **/src/ConfigProvider.php : Use Hyperf's ConfigProvider pattern for auto-discovery in components, defining dependencies, commands, listeners, aspects, and annotations

Applied to files:

• src/sentry/src/ConfigProvider.php

🧬 Code graph analysis (3)

src/sentry/src/ConfigProvider.php (1)

src/sentry/src/Aspect/SafeCallerAspect.php (1)

• SafeCallerAspect (22-50)

src/sentry/src/Annotation/SafeCaller.php (1)

src/sentry/src/Util/SafeCaller.php (1)

• SafeCaller (20-50)

src/sentry/src/Aspect/SafeCallerAspect.php (6)

src/sentry/src/Util/SafeCaller.php (1)

• SafeCaller (20-50)

src/sentry/class_map/SentrySdk.php (2)

• SentrySdk (24-65)
• getCurrentHub (51-54)

src/support/src/Once.php (1)

• value (54-73)

src/http-client/src/Request.php (1)

• method (54-57)

src/exception-event/src/Functions.php (1)

• report (23-44)

src/sentry/src/Listener/EventHandleListener.php (1)

• captureException (145-160)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Test on PHP 8.1 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.1 with Swoole 6.1.3

🔇 Additional comments (4)

src/sentry/src/ConfigProvider.php (1)

23-23: 正确地将新切面集成到 AOP 系统中

SafeCallerAspect 已正确添加到 aspects 数组中，遵循了 Hyperf 的 ConfigProvider 自动发现模式。

src/sentry/src/Aspect/SafeCallerAspect.php (2)

24-26: 正确定义了切面触发的注解

annotations 属性正确声明了此切面处理的注解类型，符合 Hyperf AOP 规范。

---

47-47: 返回值处理方式优于工具类版本

此实现将异常 $e 传递给 value() 函数，这允许 $default 为闭包时接收异常参数，提供了比 src/sentry/src/Util/SafeCaller.php 更灵活的错误处理能力。

src/sentry/src/Annotation/SafeCaller.php (1)

17-18: 正确使用 PHP 8 特性和 Hyperf 注解模式

注解类正确继承 AbstractAnnotation 并使用 Attribute::TARGET_METHOD 限定作用范围，符合框架规范。