版本兼容处理

组件开发规范中，版本兼容处理是确保系统稳定性和可维护性的关键环节。合理的版本管理策略能减少升级带来的风险，同时保证新旧功能的无缝衔接。

版本号规范

采用语义化版本控制（SemVer）是行业通用做法，格式为MAJOR.MINOR.PATCH：

// 示例版本号
const version = {
  major: 2,  // 不兼容的API修改
  minor: 1,  // 向下兼容的功能新增
  patch: 0   // 向下兼容的问题修正
};

MAJOR版本变更时需特别注意：

• 移除或修改公共API
• 变更核心功能逻辑
• 依赖的重大升级

向后兼容实现方案

接口适配层

// 新旧API适配示例
class APIVersionAdapter {
  static getData(params: NewParamsType): LegacyResultType {
    const newResult = NewAPI.getData(params);
    return {
      old_format_data: newResult.dataList,
      status: newResult.code === 200 ? 'success' : 'fail'
    };
  }
}

功能开关控制

// 功能开关配置
const featureFlags = {
  useNewComponent: localStorage.getItem('FEATURE_2023') === 'true',
  legacyFallback: true
};

function renderComponent() {
  return featureFlags.useNewComponent ? 
    <NewComponent /> : 
    <LegacyComponent />;
}

多版本共存策略

动态加载机制

// 按版本动态加载组件
async function loadComponent(version) {
  try {
    const module = await import(`./components/v${version}/Main.js`);
    return module.default;
  } catch (e) {
    console.warn(`Version ${version} not found, falling back`);
    return await import('./components/v1/Main.js');
  }
}

CSS命名空间隔离

// 不同版本的样式隔离
.v2-component {
  .button {
    // v2特有样式
  }
}

.v1-component {
  .button {
    // v1保留样式
  }
}

依赖管理实践

peerDependencies配置

{
  "peerDependencies": {
    "react": ">=16.8.0 <18.0.0",
    "react-dom": ">=16.8.0 <18.0.0"
  }
}

版本检测警告

// 运行时版本检查
if (React.version.startsWith('15.')) {
  console.warn(
    'Deprecated React version detected, please upgrade to v16+'
  );
}

废弃流程管理

渐进式废弃方案

// 分阶段废弃函数
function deprecatedMethod() {
  console.warn('This method will be removed in v3.0');
  return legacyImplementation();
}

// 配置废弃时间表
const deprecationSchedule = {
  'utils/old.js': {
    since: '2.1.0',
    removeIn: '3.0.0',
    alternative: 'utils/new.js'
  }
};

测试验证体系

版本矩阵测试

# CI测试配置示例
test_matrix:
  node: ["12.x", "14.x", "16.x"]
  react: ["16.8", "17.0", "18.0"]
  browser: ["chrome-latest", "firefox-latest"]

类型定义兼容

// 类型兼容性检查
type IsCompatible<T, U> = T extends U ? true : false;

type CheckParams = IsCompatible<LegacyParams, NewParams>;
// => 返回true表示类型兼容

文档记录规范

版本变更文档应包含：

1. 变更影响范围说明
2. 迁移指南（含代码示例）
3. 时间线规划
4. 紧急回滚方案

## [2.2.0] - 2023-05-15

### Breaking Changes
- `config.set()` 方法签名变更：
  ```diff
  - set(key: string, value: any)
  + set(options: { key: string; value: any; persist?: boolean })

Migration Guide

1. 替换所有set调用：

   // 旧写法
   config.set('theme', 'dark');
   
   // 新写法
   config.set({ key: 'theme', value: 'dark' });
   

## 错误监控与统计

实现版本使用情况追踪：

```javascript
// 版本使用统计上报
window.addEventListener('load', () => {
  navigator.sendBeacon('/analytics', JSON.stringify({
    componentVersion: window.__COMPONENT_VERSION,
    userAgent: navigator.userAgent
  }));
});

自动化工具集成

版本迁移脚本

// codemod转换示例
module.exports = function transformer(file, api) {
  const j = api.jscodeshift;
  
  return j(file.source)
    .find(j.CallExpression, {
      callee: { property: { name: 'set' } }
    })
    .replaceWith(path => {
      // 自动转换新旧API调用
    })
    .toSource();
};

依赖版本检查

# 使用npm-check-updates
ncu --dep dev,prod --upgrade

灰度发布控制

实现分阶段发布策略：

// 基于用户ID的灰度发布
function shouldEnableNewVersion(userId) {
  const hash = hashCode(userId);
  return hash % 100 < 10; // 10%流量
}

回滚应急预案

制定详细的回滚检查清单：

1. 数据库迁移回滚脚本
2. 静态资源版本回退
3. 配置项恢复机制
4. 客户端缓存清除方案

# 回滚示例命令
git revert v2.3.0
npm run rollback -- --target=2.2.5