通用接口格式

发起请求

Apihub 的开放接口，调用方式通常长这个样子（以天气实况接口为例）：

curl -X POST \
  "https://open.apihub.net/api/weather-basic/now" \
  -H "apihub-token: {{ apihub_token }}" \
  -H "Content-Type: application/json" \
  -d '{
    "lng": 116.40,
    "lat": 39.93
}'

HTTP method 是 POST，但每个接口也都兼容用 GET 方法发起请求。

在 url 中，隐藏着两个 路径参数。

weather-basic 是 api_code 参数的值，它以中横杆分割单词，同时也兼容 weather_basic 这种写成下划线的形式。

now 是 action 参数的值，根据具体的 api 而定。

Header 中传递 apihub-token 参数，作为接口请求的认证依据。

Body 里的 json 参数，是主要传参方式。但是简单的参数也可以在 queryParams 中传递。queryParams 和 jsonBody 中存在同名参数时，queryParams 的优先级更高。

处理返回值

返回值的格式，通常长这样：

// 成功
{
    "success": true,
    "trace": "c0f039d8219c11f09f814a73ab197607",
    "result": {
        "location": {
            "name": "福州",
            "path": "福州,福州,福建,中国"
        },
        "now": {
            "text": "阴",
            "code": "9",
            "temperature": "17"
        },
        "lastUpdated": 1745561261000
    }
}

// 业务异常
{
  "success": false,
  "trace": "64c7ddc2224211f0958b5e23dd3c76d7",
  "code": "INVALID_PARAMS",
  "msg": "参数异常",
  "detail": null
}

// 系统异常
{
  "success": false,
  "code": "UNKNOWN",
  "msg": "未知异常",
  "detail": "ZeroDivisionError('division by zero')"
}

接口调用失败时，

code 字段作为错误码，可以用作程序判断下一步操作的依据。

msg 可以作为展示给用户的提示信息。

detail 提供给开发人员，用于判断错误的具体原因。