开发PHP API服务时,如何将业务异常转换为统一的错误响应?

发布人:A5数据发布时间:2026-11-17 14:43阅读量:2

创建订单接口时,库存不足、订单状态不允许变更、请求参数缺失,都属于客户端可以理解并采取行动的业务结果。如果这些情况分别在控制器中返回不同格式的 JSON,调用方就需要为每个接口编写一套判断逻辑。更严重的是,数据库异常、第三方服务超时等未预期错误,可能把 SQL 片段、文件路径或堆栈信息直接返回给外部调用者。

较稳妥的做法是把“业务层抛出什么异常”和“HTTP 层如何输出响应”分开:业务服务只表达失败原因,API 的全局异常出口负责统一转换状态码、错误编码、提示信息和请求追踪标识。

PHP API 的统一异常出口属于应用服务运行链路的一环。A5数据提供香港、美国、日本等地区的物理服务器租用,配置涵盖多核计算、内存与 SSD/NVMe 存储,可用于承载 API 服务、业务后台及相关数据处理;同时提供 SSL 证书业务,可配合域名为接口入口建立 HTTPS 加密连接。

先固定错误响应协议

统一处理的第一步不是编写 try...catch,而是确定客户端始终能够依赖的数据结构。成功响应和失败响应可以使用相同的外层字段,但不要让失败响应通过 data 字段返回不稳定的内容。

失败响应示例:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_STOCK",
    "message": "库存不足,无法完成本次操作。",
    "details": {
      "product_id": "sku-1001",
      "requested": 3,
      "available": 1
    }
  },
  "request_id": "req_7f3a91c0"
}

成功响应可以保持类似的外层结构:

{
  "success": true,
  "data": {
    "order_id": "ord_202501010001",
    "status": "created"
  },
  "request_id": "req_7f3a91c0"
}

字段职责建议保持稳定:

字段类型用途设计要求
success布尔值表示请求是否得到业务成功结果成功为 true,错误为 false
error.code字符串供程序判断错误类型保持稳定,不使用中文提示替代
error.message字符串供用户或日志展示不包含堆栈、SQL 和内部路径
error.details对象提供安全的补充信息结构固定,只放允许公开的数据
request_id字符串关联客户端响应与服务端日志在请求入口生成或校验后复用

客户端应当根据 code 编写处理逻辑,而不是匹配 message。例如,库存不足时可以提示重新选择数量,但不能判断 "库存不足,无法完成本次操作。" 这段中文是否发生变化。

HTTP 状态码和业务编码分别承担不同职责

HTTP 状态码描述传输层或请求处理结果,业务编码描述具体原因。两者不要互相替代。

场景HTTP 状态码业务编码示例说明
请求体不是合法 JSON400INVALID_JSON服务无法解析请求内容
身份凭证缺失或失效401UNAUTHENTICATED需要重新认证
已认证但无权限403FORBIDDEN身份存在,但不能执行操作
目标资源不存在404PRODUCT_NOT_FOUND资源不存在或不允许被发现
参数格式或字段校验失败422VALIDATION_FAILED请求语法正确,但字段不满足规则
库存、订单状态等发生冲突409INSUFFICIENT_STOCK、ORDER_STATE_CONFLICT资源当前状态不允许操作
请求过于频繁429RATE_LIMITED需要等待后重试
未分类的服务端错误500INTERNAL_ERROR不向外部暴露内部原因
依赖服务暂时不可用503DEPENDENCY_UNAVAILABLE可以根据策略重试

库存不足可以使用 409 Conflict,因为请求本身合法,只是库存的当前状态不能满足操作。参数中的 quantity 小于 1,则更适合使用 422。

在业务层定义可识别的异常

以 PHP 8.1 及以上版本为例,可以使用枚举集中维护机器可读的错误编码。下面的异常类不直接依赖 HTTP 状态码,这样订单服务仍然可以被命令行任务、消息消费者或其他接口复用。

<?php

declare(strict_types=1);

