写给未来的代码：什么是 Legacy-Free Code？

把一个工程做到没有包袱，意味着你写下的每一行都不再被陈旧依赖、过时接口、浏览器旧特性、历史命名空间污染或同步阻塞 I/O 牵着鼻子走。很多团队把这种目标概括为 Legacy-Free Code。要弄清它的边界，先把两个常被混用的概念拆开：Legacy Code 与 Legacy-Free Code。

Legacy Code 在行业里的主流定义有两层含义。一层是常识版：用过时技术栈写成、还在服役、维护成本偏高的代码；它可能依赖淘汰的硬件、编译器、语言或旧版 API，这样的系统很难跟上新标准与新架构的节奏。IBM 的条目就给出了这样一个现代、务实的界定，并顺带提醒了成本、适配性、性能与合规等维度的隐患。(IBM) 另一层是工程实践版：Michael Feathers 在 Working Effectively with Legacy Code 一书里强调，Legacy Code 可以直接等同于“没有自动化测试的代码”。没有测试，任何修改都像赌运气；有了测试，行为才可验证、可演进。这个视角如今已被大量工程文章、播客和实践指南反复印证。(IBM, understandlegacycode.com, techleadjournal.dev)

从这个对照面反推出去，Legacy-Free Code 并不只是“没有历史”的代码，而是主动消除导致代码变旧的成因——技术与工艺两个层面都要治理。下面分层拆解它到底包含哪些要点、如何落地、怎样度量，以及给出若干可以运行的小脚本来辅助你把存量项目往这个目标推。

---

1) 概念锚点：把“无包袱”具体化

在具体框架的文档里，Legacy-Free Code 已经被给出了操作性极强的清单。例如 SAP UI5 的官方最佳实践把“无遗留”的目标浓缩为四条硬标准：不做同步代码与数据加载、杜绝全局命名空间、只用公开且未废弃的 API、符合 CSP（内容安全策略）约束。围绕这些目标，又列出如何异步化视图与组件、如何声明模块依赖、如何替换废弃的工厂方法、如何用工具链扫描与预加载等操作指南。这类条目非常适合拿来当项目体检表。(SAPUI5 SDK)

把这套清单推广到框架之外，我们可以把 Legacy-Free Code 提炼为三类原则：

• 向前演进优先：避免对旧平台特性的硬绑定，尽量基于现代标准（例如模块化、原生 fetch、Web 平台最新 API），并用语义化版本、弃用策略与迁移窗口把“旧接口的寿命”压到合理范围。(TiDB, unkey.com)
• 同步阻塞零容忍：主线程同步 I/O 会劣化用户体验，也在被浏览器持续收紧；把这类同步点从根上移除。(MDN Web Docs)
• 依赖可替换、边界可收缩：通过门面、适配器与反腐层把外部系统的“遗留信号”隔离在边界之外，用 Strangler Fig 这类迁移模式渐进替换旧实现。(Microsoft Learn, martinfowler.com)

有时把“无遗留”的感觉类比成硬件世界的 legacy-free PC 会更直观：那类机器干脆取消了软驱、串并口、ISA 总线等历史接口，只保留现代 I/O，因此更稳定也更易维护。软件上的 Legacy-Free Code 追求的是同一件事——与过去友好告别，而不是无限背兼容债务。(Wikipedia, AllBusiness.com)

---

2) 诊断单：你的代码为什么会“变旧”

把代码拖向“遗留”的常见诱因，基本都能落到下面几类：

• 同步阻塞路径：例如 XMLHttpRequest.open(..., false) 或 jQuery.ajax({ async: false })；现在已被明确标注为不推荐甚至弃用。(MDN Web Docs, Stack Overflow)
• 全局命名空间污染与隐式依赖：直接用全局对象找模块、或把第三方库当全局常量使用，破坏模块边界与可替换性。SAP UI5 对此有一整套替代方案与加载约定。(SAPUI5 SDK)
• 废弃 API 与内部不稳定接口：继续依赖“已经被标注为弃用”的接口，会在下一轮升级时直接踩雷；官方建议配合 linter 与运行时日志清理这类使用。(SAPUI5 SDK)
• 硬耦合到老平台：比如在浏览器里保守地为 IE11 写分支。框架层面已经宣布终止这些平台，继续保留只会放大维护面。(SAPUI5 SDK)

---

3) 手术方案：把项目拉回 Legacy-Free 的三步走

第 1 步：建立“行为护城河” 既然 Legacy Code 的关键问题是“改不动”，先用表征测试把现状钉住，再做改造。这种测试并不评判“对不对”，而是锁定“现在怎么做”。等异味被隔离后，再逐步重构与替换。IBM 的流程建议正是“理解代码 → 拆分治理 → 写表征测试 → 重构 / 迁移 / 重写 → 回归与文档”。(IBM)

