Backstage 架构决策记录解读：ADR003 为何弃用默认导出（Default Exports）并全面采用具名导出-育师

Backstage 架构决策记录解读：ADR003 为何弃用默认导出（Default Exports）并全面采用具名导出

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

导读

本文深度解析 Backstage 项目架构决策记录（Architecture Decision Record，ADR）中的 ADR003：Avoid Default Exports and Prefer Named Exports。Backstage 是一个用于构建开发者门户（Developer Portal）的开源框架，其代码库横跨数百个 npm 包、数千个 TypeScript 模块（packages/与plugins/目录下的源码），模块导出风格直接影响整个生态的可维护性。读完本文，你将掌握：默认导出在 ESM 时代带来的具体问题、Backstage 确立的导出规范与例外场景、以及该决策在实际代码库中的落地痕迹与配套工具演进方向。

ADR 是什么：Backstage 架构决策的背景

在展开 ADR003 之前，有必要先理解它所处的制度框架。架构决策记录总览指出：Backstage 将项目中的重要架构决策以 ADR 的形式集中存放在docs/architecture-decisions/目录下，记录"永不删除"，但可以被新决策标记为 superseded（取代）或 deprecated（弃用）。每个 ADR 遵循 adr000-template 模板，采用经典的 "Context → Decision → Consequences" 三段式结构。

ADR003 正是这一制度下的产物——当 JavaScript 模块体系从 CommonJS 迁移到 ES Modules 时，Backstage 需要为全仓库的导出风格定下统一基调，于是形成了这份编号为 003 的决策记录。

Context：从 CommonJS 到 ES Modules 的范式转移

ADR003 首先回溯了历史语境。在 CommonJS 作为主要编写格式的年代，最佳实践是"一个模块只导出一件事"，即：

module.exports = ...

这种方式与 UNIX 哲学中"Do one thing well"（做好一件事）的理念相契合。消费方在使用时无需了解模块内部结构：

const localName = require('the-module');

而现在，ES Modules（ESM）已成为主要编写格式。ESM 带来了诸多好处，例如编译期导出校验（import 的符号必须在编译时就能解析确认）和标准定义的语义。ESM 也提供了一种与 CommonJS 默认导出类似的机制——"默认导出"，允许消费方这样写：

import localName from 'the-module';

这等价于：

import { default as localName } from 'the-module';

也就是说，默认导出本质上是一个名为default的具名导出，只是语法糖让使用者可以省略花括号并自行指定本地名称。正是这种"隐式映射"，埋下了 ADR003 所批判的一系列问题。

默认导出的五大问题：为什么要弃用

ADR003 引用了社区既有讨论（Nicholas C. Zakas 在 2019 年撰写的《Stop Using Default Exports in JavaScript Modules》）并做了归纳，总结出默认导出的五大问题：

1. 引入间接性，增加认知负担

默认导出鼓励开发者为模块随意创建本地名称，导致代码理解变慢。ADR 中给出的例子非常形象：

import TheListThing from 'not-a-list-thing';

TheListThing这个名字与模块实际导出的内容毫无关联，读者必须跳转到模块源码才能确认它到底是什么。这在大型代码库中会迅速累积为阅读成本。

2. 阻碍 IDE 自动重命名与重构

具名导出让符号名在"导出处"与"导入处"保持一致，IDE 可以可靠地追踪、重命名和重构符号。而默认导出允许每个消费方使用不同的本地名，导致 IDE 无法自动同步重命名。

3. 助长拼写错误

由于导入的成员名完全由消费方开发者自行定义，一旦拼错或命名不统一，错误会在代码审查中被反复忽略，且不产生编译期错误（因为本地名本来就可以随意取）。

4. 在 CommonJS 互操作中表现丑陋

在 Node/打包器的 CJS 与 ESM 互操作场景下，消费方必须手动指定.default属性。这种丑陋的写法往往被 Babel 的模块互操作逻辑隐藏，导致开发者对真实运行时行为产生误解。

5. 破坏再导出（re-export），引发命名冲突

当模块想要export * from './module'时，如果依赖的模块是默认导出，就需要手动为其命名，否则会与其他模块的默认导出发生冲突。这让批量转发导出变得困难重重。

具名导出的收益：可搜索、可追踪、可重构

与之相对，ADR003 明确指出采用具名导出能带来一系列实际收益：

IDE 工具链受益："Find All References"（查找所有引用）和"Go To Definition"（转到定义）等能力只有在符号名全局一致时才能充分发挥作用；
纯文本搜索更可靠：使用 grep 或仓库内搜索（如本仓库常用的 search_in_files 类工具）定位唯一符号时，具名导出的唯一名称让搜索结果准确、无噪声。

换言之，具名导出把"符号名"变成了一个可在全代码库内可靠引用的标识符，这是大规模 monorepo（Backstage 正是这种形态）工程化协作的基础。

Decision：决策本身与唯一例外

基于以上分析，Backstage 作出如下决策：

我们将停止使用默认导出，除非绝对必要——例如React.lazy动态加载的模块。

