1. 从一次支付重构说起接口到底解决了什么先说个真实场景。我之前维护过一套电商系统订单模块里写死了各种支付方式的调用逻辑。一开始只有支付宝代码长这样class OrderService { public function pay($order, $amount) { $alipay new Alipay(); $result $alipay-pay($order[no], $amount); return $result; } }后来老板说要接入微信支付好我复制了一段代码。再后来要接银行卡支付我又复制了一段。半年之后OrderService里堆了三百多行代码每个支付方式的参数格式、返回值结构、异常处理全都不一样。订单模块开始耦合支付细节改一个支付通道订单逻辑跟着遭殃。这时候我意识到问题不在怎么写支付逻辑而在于订单根本不该知道支付方是谁。它只需要知道有一个东西能接收订单号、能接收金额、能返回一个支付结果。至于背后是支付宝还是微信订单模块不关心。这就是接口存在的意义——把你要什么和谁来做彻底拆开。如果你也遇到过类似的问题比如代码里全是if ($payType alipay)的分支或者每次新增渠道都要去改老方法那这篇内容就是为你准备的。我会从一个具体的interface PaymentService出发把 PHP 接口的语法、设计思路、落地方式全部拆开讲一遍包括那些文档里不常写、踩过坑才知道的细节。提示这篇文章假设你已经有基本的 PHP 语法基础至少知道类、方法、继承是怎么回事。如果你是刚接触面向对象的小白我先用一句话给你定个调接口就是一份合同它只规定签合同的人必须提供哪些能力完全不关心对方怎么实现。2. 接口的语法拆解interface PaymentService 的每个部分2.1 interface 关键字与命名规范先看最基础的写法interface PaymentService { public function pay(string $orderNo, float $amount): bool; }interface是关键字表示声明一个接口。PaymentService是接口名按照 PHP 社区通行的规范接口名通常以名词或名词短语命名能直接表达它的职责。像PaymentService、UserRepository、LoggerInterface都是常见风格。有些团队习惯在接口名上挂Interface后缀比如PaymentServiceInterface也有团队不加这取决于你的框架或团队约定没有绝对的对错。我个人的倾向是在框架无关的领域层直接叫PaymentService更干净因为实现类已经可以命名为AlipayPaymentService名字上已经能区分接口和实现不必多一个后缀。接口里声明的方法不能有方法体函数体的大括号都不允许出现。它只规定长什么样不规定怎么干。这就像一个餐厅招聘信息写着需要一名厨师能做宫保鸡丁但不会在招聘启事里告诉你鸡肉要怎么切、花生米要怎么炸。2.2 接口里能放什么方法签名与常量接口里能放两类东西方法声明和常量。先看方法interface PaymentService { public function pay(string $orderNo, float $amount): bool; public function refund(string $orderNo, float $amount): bool; }方法声明有几个硬性要求我当年踩坑总结出来的接口中的方法必须声明为public写protected或private直接报致命错误。参数类型和返回类型可以在接口中先行约定。PHP 7.0 之后支持标量类型声明7.1 之后支持?type可空类型8.0 之后支持联合类型和mixed。接口中写了什么类型实现类必须严格匹配或使用更宽泛的类型这个细节后面第 5 章我会专门讲。接口不能声明属性。private $config这种东西在接口里是禁止的因为接口只约行为不管状态。如果你发现自己在接口里想写属性多半是设计思路出了问题——把实现类特有的状态拿出来会造成不合理的耦合。常量是接口的另一个合法成员interface PaymentService { public const STATUS_PENDING pending; public const STATUS_SUCCESS success; public function pay(string $orderNo, float $amount): bool; }接口常量建议少用因为它会被所有实现类共享语义上容易被滥用。我见过有的项目把错误码堆在接口里结果实现类之间互相引用这些常量接口反而变成了一个杂物间。真正需要公共常量的场景独立放到专门的类里更清晰。2.3 接口方法与实现类的方法签名约束这一节值得单独强调因为它是最容易出错的点。PHP 对接口方法的签名有逆变参数、协变返回的规则翻译成大白话就是参数类型实现类可以放宽但不能收紧。返回类型实现类可以更具体但不能更抽象。代码说明最直观。接口这样定义interface PaymentService { public function pay(string $orderNo, float $amount): bool; }下面这种实现在 PHP 8.0 是合法的参数类型从string放宽为string|int联合类型class AlipayPaymentService implements PaymentService { public function pay(string|int $orderNo, float $amount): bool { // ... } }但下面这种是致命错误因为参数从string收窄成了int不满足契约class AlipayPaymentService implements PaymentService { public function pay(int $orderNo, float $amount): bool { // Fatal error } }返回类型同理。接口返回bool实现类也能返回bool这是等价的。接口返回一个父类PaymentResult实现类返回子类AlipayPaymentResult是被允许的协变返回反过来会报错。这个规则看起来枯燥但它保护的是调用方。接口是给外部看的合同外部按接口的签名来调用实现类只能在这个基础上做兼容性的变化不能突然跟外部说我不认这个参数了。你写支付接口时如果遇到Fatal error: Declaration of ... must be compatible with ...绝大多数情况下就是这里出了偏差。3. 接口的扩展规则继承、多实现与多态3.1 接口可以继承接口接口与接口之间可以建立继承关系用extends关键字interface RefundablePaymentService extends PaymentService { public function refund(string $orderNo, float $amount): bool; }这样RefundablePaymentService就包含了PaymentService的pay方法同时又加了自己的refund。任何类实现RefundablePaymentService时两个方法都得实现。注意接口继承用的是extends而不是implements。一个接口可以同时继承多个接口用逗号分隔interface OnlinePaymentService extends PaymentService, RefundableService { }这个特性在业务上的意义很大。支付场景里有些渠道支持退款有些不支持。你可以在接口层面就把能力边界画出来。调用方根据自己的业务需求选择依赖PaymentService还是RefundablePaymentService而不是把所有能力塞进一个大接口里逼所有实现类空实现。3.2 一个类可以实现多个接口PHP 是单继承语言一个类只能继承一个父类但可以实现多个接口。这个设计非常有价值。比如我的支付服务除了要实现支付能力还要满足日志、风控上报等需求可以这样写class WechatPaymentService implements PaymentService, LoggableInterface, RiskReportableInterface { public function pay(string $orderNo, float $amount): bool { // 实现支付 } public function log(string $message): void { // 实现日志 } public function report(array $riskData): void { // 实现风控上报 } }我用一个生活化的类比来解释现实世界的能力是多维的。一个人可以同时是能编程的程序员和会讲段子的喜剧演员接口在这个意义上就是能力标签。类通过implements往自己身上贴标签外部代码只关心它需要的那张标签。但这里有一个设计上的提醒接口不要设计得过于胖。如果一个接口有七八个方法而你的某个实现类只能实现其中四个剩下三个只能抛异常或者返回 null说明接口粒度有问题。我处理支付接口时的一条经验是接口的方法控制在 2 到 4 个之间超过 5 个就考虑拆接口。你宁可有三个小接口也不要有一个又大又全的接口。3.3 接口与抽象类边界在哪里PHP 里abstract class和interface是两类不同的工具它们的边界经常被混淆我用几句话帮你理清接口只约定能做什么完全不管状态是什么。抽象类可以定义属性、构造函数、具体方法并且允许部分方法没有实现。一个类可以实现多个接口但只能继承一个抽象类。抽象类适合有公共默认行为的场景接口适合只要有契约、没有共享代码的场景。还是拿支付举例。支付宝和微信的支付请求参数不同、签名算法不同但都有一套公共的逻辑记录日志、校验订单状态、发送通知。这种公共逻辑放哪里我的选择是定义一个抽象基类AbstractPaymentService implements PaymentService在抽象类里写好公共的模板方法把支付动作留给子类实现。这实际上是模板方法模式的应用。abstract class AbstractPaymentService implements PaymentService { public function pay(string $orderNo, float $amount): bool { $this-logStart($orderNo, $amount); $result $this-doPay($orderNo, $amount); $this-notify($orderNo, $result); return $result; } abstract protected function doPay(string $orderNo, float $amount): bool; private function logStart(string $orderNo, float $amount): void { // 公共日志逻辑 } private function notify(string $orderNo, bool $result): void { // 公共通知逻辑 } }这种组合方式很实用。对外外部代码通过PaymentService接口来调用感知不到抽象类的存在对内实现类复用底层的公共逻辑少写很多重复代码。接口负责立约抽象类负责提供公共能力设计上各司其职。4. PaymentService 实战设计从接口到完整支付链路4.1 先定义接口把业务语言翻译成代码合同回到我们最初的问题。假设你要重新设计一个支持多渠道支付的模块第一步不要写任何实现先把接口定义出来。这个步骤是在回答一个问题调用方到底需要支付服务提供什么能力以我的经验支付场景的调用方通常需要这些能力发起支付给订单号、金额、支付参数返回一个支付凭据。查询支付状态给订单号返回当前状态。处理退款给原订单号、退款金额返回退款结果。对应接口interface PaymentService { public function createPayment(string $orderNo, float $amount, array $options []): PaymentResult; public function queryPayment(string $orderNo): PaymentStatus; }这里我额外说明两个小细节。第一返回值为什么是一个对象PaymentResult/PaymentStatus而不是简单类型这是我从实践中总结的教训支付结果里通常不止一个字段——支付凭据、渠道流水号、状态码、消息文本如果你返回数组调用方每用一次就得自己查一次数组里到底有哪些键一旦拼错一个键名问题排查很痛苦。用对象封装之后字段有明确的类型约束和 IDE 补全调用方几乎不可能拼错。这也正是热搜词里php接口数组对象这个方向的核心接口的返回值约定比接口本身更值得认真设计。第二参数里那个array $options []是我故意留的逃逸口。不同支付渠道总有一些特殊参数比如支付宝的qr_pay_mode、微信的openid。如果在接口层面把这些差异参数全部写死成具名参数接口就会膨胀。一个options数组让扩展变得灵活当然它的代价是弱类型所以需要在实现类里做校验和默认值兜底。4.2 实现类怎么写支付宝、微信、银行卡三种风格接口定义好之后实现类就可以各显神通了。下面给两个典型的实现类示例。class AlipayPaymentService implements PaymentService { public function createPayment(string $orderNo, float $amount, array $options []): PaymentResult { // 组装支付宝请求参数 $params [ out_trade_no $orderNo, total_amount $amount, subject $options[subject] ?? 默认商品, ]; // 调用支付宝 SDK 或 HTTP API // $response $this-alipayClient-execute($params); // 返回统一结构 return new PaymentResult( orderNo: $orderNo, channel: alipay, status: PaymentStatus::PENDING, credential: $response[qr_code] ?? , raw: $response, ); } public function queryPayment(string $orderNo): PaymentStatus { // 查询支付宝订单状态 } }class WechatPaymentService implements PaymentService { public function createPayment(string $orderNo, float $amount, array $options []): PaymentResult { $params [ out_trade_no $orderNo, total_fee (int) round($amount * 100), // 微信支付单位是分 openid $options[openid] ?? , ]; // 调用微信支付 API return new PaymentResult( orderNo: $orderNo, channel: wechat, status: PaymentStatus::PENDING, credential: $prepayId ?? , raw: $response, ); } public function queryPayment(string $orderNo): PaymentStatus { // 查询微信订单状态 } }注意到没有两边的方法签名一模一样返回的都是PaymentResult但内部逻辑完全不同。支付宝要组装subject微信要算total_fee金额单位是分还涉及浮点数四舍五入的坑这些细节全部被封装在各自的实现类里。调用方拿到接口之后根本不需要关心今天是支付宝还是微信。4.3 依赖注入与容器接口怎么被用起来接口定义好了实现类也写了接下来要解决一个问题:代码里到底怎么拿到那个实现类最原始的方式是new$service new AlipayPaymentService();但这种方式违背了接口设计的初衷——调用方又回到了必须知道具体类的老路上。真正要做的是依赖注入。你不需要自己new而是由框架或容器把合适的实现类送到你的构造函数里。class OrderService { public function __construct( private PaymentService $paymentService, ) { } public function checkout(string $orderNo, float $amount): void { $result $this-paymentService-createPayment($orderNo, $amount); // 处理 $result } }OrderService构造函数要求一个PaymentService类型的参数。不管你用的是 Laravel、ThinkPHP、Symfony 还是纯手写的简易容器它会在实例化OrderService时自动查一下容器里绑定的 PaymentService 是哪个实现类然后注入进来。容器绑定一般长这样以 Laravel 为例// 在 ServiceProvider 里绑定 $this-app-bind(PaymentService::class, function ($app) { $channel config(payment.default_channel); return match ($channel) { alipay new AlipayPaymentService(), wechat new WechatPaymentService(), default throw new RuntimeException(Unsupported channel: {$channel}), }; });这种情况下OrderService甚至不需要知道自己会被注入哪个支付渠道。改一个配置项整个系统的支付渠道就换了订单模块一行代码都不用动。这就是接口 容器带来的可替换性。4.4 返回结果对象的设计告别裸数组前面提到接口返回对象而不是数组这里我把返回对象的设计展开讲一下。先看一个反面案例。假设接口的返回值约定是数组public function createPayment(string $orderNo, float $amount): array;调用方写代码时就要靠猜$result $paymentService-createPayment(20240001, 100.0); $qrCode $result[qr_code] ?? $result[credential] ?? $result[code] ?? ;这三个键名到底哪个对没人说得清。这就是数组作为公共接口返回值的最大问题——键名没有任何约束力。你把这个数组从支付宝实现类里丢出去微信实现类可能给你返回结构完全不同的数组调用方为了兼容只能写一堆isset判断代码难看且脆弱。我的做法是定义一个不可变的结果对象class PaymentResult { public function __construct( public readonly string $orderNo, public readonly string $channel, public readonly PaymentStatus $status, public readonly string $credential, public readonly array $raw [], ) { } }再用一个枚举表示状态PHP 8.1enum PaymentStatus: string { case PENDING pending; case SUCCESS success; case FAILED failed; }调用方拿到的就是强类型、结构稳定的对象。$result-credential是字符串$result-status是PaymentStatus枚举IDE 能自动补全拼写错误在编译期就能暴露。这才是接口设计真正应该达到的效果合同不只是约束方法名和参数连返回结构也一并锁死这才叫完整的契约。5. 常见错误与排查技巧实录接口开发踩坑清单接口代码写起来不算难但真正生产环境跑起来问题五花八门。下面这几类是我在项目中碰到的典型问题整理成一张排查表路过坑的可以对照自查。5.1 声明不兼容方法签名必须匹配PHP 是弱类型语言但接口在这点上非常较真。最常见的报错是Fatal error: Declaration of WechatPaymentService::createPayment(string $orderNo, string $amount, array $options []): PaymentResult must be compatible with PaymentService::createPayment(string $orderNo, float $amount, array $options []): PaymentResult我在实际项目中见过一个特别典型的案例有人把微信支付实现类的金额参数写成了string $amount因为微信接口的金额参数确实可能是字符串。这一改直接报 Fatal error。看似差不多但 PHP 的类型检查不会给你通融——string和float之间参数类型收窄了。排查策略很简单打开报错信息对着接口定义逐行比对参数类型、返回类型。尤其是参数名虽然 PHP 8.0 之前参数名不一致不报错但从 8.0 开始命名参数机制上线后参数名不一致可能导致调用端的命名参数失效所以接口里定义了什么参数名实现类最好保持一致这是最稳妥的做法。5.2implements写漏或写错少了implements PaymentService你的类就算长得再像接口的实现容器也无法把它当作PaymentService注入。这种错误不会立刻报 Fatal error而是会在运行时出现TypeError: OrderService::__construct(): Argument #1 ($paymentService) must be of type PaymentService, AlipayPaymentService given注意这个报错它不是说没有实现而是说类型不匹配。如果你把代码里class AlipayPaymentService仔细看一遍发现它没有implements PaymentService那一刻就会恍然大悟。排查建议写实现类时先写implements再写方法而不是写完所有方法才想起来补。这也是我在新人 code review 里反复强调的一个习惯——把契约挂在类声明上比方法里碰巧实现了接口方法要可靠得多。5.3 接口开发中最容易忽略的返回值问题接口方法签名写的是PaymentResult实现类却因为某个分支返回了null这在严格模式下会直接抛TypeError。很多新人写接口实现时只关注正常路径忘了处理异常路径。我的建议是接口设计阶段就要考虑失败时怎么办。两种思路方法声明返回可空类型?PaymentResult允许返回 null调用方拿到 null 自行处理。方法始终抛异常调用方用 try/catch 包住。我个人的偏好是第二种。理由很简单接口的返回类型一旦写死为PaymentResult调用方就能放心地通过$result-status访问状态不用每行都判断if ($result null)。支付失败属于非正常流程用异常机制表达更合适而不是通过返回 null 来表达。5.4 HTTP 接口、JSONP 和 PHP interface 别搞混最后额外说一个很容易被搜索引擎误导的点。聊 PHP 接口的时候很多人搜到的是接口数组对象跨域 JSONPaxios 接口对接这类文章它们说的接口是 HTTP API也就是 URL、请求参数、响应 JSON 那一套完全不是interface关键字。咱们这篇文章聊的是面向对象层面的接口两者虽然都叫接口但层级差了十万八千里。如何区分一句话就够了HTTP API 是系统与系统之间的通信协议interface是代码内部的对象协作契约。它们确实有关联——一个 HTTP API 的响应结构往往会用 PHP 接口的返回对象来封装就像我在第 4.2 节里把支付渠道第三方 HTTP API 的响应包进了PaymentResult一样。但开发时不要混淆先规划代码内的interface再去对接外部 HTTP API顺序反了你就会陷入为了对接口而改接口的被动局面。5.5 系列化的坑接口实现类里的属性可见性还有一个常被忽略的细节接口约定了方法但没有约定属性。很多人在写实现类时喜欢把配置项写进构造函数class AlipayPaymentService implements PaymentService { public function __construct( private array $config, ) { } }这没有问题属性是private的对调用方完全隐藏。但有人会手滑把属性写成public等于把内部状态暴露给了调用方一不小心就破坏了封装性。这是一种设计层面的污染——接口没有限制属性可见性但实现类自己应该意识到接口边界之外暴露的成员越多日后重构的阻力就越大。保持接口即门面的纪律感实现类的内部状态越干净代码就越容易维护。6. 总结一下我在实战中的几个体会写了这么多年 PHP我越来越觉得接口是面向对象设计里最被低估的一个特性。它不像设计模式那样听着高大上也不像框架源码那样充满炫技感但它决定了你的代码是水泥糊出来的还是零件组装起来的。interface PaymentService这样一个看起来平平无奇的定义背后承载的是整个业务模块的扩展边界。给你几个落地建议都是我实际踩坑换来的第一接口设计先于实现类写。你在一个新功能里发现自己要写class XxxService先停下来想想它的方法列表是什么把它提炼成接口。哪怕你目前只有一个实现类接口的规范性也会逼你思考调用方到底需要什么。第二不要为了接口而接口。如果一个类只有一个实现、短期内不会有第二个实现接口可以先不抽。过度设计同样是技术债等出现真实的变更多实现需求时再抽取成本并不高。第三接口一旦对外发布修改要谨慎。你定义的PaymentService如果被多个业务模块依赖改接口签名就是牵一发动全身。真要变更优先新增一个子接口或者新增方法而不是改老方法的签名。在写这篇文章的过程中我把当年那个订单模块重构成了基于接口的版本运行方式和预期完全一致。每次新增支付渠道只需要新增一个实现类在容器注册一下订单模块一行都不用动。那种解牛的快感你试过就知道。
