PHP代码注释生成专家

<?php
declare(strict_types=1);

namespace App\Report;

use DateTimeImmutable;
use RuntimeException;

/**
 * 订单汇总器
 *
 * 将原始订单行数据进行聚合，计算以下指标：
 * - 总订单数（count）
 * - 金额总和（totalAmount）
 * - 平均订单金额（averageAmount，保留两位小数）
 * - 按状态统计数量（byStatus）
 * - 按月份统计金额汇总（byMonth，键格式为 "Y-m"）
 *
 * 可选地根据给定状态进行严格等值过滤（仅统计匹配该状态的订单）。
 * 输入数据每行必须包含 id、status、amount、created_at 四个字段，其中 created_at 必须为 "Y-m-d H:i:s" 格式。
 * 汇总结果中的货币固定为 CNY。
 */
final class OrderAggregator
{
    /**
     * 对订单行数据进行聚合汇总。
     *
     * 当提供 $statusFilter 时，仅汇总状态与其完全匹配的订单；未匹配的行将被跳过。
     * 如发现缺失必需字段或 created_at 日期格式无效，将抛出 RuntimeException。
     *
     * @param array<int, array{id:int|string, status:string, amount:float|int|string, created_at:string}> $rows
     *   待汇总的订单行数组：
     *   - id：订单标识（未参与计算，仅用于数据完整性校验）
     *   - status：订单状态（将用于状态过滤及状态统计）
     *   - amount：订单金额（将被强制转换为 float 后参与计算）
     *   - created_at：创建时间，必须为 "Y-m-d H:i:s" 格式，用于按月聚合
     * @param string|null $statusFilter 可选的状态过滤条件（严格等值匹配）
     *
     * @return array{
     *   count:int,
     *   totalAmount:float,
     *   byStatus:array<string,int>,
     *   byMonth:array<string,float>,
     *   currency:string,
     *   averageAmount:float
     * }
     *   汇总结果：
     *   - count：订单数量
     *   - totalAmount：金额合计
     *   - byStatus：按状态的数量统计
     *   - byMonth：按月份（"Y-m"）的金额合计
     *   - currency：货币代码（恒为 "CNY"）
     *   - averageAmount：平均订单金额（两位小数），若 count 为 0 则为 0.0
     *
     * @throws RuntimeException 当行数据缺少必需字段或 created_at 格式无效时抛出
     *
     * @example
     * $rows = [
     *     ['id' => 1, 'status' => 'paid',    'amount' => '99.50', 'created_at' => '2025-05-01 10:30:00'],
     *     ['id' => 2, 'status' => 'pending', 'amount' => 50,      'created_at' => '2025-05-12 08:15:00'],
     *     ['id' => 3, 'status' => 'paid',    'amount' => 20.0,    'created_at' => '2025-06-03 09:45:00'],
     * ];
     *
     * $aggregator = new \App\Report\OrderAggregator();
     * $summary = $aggregator->aggregate($rows, 'paid');
     * // 返回示例：
     * // [
     * //   'count' => 2,
     * //   'totalAmount' => 119.5,
     * //   'byStatus' => ['paid' => 2],
     * //   'byMonth' => ['2025-05' => 99.5, '2025-06' => 20.0],
     * //   'currency' => 'CNY',
     * //   'averageAmount' => 59.75,
     * // ]
     */
    public function aggregate(array $rows, ?string $statusFilter = null): array
    {
        $summary = [
            'count' => 0,
            'totalAmount' => 0.0,
            'byStatus' => [],
            'byMonth' => [],
            'currency' => 'CNY',
        ];

        foreach ($rows as $i => $row) {
            if (!isset($row['id'], $row['status'], $row['amount'], $row['created_at'])) {
                throw new RuntimeException(sprintf('Row #%d missing required fields.', $i));
            }

            if ($statusFilter !== null && $row['status'] !== $statusFilter) {
                continue;
            }

            $amount = (float) $row['amount'];
            $summary['totalAmount'] += $amount;
            $summary['count']++;

            $status = (string) $row['status'];
            $summary['byStatus'][$status] = ($summary['byStatus'][$status] ?? 0) + 1;

            $dt = DateTimeImmutable::createFromFormat('Y-m-d H:i:s', (string) $row['created_at']);
            if (!$dt) {
                throw new RuntimeException(sprintf('Invalid date format at row #%d.', $i));
            }
            $monthKey = $dt->format('Y-m');
            $summary['byMonth'][$monthKey] = ($summary['byMonth'][$monthKey] ?? 0.0) + $amount;
        }

        $summary['averageAmount'] = $summary['count'] > 0 ? round($summary['totalAmount'] / $summary['count'], 2) : 0.0;

        return $summary;
    }
}

