罗罗编程学习记录
本页内容 展开查看

03.3.1.5 工程实践与声明文件

所属:全栈开发面试题库 / 03 前端基础与 Web 开发 / 03.3 TypeScript / 03.3.1 类型系统与工程实践

03.3.1.5-001 .d.ts 声明文件有什么作用?

一句话结论

.d.ts 只包含类型声明、不包含运行时实现,用于描述已有 JavaScript 库、全局变量与模块的类型形状,供编译器检查与编辑器提示。

概念解释

  • 声明文件编译后不生成对应 JS。
  • 可手写描述第三方无类型包,也可由 TS 编译自动生成。
  • 项目内类型约定可放在 types/ 目录并被 tsconfig 包含。

原理流程

  1. 为模块/全局对象写类型声明。
  2. 编译器在解析导入与全局引用时读取声明。
  3. 匹配调用处类型并报错或提示。

代码 / 示例

// global.d.ts
declare const APP_VERSION: string;

declare module "legacy-lib" {
  export function format(input: string): string;
}

常见误区

  • 误区:.d.ts 里可以写运行时逻辑;正解:它只放类型与声明,实现必须在 JS/TS 源码中。
  • 误区:声明文件会被打包进产物;正解:类型声明在编译期擦除,不进入运行时包。

追问

  • Q:库发布时如何让消费者拿到类型? A:开启 declaration 编译生成 .d.ts,并在 package.json 的 types 字段指向入口声明。
  • Q:项目内全局类型放哪里? A:放被 tsconfig 包含的 .d.ts 文件,避免在每个文件重复声明。

03.3.1.5-002 declare module 如何描述与扩展模块?

一句话结论

declare module "包名" 为没有类型的第三方包写整体类型声明;在已存在模块声明内追加成员则属于模块扩展(增强),需遵循对应模块系统规则。

概念解释

  • 缺失类型包用 declare module 兜底,避免导入报错。
  • 扩展现有库类型(如给 window 加字段)用声明合并或模块增强。
  • 模块声明放在被 tsconfig 包含的 d.ts 中。

原理流程

  1. 定位导入的模块名。
  2. 用 declare module 导出函数/对象/类型签名。
  3. 调用处按声明获得类型提示。

代码 / 示例

declare module "legacy-utils" {
  export function debounce<T extends (...args: any[]) => any>(
    fn: T, wait: number
  ): T;
  export const version: string;
}

常见误区

  • 误区:declare module 能补全运行时缺失的导出;正解:它只描述类型,运行时不存在的导出仍会报错。
  • 误区:在模块文件里随便写 declare module 就能增强全局;正解:全局增强与模块增强写法和位置不同,需按模块系统确认。

追问

  • Q:包自带类型与本地声明冲突怎么办? A:本地声明不应覆盖官方类型,优先修复类型缺口或提交类型包。
  • Q:类型声明里能引用项目类型吗? A:可以 import 项目类型,但需注意声明文件的模块隔离边界。

03.3.1.5-003 三斜线指令 /// <reference> 用于什么?

一句话结论

三斜线指令用于在声明文件中引用其他类型文件、类型包或 lib 类型,是声明之间显式依赖的方式;现代工程更多用 import type 替代大部分场景。

概念解释

  • <reference path="..."> 引用本地声明文件。
  • <reference types="..."> 引用 @types 包。
  • 指令必须出现在文件顶部、其他语句之前。

原理流程

  1. 在 d.ts 顶部写三斜线引用。
  2. 编译器加载被引用的类型声明。
  3. 当前声明可使用其中导出的类型。

代码 / 示例

/// <reference types="node" />
/// <reference path="./models.d.ts" />

declare namespace App {
  const env: NodeJS.ProcessEnv;
}

常见误区

  • 误区:三斜线可以放在文件任意位置;正解:必须位于所有语句之前,否则不生效。
  • 误区:普通业务文件应大量使用三斜线;正解:模块内依赖优先用 import/import type,三斜线主要用于声明文件。

追问

  • Q:types 与 path 引用区别? A:types 指向类型包,path 指向本地声明文件路径。
  • Q:skipLibCheck 与三斜线有关系吗? A:无关,skipLibCheck 跳过对声明文件内部的类型检查。

