企业官网建设流程全解析

如果把 ThinkPHP 8 当成"ThinkPHP 6 加几个新语法"来用，大概率会在第一次代码评审时被打回。真正让 TP8 和上一代拉开距离的，不是某个新方法，而是它把PSR 标准摆到了台面上：容器认 PSR-11，日志认 PSR-3，缓存认 PSR-16，自动加载走 PSR-4，编码风格对齐 PSR-12。这些接口看起来只是几个use语句的差别，实际决定了你的代码能不能被替换、被测试、被复用。这篇内容面向已经会用 TP 写增删改查、但写出来的代码总感觉"黏在框架上"的开发者，也适合刚接手一个 TP8 项目、想先把地基摸清楚的人。我会把 PSR 在 TP8 里到底落地在哪几个位置、哪些地方只是"长得像"其实并不是标准实现、以及分层、注入、事务、类型声明这些最佳实践该怎么落到具体文件上，一条条拆开讲。

1. 从一次代码评审被打回说起：TP8 的底层规矩变在哪

几年前帮一个团队看代码，某个接口类里塞了Db::name('order')->where(...)、Cache::get()、Log::info()三种静态调用，方法体一百二十行，中间还夹着两次halt()。这段代码在 TP5 时代是"正常水平"，放到 TP8 的项目里就成了典型反例。不是写法变难了，而是 TP8 所依托的生态把"可替换性"当成了默认要求，静态调用把依赖固化在类内部，替换和测试都无从下手。

1.1 PHP 8 作为硬门槛带来的连锁反应

TP8 的最低运行要求是 PHP 8.0，这条约束带来的变化远不止"能跑就行"。PHP 8.0 引入的构造器属性提升、命名参数、联合类型、match表达式、空安全运算符，直接改变了框架内部类的写法，也改变了你写业务类的习惯。举个最直观的例子：过去写一个服务类，构造函数里一堆$this->x = $x的赋值样板，现在可以直接在构造参数上加可见性修饰符，属性声明和赋值一步完成。

<?php declare(strict_types=1); namespace app\common\service; use app\common\repository\OrderRepository; use Psr\Log\LoggerInterface; final class OrderService { public function __construct( private OrderRepository $repository, private LoggerInterface $logger, ) { } public function detail(int $orderId): array { $order = $this->repository->findById($orderId); if ($order === null) { $this->logger->warning('order not found', ['id' => $orderId]); throw new \RuntimeException('订单不存在'); } return $order; } }

这段代码里有两个关键点值得注意。第一是declare(strict_types=1)，它让类型声明从"尽量转换"变成"严格比对"，传"123"给int $orderId会直接抛TypeError，而不是悄悄转成 123。第二是构造器属性提升，属性声明、参数接收、赋值三件事合并成一行，减少了样板也减少了漏赋值的可能。

这里有个容易踩的细节：readonly修饰符是 PHP 8.1 才有的，enum也是 8.1。如果你的部署环境还停在 8.0，写private readonly会直接语法错误。我在一个项目里就遇到过本地 8.2 跑得好好的，测试环境 8.0 一部署全线崩的情况，报错信息还很隐晦。判断方式很简单，跑一句php -v，或者在composer.json里把"php": ">=8.0"写死，让 Composer 在安装阶段就拦住不匹配的环境。

1.2 容器、日志、缓存这三处的 PSR 落地位置

TP8 里真正"原生对接"PSR 接口的地方，主要集中在三处，这三处也是最值得你主动去用接口类型而不是具体类的地方。

表格里"类型提示该写什么"这一列是重点。你在构造函数里写LoggerInterface $logger，容器会自动解析并注入框架的日志实例；写Log $logger也能跑，但从此你的类就和 TP 的日志实现绑死了，单元测试时想塞一个把日志写进内存的假对象都做不到。

我在实际项目里做过一次对比：一个二十多个类的模块，日志全部用LoggerInterface注入的版本，写单元测试时用匿名类实现接口、把日志收集到数组里断言，一个测试文件三十行搞定；而另一批用Log::info()静态调用的，只能靠Log::close()加临时文件重定向来验证，跑一次测试留下十几个临时文件。这个差距在项目后期会指数级放大。

1.3 长得像但并不是标准实现的三处，别混淆