<?php
declare(strict_types=1);

namespace App\Integration;

use GuzzleHttp\ClientInterface;
use Psr\Log\LoggerInterface;
use RuntimeException;

/**
 * 用户资料同步服务
 *
 * 通过外部集成端点发起用户资料同步请求，并在成功时返回远端资料快照。
 * 特性：
 * - 最多重试 3 次：网络/解码等异常或非预期响应均会触发重试；
 * - 使用 Guzzle 的 ClientInterface 发送 JSON 请求，超时默认 3 秒；
 * - 采用 PSR-3 Logger 记录成功、警告与错误日志；
 * - 成功判定条件：HTTP 200 且响应体中 ok === true。
 *
 * 使用约定：
 * - $endpoint 为对方系统的基础地址（可包含路径前缀），可带或不带尾部斜杠，方法内部会自行规范化；
 * - 同步成功仅在满足判定条件时返回，失败会在重试用尽后抛出异常。
 */
final class UserSyncService
{
    /**
     * 构造函数
     *
     * @param ClientInterface $http   Guzzle HTTP 客户端实例，用于发送 JSON 请求
     * @param LoggerInterface $logger PSR-3 日志记录器，用于记录同步过程信息与错误
     * @param string          $endpoint 外部集成服务基础 URL（可带或不带尾部斜杠），例如：https://api.partner.com/v1
     */
    public function __construct(
        private ClientInterface $http,
        private LoggerInterface $logger,
        private string $endpoint
    ) {}

    /**
     * 将指定用户的资料与外部系统进行同步，并返回同步结果与资料快照
     *
     * 工作流程：
     * 1. 以 JSON 形式发送 POST 请求到 {endpoint}/profile/sync，载荷为 { userId }；
     * 2. 解析 JSON 响应并校验：HTTP 状态码为 200 且数据字段 ok 为 true 视为成功；
     * 3. 出现异常（网络、超时、JSON 解析等）或非预期响应时，最多重试 3 次（异常时每次间隔约 200ms）；
     * 4. 重试用尽仍失败则抛出 RuntimeException。
     *
     * 返回值约定：
     * - synced: 恒为 true（仅在成功时返回）；
     * - profile: 远端返回的用户资料（若缺失则为空数组）；
     * - fetchedAt: 成功获取数据的时间戳（Unix 时间，秒）。
     *
     * @param int $userId 需要同步的用户 ID
     *
     * @return array{
     *     synced: true,
     *     profile: array<mixed>,
     *     fetchedAt: int
     * }
     *
     * @throws RuntimeException 当超过最大重试次数仍无法成功同步时抛出
     */
    public function sync(int $userId): array
    {
        $payload = ['userId' => $userId];
        $attempts = 0;
        $lastError = null;

        while ($attempts < 3) {
            $attempts++;
            try {
                $resp = $this->http->request('POST', rtrim($this->endpoint, '/') . '/profile/sync', [
                    'json' => $payload,
                    'timeout' => 3.0,
                ]);

                $code = $resp->getStatusCode();
                $body = (string) $resp->getBody();
                $data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);

                if ($code === 200 && ($data['ok'] ?? false) === true) {
                    $this->logger->info('User sync success', ['userId' => $userId]);
                    return [
                        'synced' => true,
                        'profile' => $data['profile'] ?? [],
                        'fetchedAt' => time(),
                    ];
                }

                $lastError = 'Unexpected response: ' . $code;
                $this->logger->warning('User sync unexpected response', ['userId' => $userId, 'code' => $code]);
            } catch (\Throwable $e) {
                $lastError = $e->getMessage();
                $this->logger->error('User sync error', ['userId' => $userId, 'error' => $lastError]);
                usleep(200000);
            }
        }

        throw new RuntimeException('Failed to sync user after retries: ' . $lastError);
    }
}

使用示例

use App\Integration\UserSyncService;
use GuzzleHttp\Client;
use Monolog\Handler\StreamHandler;
use Monolog\Logger;

$http = new Client(); // 或基于具体项目配置化创建
$logger = new Logger('sync');
$logger->pushHandler(new StreamHandler('php://stdout'));

$service = new UserSyncService($http, $logger, 'https://api.partner.com/v1');

try {
    $result = $service->sync(12345);
    // $result = ['synced' => true, 'profile' => [...], 'fetchedAt' => 1700000000]
    // TODO: 使用 $result['profile'] 更新本地用户资料
} catch (\RuntimeException $e) {
    // TODO: 告警或补偿逻辑
    $logger->error('Sync failed', ['exception' => $e]);
}