03.3.1.5-004 import type、export type 与隔离模块有什么关系?

一句话结论

import type/export type 只导入导出类型、编译后擦除;开启 isolatedModules 后,文件转译时无法跨文件判断导入是否为类型,必须显式区分类型导入与值导入。

概念解释

  • 普通 import 可同时带值与类型;type 限定符只保留类型用途。
  • isolatedModules 要求每个文件能独立转译,避免类型被误当运行时值移除。
  • re-export 类型需用 export type。

原理流程

  1. 区分导入是值、类型还是二者兼有。
  2. 类型依赖用 import type,避免打包残留。
  3. 隔离模块下编译器强制显式标注类型导入。

代码 / 示例

import type { User } from "./user";
import { createUser } from "./user";

export type { User };
export { createUser };

常见误区

  • 误区:isolatedModules 下普通 import 类型也能正常擦除;正解:转译器看不到跨文件类型信息,需 import type 显式标注。
  • 误区:export type 与普通 export 完全等价;正解:隔离模块下 re-export 类型必须用 export type,否则可能被当作值导出。

追问

  • Q:esModuleInterop 与类型导入有关吗? A:无关,它处理 CJS/ESM 默认导入互操作,类型导入管的是编译期擦除。
  • Q:Vite/esbuild 等转译器对 isolatedModules 的要求? A:默认按单文件转译,行为属工具版本相关,需对照当前构建配置确认。

03.3.1.5-005 tsconfig 有哪些决定类型行为的关键选项?

一句话结论

strict 控制检查严格度,target/module/moduleResolution 控制产物语法与模块解析,esModuleInterop 控制 CJS 互操作,skipLibCheck 跳过声明文件内部检查,noEmitOnError 控制报错是否阻断产物。

概念解释

  • strict 是一组严格检查总开关。
  • moduleResolution 决定如何按模块说明找文件(bundler/node16/classic 等)。
  • 选项组合需与运行环境(浏览器/Node/打包工具)匹配。

原理流程

  1. 按目标环境设置 target 与 module。
  2. 开启 strict 收紧类型检查。
  3. 配置模块解析与互操作选项,消除导入类型偏差。

代码 / 示例

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "noEmit": true
  }
}

常见误区

  • 误区:strict 只影响空值检查;正解:它包含一组检查项,见 03.3.1.1-011。
  • 误区:moduleResolution 选什么都一样;正解:解析规则不同会影响类型能否找到,需与 module 和打包工具匹配。

追问

  • Q:noEmit: true 下类型检查怎么做? A:tsc --noEmit 只做类型检查不产 JS,适合 CI 与编辑器校验。
  • Q:如何确认某个选项在所用 TS 版本中的行为? A:对照官方文档对应版本,版本新增选项需实测确认。

03.3.1.5-006 第三方类型包 @types 如何组织与引用?

一句话结论

DefinitelyTyped 维护的类型包以 @types/包名 发布,TS 默认自动包含;项目也可用 types 字段限定加载哪些类型包,或在本地写声明兜底。

概念解释

  • 包自带类型时优先使用包内 types/typings 字段。
  • 无类型包安装对应 @types/包名。
  • types 编译选项可限制自动加载的全局类型包。

原理流程

  1. 检查依赖包是否自带类型。
  2. 缺失时安装 @types 包或本地 declare module。
  3. 编译器自动解析导入的类型声明。

代码 / 示例

npm i -D @types/lodash
{ "compilerOptions": { "types": ["node", "jest"] } }

常见误区

  • 误区:所有第三方包都有 @types;正解:部分包无类型,需本地声明或换有类型替代。
  • 误区:在 types 里列出所有 @types;正解:列出后未列出的全局类型包不会自动加载,按需取舍。

追问

  • Q:包自带类型与 @types 冲突时以谁为准? A:包内声明优先,具体解析规则按 moduleResolution 版本行为确认。
  • Q:本地声明文件会被打包进发布物吗? A:库发布需通过 declaration 配置生成类型,本地兜底声明不应替代正式类型产物。

03.3.1.5-007 全局环境类型(window、document、process)从哪里来?

