简介

本指南面向高级开发者，系统化说明如何在 DouPHP 中开发“自定义服务提供者”。内容涵盖：

• 服务提供者的基类与抽象类的继承关系
• 接口定义、实现类与配置文件的编写规范
• 命名约定与目录结构规范
• 配置文件格式与参数校验规则
• 测试策略与单元测试方法
• 调试技巧与常见问题解决方案
• 实际示例（以支付插件 Provider 为例）
• 复杂场景的设计模式与最佳实践

项目结构

DouPHP 将“服务”与“提供者”分层组织：

• core/service：业务服务基类 BaseService，作为领域服务的统一入口。
• core/foundation/provider：平台能力提供者注册总线与具体 Provider（语言、插件、数据）。
• core/contract：跨端共享的契约（如 PluginServiceContract）。
• core/infra/plugin/contract：插件实现方契约（支付、连接、物流等）。
• plugin/*：第三方插件的具体实现（如支付宝 AlipayProvider）。

graph TB
subgraph "核心服务"
BS["BaseService<br/>服务基类"]
end
subgraph "基础能力提供者"
PR["ProviderRegistry<br/>注册总线"]
LSP["LanguageServiceProvider"]
PSP["PluginServiceProvider"]
DSP["DataServiceProvider"]
end
subgraph "插件契约层"
PPCI["PaymentPluginProviderInterface"]
RPPI["ReconcilablePaymentProviderInterface"]
PSC["PluginServiceContract"]
end
subgraph "插件实现"
ALP["AlipayProvider"]
end
PR --> LSP
PR --> PSP
PR --> DSP
BSP["业务调用方"] --> BS
BS --> PSC
ALP --> PPCI
RPPI --> PPCI
ALP --> RPPI

核心组件

• 服务基类 BaseService：定义领域服务的统一入口与依赖获取约定（通过门面/辅助函数就近解析），不直接持有 Model 实例，写操作优先使用静态门面创建或更新。
• 提供者注册总线 ProviderRegistry：集中管理各平台能力 Provider 的注册，三端 Init 在配置就绪后一次性调用 registerAll。
• 具体 Provider：
  • LanguageServiceProvider：注册语言相关能力。
  • PluginServiceProvider：注册插件查询能力（面向业务读取）。
  • DataServiceProvider：注册数据访问相关能力。
• 插件契约：
  • PaymentPluginProviderInterface：支付插件最小契约（start/notify/finish）。
  • ReconcilablePaymentProviderInterface：扩展支持主动对账（query）。
  • PluginServiceContract：面向业务的插件表读取能力（与实现方契约解耦）。
• 插件实现示例：AlipayProvider 实现了可对账的支付 Provider。

架构总览

服务提供者体系由“注册总线 + 能力 Provider + 业务服务 + 插件契约 + 插件实现”构成。业务服务通过 BaseService 获得稳定依赖；ProviderRegistry 负责启动期装配；插件契约保证不同实现的互操作性；具体插件按契约实现并交由聚合器调度。

sequenceDiagram
participant App as "应用启动"
participant Reg as "ProviderRegistry"
participant LSP as "LanguageServiceProvider"
participant PSP as "PluginServiceProvider"
participant DSP as "DataServiceProvider"
participant Biz as "业务服务(BaseService)"
participant Contract as "插件契约"
participant Impl as "AlipayProvider"
App->>Reg : 调用 registerAll(container)
Reg->>LSP : register(container)
Reg->>PSP : register(container)
Reg->>DSP : register(container)
Note over App,Reg : 完成平台能力注册
Biz->>Contract : 调用插件查询/能力
Contract-->>Biz : 返回结果(或兜底实现)
Biz->>Impl : 通过聚合器选择并调用 start/notify/finish/query
Impl-->>Biz : 返回处理结果

详细组件分析

服务基类 BaseService

• 职责：为业务服务提供统一的依赖获取约定与 ORM 访问方式。
• 关键约定：
  • 依赖通过 helper/门面就近解析（数据库、请求上下文、语言、安全、视图、资源、模块、站点态等）。
  • ORM 采用静态门面访问 Model，避免构造注入业务 Model。
  • 写操作统一走 create/update；读操作支持 with/first/get/paginate。
  • 复杂查询/聚合建议抽取到 Reader/Query/*Core 服务类并按常规 DI 注入。
• 复杂度：O(1) 查找；无状态基类，便于复用。

classDiagram
class BaseService {
<<abstract>>
+依赖获取约定
+ORM访问约定
}

提供者注册总线 ProviderRegistry

• 职责：集中维护已注册的平台能力 Provider 列表，并在容器就绪时依次调用其静态 register 方法。
• 关键点：
  • 白名单式 Provider 列表，避免随意扩展导致不可控。
  • 仅引入 register 阶段，不引入 boot，语义简单清晰。
  • 未加载的 Provider 类会被跳过，具备容错性。

flowchart TD
Start(["调用 registerAll"]) --> Loop{"遍历 providers"}
Loop --> |存在| Call["调用 Provider::register(container)"]
Loop --> |不存在| Next["跳过"]
Call --> Next
Next --> Loop
Loop --> |结束| End(["完成"])

语言/插件/数据 Provider

• LanguageServiceProvider：注册语言相关能力，供多语言环境使用。
• PluginServiceProvider：注册插件查询能力（面向业务读取），与插件实现方契约解耦。
• DataServiceProvider：注册数据访问相关能力。
• 这些 Provider 均暴露静态 register(Container) 方法，由 ProviderRegistry 统一调用。

插件契约与实现（以支付为例）

• 契约层次：
  • PaymentPluginProviderInterface：定义 start/notify/finish 的最小集。
  • ReconcilablePaymentProviderInterface：扩展 query 能力，支持主动对账。
• 实现示例：
  • AlipayProvider 实现了 ReconcilablePaymentProviderInterface，并通过 meta() 声明插件元信息与配置项 schema。
  • 通过 pluginId() 标识插件 slug，供聚合器路由。

classDiagram
class PaymentPluginProviderInterface {
+pluginId() string
+meta() array
+start(request) string
+notify(payload) string
+finish(payload) string
}
class ReconcilablePaymentProviderInterface {
+query(request) PaymentQueryResult
}
class AlipayProvider {
+pluginId() string
+meta() array
+start(request) string
+notify(payload) string
+finish(payload) string
+query(request) PaymentQueryResult
}
ReconcilablePaymentProviderInterface <|-- AlipayProvider
PaymentPluginProviderInterface <|.. ReconcilablePaymentProviderInterface

业务侧插件读取契约 PluginServiceContract

• 定位：面向业务层的插件表读取能力，屏蔽底层实现细节。
• 能力：
  • isAvailable / hasGroup / valueByGroup / valueBySlug / getBySlug / existsBySlug / getWithConfig / defaultPaymentSlug / hasConnect。
• 设计要点：当 plugin 模块关闭或未安装时，由 Null 实现兜底，确保调用面无需判空。

支付发起流程（序列图）

sequenceDiagram
participant Client as "客户端"
participant Service as "业务服务(BaseService)"
participant Agg as "支付聚合器"
participant Prov as "AlipayProvider"
participant SDK as "支付宝SDK"
Client->>Service : 提交订单并请求支付
Service->>Agg : 根据插件ID选择Provider
Agg->>Prov : start(PaymentRequest)
Prov->>SDK : 生成支付表单/链接
SDK-->>Prov : 返回HTML/URL
Prov-->>Agg : 返回HTML/URL
Agg-->>Service : 返回HTML/URL
Service-->>Client : 渲染支付页面

依赖关系分析

• 松耦合：业务服务通过 BaseService 与门面/辅助函数交互，不直接依赖外部库。
• 明确边界：插件契约与实现分离，聚合器负责路由与生命周期管理。
• 可替换性：通过契约可替换不同实现（如多种支付方式）。
• 注册机制：ProviderRegistry 集中管理，避免散落的初始化逻辑。

graph LR
Biz["业务服务(BaseService)"] --> Facade["门面/辅助函数"]
Biz --> Contract["PluginServiceContract"]
Contract --> ImplA["NullPluginService(兜底)"]
Contract --> ImplB["PluginService(真实)"]
Agg["支付聚合器"] --> I1["PaymentPluginProviderInterface"]
Agg --> I2["ReconcilablePaymentProviderInterface"]
ImplA -.->|可选| Agg
ImplB -.->|可选| Agg

性能考虑

• 延迟加载：ProviderRegistry 仅在启动时注册一次，避免重复开销。
• 轻量契约：接口定义保持最小必要方法，减少实现成本。
• ORM 优化：Service 内复杂查询下沉至 Reader/Query 服务，利用预加载与分页降低内存占用。
• 兜底实现：PluginServiceContract 的 Null 实现避免运行时判空分支带来的额外判断。

故障排查指南

• 问题：Provider 未生效
  • 检查 Provider 是否在 ProviderRegistry::$providers 列表中。
  • 确认 Provider 类存在且包含静态 register 方法。
• 问题：插件无法被识别
  • 核对插件实现是否实现了对应契约接口。
  • 检查 pluginId() 返回值是否与 plugin.slug 一致。
• 问题：支付回调失败
  • 确认 notify/finish 实现正确解析回调载荷。
  • 检查签名验证与异常处理路径。
• 问题：配置项无效
  • 核对 meta().config 字段名与存储键一致。
  • 校验输入值是否符合预期类型与约束。

结论

DouPHP 的服务提供者体系通过“基类约定 + 注册总线 + 契约抽象 + 具体实现”的分层设计，实现了高内聚、低耦合与强扩展性。遵循本文的命名、目录、配置与校验规范，结合测试与调试策略，可高效构建稳定可靠的自定义服务提供者。

附录

命名约定与目录结构规范

• 命名约定
  • 服务基类：BaseService（位于 core/service）。
  • 提供者：*ServiceProvider（位于 core/foundation/provider）。
  • 契约：*Interface（位于 core/infra/plugin/contract 或 core/contract）。
  • 实现：以插件域命名，如 AlipayProvider（位于 plugin/*）。
• 目录结构
  • core/service：业务服务基类与通用服务。
  • core/foundation/provider：平台能力提供者。
  • core/contract：跨端共享契约。
  • core/infra/plugin/contract：插件实现方契约。
  • plugin/*：第三方插件实现。

配置文件格式与参数校验规则

• 配置来源
  • 插件元信息中的配置 schema 由 Provider.meta().config 描述，用于后台渲染与校验。
  • 业务设置可通过 SettingService 等组件进行持久化与校验。
• 校验规则
  • 字段类型与必填性由 schema 定义。
  • 业务层可在 Request 或 Service 中追加规则（如域名清洗、正则匹配等）。
• 最佳实践
  • 敏感字段（私钥等）建议使用加密存储。
  • 对外暴露的配置项需做白名单过滤与长度限制。

测试策略与单元测试编写方法

• 单元覆盖
  • 针对 Provider.meta() 的 schema 进行断言，确保后台渲染正确。
  • 针对 start/notify/finish/query 的关键路径编写用例，模拟第三方响应。
• 契约驱动
  • 基于契约接口编写 Mock，隔离第三方依赖。
• 集成测试
  • 通过 ProviderRegistry 注册后进行端到端验证。
• 回归保障
  • 对支付回调、对账流程增加稳定性用例。

调试技巧与常见问题解决方案

• 启用日志
  • 在 Provider 关键路径记录入参与出参，便于定位问题。
• 快速验证
  • 使用最小化请求复现问题，逐步缩小范围。
• 常见错误
  • 插件 ID 不一致：核对 pluginId() 与数据库 slug。
  • 回调签名失败：核对密钥与加签算法。
  • 配置项缺失：检查 meta().config 字段与存储键映射。

实际项目示例（参考路径）

• 支付插件 Provider 示例：AlipayProvider.php
• 支付契约：PaymentPluginProviderInterface.php
• 可对账支付契约：ReconcilablePaymentProviderInterface.php
• 服务基类：BaseService.php
• 提供者注册总线：ProviderRegistry.php