API.PLUS 接入与调用：Python、PHP、JavaScript 的通用骨架与核实边界

接入 API.PLUS 时，Python、PHP、JavaScript 的差异主要在 HTTP 客户端，而不在业务契约。先要从官方文档确认四件事：鉴权头名称与值的格式、端点路径、请求与响应字段、错误码与限额口径。本次参考材料只有主题标题，没有正文和官方链接，因此下面只给传输层骨架；具体路径、请求头和载荷字段需按文档替换，示例均未执行。

来源说明：本文未能核验 API.PLUS 的官方文档内容。端点、鉴权方式、计费、限流与可用性均待核实；不要把示例中的环境变量或路径当作真实接口。

先固定契约，再写代码#

语言示例只能解决“怎么发请求”，不能替代接口契约。动手前至少应确认：

• 鉴权：请求头名称是什么，值是原始密钥还是 Bearer <key>；测试与生产密钥是否分开。
• 请求：HTTP 方法、路径、Content-Type、必填字段与字段类型。
• 响应：成功结构、业务错误与 HTTP 状态码的对应关系、是否返回请求 ID。
• 边界：建议超时、限流维度、哪些错误可以重试、计费单位。

这些项目通常写在官方文档或控制台中；本次材料未提供，不能代为填写。

Python：显式超时，保留状态码#

适用环境为 Python 3.10 及以上、已安装 requests；以下示例未执行。

import os
import requests

BASE = os.environ["API_PLUS_BASE_URL"].rstrip("/")
HEADERS = {
    os.environ["API_PLUS_AUTH_HEADER"]: os.environ["API_PLUS_API_KEY"],
    "Content-Type": "application/json",
}

def call(path: str, payload: dict, timeout: float = 15.0):
    url = f"{BASE}/{path.lstrip('/')}"
    resp = requests.post(url, headers=HEADERS, json=payload, timeout=timeout)
    if resp.status_code >= 400:
        raise RuntimeError(f"HTTP {resp.status_code}: {resp.text[:300]}")
    return resp.json()

要点：timeout 不设置时，请求可能长期挂起；错误分支先保留状态码和响应体前若干字符，便于区分鉴权失败、参数错误与服务端错误。若官方要求 Bearer 格式，应在构造请求头时拼接，而不是把密钥直接当作头值。日志中不要打印完整密钥。

PHP：把传输错误和 HTTP 错误分开#

适用环境为 PHP 8.x 并启用 cURL 扩展；以下示例未执行。

<?php
$base = rtrim(getenv('API_PLUS_BASE_URL'), '/');
$key = getenv('API_PLUS_API_KEY');
$authHeader = getenv('API_PLUS_AUTH_HEADER');

function callApiPlus(string $base, string $path, array $payload, string $authHeader, string $key, int $timeoutSec = 15): array {
    $ch = curl_init($base . '/' . ltrim($path, '/'));
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => $timeoutSec,
        CURLOPT_HTTPHEADER => [
            $authHeader . ': ' . $key,
            'Content-Type: application/json',
            'Accept: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    ]);
    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $err = curl_error($ch);
    curl_close($ch);

    if ($body === false || $err !== '') {
        throw new RuntimeException('transport: ' . $err);
    }
    if ($status >= 400) {
        throw new RuntimeException("HTTP $status: " . substr($body, 0, 300));
    }
    return json_decode($body, true, 512, JSON_THROW_ON_ERROR);
}

curl_exec() 返回 false 表示传输层失败；HTTP 4xx/5xx 仍可能带回响应体。两层都检查，才能避免把网络故障误判为业务错误。

JavaScript：fetch 不会因 4xx/5xx 抛错#

适用环境为 Node.js 18 及以上（内置 fetch）；浏览器端仅作结构示意，不应放置密钥。以下示例未执行。

const base = process.env.API_PLUS_BASE_URL.replace(/\/+$/, "");
const key = process.env.API_PLUS_API_KEY;
const authHeader = process.env.API_PLUS_AUTH_HEADER;

async function callApiPlus(path, payload, timeoutMs = 15000) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);
  try {
    const res = await fetch(`${base}/${path.replace(/^\/+/, "")}`, {
      method: "POST",
      headers: {
        [authHeader]: key,
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify(payload),
      signal: controller.signal,
    });
    const text = await res.text();
    if (!res.ok) throw new Error(`HTTP ${res.status}: ${text.slice(0, 300)}`);
    return JSON.parse(text);
  } finally {
    clearTimeout(timer);
  }
}

fetch 只在网络失败时拒绝 Promise；收到 401、429 或 500 时仍会正常返回。必须检查 res.ok 或状态码。浏览器直连还会把密钥暴露给访问者，生产环境应通过自己的服务端转发，并在服务端完成身份校验与限额。

三种语言共用的失败处理#

• 重试只针对可恢复错误，并在确认请求幂等后进行；否则可能重复创建或重复计费。
• 退避加随机抖动，设置最大次数和总时限；不要在 401、403 上盲目重试。
• 日志记录状态码、耗时、重试次数和请求 ID（若响应提供），不记录完整鉴权头和敏感载荷。
• 把官方错误码映射成内部错误类型，不要三种语言各写一套互不兼容的错误壳。

密钥放在哪里#

密钥只应存在于服务端环境变量或密钥管理系统中，不进入前端代码、仓库和构建产物。需要浏览器调用时，让浏览器请求自己的后端，由后端附加 API.PLUS 凭据，并在后端完成鉴权、限流和审计。至于 API.PLUS 的密钥轮换、作用域与配额规则，需查官方控制台和文档；本次材料不足以确认。

先用一个最小请求验证“鉴权、请求、错误分支”三段链路，再补超时、重试与日志，比一次性封装完整 SDK 更稳妥。待官方契约核实后，把示例中的占位配置替换为真实值即可。