一句话结论

浏览器全局类型来自 TS 内置 DOM lib;Node 全局类型来自 @types/node;项目自定义全局变量在 d.ts 中用 declare const/interface 声明并确保被包含。

概念解释

  • lib 选项决定内置类型集合(DOM、ES 版本、WebWorker 等)。
  • process 不是浏览器内置,需 Node 类型包。
  • 扩展 window 接口用声明合并追加字段。

原理流程

  1. tsconfig lib 加载 DOM/ES 类型。
  2. 安装并引用 Node 类型包获得 process。
  3. 自定义全局在 d.ts 中声明,编译器纳入作用域。

代码 / 示例

// env.d.ts
interface Window {
  myApp: { version: string };
}

declare const process: NodeJS.Process;

常见误区

  • 误区:浏览器里直接用 process 有类型;正解:process 是 Node 类型,浏览器环境需类型隔离与环境判断。
  • 误区:给 window 加字段直接赋值即可有类型;正解:需先在接口合并中声明该字段。

追问

  • Q:lib 与 @types 区别? A:lib 是 TS 内置基础类型(DOM/ES),@types 是第三方社区类型包。
  • Q:多端环境类型冲突怎么处理? A:按工程拆分 tsconfig,分别加载对应 lib 与类型包。

03.3.1.5-008 类型约定与运行时校验的边界在哪里?

一句话结论

TypeScript 类型只在编译期约束约定,运行时不拦截非法值;跨边界输入(接口响应、表单、存储、消息)必须做运行时校验,可用手写守卫或 schema 库把类型与校验规则关联。

概念解释

  • 编译期类型被擦除,运行时对象形状不受类型保护。
  • 可信内部代码可依赖类型,不可信外部输入必须校验。
  • schema 库可从校验规则推导类型,减少重复标注。

原理流程

  1. 划定可信边界:内部函数、模块间调用。
  2. 不可信输入进入时执行守卫/schema 校验。
  3. 校验通过后类型收窄到约定类型再使用。

代码 / 示例

function parseUser(json: string): User | null {
  const raw = JSON.parse(json) as unknown;
  if (typeof raw === "object" && raw !== null && "id" in raw) {
    return raw as User; // 复杂校验应交给 schema 库
  }
  return null;
}

常见误区

  • 误区:标注了 User 接口,接口返回什么都安全;正解:运行时响应形状可能与类型不符,需校验。
  • 误区:类型断言能替代校验;正解:断言不产生运行时判断,错误会延迟到使用时暴露。

追问

  • Q:schema 库如何做到类型与校验一致? A:解析校验定义推导 TS 类型,运行时按同一套规则校验,避免两边手写漂移。
  • Q:哪些场景最容易漏校验? A:URL 参数、localStorage 读取、postMessage、第三方回调数据。

03.3.1.5-009 库项目如何发布类型声明?

一句话结论

开启 declaration(必要时 declarationMap)编译生成 .d.ts 与 source map,package.json 的 types/typings 指向入口声明文件,消费者导入即可获得类型。

概念解释

  • declaration 为每个源文件生成对应声明文件。
  • declarationMap 支持跳转到原始源码。
  • 类型产物需与 JS 产物一起发布到包目录。

原理流程

  1. 配置 declaration 输出。
  2. 编译生成 JS 与 d.ts。
  3. package.json 声明 types 入口,消费者解析类型。

代码 / 示例

{
  "compilerOptions": { "declaration": true, "declarationMap": true, "outDir": "dist" }
}
{ "types": "dist/index.d.ts" }

常见误区

  • 误区:只发布 JS 消费者也能拿到类型;正解:缺 d.ts 时导入会提示无类型,需 any 兜底。
  • 误区:声明文件随源码打包进运行时包;正解:d.ts 不进入浏览器/Node 运行时,仅供工具链读取。

追问

  • Q:emitDeclarationOnly 用于什么? A:只生成声明文件不产 JS,适合类型产物单独发布场景。
  • Q:内部类型需要导出吗? A:公共 API 用到的类型应导出,私有实现类型可不暴露。

03.3.1.5-010 枚举、as const 与常量对象的类型如何选择?