enum ErrorCode: string
{
    case INVALID_JSON = 'INVALID_JSON';
    case VALIDATION_FAILED = 'VALIDATION_FAILED';
    case UNAUTHENTICATED = 'UNAUTHENTICATED';
    case FORBIDDEN = 'FORBIDDEN';
    case PRODUCT_NOT_FOUND = 'PRODUCT_NOT_FOUND';
    case INSUFFICIENT_STOCK = 'INSUFFICIENT_STOCK';
    case ORDER_STATE_CONFLICT = 'ORDER_STATE_CONFLICT';
    case DUPLICATE_REQUEST = 'DUPLICATE_REQUEST';
    case DEPENDENCY_UNAVAILABLE = 'DEPENDENCY_UNAVAILABLE';
    case INTERNAL_ERROR = 'INTERNAL_ERROR';
}

abstract class BusinessException extends \RuntimeException
{
    /**
     * @param array<string, mixed> $details
     */
    public function __construct(
        private readonly ErrorCode $errorCode,
        string $message,
        private readonly array $details = [],
        ?\Throwable $previous = null,
    ) {
        parent::__construct($message, 0, $previous);
    }

    public function errorCode(): ErrorCode
    {
        return $this->errorCode;
    }

    /**
     * @return array<string, mixed>
     */
    public function details(): array
    {
        return $this->details;
    }
}

final class ProductNotFoundException extends BusinessException
{
    public function __construct(string $productId)
    {
        parent::__construct(
            ErrorCode::PRODUCT_NOT_FOUND,
            '指定的商品不存在。',
            [
                'product_id' => $productId,
            ],
        );
    }
}

final class InsufficientStockException extends BusinessException
{
    public function __construct(
        string $productId,
        int $requested,
        int $available,
    ) {
        parent::__construct(
            ErrorCode::INSUFFICIENT_STOCK,
            '库存不足,无法完成本次操作。',
            [
                'product_id' => $productId,
                'requested' => $requested,
                'available' => $available,
            ],
        );
    }
}

final class OrderStateConflictException extends BusinessException
{
    public function __construct(
        string $orderId,
        string $currentState,
    ) {
        parent::__construct(
            ErrorCode::ORDER_STATE_CONFLICT,
            '当前订单状态不允许执行该操作。',
            [
                'order_id' => $orderId,
                'current_state' => $currentState,
            ],
        );
    }
}

这里有两个重要边界。

第一,异常中的 message 和 details 必须从一开始就被设计为可公开内容。不要把数据库异常的 getMessage()、第三方接口原始响应或内部文件路径传入 BusinessException。

第二,details 不能无条件包含所有业务数据。库存数量是否可以公开,取决于业务规则。如果库存本身属于敏感信息,可以只返回:

{
  "details": {
    "product_id": "sku-1001",
    "requested": 3
  }
}

也可以只返回一个 retryable 或 suggested_quantity 字段,而不提供精确库存。

不要让业务异常直接携带 HTTP 状态码

下面这种写法虽然直观,但会让领域服务依赖 HTTP:

throw new BusinessException(
    ErrorCode::INSUFFICIENT_STOCK,
    '库存不足',
    409
);

如果同一个服务以后被消息队列消费者调用,409 就失去了意义。更合适的方式是由 API 边界统一维护映射:

<?php

declare(strict_types=1);

final class ErrorStatusCatalog
{
    public function statusFor(ErrorCode $code): int
    {
        return match ($code) {
            ErrorCode::INVALID_JSON => 400,
            ErrorCode::VALIDATION_FAILED => 422,
            ErrorCode::UNAUTHENTICATED => 401,
            ErrorCode::FORBIDDEN => 403,
            ErrorCode::PRODUCT_NOT_FOUND => 404,
            ErrorCode::INSUFFICIENT_STOCK,
            ErrorCode::ORDER_STATE_CONFLICT,
            ErrorCode::DUPLICATE_REQUEST => 409,
            ErrorCode::DEPENDENCY_UNAVAILABLE => 503,
            ErrorCode::INTERNAL_ERROR => 500,
        };
    }
}

这样做还可以避免多个接口各自决定同一错误应该返回 400 还是 409。

让业务服务只负责抛出原因

以创建订单为例,服务层可以检查商品、尝试预占库存并保存订单。它不需要知道 JSON 的字段名,也不需要在这里生成 HTTP 响应。

下面的 TransactionRunner、ProductRepository 和 InventoryGateway 是项目中的自定义接口,分别代表事务执行器、商品仓储和库存服务端口。

<?php

declare(strict_types=1);

