chore(release): 1.0.3

- 将 roave/dont 的版本约束从 ^1.6.0 更改为 *
- 添加了两个新的 PhpSpecSuiteConfiguration 配置块到 .idea/phpspec.xml 文件中

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

.gitea/workflows/publish_on_tagged.yml

@@ -19,10 +19,10 @@ jobs:
         run: |
           apt-get update
           apt-get install zip
-          zip -r hdk-core.dist.zip *
+          zip -r dist.zip *
       - name: Publish to registry
         run: |
           curl --user ch4o5:4fd300672472e666014314c1c94c604c634165a9 \
-               --upload-file ./hdk-core.dist.zip \
+               --upload-file ./dist.zip \
-               https://nest.doylee.cn/api/packages/HDK/composer?version=${{ gitea.ref_name }}-alpha
+               https://nest.doylee.cn/api/packages/HDK/composer?version=${{ gitea.ref_name }}
       - run: echo "🍏 This job's status is ${{ job.status }}."

.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" />

.idea/phpspec.xml

@@ -5,6 +5,12 @@
       <PhpSpecSuiteConfiguration>
         <option name="myPath" value="$PROJECT_DIR$" />
       </PhpSpecSuiteConfiguration>
+      <PhpSpecSuiteConfiguration>
+        <option name="myPath" value="$PROJECT_DIR$" />
+      </PhpSpecSuiteConfiguration>
+      <PhpSpecSuiteConfiguration>
+        <option name="myPath" value="$PROJECT_DIR$" />
+      </PhpSpecSuiteConfiguration>
     </suites>
   </component>
 </project>

CHANGELOG.md

@@ -1,4 +1,50 @@
 # 版本更新日志
+### [1.0.3](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.2...v1.0.3) (2025-11-25)
+
+
+### 🚀 Chore | 构建/工程依赖/工具
+
+* **deps:** 更新 roave/dont 依赖版本约束 ([29ad0ab](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/commit/29ad0ab1c9c7bd8a634505a390efda82d954a929))
+
+### [1.0.2](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.1...v1.0.2) (2025-09-26)
+
+### [1.0.1](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.0...v1.0.1) (2025-08-19)
+
+
+### 👷 Continuous Integration | CI 配置
+
+* **gitea:** 更新发布流程并简化版本号 ([bc9977a](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/commit/bc9977a16f0a996aebccda403ceb51b65c28dddd))
+
+## [1.0.0](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.0-beta.14...v1.0.0) (2025-08-18)
+
+## [1.0.0-beta.14](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.0-beta.13...v1.0.0-beta.14) (2025-08-12)
+
+
+### ♻️ Code Refactoring | 代码重构
+
+* **exception:** 重构异常处理逻辑 ([3a1f912](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/commit/3a1f912520999ec947295efed564448a85ad1039))
+
+## [1.0.0-beta.13](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.0-beta.12...v1.0.0-beta.13) (2025-08-08)
+
+
+### 🐛 Bug Fixes | Bug 修复
+
+* **CoreMiddleware:** 修复分页头部信息设置错误 ([15da6e6](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/commit/15da6e67702cdd7d31b55ab58ba9cbbb1a698157))
+
+## [1.0.0-beta.12](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.0-beta.11...v1.0.0-beta.12) (2025-08-08)
+
+
+### ✨ Features | 新功能
+
+* **exception:** 新增业务错误处理和 API 迁移支持 ([55da020](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/commit/55da02080efa5bd6978b7d0a0e3bbcb1cde41027))
+
+## [1.0.0-beta.11](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.0-beta.10...v1.0.0-beta.11) (2025-07-11)
+
+
+### ✨ Features | 新功能
+
+* 新增SP相关配置的枚举 ([bf40c6e](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/commit/bf40c6e681cb1ff37a8fc331a3cd0cdb495e6ff1))
+
 ## [1.0.0-beta.10](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.0-beta.9...v1.0.0-beta.10) (2025-07-09)
 
 

VERSION_TRACKER.txt

