版本与兼容承诺
v1
URL 即版本
主版本号在路径里（/api/v1/…）。同一主版本内只做向后兼容的增量：新增字段、新增端点、新增可选参数。
+
不做什么
不在 v1 内删除或重命名字段、不收紧校验、不改变已有字段含义。破坏性变更只出现在新主版本，并提前至少 90 天公告。
≡
客户端该怎么写
忽略未知字段（不要因为多了字段就报错）、不要依赖字段顺序、把 error 码当枚举用并保留默认分支——这样新增字段和新错误码都不会打断你。
从 www 旧路径迁移
www 与 api 当前服务同一批接口、同一份数据；限流按全局计数，两个入口不会各算一份。迁移只需换域名。
| 步骤 | 说明 |
|---|---|
| 改基址 | 把 https://www.quickfindapp.com 换成 https://api.quickfindapp.com，路径与参数一字不改。 |
| 跑一遍 /api/health | 确认新主机可达并列出上线的接口家族，这是唯一免鉴权的探活端点。 |
| 跑一遍 /api/v1/me | 确认密钥在新主机上生效、作用域与配额一致。 |
| 灰度切流 | 按 5% → 50% → 100% 切，切流期间盯 RateLimit-* 与 4xx/5xx 比例；www 旧路径保留可用，不必一次性切完。 |
先在本页试一遍
「在线试调用」页可以粘贴你的密钥直接发请求，不用写一行代码就能确认新主机的响应与旧主机一致。