20-术语表与文档索引

项目：my-ts-axios ｜ 版本：v1.2 ｜ 生成日期：2026-10-06 ｜ 依据：源码分析

1. 本篇定位

这是整套 21 篇文档（0020）的最后一篇，承担两个收束职能。其一是术语表：把前 20 篇反复使用、但散落在各篇中的领域术语集中定义——每个术语给出精确定义、源码锚点与"详见篇目"，让新读者可以从任何一篇跳进来时都有统一的词汇表兜底。其二是索引：先给出 src/ 下全部源文件与篇目的反向映射（按文件查文档），再给出四条按任务组织的阅读路径（按目的查文档）。与前序篇目的分工是：本篇不引入任何新的分析结论，所有定义与指引都收束自《0019》已经论证过的内容，标注篇目引用而非重复论证。术语排序按"概念层级"组织（先架构级、再链路级、后工程级），检索建议用目录跳转。

2. 术语表

2.1 架构级术语

2.2 链路级术语

2.3 工程级术语

2.4 易混淆术语辨析

六组术语在阅读中极易互串，单独立一条辨析。其一，Cancel / CanceledError / isCancel：Cancel 是旧轨的取消原因对象（只有 message 字段，src/cancel/Cancel.ts），CanceledError 是新轨的取消错误（AxiosError 子类，code 固定 ERR_CANCELED），isCancel 是横跨两轨的判定函数——用 instanceof Cancel 判定会漏掉 signal 轨的拒绝值，用 isCancel 则两轨通吃；官方 v1 里 Cancel 是 CanceledError 的别名，本项目刻意保持两类（《13》D 级取舍）。其二，适配器与传输（transport）：适配器是 (config) => AxiosPromise 签名的库级抽象；transport 是 http 适配器内部的一个更小的替换点（config.transport，可整体替换 http/https 模块的调用者）——前者换"策略"，后者换"socket 来源"，不在一个抽象层级。其三，shim 与 stub 与 mock：shim 特指构建期替身（浏览器构建中顶替 Node 内置模块，调用即抛错）；stub 与 mock 是测试语汇（test/boot.ts 引入的 jasmine-ajax 属于 mock——接管真实 XHR 并回放响应）。三者的共同点是"占住接口的位置"，差异在生效时机：shim 在打包时决定、mock 在测试运行时接管。其四，exports:'default' 与 named exports：前者是 Rollup 对"源码只有默认导出"的 CJS 翻译策略（module.exports 直得函数），后者会产出 {default} 包装——本项目选前者并有坏包事故背书。其五，synchronous 拦截器与同步异常：synchronous 是注册选项（描述拦截器可同步执行），不是"错误同步抛出"的开关——同步快路径里拦截器抛错确实会同步抛出，但那是调用栈位置的副产品而非选项语义本身。其六，transformer 与 interceptor：转换器加工的是数据（data + headers，纯管道，无 reject 能力），拦截器加工的是链路环节（config/response，可以抛错、可以返回 rejected promise 改变控制流）；把"改个请求头"写成拦截器还是转换器，取决于要不要控制流能力。

3. 源码文件 ↔ 篇目反向索引

下表覆盖 src/ 目录全部 29 个源文件（实测清单；若以 30 计，差异或来自把目录本身计入，本索引以 find src -type f 的实际结果为准），给出每个文件的一句话职责与主要篇目落点。行号与行数以当前版本为准（行数见《07》各节标题）。按文件查文档时，先看"主要篇目"，需要更细的逐函数说明再看《07》对应小节。

4. 按任务阅读路径

四条路径的共性结构是"一篇 SOP 打头、源码锚点居中、质量闸门收尾"：SOP 告诉你步骤，源码锚点让你在改之前知道行为边界，质量闸门（覆盖率、CI、冒烟）替你验证改动没有破坏契约。路径之间可以交叉引用——例如路径一（新增适配器）走到"注册进注册表"一步时会自然需要路径四的准备清单，因为那已经是贡献代码。使用时不必线性读完，先找与自己任务同名的小节，沿其中的篇目引用按需跳转即可；每条路径的起点篇目都假设读者尚未读过任何文档，从零开始也不会迷路。若四条路径都不能覆盖你的任务，退回两篇总纲重读：《00》第 6 节的源码阅读路线（面向"读代码"）与本篇第 3 节的反向索引（面向"查文件"）——前者给顺序，后者给定位，两者组合等价于一份自导的阅读计划。

路径一：给库新增一个适配器（如 mock / http2）

起点《11-扩展开发指南》SOP 一（完整操作清单），配合顺序建议如下。第一步读《02-模块设计》第 5 节，理解 AxiosAdapter 签名与三适配器的横切对照表（取消/超时/进度/headers 在每个适配器的落点）。第二步以 src/core/adapters/xhr.ts（205 行，全库最短）为模板通读一遍，注意它对 settle 的调用与 cleanup 的幂等清理形态。第三步看 src/core/getAdapter.ts：新适配器要么在 knownAdapters 注册一个键（可被命名引用），要么只作为函数适配器由用户直接传入；注册时同步思考环境探测（xhr 的条件注册形态是范本，《16》ADR-005）。第四步读《09-测试与质量保障》5.1/5.5 节并仿写测试——xhr 系用 jasmine-ajax、http 系用真实本地服务器，你的适配器选哪条路。最后自查三件事：覆盖率门槛（ADR-010）是否会卡住新分支、若引入新的 Node 内置 API 是否需要同步 src/shims/node-builtins.ts（ADR-007 的同步契约）、新行为是否需要登记进《03》差异清单。收尾跑 npm test 与 npm run build，CI 会替你复验一遍。

路径二：排查"取消请求失效"

