feat(exception): 新增业务错误处理和 API 迁移支持

- 新增业务错误类型和相关错误码
- 实现 API 迁移异常处理
- 增加未实现功能异常处理
- 更新错误处理逻辑，支持新错误类型

Signed-off-by: 李东云 <dongyu.li@luxcreo.ai>

.idea/php.xml

@@ -15,9 +15,6 @@
       <PhpCSFixerConfiguration standards="PSR1;PSR2;Symfony;DoctrineAnnotation;PHP70Migration;PHP71Migration" tool_path="$PROJECT_DIR$/vendor/friendsofphp/php-cs-fixer/php-cs-fixer" />
     </phpcsfixer_settings>
   </component>
-  <component name="PhpExternalFormatter">
-    <option name="externalFormatter" value="PHP_CBF" />
-  </component>
   <component name="PhpIncludePathManager">
     <include_path>
       <path value="$PROJECT_DIR$/vendor/hyperf/pool" />

publish/languages/en/common_error.php

@@ -163,4 +163,11 @@ return [
             'default' => 'DOC deleted',
         ],
     ],
+
+    // 业务错误
+    'business' => [
+        'default' => 'Business Error',
+        'old_version' => 'This feature is not available in the current version.',
+        'not_implemented' => 'This feature is not implemented yet.',
+    ],
 ];

publish/languages/zh_CN/common_error.php

@@ -172,4 +172,11 @@ return [
             'default' => '文档已删除',
         ],
     ],
+
+    // 业务错误
+    'business' => [
+        'default' => '业务错误',
+        'old_version' => '当前版本过低，请升级到最新版本',
+        'not_implemented' => '该功能尚未实现',
+    ],
 ];

src/Constants/CommonErrorCode.php

@@ -12,6 +12,7 @@ namespace Singularity\HDK\Core\Constants;
 
 use Hyperf\Constants\AbstractConstants;
 use Hyperf\Constants\Annotation\Constants;
+use Hyperf\Constants\Annotation\Message;
 
 /**
  * Singularity\HyperfDevelopmentKit\Utils\Constants\CommonErrorCode@hyperf-development-kit
@@ -319,4 +320,15 @@ class CommonErrorCode extends AbstractConstants
      * @Message("common_error.model.document.default")
      */
     public const DOCUMENT_NOT_EXISTS = 4020201;
+
+    // 500 业务错误
+
+    #[Message('common_error.business.defaul')]
+    public const BUSINESS_ERROR = 500001;
+    // 501 版本问题
+    #[Message('common_error.business.old_version')]
+    public const BUSINESS_FLAT_OLD_VERSION = 501001;
+
+    #[Message('common_error.business.not_implemented')]
+    public const BUSINESS_NOT_IMPLEMENTED = 501002;
 }

src/Exceptions/ApiMigrated.php

@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * DomainOrderNotSupportException.php@LuxDesign
+ *
+ * @author 李东云 <Dongyun.Li@LuxCreo.Ai>
+ * Powered by PhpStorm
+ * Created on 2025/8/1
+ */
+declare(strict_types=1);
+
+namespace Singularity\HDK\Core\Exceptions;
+
+use Hyperf\HttpMessage\Exception\HttpException;
+use Singularity\HDK\Core\Constants\CommonErrorCode;
+use Teapot\StatusCode\RFC\RFC7231;
+use Throwable;
+
+final class ApiMigrated extends HttpException
+{
+    public function __construct(
+        public string $apiPath,
+        int $code = CommonErrorCode::BUSINESS_FLAT_OLD_VERSION,
+        ?string $message = null,
+        Throwable $previous = null,
+    ) {
+        parent::__construct(RFC7231::SEE_OTHER, $message, $code, $previous);
+    }
+
+    public function getNewPath(): string
+    {
+        return $this->apiPath;
+    }
+}

src/Exceptions/Handler/CommonHandler.php

@@ -32,6 +32,8 @@ use Lmc\HttpConstants\Header;
 use Psr\Http\Message\ResponseInterface;
 use RedisException;
 use Singularity\HDK\Core\Constants\CommonErrorCode;
+use Singularity\HDK\Core\Exceptions\ApiMigrated;
+use Singularity\HDK\Core\Exceptions\NotImplementedException;
 use Singularity\HDK\Core\Exceptions\ValidateException;
 use Singularity\HDK\Core\Service\ApiStyleService;
 use Symfony\Component\Mailer\Exception\TransportException;
@@ -133,7 +135,7 @@ class CommonHandler extends ExceptionHandler
             $data = [
                 $code_name => CommonErrorCode::REQUEST_PARAMS_ERROR,
                 $message_name => $is_testing ? $throwable->getMessage() : CommonErrorCode::getMessage(
-                    CommonErrorCode::SERVER_ERROR
+                    CommonErrorCode::SERVER_ERROR,
                 ),
             ];
             $status_code = RFC4918::UNPROCESSABLE_ENTITY;
