用户沟通

通过用户实际读的渠道告知弃用和破坏性变更。

为什么

仅在 changelog 沟通的弃用是无人听到的弃用 — 多数用户从不读 changelog。有效沟通用多渠道带升级紧急度：编程信号（Deprecation 头/console.warn）对活跃调用者不可错过、changelog 条目给勤奋者、按 API key 直接邮件 top 调用者给滞后者、博客给广众。原则是通知负担在你非用户 — 若用户被删除惊吓则你沟通失败，无论写多少 changelog。多渠道沟通带对高用量调用者直接触达才真驱动迁移。

何时使用

每次弃用和 sunset 时间线每阶段转换时。

如何做

1. 编程：弃用端点每响应带 Deprecation + Sunset + Link HTTP 头
2. 代码内：每次调用 console.warn / logger.warn（SDK）、@deprecated JSDoc（库）
3. Changelog："弃用"节含功能、替代、sunset 日期、迁移链接
4. 直接邮件：按 API key + 用量查 top 100 调用者；每人邮件个性化迁移指南
5. 博客：公开"即将破坏性变更"文广触达 + SEO
6. 仪表盘：弃用状态页（公开或认证）显示每功能 sunset 日期
7. 每阶段升级：公告（邮件全部）-> 提醒（邮件滞后）-> 限制（429 中警告）

示例

# 多渠道弃用沟通
# 1. HTTP 头（对活跃调用者不可错过）
res.set('Deprecation', 'true');
res.set('Sunset', 'Sat, 31 Dec 2024 GMT');
res.set('Link', '</v2/orders>; rel="successor-version"');

# 2. 代码内警告（SDK）
console.warn('[ez4code] /v1/orders 已弃用，2024-12-31 删除。迁到 /v2/orders — 见 https://docs.ez4code.com/migrate-v1-v2');

# 3. Changelog 条目
## 弃用（2024-06-01）
- `GET /v1/orders` — 用 `GET /v2/orders` 替代。2024-12-31 删除。
  迁移指南：docs/migrate-v1-v2.md

# 4. 直接邮件 top 调用者（脚本）
const topCallers = await db.query(`
  SELECT api_key, count(*) as calls
  FROM api_logs WHERE path LIKE '/v1/orders%'
  GROUP BY api_key ORDER BY calls DESC LIMIT 100`);
for (const c of topCallers) {
  await sendEmail(c.api_key_owner, 'migrate-v1-v2', { sunset: '2024-12-31' });
}

常见问题

⚠仅在 changelog 沟通 — 最可能坏的用户最不可能读它。
⚠泛泛"我们弃用一些 API"邮件无具体 — 用户不知是否影响自己故忽略。
⚠无对高用量调用者直接触达 — 按量 top 10 调用者坏得最响且最易识别。

最佳实践

✓用 4+ 渠道：HTTP 头、代码内 warn、changelog、直接邮件 top 调用者 — 冗余是重点。
✓直接邮件个性化带调用者具体用量（"你上周调 /v1/orders 12,000 次"）— 具体驱动行动。
✓通知负担在你 — 若用户被删除惊吓则你沟通失败，非他们没读。