调用约定

很多接口问题不是参数写错，而是请求方式、缓存、Cookie 或代理没处理好。这一页整理这几类规则。

请求方式

为了兼容常见调用方式，大多数接口同时支持 GET / POST。实际使用时建议按场景选择：

• 简单调试：GET
• 密码、Cookie、复杂输入：优先 POST

时间戳与缓存

部分接口为了降低对上游的重复请求，会对相同 URL 在短时间内命中缓存。因此：

• 如果需要每次都重新请求结果，请追加时间戳参数
• 轮询二维码状态、刷新登录状态、需要强制刷新结果的接口，请务必这么处理

示例：

/simi/playlist?id=347230&timestamp=1503019930000

Cookie 传递

跨域请求或脚本调用时，Cookie 需要显式传入：

• 浏览器：确保请求携带凭证
• 程序化调用：把 cookie 放在 query 对象中
• 手动 HTTP 调用：把 cookie 作为 query/body 字段

登录态接口

如果接口说明中标注了“需要登录”或“登录后调用”，未携带有效 Cookie 时常见现象包括：

• 301
• 返回空数据
• 上游要求额外验证

遇到这类问题时，优先确认：

1. 是否真的带了 Cookie
2. 是否命中了缓存中的旧结果
3. 登录状态是否过期

代理、IP 与区域限制

项目支持通过 query 参数传入代理：

?proxy=http://host:port

在部分环境下，如果网易上游出现区域限制或 460 一类异常，可尝试传入国内 IP：

?realIP=116.25.146.177

其他常见约定

• 图片资源支持 ?param=宽y高 形式控制尺寸
• 分页接口的 more = true 通常表示还有下一页
• 可通过 noCookie=true 禁止接口头部携带 Cookie
• 可通过 ua 参数手动覆盖 User-Agent

当文档与实际行为不一致时

受上游策略变化影响，少数接口的参数、返回字段或可用性可能出现调整。若页面说明与实际调用结果不一致，建议优先以当前服务行为为准，以下情况尤其值得留意：

• 页面示例可访问，但旧参数名已经失效
• 返回字段与示例存在差异
• 上游接口已下线、限流，或需要额外验证

深入请求层

如果要改造请求层本身，比如换底层 fetch、配置重试与超时、做流量伪装、接入埋点，从 请求层架构总览 开始。