企业官网建设流程全解析

1. 理解错误与异常：这条分界线画错了，后面会很难受

PHP 的错误机制在过去十年里发生了很大的变化，但说实话，很多靠 PHP 吃饭的人对"错误"和"异常"的理解还停留在 PHP 5 时代，甚至更早。每次我 review 别人的代码，看到@file_get_contents()后面跟一堆if判断，或者吐槽"PHP 的异常机制真难用"的时候，我都想拉着他们聊聊这个核心分界线：错误（Error）和异常（Exception）在 PHP 里是两个不一样的东西，而且从 PHP 7 开始，这条分界线的处理方式又变了一次。

在 PHP 5 里，程序出问题主要是靠"错误"这个机制来通知的。比如E_WARNING、E_NOTICE，它们不是一个可以被捕获的对象，而是一个由 PHP 引擎直接抛出的信号，传统做法是配合set_error_handler()去拦截。这种机制导致了一个很麻烦的局面：每个函数都有可能"静默地"出问题，然后在下一行代码里你才发现变量是 null 了，但要回头查到底是哪个函数、在哪个环节吞掉了错误，往往要废很大的功夫。

PHP 7 引入了一个转折点：把原来很大一部分致命错误（E_ERROR）改成了Error/Throwable体系，让它们可以被try...catch捕获。这意味着 PHP 在向 Java、Python 看齐，把异常作为处理程序故障的主要通道。但问题也来了：一套全新的异常类体系和一个老旧的错误机制并存，如果开发者不理解两者的分界，极容易写出"半异常半错误"的代码，表面看起来能用，实际脆弱得不行。

作为一个做了不少年 PHP 后端的人，我的观点很直接：在 PHP 7 之后的时代，任何你自己的业务代码，都应该把异常处理作为主路径，把传统错误处理作为兜底。自定义错误类型不是为了炫技，而是为了让你在几百个类、几十层调用栈里，一眼看出问题出在哪一层、属于哪一类、该怎么处理。

2. 系统级错误不够用的真正原因：错误信息不等于错误处理

很多人觉得"错误处理"就是"把错误信息打出来"，这其实是个天大的误解。系统内置的异常和错误类型确实能在出状况时抛出一堆信息，但它解决的是"引擎视角"的问题，而不是"业务视角"的问题。

举个例子：你写了一个从外部 API 拉取用户数据的封装类。如果 API 超时了，PHP 可能会抛一个ErrorException，也可能是curl扩展返回 false 然后你在代码里手动判断，还可能直接在file_get_contents上触发一个 WARNING。系统只会告诉你"连接失败"或者"操作超时"，但不会告诉你这究竟是网络问题、对方服务 500、还是你这边代理配错了。等你的代码跑到了线上，日志里躺着一堆含义不明的错误消息，你靠什么来快速定位？

这就是自定义错误类型的第一层价值：用异常类的名字表达错误的语义，而不是让错误消息去承担这个语义。

我见过一个比较典型的项目，日志里全是PHP Fatal error: Uncaught Exception: Error: something went wrong.，仔细一看，原来是把所有的处理逻辑放在一个大的try...catch里，不管什么错误都throw new \Exception('something happened')。后来排查生产事故，只能靠猜。真正的解决方案很简单：定义几个对应业务场景的异常类，比如ApiConnectionException、ApiTimeoutException、ApiResponseParseException，在抛出的瞬间就把问题类型固定下来，catch 的时候按类别处理，日志里按类名过滤。这个做法的好处是，你从异常类名就能判断问题类别，错误消息只是补充信息，而不是唯一线索。

再往深一层说，自定义异常类也不仅仅是"给异常起个好名字"。它还会影响你的代码架构。在异常类型定义清晰的系统里，业务代码和基础设施错误是可以分层的。比如你写的是 Service 层，底层传来的是 PDOException，你既不应该把 PDOException 直接抛给 Controller（太底层，调用者看不懂），也不应该完全吞掉（会丢失故障线索），而是应该捕获它，包装成一个自定义的RepositoryException再抛出去。这个包装动作，把底层实现细节和上层业务语义隔离开来，整个系统的可维护性会有非常大的提升。

3. 一套可复用的 PHP 异常体系设计：从场景出发，不要从 API 出发