对于希望完全不用default关键字的场景，ADR003 给出了React.lazy的标准替代写法：

const Component = React.lazy(() => import('../path/to/Component').then(m => ({ default: m.Component })), );

这种写法通过显式地将具名导出包装为{ default: m.Component }对象，让消费方仍然使用具名导出风格，而把默认导出的适配工作收敛在动态加载这一处必要场景。

为什么 React.lazy 是例外

React.lazy的 API 契约要求传入的 Promise 解析结果为包含default属性的模块对象——这是 React 官方规定的接口形态，无法通过具名导出直接满足。因此 Backstage 将这类"框架强制要求默认导出"的场景认定为"绝对必要"的例外，并提供了上述 workaround 来最小化默认导出在业务代码中的扩散。

Consequences：迁移路径与工程落地

决策的第三部分是后果与执行承诺。ADR003 声明：

我们将积极从代码库中移除默认导出，并尽可能保持显式。

原文给出了一个典型迁移示例——连接（connected）组件的写法：

export const ConnectedComponent = connect(Component);

即：即使是高阶组件（HOC）包装后的产物，也使用具名导出而非export default connect(Component)，保证符号名在包装前后依然可追踪。

同时，ADR003 承诺：

我们将引入工具（如 lint 规则）来帮助迁移，逐步远离默认导出。

仓库实证：决策在 Backstage 代码库中的落地痕迹

ADR003 发布于 ES Modules 全面铺开时期，而本文所基于的仓库（Backstage 主仓库）正是这份决策的活样本。从源码中可以观察到决策的贯彻与例外并存：

例外场景的真实存在

默认导出并未在仓库中消失，而是集中在框架契约所要求的边界位置。例如：

packages/app/src/App.tsx 中export default app.createRoot();—— 这是 Backstage App 实例的入口导出，面向框架加载器的固定契约；
packages/backend/src/authModuleGithubProvider.ts 等后端模块入口，同样面向新后端系统的模块加载约定；
packages/cli-module-*系列中大量commands/*.ts与src/index.ts的默认导出，面向@backstage/cli的命令注册机制。

这些位置表明：当默认导出是框架/加载器约定的接口形态（"绝对必要"）时，ADR003 允许其存在；而普通业务组件、工具函数则严格遵循具名导出。

lint 工具层的强制执行

ADR003 承诺的"lint 规则"在仓库的 .eslintrc.js 中可以看到同源思路。例如根级 ESLint 配置通过no-restricted-syntax规则禁止 React 默认导入：

{ message: "React default imports are deprecated. Follow the x migration guide for details.", selector: "ImportDeclaration[source.value='react'][specifiers.0.type='ImportDefaultSpecifier']", },

虽然这针对的是import React from 'react'这一具体对象，但其"用 lint 规则约束导入/导出风格"的思路与 ADR003 一脉相承——借助静态检查在 CI 阶段拦截不规范写法，而不是依赖人工 review。

与 ADR004 的协同：可追踪的导出结构

值得注意的是，ADR003 并非孤立决策。紧邻的 ADR004：Module Export Structure 进一步规定了"每个导出符号都必须能通过 index 文件一路追踪到包根src/index.ts"，并要求 index 文件的再导出使用通配符或显式列举。两条 ADR 相互配合：

ADR003 解决"导出什么"（只导出具名符号，不用 default）；
ADR004 解决"从哪里导出"（每个符号都可沿 index 链追踪到包边界）。

两者共同服务于同一个目标：让@backstage/core-components这类拥有海量导出的库包，其公共 API 边界清晰、可审计、可重构。

实践建议：如何在你的 Backstage 插件中遵守 ADR003

结合 ADR003 的规范与仓库中的真实代码模式，在编写 Backstage 插件或自定义代码时可遵循以下清单：

普通组件、工具函数一律具名导出：

export const MyCard = () => { /* ... */ }; export function formatEntityRef(entity: Entity) { /* ... */ }

HOC 包装后保持具名导出：

export const MyConnectedCard = connect(MyCard);

唯一例外是框架要求的入口（如 App 根、CLI 命令注册、动态加载模块），此时接受export default；
React.lazy 场景使用 ADR003 的 workaround，把默认导出的适配收敛在.then()中：

const LazyComponent = React.lazy(() => import('./Component').then(m => ({ default: m.Component })), );

配合 ADR004：让每个导出的符号都能通过 index 文件追踪到包根，便于 grep 检索与 IDE 导航。

总结

ADR003 是 Backstage 在 ES Modules 时代对模块导出风格做出的关键架构决策：以"具名导出优先、默认导出仅限绝对必要"为原则，换取全代码库范围内符号的可搜索性、可追踪性与可重构性。从当前仓库源码看，这一决策已深入落地——日常业务代码几乎全部采用具名导出，默认导出只保留在框架契约所要求的入口位置；同时配合 lint 规则与 ADR004 的导出结构规范，形成了完整的"导出治理"体系。对任何在 Backstage 生态内开发插件或贡献代码的开发者而言，遵循这一约定都是让代码易于审查、易于检索、易于长期维护的务实之选。

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考