这一节是我认为整篇里最容易被忽略、也最容易出事故的部分。PSR 有一整套编号，但不是每个编号 TP8 都完整实现了。把"设计思路相似"当成"接口兼容"，会在需要接入第三方包时吃大亏。

第一处是中间件。TP8 的中间件接口是think\MiddlewareInterface，方法签名是handle($request, \Closure $next)。而 PSR-15 的MiddlewareInterface要求的是process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface。两者思路一致，都是洋葱模型，但类型完全不同，一个 PSR-15 的中间件包不能直接扔进 TP8 的middleware.php里用，必须写一层适配。

第二处是 HTTP 消息对象。think\Request和think\Response不是 PSR-7 的ServerRequestInterface和ResponseInterface实现。这意味着那些依赖 PSR-7 的第三方组件，比如某些 HTTP 客户端中间件、某些 OpenAPI 生成器，没法直接接收 TP 的请求对象。常见的做法是在边界处做一次转换，把需要的信息抽成数组或自定义 DTO 传进去。

第三处是事件。TP8 有think\Event，注册和监听都挺顺手，但它没有实现 PSR-14 的EventDispatcherInterface。如果你打算引入一个基于 PSR-14 的第三方事件库，两边的事件总线是需要桥接的。

注意：判断一个包能不能"直接"用，看它的composer.json里的require段最准。如果它要求psr/http-message，那基本可以确定它期望的是 PSR-7 对象，别指望把think\Request直接传进去。

把这些边界搞清楚，后面的分层、注入、测试才有意义。很多人觉得 PSR 是"教条"，其实它解决的就是"我这段代码能不能换个环境继续用"这个非常实际的问题。

2. 骨架与自动加载：命名空间映射错一步，后面全是白费

项目初始化这一步看着最没技术含量，恰恰是后面所有问题的源头。我见过不止一个项目，app目录下的命名空间和 Composer 的autoload配置对不上，本地因为缓存文件还在跑得好好的，换台机器composer install之后满屏Class not found。这类问题排查起来极其费时，因为报错位置和真实原因隔了好几层。

2.1 composer.json 里 autoload 段的真实含义

TP8 的项目骨架里，composer.json的autoload段通常是这个形状：

{ "autoload": { "psr-4": { "app\\": "app" }, "files": [], "classmap": [] } }

psr-4这一行的意思要拆开理解：键app\\是命名空间前缀，值app是相对项目根目录的路径。合起来就是——任何以app\开头的类名，去掉这个前缀后，剩余部分按反斜杠转成目录分隔符，再拼上.php，就是文件的物理路径。所以app\common\service\OrderService对应的文件是app/common/service/OrderService.php。

这里有两个高频错误。一是大小写。PSR-4 是大小写敏感的规范，虽然 PHP 的类名本身不区分大小写，但文件系统在 Linux 上是区分的。类名写OrderService、文件名写成orderservice.php，在本地 Windows 或 macOS 的默认文件系统上照样能加载，一上 Linux 服务器就找不到文件。这个问题在团队协作里特别隐蔽，因为出问题的人往往不是写错的人。

二是目录层级和命名空间不能多也不能少。有人在app下新建了app/service/order/OrderService.php，命名空间写成app\service\OrderService，少了一层order目录。Composer 按命名空间去找app/service/OrderService.php，文件不在那儿，直接失败。

修改autoload段之后，必须执行一次composer dump-autoload重新生成映射表。开发阶段建议加-o参数生成优化过的类映射，加载更快；但如果频繁增删文件，优化后的映射不会自动更新，反而会造成"新加的类找不到"，这时候去掉-o或者重新 dump 一次即可。这个问题我在调试时踩过，明明文件在那儿、命名空间也对，就是不认，折腾了快半小时才想起来映射表是旧的。

2.2 多应用模式下的命名空间映射该怎么配

TP8 默认是单应用结构，app目录下直接放controller、model这些。要用多应用模式，得先装topthink/think-multi-app，装完之后目录变成app/admin、app/api这样的结构，每个应用下再有自己的controller、model。

这里的关键是命名空间要跟着变。app/admin/controller/User.php的命名空间是app\admin\controller，而不是app\controller。如果从单应用迁移到多应用，最容易漏改的就是各类use语句和容器绑定里的类名，报错信息通常只说"类不存在"，不会告诉你是因为命名空间多了一层。