自定义异常类说起来容易，可是很多人一开始就会栽在"类要怎么拆"这个问题上。我建议你反过来想：不要先想一共有几种异常类型，而是先想你的系统里有哪些必须被区分对待的失败场景。换句话说，异常体系是对业务失败场景的一次建模，跟建表结构差不多，这是需要认真设计的。

3.1 一个具体场景：报表导出功能里的错误处理

我拿一个典型的例子说：你有一个报表导出功能，大致流程是：先从数据库查数据，然后生成 CSV 文件，最后把文件通过邮件发出去。这个流程里可能会出现这些故障：

• 数据库查询因 SQL 语法错误或连接问题失败；
• 业务校验发现自己没有权限导出某些字段；
• CSV 写入目录没有写权限；
• 邮件发送服务超时或返回失败。

如果用系统内置的Exception来抛，最后在 Controller 层你会收到很多Exception，你只能靠 message 解析，这是灾难。但如果自定义几个异常类型，情况就会完全不一样。

我给的方案是这样的：

<?php namespace App\Exception; class ExportException extends \RuntimeException { protected array $context = []; public function __construct(string $message, array $context = [], int $code = 0, ?\Throwable $previous = null) { $this->context = $context; parent::__construct($message, $code, $previous); } public function getContext(): array { return $this->context; } }

首先定义一个基类ExportException，它继承了RuntimeException。为什么用RuntimeException而不是Exception？因为理论上，导出相关的错误都属于"运行时才可能暴露的错误"——在代码编译阶段你是发现不了报表导不出、邮件发不出的，它们不具备可检查性。选择RuntimeException作为基类，能让人从类名直接感知到这个错误的发生时机，这是一种类型层面的自描述。

context属性是我非常强调的一个点。系统内置异常只有 message、code、file、line 这些信息，但真实项目里往往还缺一部分关键上下文数据，比如是哪个用户触发的、传入了哪些参数、操作的是哪个报表 ID。把这些塞进Exception的 message 里，会导致日志乱成一团；不塞进去，排查问题时又要抓瞎。所以我把 context 作为构造参数传入异常，并且提供getContext()方法拿取。

然后是这个导出场景下的具体异常分工：

<?php namespace App\Exception; class QueryDataException extends ExportException {} class PermissionDeniedException extends ExportException {} class CsvFileWriteException extends ExportException {} class EmailSendException extends ExportException {}

这四个异常全部继承自ExportException。这样做的最大好处是：调用方可以根据需要做两道拦截。