@@ -1 +1 @@
-1.0.0-beta.10
+1.0.3

composer.json

@@ -38,7 +38,7 @@
     "jetbrains/phpstorm-attributes": "^1.0",
     "lmc/http-constants": "^1.2.0",
     "myclabs/php-enum": "^1.8.4",
-    "roave/dont": "^1.6.0",
+    "roave/dont": "*",
     "symfony/http-foundation": "^6.4",
     "symfony/polyfill-php81": "^1.28",
     "symfony/polyfill-php82": "^1.28",
@@ -136,5 +136,5 @@
       "url": "https://mirrors.aliyun.com/composer/"
     }
   },
-  "version": "1.0.0-beta.10"
+  "version": "1.0.3"
 }

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.default')]
+    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/Enumerations/Sp/EnvConfiguration.php

@@ -0,0 +1,16 @@
+<?php
+/**
+ * EnvConfiguration.php@Core
+ *
+ * @author 李东云 <Dongyun.Li@LuxCreo.Ai>
+ * Powered by PhpStorm
+ * Created on 2025/7/11
+ */
+
+namespace Singularity\HDK\Core\Enumerations\Sp;
+
+interface EnvConfiguration
+{
+    public const DEVELOPMENT = 'development';
+    public const PRODUCTION = 'production';
+}

src/Enumerations/Sp/ServiceProviderConfiguration.php

@@ -0,0 +1,12 @@
+<?php
+/**
+ * ServiceProviderConfiguration.php@Core
+ *
+ * @author 李东云 <Dongyun.Li@LuxCreo.Ai>
+ * Powered by PhpStorm
+ * Created on 2025/7/11
+ */
+
+namespace Singularity\HDK\Core\Enumerations\Sp;
+
+interface ServiceProviderConfiguration extends EnvConfiguration, SiteConfiguration {}

src/Enumerations/Sp/SiteConfiguration.php

@@ -0,0 +1,16 @@
+<?php
+/**
+ * SiteConfigration.php@Core
+ *
+ * @author 李东云 <Dongyun.Li@LuxCreo.Ai>
+ * Powered by PhpStorm
+ * Created on 2025/7/11
+ */
+
+namespace Singularity\HDK\Core\Enumerations\Sp;
+
+interface SiteConfiguration
+{
+    public const CN = 'CN';
+    public const NA = 'NA';
+}

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;
@@ -40,6 +42,7 @@ use Teapot\StatusCode\RFC\RFC7231;
 use Throwable;
 
 use function Hyperf\Config\config;
+use function Hyperf\Support\make;
 use function Hyperf\Translation\__;
 
 /**
@@ -52,9 +55,6 @@ use function Hyperf\Translation\__;
  */
 class CommonHandler extends ExceptionHandler
 {
-    #[Inject(required: false)]
-    private ?RequestInterface $request;
-
     #[Inject]
     private StdoutLogger $logger;
 
@@ -68,18 +68,23 @@ class CommonHandler extends ExceptionHandler
     {
         // 阻止异常冒泡
         $this->stopPropagation();
+        if ($throwable instanceof BadRequestHttpException) {
+            $request = $throwable->getRequest();
+        } else {
+            $request = make(RequestInterface::class);
+        }
         $restful = $this->apiStyleService->get();
         // $restful = config('common.response.restful');
         $code_name = config('common.response.code_name');
         $message_name = config('common.response.message_name');
         $is_testing = config('app_status') === true;
-        $this->request?->url();
+        $request?->url();
 
         $is_debug = $is_testing;
         $error_type = $throwable::class;
         $request_time = Carbon::now()->toDateTimeString();
-        $request_data = Json::encode($this->request?->getParsedBody());
+        $request_data = $request?->getBody()->getContents();
-        $request_headers = Json::encode($this->request?->getHeaders());
+        $request_headers = Json::encode($request?->getHeaders());
         // 901 程序语法错误
         // 902 SQL 语法错误
         if ($throwable instanceof QueryException) {
@@ -123,7 +128,7 @@ class CommonHandler extends ExceptionHandler
             $data = [
                 $code_name => $code,
                 $message_name => CommonErrorCode::getMessage($code, ['methods' => join(', ', $allow_method)]),
-                'currentMethod' => $this->request?->getMethod(),
+                'currentMethod' => $request?->getMethod(),
                 'allowedMethod' => $allow_method,
             ];
             $status_code = RFC7231::METHOD_NOT_ALLOWED;
@@ -133,7 +138,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 +163,7 @@ class CommonHandler extends ExceptionHandler
                         $code,
                         [
                             'param' => $throwable->getFieldName(),
-                        ]
+                        ],
                     )
                     : $message,
             ];