一句话结论

有限且需要运行时可遍历的取值集合可用枚举;纯类型层面的固定取值用字面量联合;不希望字面量被拓宽、属性保持只读的对象用 as const。

概念解释

  • 枚举编译为运行时对象,有反向映射与开销。
  • 字面量联合是纯类型,无运行时代码。
  • as const 收紧推断但不冻结运行时对象。

原理流程

  1. 判断是否需要运行时遍历该集合。
  2. 需要运行时对象用枚举,只约束类型用联合。
  3. 固定配置对象用 as const 收紧字面量与只读。

代码 / 示例

type Role = "admin" | "guest";            // 纯类型
enum Status { Todo = "TODO", Done = "DONE" } // 运行时对象

const routes = { home: "/", admin: "/admin" } as const;
type Route = typeof routes[keyof typeof routes];

常见误区

  • 误区:as const 会在运行时冻结对象;正解:只改类型,冻结需 Object.freeze。
  • 误区:枚举比字面量联合更安全;正解:二者都约束取值,枚举额外带来运行时对象与双向映射。

追问

  • Q:数字枚举反向映射是什么? A:编译后同时存键→值与值→键,字符串枚举无反向映射。
  • Q:const enum 跨文件使用注意什么? A:内联行为受 isolatedModules 等配置影响,细节按版本确认。

03.3.1.5-011 如何在 CI 中做类型检查?

一句话结论

用 tsc --noEmit(或构建工具的类型检查模式)在流水线单独跑类型检查,类型错误即阻断合并;不依赖打包工具隐式转译来发现类型问题。

概念解释

  • --noEmit 只检查不产 JS,速度适合 CI。
  • 项目已有构建流程时可在脚本中先跑类型检查再打包。
  • 编辑器类型提示不能替代流水线门禁。

原理流程

  1. 脚本定义 type-check: tsc --noEmit。
  2. CI 拉取依赖后执行类型检查。
  3. 出现 error 非零退出,阻断后续部署。

代码 / 示例

{
  "scripts": {
    "type-check": "tsc --noEmit",
    "build": "npm run type-check && vite build"
  }
}

常见误区

  • 误区:打包成功就代表类型没问题;正解:esbuild/vite 转译默认不做完整类型检查。
  • 误区:CI 类型检查可以跳过历史报错;正解:应清零错误或按子项目拆分渐进修复。

追问

  • Q:大型项目类型检查慢怎么办? A:按项目引用拆分 tsconfig、增量构建,或限制检查范围,具体方案按工具版本确认。
  • Q:类型检查报错与 lint 报错如何分工? A:tsc 管类型正确性,lint 管代码风格与可疑模式。

03.3.1.5-012 存量 JS 项目如何渐进迁移到 TS?

一句话结论

先开 allowJs 让混合共存,用 checkJs 与 JSDoc 标注给关键文件补类型,再逐个改名 .ts;不要求一次性全量转换,迁移文件按风险与价值排序。

概念解释

  • allowJs 允许 TS 工程包含 JS 文件。
  • checkJs 对 JS 文件也做类型推断检查。
  • JSDoc 注解可在不改文件后缀的情况下提供类型信息。

原理流程

  1. 开启 allowJs,工程可同时识别 JS/TS。
  2. 核心模块先补 JSDoc 或迁移 .ts。
  3. 逐步打开 checkJs 收紧 JS 文件检查。

代码 / 示例

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "jsx": "react-jsx"
  }
}
/** @param {string} name @returns {User} */
function create(name) { return { name }; }

常见误区

  • 误区:迁移必须把所有文件改成 .ts;正解:可长期混合存在,按优先级逐文件推进。
  • 误区:checkJs 一开就能发现所有问题;正解:JS 推断能力有限,关键类型仍需 JSDoc 或迁移后标注。

追问

  • Q:JS 文件里 import TS 类型可行吗? A:需 JSDoc @type 或 allowJs 配合,跨文件类型引用按配置确认。
  • Q:迁移中 any 如何控制? A:记录 any 位置与替换计划,逐步收窄到 unknown 与具体类型。

03.3.1.5-013 类、接口与抽象类在工程中如何约定使用?

