12.7.4 变更要广而告之——开发者沟通机制

一句话破题

变更通知的核心是"让用户无法忽视"——通过多渠道、多次、清晰地传达变更内容和影响。

沟通渠道矩阵

渠道	适用场景	频率
变更日志	所有变更	每次发布
邮件通知	重要变更	弃用公告时
控制台警告	开发者工具	每次调用
响应头	API 调用	每次调用
文档横幅	文档站点	弃用期间
社交媒体	公告	重大变更

变更日志格式

遵循 Keep a Changelog 规范：

# Changelog

## [2.0.0] - 2024-06-01

### Added
- 新增 `/api/v2/users` 端点，支持分页和过滤

### Changed
- 用户响应格式改为嵌套结构

### Deprecated
- `/api/v1/users` 将于 2024-12-31 下线

### Removed
- 移除 `/api/v0/*` 所有端点

### Fixed
- 修复用户搜索的性能问题

### Security
- 修复 CVE-2024-XXXX 安全漏洞

邮件通知模板

interface DeprecationNotice {
  feature: string;
  deprecationDate: Date;
  sunsetDate: Date;
  migrationGuide: string;
  affectedEndpoints: string[];
}

function generateDeprecationEmail(notice: DeprecationNotice): string {
  return `
    <h1>重要通知：${notice.feature} 即将弃用</h1>
    
    <p>尊敬的开发者，</p>
    
    <p>我们计划于 <strong>${notice.sunsetDate.toLocaleDateString()}</strong> 
    下线以下功能：</p>
    
    <ul>
      ${notice.affectedEndpoints.map(e => `<li><code>${e}</code></li>`).join('')}
    </ul>
    
    <h2>时间线</h2>
    <ul>
      <li>弃用开始：${notice.deprecationDate.toLocaleDateString()}</li>
      <li>完全下线：${notice.sunsetDate.toLocaleDateString()}</li>
    </ul>
    
    <h2>迁移指南</h2>
    <p>请参阅 <a href="${notice.migrationGuide}">迁移文档</a> 了解如何升级。</p>
    
    <h2>需要帮助？</h2>
    <p>如有问题，请联系我们的技术支持团队。</p>
  `;
}

控制台警告

function warnDeprecation(feature: string, alternative: string, sunset: Date) {
  if (process.env.NODE_ENV === 'development') {
    console.warn(
      `%c⚠️ 弃用警告`,
      'color: orange; font-weight: bold;',
      `\n\n"${feature}" 将于 ${sunset.toLocaleDateString()} 下线。` +
      `\n请迁移到 "${alternative}"。` +
      `\n\n详情请参阅：https://docs.example.com/migration`
    );
  }
}

// 在 API 调用时触发
export async function legacyGetUsers() {
  warnDeprecation('getUsers()', 'fetchUsers()', new Date('2024-12-31'));
  return fetch('/api/v1/users');
}

迁移指南结构

# 从 v1 迁移到 v2

## 概述
本指南帮助你将应用从 API v1 迁移到 v2。

## 破坏性变更清单
- [ ] 用户 ID 类型从 `number` 改为 `string`
- [ ] 响应结构从扁平改为嵌套
- [ ] 分页参数从 `page` 改为 `cursor`

## 逐步迁移

### 1. 更新类型定义

```typescript
// 旧版本
interface User {
  id: number;
  name: string;
}

// 新版本
interface User {
  id: string;
  profile: {
    displayName: string;
  };
}

2. 更新 API 调用

// 旧版本
const response = await fetch('/api/v1/users');

// 新版本
const response = await fetch('/api/v2/users');

常见问题

Q: 我可以同时使用 v1 和 v2 吗？

A: 可以，在迁移期间两个版本都可用。

需要帮助？

联系 developer-support@example.com

### AI 协作指南

- **核心意图**：让 AI 帮你撰写变更通知和迁移文档。
- **需求定义公式**：`"请帮我撰写 API v1 到 v2 的迁移指南，包括破坏性变更清单和代码示例。"`
- **关键术语**：`变更日志 (changelog)`、`迁移指南`、`弃用通知`

### 避坑指南

- **提前通知**：重大变更至少提前 3-6 个月通知。
- **多渠道触达**：不是所有人都会看邮件，使用多种渠道。
- **清晰的行动项**：告诉用户具体需要做什么，而不仅仅是"有变更"。
- **提供支持**：开放提问渠道，帮助用户解决迁移问题。