多应用模式下还有一个配置项值得留意，就是应用映射和默认应用。如果只有一个应用需要被外部直接访问，可以在配置里指定默认应用，避免 URL 里必须带应用名。但这个配置改完之后，路由文件的位置也跟着变，从route/app.php变成各应用目录下的route子目录。我建议的做法是：先在单应用模式下把业务跑通，确认路由、中间件、容器绑定都没问题，再整体迁移到多应用，一次性改完命名空间和路由文件位置，别边写业务边迁移。

2.3 extend 目录和自建包之间的取舍

TP 骨架里有个extend目录，历史上是用来放第三方类库的。现在既然有 Composer，这个目录的地位就有点尴尬。我的建议很简单：只放"项目私有、不打算发布、也不打算被多个项目复用"的类，而且要在composer.json的autoload里显式注册，别依赖框架的自动扫描。

{ "autoload": { "psr-4": { "app\\": "app", "extend\\": "extend" } } }

真正需要跨项目复用的东西，老老实实做成私有包，通过 Composer 的仓库配置引入。好处是版本清晰、依赖明确、升级不会互相影响。把一堆工具类堆在extend里，短期省事，时间一长就变成没人敢动的黑盒——你不知道哪些方法还有人在调，删一行都可能引发线上问题。

还有一个现实问题：extend目录下的类如果没走 PSR-4 注册，而是靠框架的Loader加载，那它在composer dump-autoload -o之后的行为可能和预期不一致。这属于"能跑但脆"的写法，能不用就不用。

3. 容器与依赖注入：从 Facade 依赖走向可测试的构造器注入

门面（Facade）大概是 ThinkPHP 里争议最大的设计。它让Db::、Cache::、Log::这类调用写起来极其顺手，一个use think\facade\Db;就能在任何地方操作数据库。问题是顺手的地方往往也是失控的地方——你很难从类的签名上看出它依赖了什么，也很难在测试里替换掉它。

3.1 静态调用为什么会在项目后期变成负担

先看一段很常见的写法：

public function create(array $data) { Db::startTrans(); try { $id = Db::name('order')->insertGetId($data); Cache::delete('order_list'); Log::info('order created', ['id' => $id]); Db::commit(); return $id; } catch (\Throwable $e) { Db::rollback(); throw $e; } }

这段代码能跑，逻辑也不算错，但它把三样东西焊死在方法体里：数据库连接、缓存驱动、日志实现。带来的直接后果是，你想验证"订单创建失败时缓存是否被误删"这个分支，就必须准备一套真实的数据库和缓存环境，没法用假对象模拟。

还有一个更隐蔽的问题：静态调用让依赖关系隐形。新人接手时看这个方法的签名create(array $data)，完全看不出它会写数据库、会清缓存、会记日志。等到某天要把订单数据同步到别的地方，得把整个方法重新读一遍才知道从哪儿下手。

容器注入的思路是把这些依赖"提到台面上"：类的构造函数明确声明"我需要一个订单仓储、一个缓存、一个日志器"，运行的时候由容器负责把实例递进来。

final class OrderService { public function __construct( private OrderRepository $repository, private CacheInterface $cache, private LoggerInterface $logger, ) { } }

签名即文档，看构造函数就知道这个类会碰什么。测试时构造三个假对象传进去就行，不需要数据库。这就是从"能跑"到"可维护"的分界线。

3.2 绑定、解析与单例注册的正确姿势

TP8 的容器绑定配置集中在app/provider.php，这个文件返回一个数组，键是抽象（接口或类名），值是具体实现。

<?php // app/provider.php use app\common\contract\PaymentGateway; use app\common\service\AlipayGateway; use app\common\service\WechatGateway; return [ PaymentGateway::class => AlipayGateway::class, 'payment.wechat' => WechatGateway::class, ];

绑定之后，任何类的构造函数只要声明了PaymentGateway这个类型，容器就会自动实例化AlipayGateway递进去。这里要注意几点。

第一，接口绑定是必须显式写的。容器没法凭空知道一个接口该实例化成哪个类，不写绑定就会抛"无法解析"的异常。而具体类（非抽象、非接口）不需要绑定，容器能自己反射出来。

第二，默认是每次解析都新建实例。如果你的服务有状态、或者初始化成本高，需要在绑定时注册成单例。TP8 里可以用bind方法的第三个参数，或者在应用启动阶段通过容器实例调instance()注册。我在一个项目里遇到过连接池被反复重建的问题，根因就是把一个内部持有连接的类当普通类解析，每次注入都 new 一份。