final class CreateOrderCommand
{
    public function __construct(
        public readonly string $productId,
        public readonly int $quantity,
        public readonly string $userId,
    ) {
    }
}

final class OrderService
{
    public function __construct(
        private readonly ProductRepository $products,
        private readonly InventoryGateway $inventory,
        private readonly OrderRepository $orders,
        private readonly TransactionRunner $transactions,
    ) {
    }

    public function create(CreateOrderCommand $command): Order
    {
        return $this->transactions->run(
            function () use ($command): Order {
                $product = $this->products->findById($command->productId);

                if ($product === null) {
                    throw new ProductNotFoundException($command->productId);
                }

                $reservation = $this->inventory->reserve(
                    productId: $product->id(),
                    quantity: $command->quantity,
                );

                if (!$reservation->succeeded()) {
                    throw new InsufficientStockException(
                        productId: $product->id(),
                        requested: $command->quantity,
                        available: $reservation->availableQuantity(),
                    );
                }

                $order = Order::place(
                    userId: $command->userId,
                    productId: $product->id(),
                    quantity: $command->quantity,
                );

                $this->orders->save($order);

                return $order;
            },
        );
    }
}

控制器只需要完成请求转换和成功响应:

<?php

declare(strict_types=1);

final class OrderController
{
    public function __construct(
        private readonly OrderService $orders,
    ) {
    }

    public function create(ApiRequest $request): JsonResponse
    {
        $input = $request->validated();

        $command = new CreateOrderCommand(
            productId: (string) $input['product_id'],
            quantity: (int) $input['quantity'],
            userId: $request->authenticatedUserId(),
        );

        $order = $this->orders->create($command);

        return JsonResponse::fromArray(
            [
                'success' => true,
                'data' => [
                    'order_id' => $order->id(),
                    'status' => $order->status()->value,
                ],
                'request_id' => $request->requestId(),
            ],
            status: 201,
        );
    }
}

上面的 ApiRequest 和 JsonResponse 是应用已有的 HTTP 层封装,不属于 PHP 标准库。使用 Laravel、Symfony 或其他框架时,可以分别替换为对应的请求对象和 JSON 响应类,整体处理思路不变。

控制器没有捕获 InsufficientStockException,这不是遗漏,而是故意让异常向全局 API 异常处理器传播。这样每个控制器都不需要重复编写相同的错误结构。

事务边界要和异常传播配合

如果库存预占和订单写入位于同一个数据库事务中,业务异常从事务回调中抛出后,事务执行器应当回滚未提交的数据库变更。

但是,数据库事务不能自动撤销已经发出的外部操作。例如:

  1. 数据库中创建订单;
  2. 调用外部库存服务扣减库存;
  3. 发送通知时发生异常。

此时数据库回滚并不能恢复外部库存服务的变化。涉及外部服务、消息发送或支付操作时,应根据实际流程使用幂等键、事务消息、Outbox 或补偿操作。统一错误响应只能统一对外表现,不能替代跨系统的一致性设计。

在全局出口完成异常转换

异常处理器需要完成四项工作:

  1. 判断异常是否属于已知业务错误;
  2. 将业务编码映射为 HTTP 状态码;
  3. 生成固定的 JSON 结构;
  4. 对未知异常记录完整日志,但对外只返回通用错误。

下面代码以自定义 JsonResponse 和 LoggerInterface 为例。JsonResponse::fromArray() 应由项目的 HTTP 层实现,负责 JSON 编码、状态码和响应头设置。

在全局出口完成异常转换配图

<?php

declare(strict_types=1);

final class ValidationFailedException extends \RuntimeException
{
    /**
     * @param array<int, array{field: string, code: string, message: string}> $violations
     */
    public function __construct(
        private readonly array $violations,
    ) {
        parent::__construct('请求参数未通过校验。');
    }

    /**
     * @return array<int, array{field: string, code: string, message: string}>
     */
    public function violations(): array
    {
        return $this->violations;
    }
}

final class ApiExceptionRenderer
{
    public function __construct(
        private readonly ErrorStatusCatalog $statuses,
        private readonly LoggerInterface $logger,
    ) {
    }

