一、前置思考

1.1 老旧项目的困境

典型画像:
  → 项目跑了 2-3 年, 技术栈停在上古版本
  → API 大量废弃 (Deprecated), 编译告警成堆
  → 代码风格混乱: JS 语法 + 无类型 + 全局状态
  → 每次升级系统版本都心惊胆战

硬撑的代价:
  → 新能力用不上 (新 API/新特性)
  → 兼容补丁越堆越厚 (技术债利息)
  → 人才流失 (没人愿意维护老代码)
  → 最终不得不"推倒重来" (最高成本)

1.2 升级改造的本质

改造不是"重写", 是"有序迁移":
  → 保持业务持续交付的前提下, 渐进升级
  → 每一小步: 可编译、可测试、可上线
  → 风险可控: 失败可回滚, 影响面最小化

原则: 业务优先, 技术让路
  → 改造期间新需求照常交付
  → 改造节奏不打断业务节奏

二、核心原理

2.1 API 废弃迁移

废弃 API 的三类处理:
  1. 有替代 → 迁移到新 API (如: 旧存储 → 新 KV API)
  2. 无替代 → 保留 + 封装兼容层
  3. 已移除 → 必须重写 (查迁移指南)

迁移流程:
  编译告警扫描 → 列出废弃清单 → 按影响排序
  → 逐个替换 → 回归验证 → 清告警

风险: 新 API 行为差异
  → 错误码/返回值/时序可能不同
  → 替换后必须跑完整回归

2.2 ArkTS 语法升级

JS → ArkTS 核心约束:
  1. 类型标注: 所有变量/参数/返回都要类型
  2. 无 any: 禁止 any, 用具体类型/泛型
  3. 对象字面量: 需要显式类型上下文
  4. 无解构赋值 (部分场景)
  5. 无未标注的对象方法

升级路径:
  1. 开启严格编译 → 收集全部报错
  2. 按错误类型批量修复 (类型补齐/any 替换)
  3. 引入类型定义: interface/type 覆盖数据模型
  4. 编译清零 → 运行回归

工具: 迁移辅助工具 + 静态检查逐项清零

2.3 架构重构策略

老旧架构特征 → 目标架构:
  全部逻辑在页面 → 三层分层
  全局状态散落 → 状态管理收敛
  直接依赖框架 → 依赖倒置 + 接口化
  模块不分家 → 按业务域拆分

策略: 绞杀者模式 (Strangler Pattern)
  → 新功能/新模块用新架构
  → 老模块逐步迁移到新架构
  → 老架构慢慢"被绞杀"直至消失
  → 全程业务不停, 系统平滑过渡

2.4 增量迁移与风险管控

增量迁移节奏:
  每次迭代带一部分迁移 (不超过整体 20%)
  → 改造与需求并行, 小步合入

风险管控四件套:
  1. 行为测试先行: 迁移前写契约测试
  2. 灰度发布: 新版本小流量验证
  3. 回滚预案: 一键回滚到迁移前版本
  4. 监控兜底: 崩溃/性能指标对比迁移前后

风险矩阵: 每项改造评估 影响面×概率
  → 高影响高概率: 分批拆解, 重点回归
  → 低影响: 快速批量处理

三、源码/API 深度解析

3.1 废弃 API 迁移示例

// 场景: 旧存储 API → 新 KV 存储 API

// ❌ 旧代码 (已废弃)
// preferences.get('user_name', (err, val) => { ... })

// ✅ 新代码 (推荐 KV Store)
import { preferences } from '@kit.ArkData';

// 迁移后: 类型化 + Promise + 新 API
async function migrateGetUserName(): Promise<string | null> {
  const ctx = getContext(this) as common.UIAbilityContext;
  const store = await preferences.getPreferences(ctx, 'user_store');
  const value = await store.get('user_name', '');
  return value as string;
}

// 兼容层 (未迁移的调用方)
// export function legacyGetUserName(cb: (v: string) => void): void {
//   migrateGetUserName().then(v => cb(v ?? ''));
// }
// → 调用方不用改, 实现换新

3.2 ArkTS 类型补齐示例

// ❌ 旧代码 (JS 风格, ArkTS 编译报错)
// const data = { name: 'x', age: 18 };      // 无类型字面量
// function getData() { return data; }        // 无返回类型
// const arr = [];                            // any[]

// ✅ 新代码 (ArkTS 合规)
interface UserInfo {
  name: string;
  age: number;
}

const data: UserInfo = { name: 'x', age: 18 };

function getData(): UserInfo {
  return data;
}

const arr: UserInfo[] = [];

// 修复策略: 先定义数据模型 interface
//   → 字面量补类型 → 函数补返回类型 → 泛型数组

3.3 增量迁移工程实践

// 绞杀者模式落地: 新旧并存
// 老模块 (legacy) 与新模块 (modern) 通过接口共存

// 接口定义 (契约)
export interface OrderService {
  getOrders(userId: string): Promise<Order[]>;
  createOrder(order: OrderDraft): Promise<Order>;
}

// 旧实现 (内部仍走老代码, 对外暴露新接口)
export class LegacyOrderService implements OrderService {
  async getOrders(userId: string): Promise<Order[]> {
    // 调用老逻辑 + 结果映射为新模型
    const raw = legacyGetOrdersSync(userId);
    return raw.map((r: LegacyOrderRow) => this.toOrder(r));
  }
  async createOrder(draft: OrderDraft): Promise<Order> {
    // ...
  }
}

