API.PLUS 接入：Python、PHP、JavaScript 的调用差异与核对项
没有官方接口文档正文时，无法给出 API.PLUS 的真实端点、鉴权方式和参数。能确定的是三语言骨架的差异：Python 的 timeout 是连接与读取两段、PHP 需要分开设置连接超时与总超时并检查 curl_errno、JavaScript 的 fetch 只在传输层失败时 reject，HTTP 4xx/5xx 仍会正常返回。接入前须向官方文档核实 Base URL、鉴权、方法、响应结构、错误码与配额。
在没有官方接口文档正文可依据的情况下，无法给出 API.PLUS 的真实端点、鉴权方式、参数名与响应字段，这些只能以官方文档为准（待核实）。本文能确定的部分是：三种语言调用 HTTP 接口时，超时、错误判定和 JSON 解析的处理方式并不相同；把这三处写错，比写错业务参数更常见。文中代码均为未执行的占位示例，端点、密钥和参数名使用 api.example.com 与 YOUR_KEY 演示。
接入前必须先确认的几项#
下文所有骨架都留了同样的空位。缺任何一项，代码只能跑通"能发请求"，跑不通"能判断失败"。
| 项目 | 为什么影响代码 | 未确认时 |
|---|---|---|
| Base URL 与版本路径 | 决定拼接方式，避免路径重复或漏版本 | 待核实 |
| 鉴权方式 | 请求头、查询参数还是签名，决定是否要算摘要 | 待核实 |
| 请求方法与参数位置 | GET 查询串与 POST 体的编码方式不同 | 待核实 |
| 成功与失败的响应结构 | 决定能否用同一段代码解析 | 待核实 |
| 错误码、限流与配额口径 | 决定重试与告警策略 | 待核实 |
Python：超时写成一个数，等于只设了一半#
# 未执行示例，占位端点与参数，需按官方文档替换
import requests
BASE = "https://api.example.com/v1" # 占位
KEY = "YOUR_KEY"
resp = requests.get(
f"{BASE}/resource",
headers={"Authorization": f"Bearer {KEY}"},
params={"q": "demo"},
timeout=(3.05, 10), # (连接超时, 读取超时)，单位秒
)
resp.raise_for_status()
data = resp.json()
要点：timeout 传单个数值时，连接与读取共用同一上限，读取慢的接口容易被误判为失败；传元组才能分别约束。raise_for_status() 只对 HTTP 状态码抛错，接口返回 200 但体内是错误信息的情况，它不拦。最后，resp.json() 在响应不是 JSON 时会抛解析异常，HTML 错误页、网关拦截页都会触发，建议先看 Content-Type 再解析。
PHP：连接超时与总超时是两回事#
<?php
// 未执行示例，占位端点与参数
$ch = curl_init("https://api.example.com/v1/resource?q=demo");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_KEY"],
CURLOPT_CONNECTTIMEOUT => 3, // 建连阶段上限
CURLOPT_TIMEOUT => 10, // 整个请求上限
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$errno = curl_errno($ch);
要点：curl_exec() 在传输层失败时返回 false，此时 CURLINFO_HTTP_CODE 可能是 0，不能只看状态码判断成败；必须同时检查 curl_errno()。另外只设 CURLOPT_TIMEOUT 而不设连接超时，遇到不可达地址会一直等到总超时耗尽。
JavaScript：fetch 不把 404 和 500 当作失败#
// 未执行示例；Node 18+ 自带 fetch，浏览器同样可用
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 10_000);
try {
const resp = await fetch("https://api.example.com/v1/resource?q=demo", {
headers: { Authorization: "Bearer YOUR_KEY" },
signal: controller.signal,
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`); // 4xx/5xx 需自己判
const data = await resp.json();
} finally {
clearTimeout(timer);
}
要点：fetch 只在网络中断、DNS 失败、被 abort 等传输层问题时 reject；HTTP 404、500 都会正常 resolve，必须读 resp.ok 或 resp.status。浏览器端还多两条约束：跨域受 CORS 限制，能否直连取决于对方是否允许；在浏览器里放密钥等于公开密钥，公开客户端应走自己的服务端转发。
三语言共同的边界#
- 把失败分成三层分别处理：传输失败（超时、连接被拒）、HTTP 状态错误、业务错误（200 但体内标识失败）。三层混在一起，日志里就分不清是网络问题还是参数问题。
- 重试只对幂等请求开启，并且要有次数上限和退避；对非幂等请求自动重试可能造成重复写入或重复计费。
- 日志至少留下请求时间、耗时、HTTP 状态、业务错误标识和响应体片段，否则线上问题无法复现。
落地顺序#
- 先从官方文档抄下上表中的六项，写进配置，不要散落在代码里。
- 用一次最小请求确认鉴权与响应结构，再补业务参数。
- 补超时、状态判定与业务错误分支，最后才加重试与并发。
如果拿不到官方文档的正文，就停在第 1 步：此时任何"完整可运行示例"都只是猜测，不宜直接接入生产环境。