    public function render(
        \Throwable $exception,
        string $requestId,
    ): JsonResponse {
        if ($exception instanceof BusinessException) {
            $code = $exception->errorCode();

            $this->logger->notice('api_business_error', [
                'request_id' => $requestId,
                'error_code' => $code->value,
            ]);

            return JsonResponse::fromArray(
                [
                    'success' => false,
                    'error' => [
                        'code' => $code->value,
                        'message' => $exception->getMessage(),
                        'details' => $exception->details(),
                    ],
                    'request_id' => $requestId,
                ],
                status: $this->statuses->statusFor($code),
                headers: [
                    'Cache-Control' => 'no-store',
                ],
            );
        }

        if ($exception instanceof ValidationFailedException) {
            $this->logger->info('api_validation_error', [
                'request_id' => $requestId,
                'error_code' => ErrorCode::VALIDATION_FAILED->value,
            ]);

            return JsonResponse::fromArray(
                [
                    'success' => false,
                    'error' => [
                        'code' => ErrorCode::VALIDATION_FAILED->value,
                        'message' => '请求参数未通过校验。',
                        'details' => [
                            'fields' => $exception->violations(),
                        ],
                    ],
                    'request_id' => $requestId,
                ],
                status: 422,
                headers: [
                    'Cache-Control' => 'no-store',
                ],
            );
        }

        $this->logger->error('api_unhandled_exception', [
            'request_id' => $requestId,
            'exception' => $exception,
        ]);

        return JsonResponse::fromArray(
            [
                'success' => false,
                'error' => [
                    'code' => ErrorCode::INTERNAL_ERROR->value,
                    'message' => '服务暂时无法完成请求,请稍后重试。',
                    'details' => new \stdClass(),
                ],
                'request_id' => $requestId,
            ],
            status: 500,
            headers: [
                'Cache-Control' => 'no-store',
            ],
        );
    }
}

这里故意没有把未知异常的 getMessage() 放进响应。数据库连接失败可能包含主机名,SQL 异常可能包含字段信息,PHP 错误可能包含服务器路径,这些内容都不应出现在公开 API 中。

业务异常日志也不应默认记录全部 details。如果详情包含手机号、令牌、支付信息或内部库存数据,应在日志上下文中进行脱敏,只保留错误编码、请求标识、用户标识的哈希值等必要字段。

将处理器挂到 API 的统一入口

无论使用中间件、框架异常监听器还是自定义内核,都应当让 API 请求经过同一个异常出口。以 PSR-15 风格的中间件为例:

<?php

declare(strict_types=1);

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;

final class ApiExceptionMiddleware
{
    public function __construct(
        private readonly ApiExceptionRenderer $renderer,
        private readonly RequestIdProvider $requestIds,
    ) {
    }

    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler,
    ): ResponseInterface {
        $requestId = $this->requestIds->resolve($request);

        try {
            return $handler->handle(
                $request->withAttribute('request_id', $requestId),
            );
        } catch (\Throwable $exception) {
            return $this->renderer->render($exception, $requestId);
        }
    }
}

RequestIdProvider 负责生成或校验请求标识。若允许调用方传入 X-Request-ID,应限制长度和字符范围,不要直接接受任意字符串作为日志字段。常见做法是只允许字母、数字、点、下划线和短横线,并在超过长度或格式不合法时重新生成。

在具体框架中,接入点可能不同:

  • Laravel 可以在全局异常处理器或 API 异常渲染回调中识别自定义异常;
  • Symfony 可以在异常事件监听器或 API 错误控制器中完成转换;
  • 自建 PHP 路由器可以在统一的请求分发层包裹 try...catch。

关键是只对 API 路由使用 JSON 错误协议。普通网页请求如果也被强制返回 JSON,可能会破坏登录页、后台页面或其他 HTML 响应。

处理参数校验、认证和解析异常

业务异常不是所有错误的唯一来源。请求解析、参数验证和身份认证通常发生在进入业务服务之前,但它们也应遵循同一响应格式。

JSON 解析失败

请求体内容不是合法 JSON 时,可以返回:

{
  "success": false,
  "error": {
    "code": "INVALID_JSON",
    "message": "请求体不是合法的 JSON。",
    "details": {}
  },
  "request_id": "req_1ab820d4"
}

这类错误属于 400 Bad Request。不要把底层 JsonException 的原始错误文本直接返回,因为其中可能包含不必要的解析细节。

