API 接入与调用教程（Python / PHP / JavaScript）：跨语言骨架与边界条件

用 Python、PHP 或 JavaScript 调用一个 HTTP API，骨架基本一致：确定端点、带上凭据、发出请求、区分成功与失败。真正的差异出现在错误怎么表达、超时怎么设、重试是否安全。需要先说明限制：本次写作材料只提供了“API 接入与调用教程（Python / PHP / JavaScript）”这一主题，没有 API.PLUS 的端点、鉴权字段、请求参数、配额与计费正文。因此下文是跨语言的通用接入骨架，凡涉及具体接口细节一律标为待核实，示例中的域名与密钥均为占位。

接入前需要先确认的三项信息#

这三项来自 API 文档而非语言选择，缺任何一项都无法写出可运行代码：

• 请求地址与方法：完整 URL、HTTP 方法，以及参数放在查询串还是 JSON 体里。
• 鉴权方式：是请求头里的 Bearer 令牌、自定义头部，还是签名参数。头部名称大小写与拼接格式必须照抄文档。
• 失败语义：哪些状态码可重试，限流时是否返回 Retry-After，错误体结构是什么。

API.PLUS 在这三项上的具体约定，本次材料未提供，属于待核实项，应以官方文档为准。

密钥放在服务端，这是唯一不能妥协的约束#

Python 与 PHP 通常运行在服务端，可以直接读取环境变量。JavaScript 要分开看：Node.js 服务端进程可用 process.env；浏览器端代码对用户完全可见，把密钥写进前端等于公开发布。若必须由浏览器发起调用，常见做法是自己后端做一层转发并附加凭据，而不是把密钥下发到页面。

判断标准很简单：这段代码会不会被打包发送到用户设备。会，就不能放密钥。

Python：用 requests 表达超时与异常#

import os, requests  # 未执行的示例，地址与密钥为占位

resp = requests.post(
    "https://api.example.com/v1/your-endpoint",   # 占位路径，待替换
    headers={"Authorization": "Bearer " + os.environ["API_KEY"]},
    json={"input": "demo"},
    timeout=(5, 30),   # (连接超时, 读取超时)，单位秒
)
resp.raise_for_status()      # 4xx/5xx 抛 HTTPError
data = resp.json()

Python 的惯例是用异常表示失败，raise_for_status() 把非 2xx 转成异常，网络错误则由 requests 抛出另一类异常。两者应分别捕获，因为前者说明请求到达了服务端，后者可能根本没建立连接。

PHP：curl 要区分传输失败与 HTTP 失败#

<?php
// 未执行的示例，地址与密钥为占位
$ch = curl_init('https://api.example.com/v1/your-endpoint');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode(['input' => 'demo']),
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT        => 30,
]);
$body   = curl_exec($ch);
$errno  = curl_errno($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($errno !== 0) { /* 传输层失败，可能未到达服务端 */ }
elseif ($status >= 400) { /* 服务端已响应，按错误体处理 */ }

PHP 里最常见的错误是只判断 $body === false，忽略了 4xx/5xx 时 curl_exec 仍可能返回正常字符串。状态码必须单独取。

JavaScript：fetch 不会因 4xx 自动拒绝#

// 未执行的示例，Node 18+ 内置 fetch，地址与密钥为占位
const resp = await fetch("https://api.example.com/v1/your-endpoint", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.YOUR_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: "demo" }),
  signal: AbortSignal.timeout(30_000),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();

fetch 只在网络层失败时拒绝 Promise，收到 500 也算“成功返回”。resp.ok 这一行不能省。超时方面，AbortSignal.timeout 在 Node 18+ 与较新浏览器可用，旧运行时需用 AbortController 手动计时，具体版本边界待核实。

共同边界：重试只对幂等请求安全#

三种写法都要面对同一组问题。超时必须显式设置，否则一个慢连接可能拖住整个工作进程；重试要有上限和退避，且只对可安全重复的请求使用——若一次调用会创建资源或扣费，盲目重试可能产生重复副作用；并发上限与配额取决于服务端约定，待核实后再定。

排查顺序建议固定下来：先确认请求确实发出（拿到状态码说明已到达服务端），再看状态码属于鉴权、参数还是限流，最后才怀疑代码。反过来先改代码，往往把配置问题掩盖成逻辑问题。