主题
参数与编码
全站接口目前都是 GET,参数一律放在查询字符串里。这一页把容易踩坑的细节集中说明。
基本形式
https://api.sco1.cn/Interface/xxx/?参数1=值1&参数2=值2?之后是查询字符串,多个参数用&连接。- 参数名区分大小写,以接口详情页的参数表为准。
- 不传可选参数时使用接口默认值;不要传空字符串去「表示默认」。
中文与特殊字符必须编码
下面这些字符直接拼进 URL 会出错:空格、&、#、+、%、?、/,以及所有非 ASCII 字符。
js
// 正确
const q = encodeURIComponent('你好')
fetch(`https://api.sco1.cn/Interface/Pinyin/?text=${q}`)
// 错误:中文和空格未编码,& 会被当成参数分隔符
fetch('https://api.sco1.cn/Interface/Pinyin/?text=你好 世界&a=1')python
# requests 会自动编码,不要自己拼
requests.get(url, params={'text': '你好 世界'}, timeout=10)php
$url = 'https://api.sco1.cn/Interface/Pinyin/?text=' . rawurlencode('你好 世界');& 会截断参数值
& 是参数分隔符。如果值里本身含 &(例如一个网址),未编码时后面的内容会被当成另一个参数。这是调试中最常见的一类「参数明明传了却说缺参」。
常见类型
| 类型 | 写法 | 例子 |
|---|---|---|
| int | 十进制整数 | ?n=3、?page=2 |
| string | 文本,需编码 | ?symbol=XAU、?text=你好 |
| 枚举 | 参数表 enum 列出的值之一 | ?action=list、?name=ssq |
| 布尔 | 按参数表约定,通常用 1/0 或 true/false | ?seen=1 |
枚举值传错会返回 400,错误信息里一般会列出可选值。
数组与多值
只有当参数表明确说明支持多值时,才用重复参数名或逗号分隔:
?ids=1,2,3
?tag=a&tag=b不要自行假设接口支持数组形式,以详情页参数表为准。
空值与默认值
- 不传 = 使用默认值。
- 传
?n=(空字符串)不等于不传,有些接口会按0或非法值处理。 - 数字参数越界(例如
count要求 1–30 却传 100)会被接口截断或返回400。
key 参数
key 是全站通用的身份参数,不写在各接口的参数表里。需要时追加到查询字符串:
https://api.sco1.cn/Interface/GoldPrice/?symbol=XAU&key=YOUR_API_KEY如果同时有业务参数,用 & 连接即可。站内详情页的调试面板有独立的「API Key(可选)」输入框。详见 鉴权与 API Key。
超时与重试
- 依赖第三方数据源的接口可能有 10–30 分钟缓存,返回不一定实时。
- 建议给请求设置 10–15 秒超时。
- 遇到
429用指数退避重试;遇到502/503稍后重试,不要立刻死循环。