Laravel HTTP Client 最佳实践以 Coolify 源码为范例的可靠外部 API 调用指南【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify本指南以 HTTP Client 最佳实践规则 为核心骨架系统讲解 Laravel HTTP ClientIlluminate\Support\Facades\Http在调用 GitHub、GitLab、Telegram、Pushover 及 CDN 等外部 API 时的超时控制、指数退避重试、显式错误处理、并发请求池与测试替身等工程要点并结合开源 PaaS 项目 Coolify 的真实实现源码、帮助函数与 Feature 测试逐一印证每一条规则如何落到生产代码中。读完你将获得一套可直接照抄 有源码佐证的可靠 API 调用范式。Coolify 是一个自托管 PaaS面向 Vercel/Heroku 的替代品其控制面需要高频对接外部系统GitHub/GitLab 仓库与 Webhook API、DigitalOcean/Hetzner/Vultr 云厂商 API、Telegram/Pushover/Discord/Slack 通知网关、以及官方服务模板 CDN。这些调用大多位于可重试的 Job 或同步辅助函数中一旦超时、重试策略或错误处理设计不当会直接表现为通知丢失模板拉取失败或部署卡死这类线上问题。因此 Laravel HTTP Client 的使用规范在本仓库内不是风格偏好而是可用性基线。一、始终设置显式超时默认 30 秒对 API 调用太长了Laravel HTTP Client 的默认请求超时是 30 秒。对外部 API 而言一次调用等待 30 秒既拖慢用户体验也会长时间占用队列 Worker 或阻塞用户请求。规则第一条显式指定timeout总超时与connectTimeout建连超时让失败快速暴露。错误写法依赖默认值最坏要等 30 秒才失败$response Http::get(https://api.example.com/users);正确写法请求 5 秒未完成即失败3 秒内无法建立 TCP 连接即失败$response Http::timeout(5) -connectTimeout(3) -get(https://api.example.com/users);对特定服务封装专用客户端时应把超时固化在Http::macro()里避免调用方每次重复配置Http::macro(github, function () { return Http::baseUrl(https://api.github.com) -timeout(10) -connectTimeout(3) -withToken(config(services.github.token)); }); $response Http::github()-get(/repos/laravel/framework);Coolify 中的落地服务模板拉取为超时配置取值的参照Coolify 的get_service_templates()位于 bootstrap/helpers/shared.php是强制刷新服务模板的核心入口。它从 CDN 拉取官方模板 JSON将重试、超时与降级策略组合在一起function get_service_templates(bool $force false): Collection { if ($force) { try { $response Http::retry(3, 1000, throw: false) -timeout(60) -connectTimeout(10) -get(config(constants.services.official)); if ($response-failed()) { return collect([]); } store_service_templates_bundle($response-body()); return collect(json_decode($response-body()))-sortKeys(); } catch (Throwable) { return get_service_templates(); } } // 非 force 时优先读取 Cache其次本地文件 ... }这里可以观察到一个值得借鉴的超时取值思路timeout(60)完整模板 JSON 属于大 payloadCDN 响应通常比 API 慢因此给足 60 秒总预算而不是套用面向普通 API 的 5~10 秒connectTimeout(10)建连阶段只给 10 秒用于快速识别源站不可达/网络被墙这类问题不占用 60 秒的整段预算端点地址走配置中心config(constants.services.official)而不是硬编码测试中即可用config([...])轻松替换见下文测试章节。实践结论timeout应该按请求实际耗时画像取值connectTimeout才是你用来快速失败的第一道闸门两者缺一不可。二、对外部 API 使用带退避的重试容忍瞬时故障外部 API 天然存在瞬时故障连接被重置、5xx、限流 429规则第二条用retry()配合递增延迟指数退避重放请求而不是调用一次就抛出异常。错误写法一次失败直接抛出业务异常没有重试机会$response Http::post(https://api.stripe.com/v1/charges, $data); if ($response-failed()) { throw new PaymentFailedException(Charge failed); }正确写法100ms → 500ms → 1000ms 递增延迟最多重试 3 次后仍失败才交给调用方处理$response Http::retry([100, 500, 1000]) -timeout(10) -post(https://api.stripe.com/v1/charges, $data);注意幂等性POST/PUT/PATCH 语义下重试意味着可能重复提交请仅在请求具备幂等能力或重试是安全的前提下使用对纯查询类 GET 则可以放心重试。更精细的做法是只在特定错误上重试可重试条件收窄到连接异常与服务端 5xx避免对 4xx 客户端错误做无意义重试$response Http::retry(3, 100, function (Throwable $exception, PendingRequest $request) { return $exception instanceof ConnectionException || ($exception instanceof RequestException $exception-response-serverError()); })-post(https://api.example.com/data);Coolify 中的落地HTTP 层重试 队列层重试的双保险Coolify 的get_service_templates()使用了 Laravel 8.4 支持的数组延迟签名Http::retry(3, 1000, throw: false)最多重试 3 次、每次间隔 1000ms且设置throw: false让重试耗尽后返回失败的Response而不是抛出异常再由$response-failed()分支做优雅降级返回空集合并把兜底逻辑放在catch (Throwable)中递归退回缓存/本地文件读取。在队列侧Coolify 把调用失败可重试的职责与队列重试机制叠加。以通知网关任务 SendMessageToTelegramJob.php 为例public $tries 5; // 整个 Job 最多尝试 5 次 public $backoff 10; // 每次失败后延迟 10 秒重试 public int $maxExceptions 3; // 未处理异常累计达 3 次即放弃handle()内调用 Telegram API 并主动把失败转为异常详见下一节从而借助队列的tries/backoff完成定时指数退避重试同类模式也见于 SendMessageToPushoverJob.php。这构成了一种通用分工面向随机瞬时抖动建连失败、网关 5xx→ 在 HTTP 请求层用Http::retry快速解决面向需要等恢复窗口的问题限流、通知网关短暂不可用→ 提升到 Job 的tries backoff失败抛出异常让队列延迟重放一旦超过maxExceptions/tries则不再重试避免无限占用 Worker。三、显式处理错误4xx/5xx 不会自动抛异常Laravel HTTP Client不会在收到 4xx/5xx 时抛异常它只是返回一个failed()为 true 的Response。规则第三条要么链式调用throw()要么显式检查状态绝不能假设拿到响应就等于成功。错误写法若 API 返回错误体$response-json()可能返回的是错误结构并被当作用户数据处理$response Http::get(https://api.example.com/users/1); $user $response-json(); // Could be an error body正确写法一快速失败把非 2xx 转成RequestException抛出$response Http::timeout(5) -get(https://api.example.com/users/1) -throw(); $user $response-json();正确写法二需要优雅降级时用语义化状态方法先分流$response Http::get(https://api.example.com/users/1); if ($response-successful()) { return $response-json(); } if ($response-notFound()) { return null; } $response-throw();除successful()/notFound()外Response还提供ok()、redirect()、clientError()、serverError()、accepted()、noContent()等语义方法以及status()、header()、json()等基础访问器。Coolify 中的落地读响应头、解析错误体、拼装可读异常Coolify 对 GitHub API 的统一封装githubApi()bootstrap/helpers/github.php是显式状态检查的教科书式实现$response Http::GitHub($source-api_url, $token)-$method($endpoint); if (! $response-successful() $throwError) { $resetTime Carbon::parse((int) $response-header(X-RateLimit-Reset))-format(Y-m-d H:i:s); $errorMessage data_get($response-json(), message, no error message found); $remainingCalls $response-header(X-RateLimit-Remaining, 0); throw new Exception( GitHub API call failed:br. Error: {$errorMessage}br. Rate Limit Status:br. - Remaining Calls: {$remainingCalls}br. - Reset Time: {$resetTime} UTC ); } return [ rate_limit_remaining $response-header(X-RateLimit-Remaining), rate_limit_reset $response-header(X-RateLimit-Reset), data collect($response-json()), ];这段代码体现了三个进阶点不盲信$response-json()先检查successful()失败时用data_get($response-json(), message, no error message found)安全读取错误信息避免 error body 结构不一致时触发 Undefined index读取响应头做上下文增强通过X-RateLimit-Reset、X-RateLimit-Remaining把 GitHub 限流状态拼进异常消息排障时一眼可见是被限流还是业务错误成功时也返回原始响应头把rate_limit_remaining等元信息随数据一并上抛给调用方做熔断参考。对 4xx 的业务化处理也值得参考——获取 GitHub 安装令牌失败时github.phpCoolify 会把 GitHub 原文Not Found翻译成对用户更友好的Repository not found. Is it moved or deleted?再以RuntimeException抛出。通知类 Job 则采用成功检查 抛异常驱动队列重试的写法例如 SendMessageToTelegramJob.php$response Http::post($url, $payload); if ($response-failed()) { throw new \RuntimeException(Telegram notification failed with .$response-status(). status code..$response-body()); }SendMessageToPushoverJobapp/Jobs/SendMessageToPushoverJob.php使用完全一致的模式。异常消息里携带状态码与原始响应体让告警日志具备足够的定位信息——这条对生产排障价值极高。四、多个独立请求用请求池并发Http::pool()当一次业务处理需要串行发起多个互不依赖的外部请求时逐个await会把总耗时累加为所有请求耗时之和。规则第四条用Http::pool()并行发出按别名取回结果。错误写法三个请求串行执行总耗时 ≈ 三者之和$users Http::get(https://api.example.com/users)-json(); $posts Http::get(https://api.example.com/posts)-json(); $comments Http::get(https://api.example.com/comments)-json();正确写法三个请求并发执行总耗时 ≈ 最慢者use Illuminate\Http\Client\Pool; $responses Http::pool(fn (Pool $pool) [ $pool-as(users)-get(https://api.example.com/users), $pool-as(posts)-get(https://api.example.com/posts), $pool-as(comments)-get(https://api.example.com/comments), ]); $users $responses[users]-json(); $posts $responses[posts]-json();Http::pool()返回一个以别名为键的数组每个元素仍是独立的Response可继续使用successful()、throw()等方法。别名不存在时键值为null取值前可用$responses[users]?-json()防御。适用前提提醒请求池适合互不依赖的扇出fan-out场景。若请求之间有先后依赖如下一个请求需要上一个的响应则不能用池化应保持顺序调用或把无依赖部分拆出合并。此外并行会同时占用多个连接与目标 API 配额应控制单池规模并遵守服务商限流约束。五、测试中永远用Http::fake()禁止真实外呼单元/功能测试一旦真实外呼 API就会引入网络抖动、限流、慢响应与外部状态污染使测试变慢且不稳定。规则第五条测试中必须用Http::fake()拦截请求用preventStrayRequests()兜底任何未被模拟的请求并用Http::assertSent()断言请求内容。错误写法测试真实打到外部 API不可复现、不可离线跑it(syncs user from API, function () { $service new UserSyncService; $service-sync(1); // Hits the real API });正确写法离线、确定、可断言it(syncs user from API, function () { Http::preventStrayRequests(); Http::fake([ api.example.com/users/1 Http::response([ name John Doe, email johnexample.com, ]), ]); $service new UserSyncService; $service-sync(1); Http::assertSent(function (Request $request) { return $request-url() https://api.example.com/users/1; }); });Http::fake()的数组键支持通配符模式如api.example.com/*值为Http::response($body, $status, $headers)、Http::failedConnection()或真实请求的序列化响应Http::response(...)preventStrayRequests()会把任何未被匹配的请求立即转为异常是防止测试偷偷外呼的保险丝。还要测试失败分支网络异常同样可以被模拟并断言优雅降级逻辑Http::fake([ api.example.com/* Http::failedConnection(), ]);Coolify 中的落地PullChangelog 的离线测试Coolify 的 tests/Feature/PullChangelogTest.php 完整覆盖了拉取更新日志Job 的 HTTP 行为是规则第五条的真实范例test(PullChangelog fetches from the configured releases_url and writes the changelog, function () { config([constants.coolify.releases_url https://example.test/releases.json]); Http::fake([ https://example.test/releases.json Http::response(fakeReleasesPayload(), 200), ]); (new PullChangelog)-handle(); Http::assertSent(fn ($request) $request-url() https://example.test/releases.json); // 然后断言生成的 changelogs/1999-01.json 内容与数量 ... });测试通过config([constants.coolify.releases_url ...])重定向请求地址配合Http::fake()返回预置的 releases 载荷随后用Http::assertSent()精确断言只向目标 URL 发起了请求。同文件中还有跳过 draft release的用例PullChangelogTest.php用同一份 fake 数据验证解析逻辑。值得注意这个测试方案之所以可行得益于生产代码 PullChangelog 与get_service_templates()都把 URL 收口到config(constants.coolify.*)/config(constants.services.official)——配置中心化是 HTTP 可测性的前提。仓库中还有大量同类测试例如PullServiceTemplatesFromCdnTest、GitlabRepositoryListingTest、GithubPrivateRepositoryTest、DigitalOceanApiTest等见 tests/Feature 目录共同遵循绝不真实外呼原则。六、用宏封装服务专用客户端把超时、鉴权与域名收口到一处规则中推荐为特定服务定义带超时的宏这正是减少重复、统一升级客户端行为的核心手段。若没有宏每次调用都要重复baseUrl()、timeout()、withToken()组合一旦要调整超时或加公共 Header就要改动全部调用点。Coolify 中的落地GitHub / GitLab 宏Coolify 在 app/Providers/AppServiceProvider.php 的configureGitHubHttp()中注册了GitHub与GitLab两个宏把域名、公共 Header 与鉴权方式全部固化Http::macro(GitHub, function (string $api_url, ?string $github_access_token null) { if ($github_access_token) { return Http::withHeaders([ X-GitHub-Api-Version 2022-11-28, Accept application/vnd.github.v3json, Authorization Bearer $github_access_token, ])-baseUrl($api_url); } else { return Http::withHeaders([ Accept application/vnd.github.v3json, ])-baseUrl($api_url); } }); Http::macro(GitLab, function (string $api_url, ?string $access_token null) { $client Http::withHeaders([ Accept application/json, ])-baseUrl($api_url); if ($access_token) { $client $client-withToken($access_token); } return $client; });这个设计与规则示例的差异点值得展开域名不写死在宏里而是作为参数传入Coolify 支持 GitHub/GitLab 的私有化部署实例api_url既可能是https://api.github.com也可能是企业版内网地址因此宏接受$api_url而非baseUrl硬编码鉴权走响应式分支$github_access_token为空时public 仓库只带Accept头匿名访问非空时才加Authorization: Bearer——同一宏服务两种身份场景版本化 Header 一次配齐GitHub 要求的X-GitHub-Api-Version: 2022-11-28、application/vnd.github.v3json这类每请求都必须带的头被收敛到宏内部调用方不可遗漏。从源码结构看Coolify 在 GitHub/GitLab 侧还额外包了一层帮助函数层bootstrap/helpers/github.php、bootstrap/helpers/gitlab.php负责令牌签发JWT/Installation Token、OAuth 令牌换取Http::asForm()-post({$baseUrl}/oauth/token, ...)见 gitlab.php、限流头解析等与业务编排解耦的职责最终统一走Http::GitHub(...)/Http::GitLab(...)宏发起请求。这套宏传输细节→ 帮助函数鉴权与语义化→ 业务调用方的三层结构比散落各处的裸Http::get()更易于审计与演进。七、综合建议一份可复用的检查清单综合规则文档与 Coolify 生产代码可以在项目中落地这样一份HTTP 调用代码审查清单超时是否每个调用都有timeout()关键外呼是否还有更短的connectTimeout()是否依据该端点的真实耗时画像取值如大文件/CDN 给 30~60s普通 API 给 5~10s重试该请求是否幂等、是否值得重试若值得是否用了Http::retry()并限制次数与延迟不可靠通知类任务是否把重试提升到队列 Job 的tries/backoff层错误处理是否假设拿到 Response 即成功是否使用了throw()或successful()/clientError()/notFound()分流异常信息是否携带状态码、响应体与关键响应头如限流头并发多个互不依赖的请求是否串行发出是否需要改用Http::pool()鉴权与域名服务专属的 base URL、公共 Header、令牌注入是否收敛到了Http::macro()/ 独立帮助函数还是散落在每个调用点可测试性目标 URL 是否来自config()而非硬编码测试是否使用Http::fake()覆盖成功与失败含failedConnection()两个分支是否开启preventStrayRequests()防止意外外呼降级外部服务不可用时是否会让用户请求直接 500还是能像get_service_templates()那样退回到缓存/本地文件延伸阅读入口本规则的原始出处.claude/skills/laravel-best-practices/rules/http-client.md宏封装范例app/Providers/AppServiceProvider.php帮助函数层bootstrap/helpers/github.php、bootstrap/helpers/gitlab.php超时 重试 降级组合范例bootstrap/helpers/shared.php队列侧重试 显式失败范例app/Jobs/SendMessageToTelegramJob.php、app/Jobs/SendMessageToPushoverJob.phpHTTP 打桩测试范例tests/Feature/PullChangelogTest.php一句话总结把显式超时 → 受控重试 → 显式错误处理 → 并发池化 → 离线打桩 → 宏收口鉴权这六件事当作默认动作而非可选项你的 Laravel 应用在对接任何外部 API 时都会从偶尔卡死、偶发丢请求进化到快速失败、自动恢复、可测可查。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Laravel HTTP Client 最佳实践：以 Coolify 源码为范例的可靠外部 API 调用指南
Laravel HTTP Client 最佳实践以 Coolify 源码为范例的可靠外部 API 调用指南【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify本指南以 HTTP Client 最佳实践规则 为核心骨架系统讲解 Laravel HTTP ClientIlluminate\Support\Facades\Http在调用 GitHub、GitLab、Telegram、Pushover 及 CDN 等外部 API 时的超时控制、指数退避重试、显式错误处理、并发请求池与测试替身等工程要点并结合开源 PaaS 项目 Coolify 的真实实现源码、帮助函数与 Feature 测试逐一印证每一条规则如何落到生产代码中。读完你将获得一套可直接照抄 有源码佐证的可靠 API 调用范式。Coolify 是一个自托管 PaaS面向 Vercel/Heroku 的替代品其控制面需要高频对接外部系统GitHub/GitLab 仓库与 Webhook API、DigitalOcean/Hetzner/Vultr 云厂商 API、Telegram/Pushover/Discord/Slack 通知网关、以及官方服务模板 CDN。这些调用大多位于可重试的 Job 或同步辅助函数中一旦超时、重试策略或错误处理设计不当会直接表现为通知丢失模板拉取失败或部署卡死这类线上问题。因此 Laravel HTTP Client 的使用规范在本仓库内不是风格偏好而是可用性基线。一、始终设置显式超时默认 30 秒对 API 调用太长了Laravel HTTP Client 的默认请求超时是 30 秒。对外部 API 而言一次调用等待 30 秒既拖慢用户体验也会长时间占用队列 Worker 或阻塞用户请求。规则第一条显式指定timeout总超时与connectTimeout建连超时让失败快速暴露。错误写法依赖默认值最坏要等 30 秒才失败$response Http::get(https://api.example.com/users);正确写法请求 5 秒未完成即失败3 秒内无法建立 TCP 连接即失败$response Http::timeout(5) -connectTimeout(3) -get(https://api.example.com/users);对特定服务封装专用客户端时应把超时固化在Http::macro()里避免调用方每次重复配置Http::macro(github, function () { return Http::baseUrl(https://api.github.com) -timeout(10) -connectTimeout(3) -withToken(config(services.github.token)); }); $response Http::github()-get(/repos/laravel/framework);Coolify 中的落地服务模板拉取为超时配置取值的参照Coolify 的get_service_templates()位于 bootstrap/helpers/shared.php是强制刷新服务模板的核心入口。它从 CDN 拉取官方模板 JSON将重试、超时与降级策略组合在一起function get_service_templates(bool $force false): Collection { if ($force) { try { $response Http::retry(3, 1000, throw: false) -timeout(60) -connectTimeout(10) -get(config(constants.services.official)); if ($response-failed()) { return collect([]); } store_service_templates_bundle($response-body()); return collect(json_decode($response-body()))-sortKeys(); } catch (Throwable) { return get_service_templates(); } } // 非 force 时优先读取 Cache其次本地文件 ... }这里可以观察到一个值得借鉴的超时取值思路timeout(60)完整模板 JSON 属于大 payloadCDN 响应通常比 API 慢因此给足 60 秒总预算而不是套用面向普通 API 的 5~10 秒connectTimeout(10)建连阶段只给 10 秒用于快速识别源站不可达/网络被墙这类问题不占用 60 秒的整段预算端点地址走配置中心config(constants.services.official)而不是硬编码测试中即可用config([...])轻松替换见下文测试章节。实践结论timeout应该按请求实际耗时画像取值connectTimeout才是你用来快速失败的第一道闸门两者缺一不可。二、对外部 API 使用带退避的重试容忍瞬时故障外部 API 天然存在瞬时故障连接被重置、5xx、限流 429规则第二条用retry()配合递增延迟指数退避重放请求而不是调用一次就抛出异常。错误写法一次失败直接抛出业务异常没有重试机会$response Http::post(https://api.stripe.com/v1/charges, $data); if ($response-failed()) { throw new PaymentFailedException(Charge failed); }正确写法100ms → 500ms → 1000ms 递增延迟最多重试 3 次后仍失败才交给调用方处理$response Http::retry([100, 500, 1000]) -timeout(10) -post(https://api.stripe.com/v1/charges, $data);注意幂等性POST/PUT/PATCH 语义下重试意味着可能重复提交请仅在请求具备幂等能力或重试是安全的前提下使用对纯查询类 GET 则可以放心重试。更精细的做法是只在特定错误上重试可重试条件收窄到连接异常与服务端 5xx避免对 4xx 客户端错误做无意义重试$response Http::retry(3, 100, function (Throwable $exception, PendingRequest $request) { return $exception instanceof ConnectionException || ($exception instanceof RequestException $exception-response-serverError()); })-post(https://api.example.com/data);Coolify 中的落地HTTP 层重试 队列层重试的双保险Coolify 的get_service_templates()使用了 Laravel 8.4 支持的数组延迟签名Http::retry(3, 1000, throw: false)最多重试 3 次、每次间隔 1000ms且设置throw: false让重试耗尽后返回失败的Response而不是抛出异常再由$response-failed()分支做优雅降级返回空集合并把兜底逻辑放在catch (Throwable)中递归退回缓存/本地文件读取。在队列侧Coolify 把调用失败可重试的职责与队列重试机制叠加。以通知网关任务 SendMessageToTelegramJob.php 为例public $tries 5; // 整个 Job 最多尝试 5 次 public $backoff 10; // 每次失败后延迟 10 秒重试 public int $maxExceptions 3; // 未处理异常累计达 3 次即放弃handle()内调用 Telegram API 并主动把失败转为异常详见下一节从而借助队列的tries/backoff完成定时指数退避重试同类模式也见于 SendMessageToPushoverJob.php。这构成了一种通用分工面向随机瞬时抖动建连失败、网关 5xx→ 在 HTTP 请求层用Http::retry快速解决面向需要等恢复窗口的问题限流、通知网关短暂不可用→ 提升到 Job 的tries backoff失败抛出异常让队列延迟重放一旦超过maxExceptions/tries则不再重试避免无限占用 Worker。三、显式处理错误4xx/5xx 不会自动抛异常Laravel HTTP Client不会在收到 4xx/5xx 时抛异常它只是返回一个failed()为 true 的Response。规则第三条要么链式调用throw()要么显式检查状态绝不能假设拿到响应就等于成功。错误写法若 API 返回错误体$response-json()可能返回的是错误结构并被当作用户数据处理$response Http::get(https://api.example.com/users/1); $user $response-json(); // Could be an error body正确写法一快速失败把非 2xx 转成RequestException抛出$response Http::timeout(5) -get(https://api.example.com/users/1) -throw(); $user $response-json();正确写法二需要优雅降级时用语义化状态方法先分流$response Http::get(https://api.example.com/users/1); if ($response-successful()) { return $response-json(); } if ($response-notFound()) { return null; } $response-throw();除successful()/notFound()外Response还提供ok()、redirect()、clientError()、serverError()、accepted()、noContent()等语义方法以及status()、header()、json()等基础访问器。Coolify 中的落地读响应头、解析错误体、拼装可读异常Coolify 对 GitHub API 的统一封装githubApi()bootstrap/helpers/github.php是显式状态检查的教科书式实现$response Http::GitHub($source-api_url, $token)-$method($endpoint); if (! $response-successful() $throwError) { $resetTime Carbon::parse((int) $response-header(X-RateLimit-Reset))-format(Y-m-d H:i:s); $errorMessage data_get($response-json(), message, no error message found); $remainingCalls $response-header(X-RateLimit-Remaining, 0); throw new Exception( GitHub API call failed:br. Error: {$errorMessage}br. Rate Limit Status:br. - Remaining Calls: {$remainingCalls}br. - Reset Time: {$resetTime} UTC ); } return [ rate_limit_remaining $response-header(X-RateLimit-Remaining), rate_limit_reset $response-header(X-RateLimit-Reset), data collect($response-json()), ];这段代码体现了三个进阶点不盲信$response-json()先检查successful()失败时用data_get($response-json(), message, no error message found)安全读取错误信息避免 error body 结构不一致时触发 Undefined index读取响应头做上下文增强通过X-RateLimit-Reset、X-RateLimit-Remaining把 GitHub 限流状态拼进异常消息排障时一眼可见是被限流还是业务错误成功时也返回原始响应头把rate_limit_remaining等元信息随数据一并上抛给调用方做熔断参考。对 4xx 的业务化处理也值得参考——获取 GitHub 安装令牌失败时github.phpCoolify 会把 GitHub 原文Not Found翻译成对用户更友好的Repository not found. Is it moved or deleted?再以RuntimeException抛出。通知类 Job 则采用成功检查 抛异常驱动队列重试的写法例如 SendMessageToTelegramJob.php$response Http::post($url, $payload); if ($response-failed()) { throw new \RuntimeException(Telegram notification failed with .$response-status(). status code..$response-body()); }SendMessageToPushoverJobapp/Jobs/SendMessageToPushoverJob.php使用完全一致的模式。异常消息里携带状态码与原始响应体让告警日志具备足够的定位信息——这条对生产排障价值极高。四、多个独立请求用请求池并发Http::pool()当一次业务处理需要串行发起多个互不依赖的外部请求时逐个await会把总耗时累加为所有请求耗时之和。规则第四条用Http::pool()并行发出按别名取回结果。错误写法三个请求串行执行总耗时 ≈ 三者之和$users Http::get(https://api.example.com/users)-json(); $posts Http::get(https://api.example.com/posts)-json(); $comments Http::get(https://api.example.com/comments)-json();正确写法三个请求并发执行总耗时 ≈ 最慢者use Illuminate\Http\Client\Pool; $responses Http::pool(fn (Pool $pool) [ $pool-as(users)-get(https://api.example.com/users), $pool-as(posts)-get(https://api.example.com/posts), $pool-as(comments)-get(https://api.example.com/comments), ]); $users $responses[users]-json(); $posts $responses[posts]-json();Http::pool()返回一个以别名为键的数组每个元素仍是独立的Response可继续使用successful()、throw()等方法。别名不存在时键值为null取值前可用$responses[users]?-json()防御。适用前提提醒请求池适合互不依赖的扇出fan-out场景。若请求之间有先后依赖如下一个请求需要上一个的响应则不能用池化应保持顺序调用或把无依赖部分拆出合并。此外并行会同时占用多个连接与目标 API 配额应控制单池规模并遵守服务商限流约束。五、测试中永远用Http::fake()禁止真实外呼单元/功能测试一旦真实外呼 API就会引入网络抖动、限流、慢响应与外部状态污染使测试变慢且不稳定。规则第五条测试中必须用Http::fake()拦截请求用preventStrayRequests()兜底任何未被模拟的请求并用Http::assertSent()断言请求内容。错误写法测试真实打到外部 API不可复现、不可离线跑it(syncs user from API, function () { $service new UserSyncService; $service-sync(1); // Hits the real API });正确写法离线、确定、可断言it(syncs user from API, function () { Http::preventStrayRequests(); Http::fake([ api.example.com/users/1 Http::response([ name John Doe, email johnexample.com, ]), ]); $service new UserSyncService; $service-sync(1); Http::assertSent(function (Request $request) { return $request-url() https://api.example.com/users/1; }); });Http::fake()的数组键支持通配符模式如api.example.com/*值为Http::response($body, $status, $headers)、Http::failedConnection()或真实请求的序列化响应Http::response(...)preventStrayRequests()会把任何未被匹配的请求立即转为异常是防止测试偷偷外呼的保险丝。还要测试失败分支网络异常同样可以被模拟并断言优雅降级逻辑Http::fake([ api.example.com/* Http::failedConnection(), ]);Coolify 中的落地PullChangelog 的离线测试Coolify 的 tests/Feature/PullChangelogTest.php 完整覆盖了拉取更新日志Job 的 HTTP 行为是规则第五条的真实范例test(PullChangelog fetches from the configured releases_url and writes the changelog, function () { config([constants.coolify.releases_url https://example.test/releases.json]); Http::fake([ https://example.test/releases.json Http::response(fakeReleasesPayload(), 200), ]); (new PullChangelog)-handle(); Http::assertSent(fn ($request) $request-url() https://example.test/releases.json); // 然后断言生成的 changelogs/1999-01.json 内容与数量 ... });测试通过config([constants.coolify.releases_url ...])重定向请求地址配合Http::fake()返回预置的 releases 载荷随后用Http::assertSent()精确断言只向目标 URL 发起了请求。同文件中还有跳过 draft release的用例PullChangelogTest.php用同一份 fake 数据验证解析逻辑。值得注意这个测试方案之所以可行得益于生产代码 PullChangelog 与get_service_templates()都把 URL 收口到config(constants.coolify.*)/config(constants.services.official)——配置中心化是 HTTP 可测性的前提。仓库中还有大量同类测试例如PullServiceTemplatesFromCdnTest、GitlabRepositoryListingTest、GithubPrivateRepositoryTest、DigitalOceanApiTest等见 tests/Feature 目录共同遵循绝不真实外呼原则。六、用宏封装服务专用客户端把超时、鉴权与域名收口到一处规则中推荐为特定服务定义带超时的宏这正是减少重复、统一升级客户端行为的核心手段。若没有宏每次调用都要重复baseUrl()、timeout()、withToken()组合一旦要调整超时或加公共 Header就要改动全部调用点。Coolify 中的落地GitHub / GitLab 宏Coolify 在 app/Providers/AppServiceProvider.php 的configureGitHubHttp()中注册了GitHub与GitLab两个宏把域名、公共 Header 与鉴权方式全部固化Http::macro(GitHub, function (string $api_url, ?string $github_access_token null) { if ($github_access_token) { return Http::withHeaders([ X-GitHub-Api-Version 2022-11-28, Accept application/vnd.github.v3json, Authorization Bearer $github_access_token, ])-baseUrl($api_url); } else { return Http::withHeaders([ Accept application/vnd.github.v3json, ])-baseUrl($api_url); } }); Http::macro(GitLab, function (string $api_url, ?string $access_token null) { $client Http::withHeaders([ Accept application/json, ])-baseUrl($api_url); if ($access_token) { $client $client-withToken($access_token); } return $client; });这个设计与规则示例的差异点值得展开域名不写死在宏里而是作为参数传入Coolify 支持 GitHub/GitLab 的私有化部署实例api_url既可能是https://api.github.com也可能是企业版内网地址因此宏接受$api_url而非baseUrl硬编码鉴权走响应式分支$github_access_token为空时public 仓库只带Accept头匿名访问非空时才加Authorization: Bearer——同一宏服务两种身份场景版本化 Header 一次配齐GitHub 要求的X-GitHub-Api-Version: 2022-11-28、application/vnd.github.v3json这类每请求都必须带的头被收敛到宏内部调用方不可遗漏。从源码结构看Coolify 在 GitHub/GitLab 侧还额外包了一层帮助函数层bootstrap/helpers/github.php、bootstrap/helpers/gitlab.php负责令牌签发JWT/Installation Token、OAuth 令牌换取Http::asForm()-post({$baseUrl}/oauth/token, ...)见 gitlab.php、限流头解析等与业务编排解耦的职责最终统一走Http::GitHub(...)/Http::GitLab(...)宏发起请求。这套宏传输细节→ 帮助函数鉴权与语义化→ 业务调用方的三层结构比散落各处的裸Http::get()更易于审计与演进。七、综合建议一份可复用的检查清单综合规则文档与 Coolify 生产代码可以在项目中落地这样一份HTTP 调用代码审查清单超时是否每个调用都有timeout()关键外呼是否还有更短的connectTimeout()是否依据该端点的真实耗时画像取值如大文件/CDN 给 30~60s普通 API 给 5~10s重试该请求是否幂等、是否值得重试若值得是否用了Http::retry()并限制次数与延迟不可靠通知类任务是否把重试提升到队列 Job 的tries/backoff层错误处理是否假设拿到 Response 即成功是否使用了throw()或successful()/clientError()/notFound()分流异常信息是否携带状态码、响应体与关键响应头如限流头并发多个互不依赖的请求是否串行发出是否需要改用Http::pool()鉴权与域名服务专属的 base URL、公共 Header、令牌注入是否收敛到了Http::macro()/ 独立帮助函数还是散落在每个调用点可测试性目标 URL 是否来自config()而非硬编码测试是否使用Http::fake()覆盖成功与失败含failedConnection()两个分支是否开启preventStrayRequests()防止意外外呼降级外部服务不可用时是否会让用户请求直接 500还是能像get_service_templates()那样退回到缓存/本地文件延伸阅读入口本规则的原始出处.claude/skills/laravel-best-practices/rules/http-client.md宏封装范例app/Providers/AppServiceProvider.php帮助函数层bootstrap/helpers/github.php、bootstrap/helpers/gitlab.php超时 重试 降级组合范例bootstrap/helpers/shared.php队列侧重试 显式失败范例app/Jobs/SendMessageToTelegramJob.php、app/Jobs/SendMessageToPushoverJob.phpHTTP 打桩测试范例tests/Feature/PullChangelogTest.php一句话总结把显式超时 → 受控重试 → 显式错误处理 → 并发池化 → 离线打桩 → 宏收口鉴权这六件事当作默认动作而非可选项你的 Laravel 应用在对接任何外部 API 时都会从偶尔卡死、偶发丢请求进化到快速失败、自动恢复、可测可查。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考