// 新实现 (完全新架构)
export class ModernOrderService implements OrderService {
  // 新数据源 + 新逻辑
}

// 切换: DI 容器换实现, 调用方零改动
// di.bind<OrderService>('OrderService').to(LegacyOrderService);  // 迁移前
// di.bind<OrderService>('OrderService').to(ModernOrderService);  // 迁移后

四、企业级实战落地

4.1 升级改造路线图

阶段	内容	产出
体检	废弃扫描/类型告警/架构评估	改造清单 + 风险矩阵
地基	行为测试 + CI 门禁	回归保障
语法	ArkTS 类型补齐/编译清零	新语法基线
API	废弃 API 批量迁移	告警清零
架构	绞杀者模式模块化	新架构模块
收尾	老代码清理 + 文档	干净基线

4.2 完整示例：升级改造演示

@Entry
@ComponentV2
struct LegacyUpgradeDemo {
  @Local phase: string = '待开始';
  @Local progress: number = 0;
  @Local logs: string[] = [];

  private runUpgrade(): void {
    this.logs = [];
    this.progress = 0;
    this.phase = '体检';
    this.log('🔍 体检: 废弃 API 87 处 · 无类型变量 342 处');
    this.log('   架构评估: 页面直连数据库, 无分层');
    this.log('   风险矩阵: 5 项高影响, 需分批处理');

    this.phase = '地基';
    this.progress = 20;
    this.log('🧪 地基: 核心流程行为测试 45 条');
    this.log('   CI 门禁接入: 编译+单测+告警检查');

    this.phase = '语法';
    this.progress = 45;
    this.log('📝 ArkTS 升级: 定义 28 个 interface');
    this.log('   字面量补类型: 342 → 0');
    this.log('   any 替换: 完整类型化');
    this.log('   编译告警: 128 → 0');

    this.phase = 'API 迁移';
    this.progress = 70;
    this.log('🔁 API 迁移: 废弃 API 87 → 12');
    this.log('   存储迁移: 旧 Preferences → 新 KV');
    this.log('   回归: 全部行为测试通过');

    this.phase = '架构重构';
    this.progress = 90;
    this.log('🏗️ 绞杀者迁移: 订单模块 → 新架构');
    this.log('   接口契约 + DI 切换, 调用方零改动');
    this.log('   灰度 5% → 50% → 100%');

    this.phase = '收尾';
    this.progress = 100;
    this.log('✅ 收尾: 老代码清理 · 文档更新');
    this.log('   启动提速 22% · 崩溃率降 45%');
    this.log('   技术债清零, 新功能可并行开发');
  }

  build() {
    Column({ space: 12 }) {
      Text('⬆️ 老旧项目升级演示').fontSize(20).fontWeight(FontWeight.Bold)
      Text('阶段: ' + this.phase + ' · 进度: ' + this.progress + '%').fontSize(13).fontColor('#9A6700')

      Row({ space: 8 }) {
        Button('▶ 模拟升级流程').layoutWeight(1).height(40).fontSize(12)
          .onClick(() => this.runUpgrade())
        Button('清空').height(40).fontSize(12)
          .onClick(() => this.logs = [])
      }
      .width('100%')

      Scroll() {
        Column() {
          ForEach(this.logs, (l: string) => {
            Text(l).fontSize(11).lineHeight(18).fontColor('#24292F').width('100%')
          }, (l: string, i: number) => l + i)
        }.width('100%')
      }
      .layoutWeight(1).width('100%').scrollBar(BarState.Off)
    }
    .width('100%').height('100%').padding(16)
    .backgroundColor('#F6F8FA')
  }
}

4.3 升级改造清单

1. 体检先行: 废弃/告警/架构全面盘点
2. 测试打底: 行为测试是改造的安全网
3. 语法先行: 类型补齐再动架构
4. API 分批: 按影响面排序, 逐个替换验证
5. 绞杀者重构: 新旧并存, 逐步替换
6. 灰度+回滚: 每阶段验证, 失败可退

五、问题排查与性能优化

问题	原因	解决
编译报错海量	无类型代码太多	批量类型补齐脚本
行为差异	新 API 语义不同	行为测试 + 逐项回归
改造影响业务	节奏过快	小步迁移 + 并行交付
老代码删不掉	调用方未清	依赖图分析 + 清理
回归测试缺失	历史欠账	核心流程先补测试
团队抵触	风险担忧	灰度数据说话

5.1 迁移效率优化

1. 批量工具: 正则/脚本批量补类型
2. 告警清零作为门禁: 新增废弃告警直接拦截
3. 依赖图可视化: 明确重构顺序
4. 改造与需求绑定: 每次迭代带一部分
5. 团队轮岗: 全员参与, 积累迁移经验

六、高阶总结与最佳实践

1. 改造不是重写：绞杀者模式让新旧并存，业务不停、风险可控。
2. 测试是安全网：没有行为测试的改造，是拿业务做赌注。
3. 语法先行：类型补齐是 ArkTS 升级的地基，先清编译再谈架构。
4. API 分批迁：按影响面排序，逐个替换、逐个回归。
5. 灰度收尾：每个阶段小流量验证，失败一键回滚。

一句话记住：老旧项目升级 = 体检盘点 + 行为测试打底 + ArkTS 类型补齐 + 废弃 API 分批迁移 + 绞杀者模式架构重构，小步快跑、灰度验证、失败可退。