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 的请求体格式、鉴权头名称、错误码含义与配额规则本次材料未提供,接入前请以官方文档逐项核对,不要直接套用文中的字段名。