一句话结论

接口定义对象结构契约,类负责实现与实例逻辑,抽象类约束子类共同行为与模板方法;implements 检查类是否满足接口结构,不影响运行时继承关系。

概念解释

  • 接口只描述形状,可被类 implements。
  • 抽象类不能实例化,可含实现与抽象方法。
  • 工程中优先用接口定义跨模块契约,降低耦合。

原理流程

  1. 跨模块约定用接口描述入参与返回结构。
  2. 实现类 implements 接口保证结构匹配。
  3. 共用行为与模板步骤用抽象类抽取。

代码 / 示例

interface Repository<T> {
  find(id: string): Promise<T | null>;
}

class UserRepository implements Repository<User> {
  async find(id: string) { return null; }
}

abstract class BaseRepo<T> {
  abstract find(id: string): Promise<T | null>;
}

常见误区

  • 误区:implements 建立运行时继承;正解:它只做编译期结构检查,原型链关系由 extends 决定。
  • 误区:接口可以写实现方法;正解:纯接口无实现,复用逻辑放抽象类或工具函数。

追问

  • Q:接口与抽象类怎么选? A:行为多继承视角用接口,需要共享实现模板用抽象类。
  • Q:类实现接口时缺方法会怎样? A:编译报错,提示缺少接口成员实现。

03.3.1.5-014 类型与模块、命名空间如何组织?

一句话结论

业务类型按模块目录就近放置,公共共享类型抽至 types/ 或共享包;现代模块系统下少用 namespace 组织代码,避免类型与运行时模块混淆。

概念解释

  • 类型随功能模块内聚,降低跨目录依赖。
  • 共享类型集中导出,避免多处重复定义。
  • namespace 主要用于声明文件组织,业务代码优先 ES 模块。

原理流程

  1. 识别类型使用范围:模块内、跨模块、全局。
  2. 模块内类型放就近文件并导出。
  3. 公共类型汇总到共享类型入口统一导出。

代码 / 示例

src/
  users/
    types.ts        # 模块内类型
  shared/
    types/          # 跨模块公共类型
      api.ts

常见误区

  • 误区:所有类型都放一个全局 d.ts;正解:就近内聚,仅全局/环境声明放 d.ts。
  • 误区:namespace 可替代 ES 模块;正解:namespace 是 TS 早期组织方式,现代工程优先 import/export。

追问

  • Q:循环引用类型依赖如何避免? A:调整类型归属方向,公共抽取到第三处,打破模块环。
  • Q:类型文件需要运行时导出吗? A:纯类型用 export type,避免被当作运行时值打包。

03.3.1.5-015 高频类型报错分别是什么原因?

一句话结论

常见报错:类型不兼容(来源无法赋值给目标)、属性不存在(键不在类型上)、参数数量/类型不符、隐式 this(未标注 this 被推断为 any)、找不到模块(缺类型包或声明)。

概念解释

  • 赋值兼容按结构可赋值性判断。
  • 属性不存在多为类型过宽或字段名拼写错误。
  • 函数参数不匹配检查参数数量与类型方向。

原理流程

  1. 定位报错指向的类型位置。
  2. 对照来源与目标类型结构差异。
  3. 收窄类型、补声明或修正字段名后消除报错。

代码 / 示例

interface User { name: string }
const u: User = { name: 1 };       // 类型不兼容:number 不能赋给 string
u.age = 1;                          // 属性不存在
function f(a: string): void {}
f(1);                               // 参数类型不符

常见误区

  • 误区:报错就加 as 压掉;正解:先判断是类型建模问题还是实现问题,断言只在确有把握时使用。
  • 误区:属性不存在是运行时问题;正解:先检查类型定义是否遗漏该字段。

追问

  • Q:找不到模块但代码能跑怎么办? A:缺类型声明,补 @types 或本地 declare module。
  • Q:this 隐式报错如何修复? A:在函数首个伪参数标注 this: T,或调整调用绑定方式。

03.3.1.5-016 如何安全地扩展第三方库类型?

一句话结论

通过声明合并扩展全局对象接口,通过模块增强在已有模块上追加导出;扩展前确认官方类型是否已支持,避免本地声明与上游类型漂移冲突。