第 2 步：用 Strangler Fig 渐进替换 不要幻想一次性重写，把流量按域或端点切给新实现，旧实现逐步抽空、下线。这是微软 Azure 架构中心与 Martin Fowler 都推荐的路径，优点是投资与收益可见且可控。(Microsoft Learn, martinfowler.com)

第 3 步：建设“不会再变旧”的机制 设计 API 的发布与弃用策略，用 MAJOR.MINOR.PATCH 的语义化版本配合弃用公告与迁移指南；数据库变更同样遵循兼容模式，减少破坏性修改。(TiDB, unkey.com)

---

4) 可运行的落地示例

4.1 把同步 XHR 迁移为 fetch（浏览器 / Node 皆可）

// sync_xhr_to_fetch.js
// 目的：演示把同步 XHR 改造成基于 fetch 的异步实现，解除主线程阻塞。

async function loadJson(url, opts = {}) {
  // 使用 AbortController 支持超时与取消，这些在同步 XHR 中要么不可用要么体验很差
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), opts.timeoutMs ?? 10000);

  try {
    const res = await fetch(url, { signal: controller.signal });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return await res.json();
  } finally {
    clearTimeout(timeout);
  }
}

// 简单演示：node 18+ 可直接运行；浏览器里在 devtools 里也能跑
(async () => {
  try {
    const data = await loadJson('https://jsonplaceholder.typicode.com/todos/1');
    console.log('[ok]', data);
  } catch (e) {
    console.error('[err]', e.message);
  }
})();

MDN 明确指出：同步 XHR 已被弃用，应采用异步方案；现代浏览器对主线程同步请求会给出显式警告或限制。上面的示例用 AbortController 兜住了取消与超时，等价需求在同步 XHR 中要么不可达、要么副作用明显。(MDN Web Docs)

4.2 一键巡检：用脚本扫出“遗留异味”

下面这个 Node.js 小脚本会递归扫描项目，找出同步 XHR、jQuery.ajax({ async:false })、典型全局入口与被弃用的 UI5 全局入口等高风险模式。你可以把它挂进本地 pre-commit 或 CI。

// legacy_free_check.js
// 用法：node legacy_free_check.js <path>
// 依赖：Node 16+，无第三方包
const fs = require('fs');
const path = require('path');

const ROOT = process.argv[2] || process.cwd();
const exts = new Set(['.js', '.ts', '.xml', '.html', '.json']);

