技术文章

外部链接将在新标签页打开。

API.PLUS 三语言接入:让 Python、PHP、JavaScript 用同一份调用契约

一句话回答

三语言接入的公共部分是一份与语言无关的调用契约:方法路径、鉴权头、连接与读取超时、成功判定、错误分层、重试条件。Python 要把超时写成(连接, 读取)元组,PHP 要分开 CONNECTTIMEOUT 与 TIMEOUT 并区分 curl_errno 与 HTTP 状态码,JavaScript 的 fetch 不会因 4xx/5xx 抛异常且默认没有超时。API.PLUS 的具体端点、鉴权方式与错误码本次材料未提供,需按官方文档核实。

把同一套调用写成 Python、PHP、JavaScript 三个版本,难点通常不在语法,而在于三个语言对“超时”“失败”“重试”的默认行为并不一致。本文只讲可以跨语言对齐的部分:先定一份调用契约,再落到代码骨架。需要说明的是,本次写作材料只有教程标题,未提供 API.PLUS 的端点路径、鉴权方式、错误码与限流规则,这些信息待核实,请以官方文档为准;下面的地址与密钥均为占位。

先写与语言无关的调用契约#

契约是六个字段,写清楚了,三种语言只是翻译方式不同。

契约项要求三语言常见偏差
完整 URL作为常量定义,不靠字符串拼接手工拼 query 时漏掉 URL 编码
鉴权头从环境变量读取前端直连会把密钥暴露给浏览器
超时连接超时与读取超时分开设fetch 默认无超时
成功判定只看 HTTP 状态码区间fetch 不因 4xx/5xx 拒绝
错误分层传输错误 / HTTP 错误 / 业务错误PHP 把 curl_errno 与状态码混在一起判断
重试仅对幂等请求、仅对传输错误与 5xx三种语言默认都不重试,需自己加

Python:超时写成元组,异常分两层#

用 requests 时,timeout 传单个数字只约束单次读操作,传元组才分别是连接与读取上限。状态码不会自动抛异常,需要显式判断。

import os, requests  # 未执行示例

URL = "https://api.example.com/v1/resource"  # 占位地址,真实端点待核实
HEADERS = {"Authorization": "Bearer " + os.environ["API_KEY"]}

try:
    r = requests.post(URL, headers=HEADERS, json={"q": "demo"}, timeout=(3, 10))
except requests.Timeout:
    pass  # 传输层:幂等请求可重试
except requests.RequestException:
    pass  # 连接 / TLS / DNS 等

if r.status_code >= 400:
    pass  # HTTP 层:按 4xx / 5xx 分流,不重试 4xx

PHP:两种超时 + 两个判定来源#

curl 扩展里 CURLOPT_CONNECTTIMEOUT 管建连,CURLOPT_TIMEOUT 管整次请求。请求失败时 curl_exec 返回 false、CURLINFO_HTTP_CODE 为 0,所以要先看 errno 再看状态码,两个来源不能互替。另外 json_encode 失败返回 false,不应直接当请求体发出。

<?php
$ch = curl_init("https://api.example.com/v1/resource"); // 占位地址
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode(["q" => "demo"]),
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("API_KEY")],
    CURLOPT_CONNECTTIMEOUT => 3,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_RETURNTRANSFER => true,
]);
$body   = curl_exec($ch);
$errno  = curl_errno($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

JavaScript:fetch 的两个默认值要自己补#

fetch 只在网络层失败时拒绝,4xx/5xx 会正常返回,必须查 res.ok;它也没有默认超时,需要 AbortSignal。AbortSignal.timeout 在较新运行时可用,旧版本改用 AbortController 加 setTimeout。在 Node 里调用与在浏览器里调用是两件事,浏览器端还要面对跨域(CORS)限制,密钥不应下发到前端。

const res = await fetch("https://api.example.com/v1/resource", { // 占位地址
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
  body: JSON.stringify({ q: "demo" }),
  signal: AbortSignal.timeout(10_000),
});
if (!res.ok) { /* 4xx/5xx 不会抛异常,需显式处理 */ }

落地前的对齐检查#

  • 三个实现是否读同一份 URL 常量与同一个环境变量名。
  • 超时数值是否一致,且都区分了建连与整体耗时。
  • 失败是否都分成传输、HTTP、业务三层,重试只作用于前两层中的幂等请求。
  • 日志里是否只记录状态码与错误类型,未打印完整请求头。
边界:以上代码是结构示意,未实际执行,也未经任何真实端点验证。API.PLUS 的请求体格式、鉴权头名称、错误码含义与配额规则本次材料未提供,接入前请以官方文档逐项核对,不要直接套用文中的字段名。

作者:沐小悠

本文约 7 分钟读完 · 关键词:API.PLUS 接入、Python 调用 API、PHP curl、JavaScript fetch、超时与重试

更多文章 GET 示例接口

「」标签下的其他文章