概念解释

  • 全局接口(如 Window)同名合并追加字段。
  • 模块增强在模块作用域内 declare module 追加成员。
  • 扩展内容应记录来源与撤销时机。

原理流程

  1. 阅读上游类型定义确定扩展点。
  2. 用声明合并或模块增强追加类型。
  3. 升级依赖后回归检查扩展是否仍需要。

代码 / 示例

// 全局接口合并
interface Window {
  __INITIAL_STATE__: Record<string, unknown>;
}

常见误区

  • 误区:本地扩展类型会随依赖自动更新;正解:上游改名或移除字段时本地声明可能过期,需升级后核对。
  • 误区:给第三方模块加类型可以直接改 node_modules;正解:应在项目 d.ts 中声明,node_modules 不纳入版本管理。

追问

  • Q:扩展类型与官方类型冲突时谁优先? A:按模块解析与声明合并规则,冲突需以官方为准并移除本地覆盖。
  • Q:模块增强需要导入原模块吗? A:增强写法依赖模块系统上下文,具体形式按 TS 版本与模块类型确认。

03.3.1.5-017 代码中的 any 如何管理与收敛?

一句话结论

any 是类型系统逃逸舱:临时桥接处可有限使用,但应登记位置与替换计划,优先用 unknown + 守卫收窄,逐步消除历史 any。

概念解释

  • any 关闭该位置全部检查,错误不会在编译期暴露。
  • 第三方无类型边界、迁移过渡期是主要 any 来源。
  • 可用 lint 规则限制 any 出现位置与注释豁免。

原理流程

  1. 扫描 any 出现位置并分类:边界桥接、历史遗留、缺失类型。
  2. 边界处先用 unknown 替代 any,配合守卫收窄。
  3. 缺失类型补声明或类型包,逐步清零。

代码 / 示例

// 临时:待补类型
/* eslint-disable @typescript-eslint/no-explicit-any */
const data: any = legacyClient.fetch();

// 收敛方向
const raw: unknown = legacyClient.fetch();
if (typeof raw === "object" && raw !== null) { /* 收窄 */ }

常见误区

  • 误区:unknown 比 any 麻烦,直接用 any 更快;正解:unknown 强制边界判断,长期维护成本更低。
  • 误区:函数参数 any 可以靠返回值推断补全;正解:参数 any 不会自动收窄,需显式标注或补类型。

追问

  • Q:lint 如何限制 any? A:开启 no-explicit-any 规则,必要处用注释豁免并说明原因。
  • Q:泛型能替代 any 封装吗? A:可复用场景用泛型保留类型信息,避免值与返回退化为 any。

03.3.1.5-018 版本相关的 TS 能力如何标注与验证?

一句话结论

对随 TS 版本演进的语法与选项(新内置工具类型、模块解析模式、类型推断行为),在文档中标注“待确认”并写明验证点:对照所用 TS 版本文档、在最小样例中编译观察结果,不凭记忆编造版本行为。

概念解释

  • 类型体操与编译器行为跨版本可能有差异。
  • 不确定时保留验证步骤,而非写死结论。
  • 工程应记录 TS 版本,便于复现类型行为。

原理流程

  1. 识别依赖版本的语法/选项/推断规则。
  2. 用最小样例在当前版本编译验证。
  3. 文档标注待确认项与验证方式,升级版本后回归。

代码 / 示例

待确认:某内置字符串工具类型在当前 TS 版本是否可用
验证点:查看 typescript 版本号,对照官方 lib 文档,
       写最小类型样例在编辑器悬停查看展开结果

常见误区

  • 误区:记住的版本行为可以直接写进题库;正解:版本相关结论必须标注验证点,避免过期信息误导。
  • 误区:示例代码在一个版本能跑就通用;正解:类型推断与报错提示可能随版本变化,需记录环境版本。

追问

  • Q:如何在项目里固定 TS 版本? A:package.json 锁定 typescript 版本,CI 按 lock 文件安装。
  • Q:发现版本行为与文档描述不符怎么办? A:以最小样例实测结果为准,记录差异并核对版本号与配置选项。