const patterns = [
  { // XHR 同步打开
    id: 'sync-xhr',
    re: /XMLHttpRequest[\s\S]*?\.open\(\s*['"][A-Z]+['"]\s*,[\s\S]*?,\s*false\s*\)/i,
    why: '主线程同步 XHR 已弃用，需迁移到 fetch 或异步 XHR'
  },
  { // jQuery 同步
    id: 'jquery-async-false',
    re: /jQuery\.ajax\([\s\S]*?async\s*:\s*false/,
    why: 'jQuery 同步请求会阻塞 UI，且与现代浏览器策略相悖'
  },
  { // 典型全局查找控件（以 UI5 为例）
    id: 'ui5-global-core',
    re: /sap\.ui\.getCore\(\)/,
    why: '避免全局入口，使用模块化与依赖注入（参考 UI5 文档）'
  },
  { // 直接挂在 window 的全局库使用
    id: 'global-namespace',
    re: /\bwindow\.[A-Za-z_$][\w$]*/,
    why: '全局命名空间污染，建议改为模块导入或显式注入'
  }
];

function* walk(dir) {
  for (const name of fs.readdirSync(dir, { withFileTypes: true })) {
    const p = path.join(dir, name.name);
    if (name.isDirectory() && !['node_modules', '.git', 'dist', 'build'].includes(name.name)) {
      yield* walk(p);
    } else if (name.isFile() && exts.has(path.extname(name.name))) {
      yield p;
    }
  }
}

const hits = [];
for (const file of walk(ROOT)) {
  const text = fs.readFileSync(file, 'utf8');
  for (const p of patterns) {
    if (p.re.test(text)) {
      hits.push({ file, rule: p.id, why: p.why });
    }
  }
}

if (hits.length) {
  console.log('发现潜在遗留模式：');
  for (const h of hits) {
    console.log(`- [${h.rule}] ${h.file} —— ${h.why}`);
  }
  process.exitCode = 1; // 在 CI 中标红
} else {
  console.log('未发现已知遗留高风险模式 ✅');
}

与其事后救火，不如在每次提交就把异味卡住。同步 XHR 的危险性与浏览器弃用态，在 MDN 与社区问答里有详实注解；UI5 的文档则系统化给出了全局访问、模块依赖与弃用 API 的替代方案。(MDN Web Docs, Stack Overflow, SAPUI5 SDK)

4.3 一个极简的 Strangler Fig 网关雏形（本地可跑）

迁移时经常需要“部分流量走新实现”。不用额外依赖，你也能用 Node.js 写一个最小替换器：路径或版本前缀匹配命中新实现，其余回落到旧实现。真实项目里把两个 handler 换成调用不同后端即可。

// strangler_demo.js
// 用法：node strangler_demo.js，然后访问 http://localhost:3000/api/v1/hello 与 /api/v2/hello
const http = require('http');
const url = require('url');

function legacyHandler(req, res) {
  res.writeHead(200, { 'content-type': 'application/json' });
  res.end(JSON.stringify({ system: 'legacy', path: req.url }));
}

function modernHandler(req, res) {
  res.writeHead(200, { 'content-type': 'application/json' });
  res.end(JSON.stringify({ system: 'modern', path: req.url }));
}

http.createServer((req, res) => {
  const { pathname } = url.parse(req.url);
  if (pathname && pathname.startsWith('/api/v2/')) {
    return modernHandler(req, res); // 新实现接管 v2
  }
  return legacyHandler(req, res);   // 其余仍由旧实现处理
}).listen(3000, () => console.log('listening on http://localhost:3000'));

这种“缠绕树”式替换让你可以按端点逐步迁徙，性能、错误率与用户反馈都可控；微软与 Fowler 的材料都把它列为遗留系统现代化的首要模式。(Microsoft Learn, martinfowler.com)

---

5) 工程化清单：让代码长期保持 Legacy-Free

• 版本与弃用治理：明确 MAJOR.MINOR.PATCH 语义与弃用周期，给出替代方案、迁移指引与“日落”时间点，既保护旧客户端，又避免无限期背兼容债。(unkey.com)
• 平台策略：选用现代浏览器与运行时目标，避免为极少量旧平台插入大量分支；框架层面的“停止支持”应被视为信号，尽快清理相应代码。(SAPUI5 SDK)
• 工具化守夜：把静态扫描（如上面的脚本或框架自带 linter）、运行时日志级别、覆盖率与性能监控接入 CI，约束“同步 I/O、全局污染、弃用 API、环依赖”等问题在提交面被拦截。(SAPUI5 SDK)
• 数据与模式演进：数据库与消息模式也要遵循兼容演进，使用双写/灰度读取、版本化主题或列扩展策略，避免“大爆炸式”破坏性变更。(TiDB)
• 知识对齐：让团队共享对 Legacy Code 与测试护城河的认知，特别是“表征测试先行”的流程；没有自动化测试的代码将迅速回到“遗留状态”。(IBM)

---

6) 误区澄清

• “只要能跑就行”：能跑 ≠ 可演进。没有测试、靠全局与同步调用堆出的系统，会把未来的每一个需求都放大成风险事件。(IBM)
• “兼容越多越好”：历史兼容是资产，但无限制背负会把工程变成“考古现场”。硬件世界的 legacy-free 给我们的启发是：在明确的迁移路径与留存窗口之后，敢于切断。(Wikipedia)
• “重写最干净”：没有迁移策略的重写，常常是另一场灾难。以 Strangler Fig 为代表的增量替换，才更符合复杂系统的演进规律。(Microsoft Learn, martinfowler.com)

---

7) 一张随手可用的小抄

• 把同步 XHR 与 全局依赖当成一票否决项，先用脚本或 linter 扫出来，逐步清零。(MDN Web Docs, SAPUI5 SDK)
• 给每个潜在“危险修改”先补上表征测试，把“可改动”变成“可回归”。(IBM)
• 用 版本与弃用政策 管理 API 生命周期，让“旧东西的退场”可预期、可追踪。(unkey.com)
• 通过 Strangler Fig 做功能级迁移，流量按端点逐步切换。(Microsoft Learn, martinfowler.com)
• 借助框架的官方指南（如 UI5 的 Legacy-Free 清单）和工具链，减少自创轮子。(SAPUI5 SDK)

---

收束

Legacy-Free Code 不是炫技口号，而是可操作的工程目标：把阻碍演进的根因逐一制度化清理。当你用异步与现代 API 把主线程拉顺、用模块化与依赖注入把边界拉清、用测试把行为拉稳、用版本与弃用政策把时间轴拉直，再用一个渐进的迁移模式把历史平稳退场，你的系统就会越来越接近“写给未来”的状态。这个过程并不需要一次性翻天覆地，上面的脚本与示例足以作为起跑线。只要每次改动都让系统更容易变更、而不是更难，你就在把代码从“走向遗留”拉回“走向未来”。

——这，就是 Legacy-Free Code。