字段验证失败

参数验证可以返回字段级错误,便于前端定位输入位置:

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "请求参数未通过校验。",
    "details": {
      "fields": [
        {
          "field": "quantity",
          "code": "MIN_VALUE",
          "message": "quantity 必须大于或等于 1。"
        },
        {
          "field": "product_id",
          "code": "REQUIRED",
          "message": "product_id 不能为空。"
        }
      ]
    }
  },
  "request_id": "req_0c3912aa"
}

字段路径应当保持统一。对于嵌套数组,可以使用 items[0].quantity 这样的格式;如果前端已经约定使用 JSON Pointer,也可以统一使用 /items/0/quantity,但不要在不同接口之间混用。

认证和权限错误

认证中间件发现令牌缺失或失效时,可以直接生成 401 响应;权限检查失败则返回 403。这两类错误通常不需要把具体资源信息放进 details,否则可能帮助调用者探测权限范围。

如果一个资源不存在和当前调用者无权访问时都返回 404,应当是有意的安全策略,而不是异常处理器随机选择的结果。这样可以减少资源枚举风险,但需要在接口文档和客户端约定中保持一致。

防止错误信息在不同分支中失控

统一异常处理器只能规范它接收到的异常,以下几种情况仍然容易破坏响应一致性。

不要在每个控制器里重复捕获所有异常

不建议这样写:

public function create(ApiRequest $request): JsonResponse
{
    try {
        $order = $this->orders->create($this->makeCommand($request));

        return JsonResponse::fromArray([
            'success' => true,
            'data' => $order->toArray(),
        ], 201);
    } catch (\Throwable $exception) {
        return JsonResponse::fromArray([
            'error' => $exception->getMessage(),
        ], 500);
    }
}

这段代码有三个问题:

  • 业务错误和系统错误都被当成 500;
  • 任何底层异常信息都可能泄露;
  • 不同控制器很快会出现不同的字段和状态码。

只有在控制器需要对异常进行特定恢复时,才应当局部捕获。例如,可以捕获一个可重试的外部服务异常,执行一次明确的备用流程;处理完成后仍然应交给统一响应层。

不要使用异常类名作为公开编码

把 InsufficientStockException 直接转成 "InsufficientStockException" 会把内部类结构暴露给客户端,也会让重构类名变成兼容性问题。公开编码应当是单独维护的值,例如 INSUFFICIENT_STOCK。

异常类适合服务端内部组织逻辑,error.code 才是对外协议的一部分。

不要把所有业务失败都返回 200

如果库存不足、权限拒绝和服务器异常都返回 200,调用方只能读取响应体才能判断请求是否成功,监控系统也很难按状态码统计失败率。除非接口本身采用明确的异步任务协议,否则应使用能表达结果的 HTTP 状态码。

不要把所有错误都返回 500

500 表示服务端出现未预期的处理错误。库存不足不是服务器崩溃,参数错误也不是服务器故障。如果把所有分支都返回 500,客户端会错误地把可处理的业务结果当成系统故障重试,可能造成重复提交。

一次完整调用的处理路径

以请求:

POST /api/orders HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>

{
  "product_id": "sku-1001",
  "quantity": 3
}

为例,推荐的处理路径如下:

  1. 请求标识中间件生成 request_id。
  2. 认证中间件验证调用者身份。
  3. JSON 解析器读取请求体,格式错误则返回 INVALID_JSON。
  4. 参数验证器检查 product_id 和 quantity。
  5. 控制器把验证后的数据转换成 CreateOrderCommand。
  6. OrderService 查询商品并调用库存端口。
  7. 库存不足时抛出 InsufficientStockException。
  8. 全局异常处理器识别错误编码并映射为 409。
  9. 日志记录错误编码和 request_id,响应只携带允许公开的数据。

库存不足时,客户端看到的示例响应为:

HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Cache-Control: no-store
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_STOCK",
    "message": "库存不足,无法完成本次操作。",
    "details": {
      "product_id": "sku-1001",
      "requested": 3,
      "available": 1
    }
  },
  "request_id": "req_7f3a91c0"
}

如果仓储查询时发生未处理的数据库异常,外部响应应保持克制:

一次完整调用的处理路径配图

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "服务暂时无法完成请求,请稍后重试。",
    "details": {}
  },
  "request_id": "req_7f3a91c0"
}