<?php try { $exportService->export($params); } catch (PermissionDeniedException $e) { // 返回 403，给用户一个明确提示 } catch (ExportException $e) { // 其他导出相关异常，统一记日志，返回 500 }

第一道拦截处理最特殊的权限问题，第二道拦截兜底其他所有导出异常。因为所有自定义异常都继承自ExportException，所以在 catch 时完全不用关心它们内部是不是来自数据库、文件系统还是邮件服务，只需要关心业务类型。

3.2 为什么我不建议直接 new Exception 再拼 message

之前有一个项目，原来的开发习惯是到处throw new \Exception('用户不存在')或者throw new \Exception('数据库连接失败')。到了后期，需要根据不同类型的错误给用户返回不同的 HTTP 状态码，或者做不同的告警处理，结果就是每个 catch 块里都要做一堆字符串匹配：

<?php catch (\Exception $e) { if (str_contains($e->getMessage(), '用户不存在')) { // 返回 404 } elseif (str_contains($e->getMessage(), '数据库')) { // 返回 500 } }

这种写法的致命弱点是：判断逻辑强依赖错误消息的文本内容。只要有人改了消息措辞，哪怕只是加个空格，你的分支逻辑就断了。更重要的是，消息是给人看的，本来就是可以随意改的，而你却把它当成了程序的逻辑分支依据，这本质上跟把用户提交的内容拼接进 SQL 没什么区别，只是反过来的方向——都是不该作为代码逻辑依据却被硬用上了。

自定义异常类型之所以是正解，就在于它把"这条错误到底是什么"从"这条错误用什么文字描述"中彻底剥离了出来。程序逻辑依赖的是异常类型，人读的才是消息文本。基于类型的 catch 和路由是稳定的，基于消息的字符串匹配是脆弱的。

3.3 三个内置的 SPL 异常不要忽视

讨论自定义异常的时候有一个前提容易被带偏：好像什么场景都得自己 new 一个异常类。这个说法对业务异常成立，但 PHP 自带了一批 SPL 异常，很多时候直接拿过来用完全够，而且表达力更好。

• InvalidArgumentException：参数不合法、超出范围、格式不对。这个我几乎每写一个公共方法都会用到。
• DomainException：当前操作不适用当前领域状态。比如订单状态是"已发货"，你要执行"取消订单"操作，这就不符合业务领域规则。
• LogicException：代码层面的逻辑错误，理论上不应该发生。比如 switch 分支走到了 default，说明可能代码有 bug。
• RuntimeException：运行时才能发现的错误，比如连接超时、文件不存在等。

我见过一些人把所有数据库查询失败都抛成RuntimeException，你这个 SQL 写错了、表不存在了，这在开发阶段就该暴露，抛RuntimeException可以用，但它表达力不够。SQL 构造出错更适合用LogicException或者\PDOException原样抛出，因为这是程序员的 bug，不是外部环境的不稳定因素。用好这些 SPL 异常，能让你的代码在你不在场时依然具有极强的自解释能力。

4. 代码落地：自定义异常类的完整实操细节

聊完理念和设计原则，下面看具体写代码时需要注意的细节。这些点看起来小，却能直接决定你的异常体系是否真的在团队里落地、是否好用。

4.1 写一个带上下文数据的通用基础异常

在实际项目中，我建议先写一个通用的、基于RuntimeException的应用异常基类，作为整个项目的根异常。这个基类不但能统一提供上下文数据和日志友好性，还能给后面所有业务异常提供一致的接口。

<?php namespace App\Exception; class ApplicationException extends \RuntimeException { protected array $context = []; protected string $errorCode = 'APPLICATION_ERROR'; public function __construct( string $message = '', array $context = [], int $code = 0, ?\Throwable $previous = null ) { $this->context = $context; $this->errorCode = $errorCode ?? $this->errorCode; parent::__construct($message, $code, $previous); } public function getContext(): array { return $this->context; } public function getErrorCode(): string { return $this->errorCode; } public function __toString(): string { $details = json_encode($this->context, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); return sprintf( '[%s] %s (context: %s)', $this->errorCode, $this->getMessage(), $details ?: '[]' ); } }

这个基类有几个设计细节值得推敲。

第一，errorCode字段。真实系统里，后面对接 API 网关、前端国际化消息，或者根据错误码查文档，都是很常见的场景。光有异常类名还不够，再配一个稳定的字符串错误码，相当于给项目里的非技术人员（比如前端、客服）也留了一个通用的沟通语言。比如USER_NOT_FOUND、ORDER_STATUS_INVALID，这类错误码其实不属于任何具体技术框架，本来是信息架构层面的设计，很适合放在异常体系里统一管理。

第二，__toString()方法的覆写。这个方法在日志输出时会被自动调用，习惯上用(string) $e或者 echo 一个异常对象时触发。我在这里让日志输出带上错误码和上下文，可以极大降低日志排查的难度。不过有一个细节要克制：__toString()里不要包含getTraceAsString()的信息，因为异常 trace 可能非常长，混入错误码和 context 之后，日志会被刷得很乱，而且很多日志框架本来就会记录 trace，不需要你自己重复输出。

第三，构造函数对$previous的透传。这个其实很重要，它保证了链式异常不会断。一个常见的反面例子：底层抛了一个 PDOException，你在 Service 层把它接住后写throw new ApplicationException('保存失败: ' . $e->getMessage());，然后不传$previous。这样做的坏处是：原始的 PDOException 对象被丢弃了，它的 trace、它更深层的上下文完全丢失，排查时你只能看到"保存失败：SQLSTATE[HY000]"，但看不到完整的 SQL、看不到是哪个调用链触发的。正确写法是throw new ApplicationException('保存失败', ['table' => 'users'], 0, $e);，把 previous 挂上，核心故障链路就不再断裂。

4.2 如何区分业务异常和基础设施异常

很多团队的自定义异常体系做不好，是因为他们把业务错误和基础设施错误混在一个基类下面。

我自己比较习惯的做法是分成两条分支：

• ServiceException（服务层异常）及其子类，描述业务规则被违反的场景。例如InsufficientBalanceException、OrderCannotCancelException。
• InfrastructureException（基础设施异常）及其子类，描述与外部系统交互失败的场景。例如RedisConnectException、HttpRequestTimeoutException。

为什么一定要拆开？因为这两类异常的处理策略完全不同。业务异常多数是要返回给用户看的，比如"余额不足""无权限"；而基础设施异常只能内部记录，不能直接对外暴露细节，否则会泄露内部网络架构、数据库结构等信息。而且这两者的监控告警级别也不一样：业务异常属于正常业务流的一部分，出现频率高但不用紧张；基础设施异常则往往代表系统健康状态出了问题，需要立刻响应。

<?php namespace App\Exception; class ServiceException extends ApplicationException {} class InfrastructureException extends ApplicationException {}

然后在各层代码里，只抛出符合该层语义的异常。比如在 Repository 层不抛OrderCannotCancelException，你抛InfrastructureException的一个子类；在 Service 层不直接抛 PDOException，而是捕获并包装为对应的基础设施异常。

这种异常分层的设计效果，是在大型项目里最明显的。有一次线上查询超时，我扫一眼 Sentry 里的异常类名和分组，立刻知道是数据库层面的问题，而不用去翻几百条错误消息。这是企业级 PHP 系统里"异常类型即监控视图"的体现。

4.3 捕获与二次包装的最佳实践

接下来是一个很容易做错的关键环节：捕获异常后，什么时候应该直接抛、什么时候应该包装后抛？我的判断标准很简单：如果原始异常的类型和语义，对外层调用者来说仍然有意义的，就不要包装；如果外层调用者需要的是更高层次的业务语义，就必须包装。

举一个实际例子。你在一个 Service 方法里调用了 HTTP 客户端：

<?php public function fetchUserProfile(int $userId): array { try { $response = $this->httpClient->get("/users/{$userId}"); } catch (ConnectException $e) { throw new ExternalServiceException( '用户服务暂时不可用', ['user_id' => $userId], 0, $e ); } ... }

这里我要求必须把ConnectException包装成ExternalServiceException。因为 Controller 层或者调用方不需要知道底层用的是 Guzzle、curl 还是其他什么客户端，它们只关心"用户服务挂了"。如果不包装，底层库的异常类型就泄漏到了上层，一旦换掉 HTTP 客户端，所有 catch 这个底层异常的地方都要改，非常脆弱。

与之相对，如果你在 Config 读取阶段发现一个配置项缺失，MissingConfigException本身就是语义清晰的异常类型，不应该再包一层什么RuntimeException，直接让它往上冒泡即可。归根到底，包装的目的不是制造更多 catch 块，而是让每一层代码只依赖它真正关心的抽象。

5. 还有几个很多人没认真对待的异常处理细节

如果上面这些你都理解了，下面这几个细节可以说是"老手和新手的区别"所在。每一个都是我实际踩过坑之后才总结出来的。

5.1 catch 顺序的问题：先小后大

前面举了一个 catch 两块异常的例子，但实际项目里异常继承关系可能更深，catch 的顺序如果不注意，就会出现"子类异常永远捕获不到"的坑。

<?php try { // do something } catch (\Exception $e) { // 所有异常都走这里 } catch (ExportException $e) { // 永远不可能执行到这里 }

PHP 是按顺序匹配 catch 块的，一旦第一个 catch 能匹配上某个异常，后续的 catch 就不会再检查。所以规则是：子类异常在前，父类异常在后，最宽泛的兜底异常放最后。这个顺序错了，代码不报错，但行为完全是错的。

5.2 finally 块里不要再抛异常

这是我见过很多团队都踩过的一个坑。有些人喜欢在 finally 里做资源清理，然后在清理过程中抛异常。比如：

<?php try { // 业务逻辑 } finally { $file->close(); // 如果 close 失败抛了异常 }

问题在于：如果 try 块里已经抛了一个异常，此时 finally 里又抛了一个新异常，PHP 会用新异常覆盖掉原来的异常，原始异常和它的完整调用链就彻底丢失了。这等于把最有价值的排查线索给扔了。

正确做法：finally 里的清理操作尽量用最稳妥的方式，如果确实可能失败，就自己再包一层 try...catch 记日志，不要让它往外抛。

5.3 日志记录时的异常上下文与数据脱敏

把 context 放进异常对象固然好，但直接记录有时会翻车。比如 context 里带了用户的身份证号、银行卡号，或者用户密码的哈希，这些内容写入日志后就是安全事故。所以我的规范是：在 Context 里永远不放置敏感字段。如果确实要记录用户标识，记录 user_id 就够了，具体手机号之类需要时再去查。

另外，有一些框架会自动把异常对象转成数组或者 JSON 时调用getContext()，如果所有异常都统一使用这个接口，只要构建 context 的人注意规则，整个日志体系就都是安全的。

5.4 吞异常：比不处理更危险的"处理"

最后要强调一个极其常见的坏习惯——空 catch。我在 Code Review 的时候最怕看到这种代码：

<?php try { // ... } catch (\Exception $e) { // 忽略 }

这行注释比没有注释更可怕。你为了不让程序中断，把异常吞掉了，但异常的真正后果是数据不一致、状态错乱、后续逻辑拿着错误的数据运行，最后以更隐蔽的方式爆炸。如果实在要吞，也必须做两件事：一是记录日志，让异常至少留下痕迹；二是明确注释为什么这里可以吞掉异常，给出业务上的正当理由。

6. 测试与最终落地：保证异常体系长期不出问题

在写代码层面，异常定义得再好，如果不配合测试，时间一久还是会变质。我在团队里推行过一套针对异常体系的测试方式，这里分享一些核心思路。

6.1 异常类的单元测试主要测什么

自定义异常类的单元测试，不只是跑一下构造函数看能不能 new 出来。更重要的验证点是序列化与日志输出行为。

<?php public function testExceptionContextAndToString(): void { $exception = new ExportException( '导出失败，目标目录不可写', ['dir' => '/tmp/reports', 'user_id' => 123] ); $this->assertSame('导出失败，目标目录不可写', $exception->getMessage()); $this->assertSame(['dir' => '/tmp/reports', 'user_id' => 123], $exception->getContext()); $string = (string) $exception; $this->assertStringContainsString('EXPORT_ERROR', $string); $this->assertStringContainsString('/tmp/reports', $string); }

这类测试看起来很基础，但它可以防止以后有人重构异常类时，把__toString()里的 context 输出搞丢，也可以防止构造函数参数顺序变化导致调用方没跟上。一个异常体系长期可控，靠的就是这些基础测试守着。

6.2 在集成测试里验证异常路由

如果你用了 Symfony 或者 Laravel 这类框架，通常会有异常监听器或者异常渲染器。这部分也需要测试：比如抛出一个PermissionDeniedException，看最终 HTTP 响应是不是 403，body 是不是符合约定的 JSON 结构。

这类集成测试的收益有两个：一个是确保异常到用户响应之间的映射稳定，不会因为某个中间件顺序调整而失效；另一个是保证异常体系里的错误码能被前端正确识别，避免前后端联调时才发现消息格式对不上。

6.3 上线之后的长期维护策略

最后说一个很多团队容易忽略的问题：异常体系是会膨胀的。半年之后，项目里的异常类可能从 10 个涨到 50 个，其中有相当一部分可能是重复的，只是命名不同，比如UserNotFoundInCacheException和CacheUserMissException。这时候怎么办？我的建议是：定期做异常类的审查，就像做数据库表结构审查一样。

可以借助 IDE 的"Find Usages"功能，筛选出那些从未被捕获、从未被明确抛出的异常类，该合并的合并、该删除的删除。异常类的命名也尽量形成团队约定：通过"动词/形容词 + 主语 + Exception"的格式，一眼就能看出这是什么问题，比如CannotCancelPaidOrderException就比OrderException好得多。

我不是说团队必须把异常类当成正式产品来维护，但它在后端系统里承担的职责，确实接近于一份活的架构文档——每当你看到一个新的异常类出现，就说明系统里又新增了一种必须被识别的失败场景。维护好这份文档，整个团队都会因此受益。