@@ -178,7 +183,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 +198,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 +212,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),
                 ),
             ];
             // 其他错误
@@ -233,45 +260,47 @@ class CommonHandler extends ExceptionHandler
         if ($is_debug && $is_testing) {
             $data += ['errorType' => $error_type, 'errorTrack' => $throwable->getTrace()];
         }
-        $cookies = json_encode($this->request->getCookieParams(), JSON_UNESCAPED_UNICODE);
+        $cookies = json_encode($request->getCookieParams(), JSON_UNESCAPED_UNICODE);
         $this->logger->error(
             <<<ERROR_LOG
-TYPE: {$error_type}
+                TYPE: {$error_type}
-[$data[$code_name]] $data[$message_name]
+                [$data[$code_name]] $data[$message_name]
-{$throwable->getMessage()}
+                {$throwable->getMessage()}
--------------------------------
+                -------------------------------
-REQUEST_TIME: {$request_time}
+                REQUEST_TIME: {$request_time}
--------------------------------
+                -------------------------------
-REQUEST_HEADERS:
+                REQUEST_HEADERS:
-{$request_headers}
+                {$request_headers}
--------------------------------
+                -------------------------------
-REQUEST_COOKIES:
+                REQUEST_COOKIES:
-{$cookies}
+                {$cookies}
--------------------------------
+                -------------------------------
-REQUEST_METHOD:
+                REQUEST_METHOD:
-{$this->request?->getMethod()}
+                {$request?->getMethod()}
--------------------------------
+                -------------------------------
-REQUEST_URL:
+                REQUEST_URL:
-{$this->request?->getUri()}
+                {$request?->getUri()}
--------------------------------
+                -------------------------------
-REQUEST_QUERY:
+                REQUEST_QUERY:
-{$this->request?->getQueryString()}
+                {$request?->getUri()->getQuery()}
--------------------------------
+                -------------------------------
-REQUEST_DATA:
+                REQUEST_DATA:
-{$request_data}
+                {$request_data}
--------------------------------
+                -------------------------------
-TRACE:
+                TRACE:
-{$throwable->getTraceAsString()}
+                {$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);
+    }
+}

src/Middleware/CommonCoreMiddleware.php

@@ -77,7 +77,7 @@ class CommonCoreMiddleware extends CoreMiddleware
                 ->withHeader('Per-Page', (string)$response->perPage())
                 ->withHeader('Total', (string)$response->total())
                 ->withHeader('Current-Page', (string)$response->currentPage())
-                ->withHeader('Total-Pages', (string)$response->hasPages());
+                ->withHeader('Total-Pages', (string)$response->lastPage());
             $fact_response = $this->utilsService->extendLinkToHeader($fact_response, $response->nextPageUrl(), 'next');
             $fact_response = $this->utilsService->extendLinkToHeader(
                 $fact_response,
@@ -90,7 +90,10 @@ class CommonCoreMiddleware extends CoreMiddleware
                 $response->previousPageUrl(),
                 'prev'
             );
-            return $fact_response->withBody(new SwooleStream(Json::encode($response->items())));
+            return $fact_response->withBody(new SwooleStream(Json::encode($response->items())))->withHeader(
+                Header::CONTENT_TYPE,
+                'application/json',
+            );
         }
 
         return parent::transferToResponse($response, $request);