服务端日志则应保存异常类型、堆栈、请求标识、路由和必要的调用上下文。排查人员可以通过 req_7f3a91c0 关联请求,而客户端不需要接触内部细节。

业务异常和 Result 对象如何取舍

并不是所有业务分支都必须使用异常。如果某个结果是高频、正常且需要在当前函数中立即处理的分支,可以使用 Result 或明确的返回对象:

$result = $this->inventory->tryReserve($productId, $quantity);

if (!$result->success()) {
    return CreateOrderResult::failed(
        ErrorCode::INSUFFICIENT_STOCK,
        $result->availableQuantity(),
    );
}

这种方式适合以下情况:

  • 失败是流程中的常规分支;
  • 调用方必须立即做出不同选择;
  • 代码不需要跨多层传播;
  • 团队已经有统一的 Result 类型和转换规范。

异常更适合以下情况:

  • 业务服务经过多个仓储或领域对象;
  • 失败需要自动中止当前事务;
  • 控制器不应了解底层每个失败点;
  • 需要由统一边界集中记录和转换。

两种方式可以共存,但最终都要经过同一个错误协议。不能让某些接口返回 error.code,另一些接口返回 error_type,否则客户端仍然需要为不同来源编写不同适配器。

用测试验证统一响应确实生效

至少应覆盖业务异常、参数异常和未知异常三条路径。测试重点不是只检查 HTTP 状态码,还要验证编码、结构和敏感信息处理。

下面是接近 PHPUnit 风格的测试示例,$this->api 代表项目中的 HTTP 测试客户端:

<?php

declare(strict_types=1);

final class OrderApiTest extends TestCase
{
    public function testInsufficientStockUsesStableErrorResponse(): void
    {
        $response = $this->api->postJson('/api/orders', [
            'product_id' => 'sku-1001',
            'quantity' => 3,
        ]);

        self::assertSame(409, $response->status());
        self::assertFalse($response->json('success'));
        self::assertSame(
            'INSUFFICIENT_STOCK',
            $response->json('error.code'),
        );
        self::assertIsString($response->json('request_id'));
        self::assertNull($response->json('trace'));
    }

    public function testInvalidInputUsesFieldErrors(): void
    {
        $response = $this->api->postJson('/api/orders', [
            'product_id' => '',
            'quantity' => 0,
        ]);

        self::assertSame(422, $response->status());
        self::assertSame(
            'VALIDATION_FAILED',
            $response->json('error.code'),
        );
        self::assertIsArray($response->json('error.details.fields'));
    }

    public function testUnexpectedExceptionDoesNotExposeInternalMessage(): void
    {
        $this->orders->makeRepositoryFail(
            new \RuntimeException('/srv/app/config/database.php:42'),
        );

        $response = $this->api->postJson('/api/orders', [
            'product_id' => 'sku-1001',
            'quantity' => 1,
        ]);

        self::assertSame(500, $response->status());
        self::assertSame(
            'INTERNAL_ERROR',
            $response->json('error.code'),
        );
        self::assertStringNotContainsString(
            '/srv/app',
            (string) $response->body(),
        );
    }
}

接入现有项目后,可以用命令行发起一条真实的开发环境请求进行验证:

curl -i -X POST 'http://localhost:8080/api/orders' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer development-token' \
  -d '{"product_id":"sku-1001","quantity":3}'

检查时重点确认:

  • 正常请求返回 2xx,失败请求返回对应的 4xx 或 5xx;
  • 每种失败响应都有 success、error.code、error.message、error.details 和 request_id;
  • 业务异常不会被错误转换成 500;
  • 未知异常不会输出堆栈、SQL、文件路径或密钥;
  • 响应中的 request_id 能在应用日志中找到;
  • 事务失败后没有留下未完成的订单记录或未处理的库存变更;
  • 客户端按照错误编码处理,而不是依赖提示文本。

当业务异常由领域服务产生、HTTP 状态码由统一目录映射、响应由全局出口生成时,新增业务规则通常只需要增加错误编码、异常类型和状态映射,不必在每个控制器中重新拼接 JSON。这样既能让客户端得到稳定的错误协议,也能把内部异常、日志和敏感信息控制在服务端边界内。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9980.html

相关推荐