Add Annotation for Sentry Safe Caller (#1047)

* safe caller

* Update SafeCaller.php

* fix(sentry): add null check for SafeCallerAnnotation

Add null check handling for SafeCallerAnnotation in SafeCallerAspect.
If the annotation is not found, proceed with normal execution
instead of throwing an error.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* feat(sentry): 添加 Graceful 注解及其处理逻辑

* feat(sentry): 移除 SafeCallerAspect，添加 GracefulAspect

* feat(sentry): 移除 SafeCallerAspect 和 SafeCaller 注解

* fix(sentry): 修正 Graceful 注解的类型提示为 null|Graceful

* fix(sentry): 更新 Graceful 注解中的中文注释为英文

---------

Co-authored-by: 何泽宏 <[email protected]>
Co-authored-by: Claude <[email protected]>
Co-authored-by: Deeka Wong <[email protected]>

Author: 4 people

src/sentry/src/Annotation/Graceful.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * This file is part of friendsofhyperf/components.
+ *
+ * @link     https://github.com/friendsofhyperf/components
+ * @document https://github.com/friendsofhyperf/components/blob/main/README.md
+ * @contact  [email protected]
+ */
+
+namespace FriendsOfHyperf\Sentry\Annotation;
+
+use Attribute;
+use Hyperf\Di\Annotation\AbstractAnnotation;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class Graceful extends AbstractAnnotation
+{
+    /**
+     * Convert to the specified exception and throw it.
+     */
+    public const STRATEGY_TRANSLATE = 'translate';
+
+    /**
+     * Call the fallback method and return.
+     */
+    public const STRATEGY_FALLBACK = 'fallback';
+
+    /**
+     * Swallow the exception and return null.
+     */
+    public const STRATEGY_SWALLOW = 'swallow';
+
+    /**
+     * Record and rethrow the original exception.
+     */
+    public const STRATEGY_RETHROW = 'rethrow';
+
+    /**
+     * @param null|callable $fallback Fallback method
+     */
+    public function __construct(
+        public string $strategy = self::STRATEGY_SWALLOW,
+        public $fallback = null, // Used when strategy=fallback
+        public ?string $mapTo = null, // Used when strategy=translate (full exception class name)
+        public bool $report = true, // Whether to log
+    ) {
+    }
+}

src/sentry/src/Aspect/GracefulAspect.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * This file is part of friendsofhyperf/components.
+ *
+ * @link     https://github.com/friendsofhyperf/components
+ * @document https://github.com/friendsofhyperf/components/blob/main/README.md
+ * @contact  [email protected]
+ */
+
+namespace FriendsOfHyperf\Sentry\Aspect;
+
+use FriendsOfHyperf\Sentry\Annotation\Graceful;
+use Hyperf\Di\Aop\AbstractAspect;
+use Hyperf\Di\Aop\ProceedingJoinPoint;
+use Sentry\SentrySdk;
+use Throwable;
+
+use function Hyperf\Support\value;
+
+class GracefulAspect extends AbstractAspect
+{
+    public array $annotations = [
+        Graceful::class,
+    ];
+
+    public function process(ProceedingJoinPoint $proceedingJoinPoint): mixed
+    {
+        $metadata = $proceedingJoinPoint->getAnnotationMetadata();
+
+        /** @var null|Graceful $annotation */
+        $annotation = $metadata->method[Graceful::class] ?? null;
+
+        if ($annotation === null) {
+            return $proceedingJoinPoint->process();
+        }
+
+        try {
+            return $proceedingJoinPoint->process();
+        } catch (Throwable $e) {
+            return match ($annotation->strategy) {
+                Graceful::STRATEGY_FALLBACK => value($annotation->fallback, $proceedingJoinPoint, $e),
+                Graceful::STRATEGY_SWALLOW => null,
+                Graceful::STRATEGY_RETHROW => throw $e,
+                Graceful::STRATEGY_TRANSLATE => throw new ($annotation->mapTo ?? Throwable::class)('Translated Exception', 0, $e),
+                default => null,
+            };
+        } finally {
+            if (isset($e) && $annotation->report) {
+                SentrySdk::getCurrentHub()->captureException($e);
+            }
+        }
+    }
+}

src/sentry/src/ConfigProvider.php

@@ -23,6 +23,7 @@ public function __invoke(): array
                 Aspect\CacheAspect::class,
                 Aspect\CoroutineAspect::class,
                 Aspect\FilesystemAspect::class,
+                Aspect\GracefulAspect::class,
                 Aspect\GuzzleHttpClientAspect::class,
                 Aspect\LoggerAspect::class,
                 Aspect\RedisAspect::class,