@@ -158,7 +160,7 @@ class CommonHandler extends ExceptionHandler
                         $code,
                         [
                             'param' => $throwable->getFieldName(),
-                        ]
+                        ],
                     )
                     : $message,
             ];
@@ -178,7 +180,7 @@ class CommonHandler extends ExceptionHandler
             $code = empty($throwable->getCode()) ? CommonErrorCode::MODEL_NOT_FOUND : $throwable->getCode();
             $message = empty($throwable->getCode()) ? CommonErrorCode::getMessage(
                 $code,
-                ['resource' => '资源']
+                ['resource' => '资源'],
             ) : $throwable->getMessage();
             $data = [$code_name => $code, $message_name => $message];
             $status_code = RFC7231::NOT_FOUND;
@@ -193,7 +195,7 @@ class CommonHandler extends ExceptionHandler
             $data = [
                 $code_name => $code,
                 $message_name => CommonErrorCode::getMessage(
-                    $is_testing ? $code : CommonErrorCode::SERVER_CACHE_REDIS_ERROR
+                    $is_testing ? $code : CommonErrorCode::SERVER_CACHE_REDIS_ERROR,
                 ),
             ];
         }
@@ -207,17 +209,39 @@ class CommonHandler extends ExceptionHandler
             $data = [
                 $code_name => $code,
                 $message_name => CommonErrorCode::getMessage(
-                    $is_testing ? $code : CommonErrorCode::SERVER_MESSAGE_EMAIL_ERROR
+                    $is_testing ? $code : CommonErrorCode::SERVER_MESSAGE_EMAIL_ERROR,
                 ),
             ];
         }
+        // 500 业务错误
+        if ($throwable instanceof ApiMigrated) {
+            $code = $throwable->getCode();
+            $data = [
+                $code_name => $code,
+                $message_name => $throwable->getMessage(),
+            ];
+            $headers = [
+                'Location' => $throwable->getNewPath(),
+            ];
+        }
+        if ($throwable instanceof NotImplementedException || $throwable instanceof \Hyperf\Framework\Exception\NotImplementedException) {
+            $code = $throwable->getCode();
+            if ($code === 0) {
+                $code = CommonErrorCode::BUSINESS_NOT_IMPLEMENTED;
+            }
+            $message = $throwable->getMessage() ?? CommonErrorCode::getMessage($code);
+            $data = [
+                $code_name => $code,
+                $message_name => $message,
+            ];
+        }
         if (empty($data)) {
             // 其他情况
             $data = [
                 $code_name => $is_testing ? $throwable->getCode(
                 ) == 0 ? CommonErrorCode::SERVER_ERROR : $throwable->getCode() : CommonErrorCode::SERVER_ERROR,
                 $message_name => $is_testing ? $throwable->getMessage() : __(
-                    CommonErrorCode::getMessage(CommonErrorCode::SERVER_ERROR)
+                    CommonErrorCode::getMessage(CommonErrorCode::SERVER_ERROR),
                 ),
             ];
             // 其他错误
@@ -263,15 +287,17 @@ REQUEST_DATA:
 TRACE:
 {$throwable->getTraceAsString()}
 ===============================
-
+ERROR_LOG,
-ERROR_LOG
         );
         $data = Json::encode($data);
         if ($restful === ApiStyleService::RESTFUL) {
             $response = $response->withStatus(
-                $status_code ?? $throwable->status ?? $throwable->statusCode ?? RFC7231::INTERNAL_SERVER_ERROR
+                $status_code ?? $throwable->status ?? $throwable->statusCode ?? RFC7231::INTERNAL_SERVER_ERROR,
             );
         }
+        foreach ($headers ?? [] as $header => $value) {
+            $response->withHeader($header, $value);
+        }
         return $response->withBody(new SwooleStream($data));
     }
 

src/Exceptions/NotImplementedException.php

@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * NotImplementedException.php@Core
+ *
+ * @author 李东云 <Dongyun.Li@LuxCreo.Ai>
+ * Powered by PhpStorm
+ * Created on 2025/8/2
+ */
+declare(strict_types=1);
+
+namespace Singularity\HDK\Core\Exceptions;
+
+use Hyperf\HttpMessage\Exception\HttpException;
+use Singularity\HDK\Core\Constants\CommonErrorCode;
+use Teapot\StatusCode\RFC\RFC7231;
+use Throwable;
+
+final class NotImplementedException extends HttpException
+{
+    public function __construct(
+        int $code = CommonErrorCode::BUSINESS_NOT_IMPLEMENTED,
+        ?string $message = null,
+        Throwable $previous = null,
+    ) {
+        $message ??= CommonErrorCode::getMessage($code);
+        parent::__construct(RFC7231::NOT_IMPLEMENTED, $message, $code, $previous);
+    }
+}