PHP 怎么服务契约

本文目录导读：

1. 接口契约（Interface Contract） —— 最基础、最常用
2. PHPDoc 与 DTO（数据传输对象）—— 数据结构的契约
3. API 契约（OpenAPI / Swagger）—— 跨系统/微服务
4. 服务契约框架：gRPC / Thrift —— 高性能微服务
5. 契约测试（Pact）—— 确保契约被双方遵守
6. 实现服务契约的最佳实践（TL;DR）
7. 总结：我应该选哪种？

在 PHP 中实现服务契约（Service Contract），核心目标是定义服务提供者和消费者之间的约定，确保接口的稳定性、可维护性和可测试性。

根据你的项目架构（单体应用、微服务、SOA），PHP 实现服务契约的方式有所不同,以下是几种主流且实用的方法：

接口契约（Interface Contract） —— 最基础、最常用

这是 PHP 面向对象编程中最直接的契约方式，通过定义 interface,强制实现类必须遵循特定的方法签名。

• 适用场景：模块化开发、依赖注入、单元测试（Mock 对象）。

• 优点：语言原生支持，IDE 友好，静态分析工具（如 PHPStan、Psalm）能自动校验。

• 实现示例：

  <?php
  // 定义契约（接口）
  interface UserRepositoryInterface {
      public function findById(int $id): ?User;
      public function save(User $user): bool;
  }
  // 服务提供者（实现契约）
  class MysqlUserRepository implements UserRepositoryInterface {
      public function findById(int $id): ?User {
          // 实际数据库查询逻辑
      }
      public function save(User $user): bool {
          // 实际保存逻辑
      }
  }
  ?>

PHPDoc 与 DTO（数据传输对象）—— 数据结构的契约

当服务间传递复杂数据结构时，仅靠接口不够，需要定义 DTO（Data Transfer Object） 和 PHPDoc 来契约化数据结构。

• 适用场景：API 请求/响应、跨模块数据传递。

• 优点：数据结构清晰，避免使用无结构的 array,配合静态分析可提前发现字段拼写错误。

• 实现示例：

  <?php
  // 定义 DTO 契约
  final readonly class CreateUserRequest {
      public function __construct(
          public string $name,
          public string $email,
          public ?string $phone = null
      ) {}
  }
  // 服务实现
  class UserService {
      public function createUser(CreateUserRequest $request): User {
          // 使用 $request->name 而不是 $data['name']
      }
  }
  ?>

API 契约（OpenAPI / Swagger）—— 跨系统/微服务

PHP 作为微服务或前后端分离的后端，通常使用 OpenAPI（Swagger） 规范来定义 HTTP 契约，这是跨语言的标准。

• 适用场景：RESTful API、微服务通信。

• 优点：生成 API 文档、自动生成客户端 SDK,实现契约驱动开发。

• 常用工具：

  • zircote/swagger-php：通过注解自动生成 OpenAPI 文档。
  • deptrac：强制代码分层,防止越层调用。

• 实现示例（注解定义契约）：

  <?php
  use OpenApi\Attributes as OA;
  #[OA\Post(path: '/api/users', summary: '创建用户')]
  #[OA\RequestBody(content: new OA\JsonContent(properties: [
      new OA\Property(property: 'name', type: 'string'),
      new OA\Property(property: 'email', type: 'string'),
  ]))]
  #[OA\Response(response: 201, description: '用户创建成功')]
  class UserController {
      public function store(CreateUserRequest $request): JsonResponse {
          // ...
      }
  }
  ?>

服务契约框架：gRPC / Thrift —— 高性能微服务

对于 PHP 作为微服务（通常结合 Swoole 或 Workerman），可以使用 gRPC 或 Apache Thrift，它们提供强类型、二进制的 RPC 契约。

• 适用场景：内部微服务高并发调用,跨语言协同。

• 优点：强类型、高性能、自动生成客户端和服务端代码。

• 实现示例（gRPC 的 .proto 文件定义契约）：

  // user.proto
  syntax = "proto3";
  package user;
  service UserService {
    rpc GetUser (UserRequest) returns (User) {}
  }
  message UserRequest {
    int32 id = 1;
  }
  message User {
    int32 id = 1;
    string name = 2;
  }

  然后在 PHP 中利用 grpc/grpc 扩展和你定义的 DTO 实现具体业务逻辑。

契约测试（Pact）—— 确保契约被双方遵守

除了代码层面的定义，还需要测试来确保契约不被破坏,契约测试是微服务架构中的重要一环。

• 适用场景：消费者驱动契约（Consumer-Driven Contracts）。
• 优点：防止服务端修改接口参数导致客户端崩溃。
• PHP 工具：Pact-PHP。
• 核心流程：
  1. 消费者（Consumer）：定义对 API 的期望响应。
  2. 生成契约文件：Pact 生成 JSON 契约。
  3. 提供者（Provider）：在 CI/CD 中运行该契约文件,验证自己的响应是否匹配。

实现服务契约的最佳实践（TL;DR）

以下是在 PHP 项目中落地服务契约时的几条核心建议：

1. 优先使用 interface + readonly DTO：对于同一个代码库内的 PHP 模块，这是最简洁、最有效的契约方式。
2. 严格类型声明（Strict Types）：在文件顶部声明 declare(strict_types=1);，避免 PHP 弱类型导致契约被意外突破。
3. 利用静态分析：配置 PHPStan（Level 8）或 Psalm,让代码在运行前验证契约是否被正确实现。
4. 版本化契约：如果服务会演进，尽量在 DTO 或 API 路径中包含版本（/api/v1/users/）,避免破坏已有调用方。
5. 避免依赖 array 作为参数：尽量使用具名的 DTO 类来约束数据，这是 PHP 服务契约中最容易忽略但很重要的一点。

我应该选哪种？

在 PHP 8+ 中，强烈推荐使用接口 + 构造函数属性提升（readonly）+ 联合类型来构建稳固的服务契约层。