第三，绑定的键名别用字符串魔法值。上面例子里的'payment.wechat'这种字符串键，用的时候也得写同样的字符串，拼错了不报错、只是解析出一个新实例。能用类名或接口名做键就用类名，IDE 还能帮你跳转和重命名。

容器解析的入口是app()辅助函数或者注入ContainerInterface。前者在框架内部随处可用，后者适合写在业务类里，让依赖更明确。

use Psr\Container\ContainerInterface; final class ReportBuilder { public function __construct(private ContainerInterface $container) { } public function build(): array { $exporter = $this->container->get(ExporterInterface::class); return $exporter->export(); } }

这种"服务定位器"模式不算优雅，但比重度静态调用好得多，至少在测试时能塞一个自定义容器进去。不过我还是建议：能用构造器注入解决的，就别用容器去get，依赖声明显式化永远是第一选择。

3.3 属性注入和服务提供者的使用边界

TP8 支持基于 PHP 属性的注解注入，比如在属性上加标记让容器自动填值。这类写法在控制器里特别省事：

use think\annotation\Inject; class OrderController { #[Inject] protected OrderService $orderService; }

写起来很爽，但我对它的态度是"谨慎使用"，理由有三个。一是属性注入让依赖不在构造函数里，从签名上看不出这个类依赖了什么，可读性反而下降。二是注解解析依赖反射，在高频调用的类上有额外开销。三是注解包本身需要单独安装和配置，不同版本之间行为有差异，升级时容易出幺蛾子。

我个人的取舍标准是：控制器可以用属性注入，业务服务层一律构造器注入。控制器本身是薄薄一层、生命周期短、几乎不会被单元测试直接实例化，用注解省事划算；服务层是要被反复测试和复用的，依赖必须显式。

服务提供者（Service Provider）这个概念的边界也要说清楚。TP8 的app/provider.php只负责绑定，不负责"启动逻辑"。如果你有一些需要在应用启动时执行的操作，比如注册自定义验证规则、注册命令、加载配置，应该放在应用初始化阶段的事件或者app/common.php里，别硬塞进 provider。把绑定和启动混在一起，会导致容器初始化阶段就产生副作用，调试起来非常难受。

4. 分层落地：Controller 薄到什么程度，Service 厚到什么程度

"三层架构"这四个字被讲烂了，但真正落地时，"薄"和"厚"的标准往往靠感觉。我的判断标准很具体：Controller 只做四件事——接收参数、调用校验、调一次服务、返回响应。超过这四件事的任何一行代码，都应该往外挪。

4.1 一个增删改查接口的三层拆分实录

拿一个"创建订单"的接口举例。先看常见的写法：

public function store() { $data = $this->request->only(['user_id', 'items', 'remark']); if (empty($data['items'])) { return json(['code' => 400, 'msg' => '商品不能为空']); } Db::startTrans(); try { $orderNo = date('YmdHis') . mt_rand(1000, 9999); $id = Db::name('order')->insertGetId([ 'order_no' => $orderNo, 'user_id' => $data['user_id'], 'remark' => $data['remark'] ?? '', 'status' => 0, 'created_at' => date('Y-m-d H:i:s'), ]); foreach ($data['items'] as $item) { Db::name('order_item')->insert([ 'order_id' => $id, 'sku_id' => $item['sku_id'], 'qty' => $item['qty'], ]); } Db::commit(); } catch (\Throwable $e) { Db::rollback(); return json(['code' => 500, 'msg' => $e->getMessage()]); } return json(['code' => 0, 'data' => ['id' => $id]]); }

这段代码信息密度很高，但每一层职责都混在一起：参数提取、校验、订单号生成、数据落库、事务控制、错误响应全在一个方法里。想复用"创建订单"这个能力给命令行任务用，得把整个方法复制一遍。

拆开之后，Controller 会瘦成这样：

final class OrderController { public function __construct(private OrderService $service) { } public function store(CreateOrderRequest $request): Json { $dto = CreateOrderDto::fromRequest($request); $result = $this->service->create($dto); return json(['code' => 0, 'data' => $result]); } }

真正的业务逻辑在OrderService::create()，它对外只认一个 DTO 对象，不关心 HTTP 层怎么传进来的。这样一来，命令行、队列消费者、后台任务都能复用同一个入口，只要拼出一个 DTO 就行。

这里有个值得强调的点：服务的入参用 DTO 而不是裸数组。裸数组的问题是键名随意、类型不明确、IDE 无法提示，运行到一半才发现少传了一个字段。DTO 把这些约束前移了。

final class CreateOrderDto { public function __construct( public int $userId, public array $items, public string $remark = '', ) { } public static function fromRequest(Request $request): self { return new self( userId: (int) $request->param('user_id', 0), items: (array) $request->param('items', []), remark: (string) $request->param('remark', ''), ); } }

fromRequest这个静态方法是刻意写的边界：DTO 知道怎么从请求里取数据，Service 完全不知道请求长什么样。两边解耦之后，Service 换成从消息队列取数据，也不用改一行代码。

4.2 参数校验该放在哪一层

关于校验位置，社区里争论过很久，我的实践结论是分两层，各管各的。

第一层在入口，负责格式校验：字段在不在、类型对不对、长度有没有超、必填项是否为空。这层用框架自带的验证器或者 DTO 的构造期检查就够了，目的是快速失败，不让脏数据往下走。

第二层在服务内部，负责业务校验：订单金额是否超限、库存是否充足、用户是否有权限下单。这些规则需要查数据库、依赖其他上下文，天然属于服务层。

把两层混在一起的后果是：业务规则被写在验证器里，验证器变成第二个服务层，越来越臃肿；或者业务规则完全不校验，服务层拿到数据直接写库，出了事才发现脏数据早就进去了。

final class OrderService { public function create(CreateOrderDto $dto): array { if ($dto->items === []) { throw new BusinessException('订单至少包含一件商品', 40001); } $stock = $this->stockReader->available($dto->items); if (! $stock->sufficient()) { throw new BusinessException('库存不足', 40002); } // 后续落库 } }

这里抛的是业务异常，不是Exception也不是RuntimeException。自定义异常类的好处是能被全局异常处理器统一识别，转成固定的错误结构返回给前端。用RuntimeException搅在一起，最后只能靠字符串匹配来判断错误类型，非常脆弱。

4.3 事务边界为什么必须下沉到 Service 层

把startTrans/commit/rollback写在 Controller 里，是我见过最多的错误之一。原因很直接：Controller 只知道"我要调一次服务"，它不知道这次服务调用背后有几个写操作、哪几个必须原子。一旦业务扩展，比如在创建订单之后还要扣减库存、写积分流水，事务边界就得跟着改 Controller，而 Controller 本不该知道这些。

正确的做法是把事务开在 Service 方法里，用框架提供的事务封装：

public function create(CreateOrderDto $dto): array { return Db::transaction(function () use ($dto) { $orderId = $this->repository->insert($dto); $this->stockService->deduct($dto->items, $orderId); $this->pointService->grant($dto->userId, $orderId); return ['id' => $orderId]; }); }

Db::transaction()的好处是异常自动回滚、正常返回自动提交，不用手写 try-catch。但仍然有两个坑要注意。

坑一：事务里别做耗时操作。发短信、调外部接口、写文件，这些动作会让事务持续时间从毫秒级拉到秒级，数据库锁被长时间占用。我在一个项目里见过在事务里调外部支付接口的写法，高峰期直接把连接池打满。正确做法是用"事务提交后执行"的机制，或者把外部调用挪到事务外面，先落库再异步处理。

坑二：嵌套事务的行为要搞清楚。TP 的事务支持嵌套计数，内层transaction并不会真的开一个新的数据库事务，而是加一层计数，最外层提交才真正提交。这意味着内层即使抛异常、外层捕获了继续往下走，数据也不会回滚——因为它根本没有独立的事务边界。涉及多数据源或者必须独立回滚的场景，得显式指定连接，别指望默认行为。

5. 编码风格与类型系统：PSR-12 加严格类型的组合拳

编码风格这件事，团队里总有人说"能跑就行"。这话在小项目里成立，在多人协作、生命周期超过一年的项目里就站不住。风格不统一的直接成本是代码评审时间翻倍，间接成本是没人愿意重构，最后整个项目变成"能跑就别碰"的状态。

5.1 PSR-12 到底规定了什么，为什么值得遵守

PSR-12 是 PSR-2 的升级版，核心内容其实不多：缩进用四个空格、每行软限制一百二十字符、类的大括号另起一行、方法的大括号另起一行、控制结构的关键字后面必须有一个空格、use语句按字母排序分组、文件末尾留一个空行、只写<?php不写结束标签。

这些条款看着琐碎，价值在于消除无意义的争论。没有规范时，一个文件里可能同时存在两种缩进、三种括号风格，diff 里一半的行是格式调整，真正的逻辑改动淹没在里面。有了规范，配合代码格式化工具，格式问题在提交前就被自动修掉，评审时只看逻辑。

工具层面，PHP 生态里最常用的是 PHP-CS-Fixer 和 PHP_CodeSniffer。前者自动修复，后者只检查。我推荐的组合是：本地用 PHP-CS-Fixer 在保存时自动修复，CI 里用 PHP_CodeSniffer 做检查，不通过就拦下。配置文件里把规则集直接指向PSR12，别自己去拼规则。

// .php-cs-fixer.php 片段 $config = (new PhpCsFixer\Config()) ->setRules([ '@PSR12' => true, 'array_syntax' => ['syntax' => 'short'], 'ordered_imports' => ['sort_algorithm' => 'alpha'], 'no_unused_imports' => true, ]) ->setFinder( PhpCsFixer\Finder::create()->in(['app', 'config', 'route']) );

no_unused_imports和ordered_imports这两条特别值得加。前者自动清理没用到的use，后者保证导入顺序一致，多人同时改一个文件时冲突能少一大半。

5.2 严格类型声明带来的真实差异

declare(strict_types=1)这一行加在文件最顶部，影响的是这个文件里所有函数调用的参数类型检查模式。不加的时候，PHP 会做隐式转换：传字符串"5"给int参数，自动转成 5；加了之后，直接抛TypeError。

这个差异在实际项目里的价值，我用一个例子说明。某个计算金额的方法签名是function calc(int $cents): int，调用方从数据库读出来的字段是字符串类型（很多驱动默认返回字符串），不加严格模式时，PHP 悄悄转换，看起来一切正常；但这个字段如果是"12.5"这种带小数的字符串，转换会截断成 12，金额就这样少算了。加了严格模式之后，这类情况在第一行调用就炸出来，问题暴露得早得多。

需要澄清一个常见误解：严格模式是"调用方文件的声明决定行为"，不是"被调用方"。也就是说，A 文件声明了严格模式，A 调用 B 的方法时按严格模式检查；B 自己有没有声明，不影响 A 的调用。这个规则很多人搞反了，以为在被调用方加就行。

我的建议是把declare(strict_types=1)加在所有新写的文件上，尤其是app目录下的业务代码。从老项目迁移过来的部分可以暂缓，逐个文件改，避免一次性大面积改动引发连锁问题。

同样的思路适用于返回类型。给每个方法都写返回类型，包括void和array。没有返回类型时，一个方法可能返回null、返回false、返回空数组，调用方要写一堆防御性判断；有了明确的返回类型，约定就清楚了——要么返回数组，要么抛异常，不会是第三种。

5.3 枚举、联合类型在业务里的落点

PHP 8.1 的枚举（enum）在业务代码里非常有用，最典型的场景是状态字段。过去用常量：

class OrderStatus { const PENDING = 0; const PAID = 1; const SHIPPED = 2; }

问题在于这只是一堆整数，方法签名写int $status，谁都可以传 99 进去，编译器不管。换成 backed enum：

enum OrderStatus: int { case Pending = 0; case Paid = 1; case Shipped = 2; public function label(): string { return match ($this) { self::Pending => '待支付', self::Paid => '已支付', self::Shipped => '已发货', }; } }

方法签名可以写OrderStatus $status，传错类型直接报错。用match做分支，穷举性也是强制的——将来加了一个新状态，match里没覆盖到，运行时会抛UnhandledMatchError，比switch漏一个分支导致返回null好得多。

联合类型（int|string）要克制使用。它确实能表达"这两种都行"，但代价是每个使用点都要判断当前是哪种。业务代码里我更倾向于用两个方法或者一个 DTO，把类型不确定性挡在入口处，别让它扩散到核心逻辑。真需要联合类型的场景通常是底层工具类，比如一个 ID 生成器既能接受 int 也能接受字符串形式的 ID。

值得一提的是，readonly属性配合构造器属性提升，非常适合写 DTO 和值对象。一旦初始化就不能再改，避免了"对象传出去被某处偷偷改了一个字段"这种极难排查的问题。前提还是那句话，运行环境得是 PHP 8.1 以上。

6. 参照 PSR 视角回看的几个高频事故

下面这几个问题，都是我在实际项目里真实遇到或者帮别人定位过的，共同特点是：代码看着没毛病，报错信息指向的位置和真实原因隔着好几层。

6.1 日志注入写成具体类，测试替换失败

现象是单元测试跑起来之后，某个服务类的所有断言都失败，日志文件里多了一堆真实环境的记录，测试库里也被写入了数据。排查了半天，最后定位到服务类的构造函数写的是Log $logger而不是LoggerInterface $logger。

原因在于，容器解析Log这个具体类时，如果没有预先绑定，会自己反射构造一个新的实例，这个实例的配置和全局的日志配置不是同一份，行为也难以预测。更麻烦的是，这个新实例在测试里无法被替换成假对象，因为类型提示锁死了必须是think\log\Log的实例。

改成接口类型之后，容器会自动注入全局配置好的日志实例，测试时塞一个自己实现的假日志器就行：

final class ArrayLogger implements LoggerInterface { public array $records = []; public function log($level, $message, array $context = []): void { $this->records[] = compact('level', 'message', 'context'); } // 其余方法按接口实现，转调 log }

这个坑的教训是：凡是接口存在的依赖，类型提示就写接口，不写实现类。除了日志，缓存、容器、数据库连接、HTTP 客户端都是同理。

6.2 缓存接口选错，PSR-6 和 PSR-16 不是一回事

有一回同事引入了一个第三方包，它要求Psr\Cache\CacheItemPoolInterface，也就是 PSR-6。他直接把 TP 的think\Cache传进去，运行时报"类型不匹配"。原因在于 TP 实现的是 PSR-16，也就是Psr\SimpleCache\CacheInterface，两者的方法签名完全不同。

两者的区别可以用一句话概括：PSR-6 是"面向对象的缓存池"，你要先getItem()拿到一个 item 对象，判断isHit()，再set()回池子，最后save()；PSR-16 是"一堆简单方法"，直接get、set、delete，一行一个动作。

TP 的think\Cache走的是 PSR-16 路线，够用且简单。如果确实需要接 PSR-6 的包，得自己写一个适配器，把 PSR-6 的调用翻译成 PSR-16 的动作。写适配器的时候要注意过期时间的语义差异，PSR-6 用"绝对时间点或 null"，PSR-16 用"秒数或 DateInterval"，直接透传会导致缓存永不过期或者立刻过期。

6.3 中间件顺序和异常处理的相互影响

这个问题的表现是：接口在正常情况下返回正确的 JSON，出错时却返回一大段 HTML 错误页，前端解析失败。查日志发现异常确实抛出来了，但全局异常处理器没生效。

根因是中间件的注册顺序。TP8 的中间件是洋葱模型，注册在前面的在外层，异常会先被外层捕获。如果路由中间件在异常处理中间件的外层，那么路由阶段抛出的异常就绕过了异常处理器。而全局中间件配置在app/middleware.php，路由中间件写在路由定义或控制器注解上，两者的相对顺序需要看框架的合并逻辑，不是简单地"全局的就在外层"。

排查这类问题的思路是：先确认异常是在哪个阶段抛的（路由匹配、中间件、控制器、模型），再确认该阶段在洋葱模型的哪一层，最后检查异常处理中间件有没有包住它。实在理不清，可以在异常处理器里加一行日志，看看到底有没有进来。

我的经验做法是：把自己写的全局中间件分两类，一类是"必须在最外层"的（跨域、请求 ID 注入、统一异常处理），一类是"靠内层"的（鉴权、限流）。前一类通过配置里的优先级保证位置，别依赖默认顺序。异常处理器本身要写得足够健壮，能处理各种阶段抛出的异常，并且根据请求的Accept头决定返回 JSON 还是 HTML，别一刀切。

注意：调试中间件问题时，临时把中间件全部注释掉再一个个打开，比盯着配置文件猜快得多。这是最笨但最有效的办法。

这几个坑的共同点是，它们都不在"写代码"的层面，而在"理解框架和标准的边界"这个层面。PSR 存在的一部分意义，就是把这些边界用接口的形式写清楚，让你在拼接组件的时候能提前知道会不会有冲突。