开发PHP API服务时,如何将业务异常转换为统一的错误响应?
创建订单接口时,库存不足、订单状态不允许变更、请求参数缺失,都属于客户端可以理解并采取行动的业务结果。如果这些情况分别在控制器中返回不同格式的 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 状态码 | 业务编码示例 | 说明 |
|---|---|---|---|
| 请求体不是合法 JSON | 400 | INVALID_JSON | 服务无法解析请求内容 |
| 身份凭证缺失或失效 | 401 | UNAUTHENTICATED | 需要重新认证 |
| 已认证但无权限 | 403 | FORBIDDEN | 身份存在,但不能执行操作 |
| 目标资源不存在 | 404 | PRODUCT_NOT_FOUND | 资源不存在或不允许被发现 |
| 参数格式或字段校验失败 | 422 | VALIDATION_FAILED | 请求语法正确,但字段不满足规则 |
| 库存、订单状态等发生冲突 | 409 | INSUFFICIENT_STOCK、ORDER_STATE_CONFLICT | 资源当前状态不允许操作 |
| 请求过于频繁 | 429 | RATE_LIMITED | 需要等待后重试 |
| 未分类的服务端错误 | 500 | INTERNAL_ERROR | 不向外部暴露内部原因 |
| 依赖服务暂时不可用 | 503 | DEPENDENCY_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 异常处理器传播。这样每个控制器都不需要重复编写相同的错误结构。
事务边界要和异常传播配合
如果库存预占和订单写入位于同一个数据库事务中,业务异常从事务回调中抛出后,事务执行器应当回滚未提交的数据库变更。
但是,数据库事务不能自动撤销已经发出的外部操作。例如:
- 数据库中创建订单;
- 调用外部库存服务扣减库存;
- 发送通知时发生异常。
此时数据库回滚并不能恢复外部库存服务的变化。涉及外部服务、消息发送或支付操作时,应根据实际流程使用幂等键、事务消息、Outbox 或补偿操作。统一错误响应只能统一对外表现,不能替代跨系统的一致性设计。
在全局出口完成异常转换
异常处理器需要完成四项工作:
- 判断异常是否属于已知业务错误;
- 将业务编码映射为 HTTP 状态码;
- 生成固定的 JSON 结构;
- 对未知异常记录完整日志,但对外只返回通用错误。
下面代码以自定义 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
}
为例,推荐的处理路径如下:
- 请求标识中间件生成
request_id。 - 认证中间件验证调用者身份。
- JSON 解析器读取请求体,格式错误则返回
INVALID_JSON。 - 参数验证器检查
product_id和quantity。 - 控制器把验证后的数据转换成
CreateOrderCommand。 OrderService查询商品并调用库存端口。- 库存不足时抛出
InsufficientStockException。 - 全局异常处理器识别错误编码并映射为
409。 - 日志记录错误编码和
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