起点《12-FAQ与故障排查》2.4 节（Cancel/CanceledError/isCancel 的判定混淆是最常见根因），然后按数据流顺序排查。第一，确认判定姿势：两轨的 reject 值不同（Cancel 实例 vs CanceledError），用 axios.isCancel(e) 判定而不是 instanceof Cancel（《19》2.4 的行为对照）。第二，确认时序：取消发生在 dispatch 之前由 dispatchRequest.ts 第 5058 行的预检拦截，发生在请求进行中由适配器处理——若在 runWhen 过滤后的同步快路径里取消，注意预检同样生效但错误形态不同（同步抛出，见《16》ADR-003 后果）。第三，确认环境与轨道：Node 端 signal 取消走 http.ts 的 abortCleanups 机制（取消的总是"当前跳"重定向，见《07》4.2），浏览器端走 xhr.ts 的 processSignal；fetch 端三个中断源收敛进内部 AbortController（《07》4.3）。第四，检查一个隐蔽杀手：开发机代理环境变量会劫持 http 适配器请求使取消表现异常——测试环境由 test/boot.ts 第 2438 行剥离，运行环境需自查（httpAdapterEnvProxy.spec.ts 是验证范式）。第五，若需要"批量取消"，确认多个请求共享的是同一个 token（2.4 节示例），而不是各自 source。全部排除后仍复现，按《12》第 3 节的排查决策树走，并在《05》流程四的时序图上标注卡点。

路径三：修构建问题（产物形态 / 缺符号 / 互操作）

起点《14-配置与环境详解》全篇（rollup.config.mjs 逐段是第 2 节），它回答"构建配置每一行是什么"。典型三类问题的路径：产物导出形态不对（require 拿到 {default} 包装）→《16》ADR-008 与《12》2.2 节，确认 rollup 第 42 行 exports: 'default' 未被改动，并用 node scripts/smoke-dist.cjs 复验三种产物导出面；浏览器构建运行时抛"Node.js 内置模块 xxx 在浏览器构建中不可用" →《12》2.3 与《01》3.7 节，这是 shim 的正常防御抛错还是缺符号（http 适配器新用了未覆盖的内置 API），对照 src/shims/node-builtins.ts 的导出面与《17》3.1 节的 alias 机制定位；类型声明缺失或漂移 → package.json 的 build:types（tsc --declaration --emitDeclarationOnly）与 tsconfig（《14》3 节），diff dist/types/ 观察漂移面。构建问题修复后的固定动作：跑 npm run build 全链 + smoke-dist，确认四产物（cjs/esm/umd/types）全部通过——这套"以消费者身份检查自己"的流程正是坏包事故后建立的（ADR-008）。

路径四：给库贡献代码之前的准备

起点《00-项目总览》第 6 节的阅读路线（axios.ts → Axios.request → dispatchRequest/mergeConfig → 适配器 → helpers），然后按顺序补齐四块背景。其一，架构约束：《01》第 5 节的三条依赖规则（core 不 import axios.ts、适配器只依赖 helpers/cancel/settle/types、helpers 无状态）——任何 PR 的 import 面先对照这三条。其二，质量门槛：《09》全篇，重点是覆盖率四阈值（新分支必须配对测试）、boot.ts 的 jasmine 兼容层（不要动全局命名空间）、istanbul ignore 的受控豁免惯例（全库仅 3 处，勿扩散）。其三，流程与提交：《06》第 6 节的提交链路（husky/lint-staged/commitizen/commitlint）与 .github/workflows/ci.yml 的四步门禁——commit 信息不符合 conventional 规范会直接被拦。其四，边界清单：《13》全篇，避免与已登记债务撞车（例如想修 xhr 就地修改 headers 时，先看条目 5 的建议方案）；再看《16》的 12 条 ADR，理解"哪些是有意为之的取舍"（如 Cancel/CanceledError 双类并存是 D 级保留项，不要顺手合并）。准备就绪后按《11》SOP 六的完整验证清单执行：lint → test（覆盖率达标）→ build → smoke → examples:build，全绿再提交。

补充路径（速查）：新增配置项、性能优化

新增默认配置项走《11》SOP 三（类型声明 → defaults 默认值 → mergeConfig 策略选择 → 消费路径 → 测试五处齐全），合并策略语义的精读在《18》走读三。性能问题先读《10-性能设计与优化》第 6 节"已有实现的性能小结"确认是已知形态还是新问题，再按第 7 节的投入产出排序取建议；Promise 链构造成本的量化在《10》第 2 节，synchronous 快路径是现成的缓解手段（《19》2.2）。

5. 小结

至此 21 篇文档收束成一个闭环：《0006》建立"是什么"的全局图景，《0710》下沉到"每一行怎么工作"，《1115》面向"怎么用、怎么扩展、怎么排障"，《1620》补上"为什么这样设计、依赖是什么、代码长什么样、示例怎么跑"四个维度，而本篇把它们全部挂到一个可检索的词汇与索引系统上。三张索引各有分工：术语表解决"这个词什么意思"，反向索引解决"这个文件在哪几篇里被讲透"，任务路径解决"我想做 X 应该按什么顺序读"。最后重申整套文档的一条元约定（见《00》第 7 节）：所有结论均来自对源码的逐文件阅读，凡无法闭环处一律 ⚠️ 待确认 而非猜测——目前已登记的待确认项包括 transitional.silentJSONParsing 的消费点、FormSerializerOptions.metaTokens/maxDepth 的消费点、_requestForm 未走 env.FormData 是否有意，以及本篇新增的《19》2.2 节示例页文案与实际执行顺序的出入。这些标记既是诚实的边界，也是后来者最好的入手点。