【TypeScript工程化必备】：构建可维护应用的6大错误处理原则

第一章：TypeScript错误处理的核心理念

TypeScript 作为 JavaScript 的超集，不仅增强了类型系统，也提升了错误处理的可预测性与安全性。其核心理念在于将错误预防前置到编译阶段，尽可能减少运行时异常的发生。

静态类型检查防止常见错误

通过严格的类型系统，TypeScript 能在代码编译阶段捕获类型不匹配、属性访问错误等问题。例如，访问未定义对象属性时，编译器会直接报错：

// TypeScript 编译时即报错
interface User {
  name: string;
}

const user: User = { name: "Alice" };
console.log(user.age); // Error: Property 'age' does not exist on type 'User'

这避免了 JavaScript 中常见的 undefined is not a property 运行时错误。

使用联合类型和类型守卫提升鲁棒性

TypeScript 支持联合类型与类型守卫，使开发者能明确处理多种可能输入，增强错误边界控制：

function processInput(input: string | number): void {
  if (typeof input === "string") {
    console.log("Received string:", input.toUpperCase());
  } else {
    console.log("Received number:", input.toFixed(2));
  }
}

该模式确保每种类型路径都被显式处理，降低逻辑错误风险。

异常处理与可预测的失败路径

尽管 TypeScript 不支持编译时检查抛出的异常，但仍推荐通过返回类型明确表达可能的错误状态。常用策略包括：

• 使用 Result 模式封装成功与失败状态
• 结合 try/catch 处理异步操作中的运行时异常
• 利用 never 类型标记不可能到达的分支

策略	适用场景	优势
类型守卫	联合类型判断	类型安全的分支逻辑
never 类型	不可达代码标记	增强代码可维护性

第二章：统一错误类型设计与异常分类

2.1 定义可扩展的自定义错误类

在构建大型应用时，标准错误类型难以满足业务场景的精细化需求。定义可扩展的自定义错误类，有助于统一错误处理逻辑，提升调试效率。

基础结构设计

通过继承内置 Error 类，可创建具有业务语义的错误类型：

class CustomError extends Error {
  constructor(message, code, details) {
    super(message);
    this.name = this.constructor.name;
    this.code = code;
    this.details = details;
    Error.captureStackTrace(this, this.constructor);
  }
}

上述代码中，code 字段用于标识错误类型，便于程序判断；details 可携带上下文信息。调用 Error.captureStackTrace 确保堆栈追踪准确。

分层扩展示例

可进一步派生具体子类：

• ValidationError：用于输入校验失败
• NetworkError：封装网络请求异常
• AuthenticationError：处理鉴权问题

这种分层结构支持 instanceof 类型判断，便于在中间件中进行差异化处理。

2.2 使用枚举区分错误语义类型

在 Go 项目中，通过枚举方式定义错误类型可显著提升错误处理的语义清晰度。使用自定义错误类型配合 iota 枚举，能有效区分网络错误、超时错误与业务校验错误。

错误类型的枚举定义

type ErrorType int

const (
    NetworkError ErrorType = iota
    TimeoutError
    ValidationError
)

func (e ErrorType) String() string {
    return [...]string{"NetworkError", "TimeoutError", "ValidationError"}[e]
}

上述代码利用 iota 自动生成递增值，每个常量对应一类错误语义，便于后续判断和分类处理。

错误分类的应用场景

• 日志系统可根据错误类型进行分级记录
• 监控组件可针对不同错误类型触发告警策略
• API 响应能返回结构化的错误码与提示

2.3 错误继承体系与类型守卫实践

在现代TypeScript开发中，错误处理的类型安全常被忽视。传统的异常捕获使用`any`类型接收错误，导致无法进行精确判断。

问题场景

```typescript try { // ... } catch (err: any) { if (err.code === 'ENOENT') { /* 处理 */ } } ``` `err`被推断为`any`，失去类型检查能力，易引发运行时错误。

类型守卫解决方案

定义类型守卫函数以安全地识别错误类型：

interface ErrnoException extends Error {
  code?: string;
}

function isErrnoException(error: unknown): error is ErrnoException {
  return typeof error === 'object' && error !== null && 'code' in error;
}

该函数通过类型谓词`error is ErrnoException`告知编译器后续上下文中`error`的具体结构。

安全的错误处理流程

• 使用`unknown`作为捕获类型，强制类型验证
• 通过自定义类型守卫缩小类型范围
• 仅在确认结构后访问特定属性

2.4 在业务逻辑中抛出结构化异常

在现代服务开发中，异常不应是模糊的错误信息，而应是可解析、可追溯的结构化数据。通过定义统一的异常模型，能够提升系统的可观测性与客户端处理效率。

定义结构化异常类型

以 Go 语言为例，可设计如下异常结构：

type AppError struct {
    Code    string `json:"code"`    // 错误码，如 USER_NOT_FOUND
    Message string `json:"message"` // 用户可读信息
    Details map[string]interface{} `json:"details,omitempty"` // 上下文详情
}

该结构支持标准化序列化，便于日志采集与前端解析。Code 字段用于程序判断，Message 提供提示，Details 可携带请求ID、时间戳等调试信息。

在业务层主动抛出

当用户余额不足时：

if balance < amount {
    return nil, &AppError{
        Code:    "INSUFFICIENT_BALANCE",
        Message: "账户余额不足，无法完成支付",
        Details: map[string]interface{}{"current": balance, "required": amount},
    }
}

调用方能基于 Code 做条件分支处理，Details 则有助于定位问题根因。

2.5 利用泛型增强错误处理函数复用性

在 Go 1.18 引入泛型后，错误处理逻辑得以高度抽象和复用。通过定义类型参数，可构建适用于多种返回类型的统一错误封装。

泛型错误包装函数

func SafeExecute[T any](f func() (T, error)) (result T, err error) {
    defer func() {
        if r := recover(); r != nil {
            var zero T
            result = zero
            err = fmt.Errorf("panic: %v", r)
        }
    }()
    return f()
}

该函数接受一个返回 T 和 error 的操作，通过泛型机制确保任意类型结果均可被安全执行并捕获异常。参数 f 封装了可能出错的业务逻辑，defer 中的 recover 防止程序崩溃，同时返回对应类型的零值与错误信息。

使用场景示例

• 数据库查询封装，统一处理连接异常
• HTTP 客户端调用，避免重复的 try-catch 模式
• 配置解析过程，集中管理格式错误

第三章：异步操作中的错误捕获策略

3.1 Promise链中的错误传递机制解析

在Promise链中，错误会沿着链式调用向后传递，直到遇到第一个 .catch() 处理器。

错误冒泡机制

Promise的错误具有冒泡特性，未被当前 .then() 捕获的异常会自动传递给后续的 .catch()：

Promise.resolve()
  .then(() => {
    throw new Error("出错了");
  })
  .then(() => console.log("不会执行"))
  .catch(err => console.error("捕获错误:", err.message));

上述代码中，第一个 .then() 抛出异常后跳过后续所有成功的回调，直接进入 .catch()。

错误处理策略对比

• 使用 .catch() 集中处理：推荐用于全局错误捕获
• 在每个 .then() 中添加第二个回调函数：可实现局部错误处理

错误一旦被捕获，链将恢复为正常状态，后续操作继续执行。

3.2 async/await场景下的优雅错误处理

在使用 async/await 时，异常会以 Promise 拒绝的形式抛出，因此需要通过 try/catch 进行捕获。

基本错误捕获模式

async function fetchData() {
  try {
    const response = await fetch('/api/data');
    if (!response.ok) throw new Error('Network error');
    return await response.json();
  } catch (error) {
    console.error('请求失败:', error.message);
  }
}

上述代码中，await 可能抛出网络错误或响应异常，通过 try/catch 统一处理，提升可读性。

错误分类处理

• 网络层错误：如连接超时、DNS 失败
• 响应层错误：状态码非 2xx，需手动抛出
• 解析错误：JSON 解析失败等

通过细化错误类型，可实现更精准的反馈与重试机制。

3.3 并发请求错误聚合与降级方案

在高并发场景下，多个依赖服务可能同时出现异常，若不加以控制，容易引发雪崩效应。因此需对错误进行聚合处理，并结合降级策略保障核心链路可用。

错误聚合机制

通过统一的熔断器（如 Hystrix）收集并发请求中的失败率，当错误比例超过阈值时自动触发熔断：

// 初始化熔断器配置
hystrix.ConfigureCommand("userService", hystrix.CommandConfig{
    Timeout:                1000,
    MaxConcurrentRequests:  100,
    ErrorPercentThreshold:  50, // 错误率超50%触发熔断
})

该配置表示在100个并发内，若错误占比超50%，则后续请求直接走降级逻辑。

降级策略实现

降级应返回兜底数据或缓存结果，避免完全中断服务：

• 优先返回本地缓存或静态资源
• 异步记录日志以便后续补偿
• 核心功能保留最低可用接口

第四章：全局错误监听与日志追踪集成

4.1 捕获未处理的Promise拒绝事件

JavaScript运行时提供了专门的机制来监听未被显式处理的Promise拒绝，避免错误静默失败。

全局事件监听

通过监听 unhandledrejection 事件，可捕获所有未处理的Promise拒绝：

window.addEventListener('unhandledrejection', event => {
  console.error('未处理的拒绝：', event.reason);
  event.preventDefault(); // 阻止默认的错误输出
});

其中，event.reason 包含拒绝原因（通常为Error对象），event.promise 指向被拒绝的Promise实例。调用 preventDefault() 可抑制浏览器控制台的报错信息，便于自定义错误上报。

应用场景

• 集中式错误监控与日志记录
• 开发环境中的异常提醒
• 防止因未捕获拒绝导致的用户界面卡顿

4.2 结合Sentry实现跨环境错误上报

在现代分布式系统中，统一的错误监控机制至关重要。Sentry 作为成熟的错误追踪平台，支持多语言、多环境的异常捕获与聚合分析，是实现跨环境错误上报的理想选择。

SDK集成与配置

以Node.js应用为例，需安装并初始化Sentry SDK：

const Sentry = require('@sentry/node');
Sentry.init({
  dsn: 'https://example@sentry.io/123',
  environment: process.env.NODE_ENV,
  tracesSampleRate: 0.2
});

其中，dsn 指定项目上报地址，environment 标识当前运行环境（如staging、production），确保错误可按环境分类追踪。

错误捕获与上下文增强

通过自动捕获与手动上报结合，提升问题定位效率：

• 自动捕获未处理的异常与Promise拒绝
• 使用 Sentry.captureException(err) 主动上报业务异常
• 通过 Sentry.setContext() 添加用户、设备等上下文信息

4.3 构建上下文感知的调用栈追踪系统

在分布式系统中，传统调用栈难以捕捉跨服务的执行上下文。为此，需构建具备上下文感知能力的追踪系统，通过唯一追踪ID串联请求链路。

上下文传播机制

使用轻量级上下文载体传递追踪元数据：

type TraceContext struct {
    TraceID    string
    SpanID     string
    ParentID   string
    Timestamp  int64
}

该结构在gRPC或HTTP头部中透传，确保跨进程上下文连续性。

自动埋点与采样策略

• 基于拦截器实现方法入口自动记录
• 采用自适应采样，高负载时动态降低采样率
• 关键事务强制全量采集

字段	用途
TraceID	全局唯一请求标识
SpanID	当前操作唯一ID

4.4 日志分级与敏感信息脱敏处理

在分布式系统中，日志的可读性与安全性同样重要。合理的日志分级有助于快速定位问题，而敏感信息脱敏则保障用户数据隐私。

日志级别设计

通常采用五级分类：

• DEBUG：调试信息，开发阶段使用
• INFO：关键流程的正常运行记录
• WARN：潜在异常，但不影响系统运行
• ERROR：业务流程出错，需告警处理
• FATAL：严重错误，可能导致服务中断

敏感信息脱敏实现

对日志中的身份证、手机号等字段进行掩码处理。例如，在Go语言中可通过正则替换实现：

func MaskSensitiveInfo(log string) string {
    // 替换手机号：138****8888
    phonePattern := `(\d{3})\d{4}(\d{4})`
    phoneReplacer := `$1****$2`
    log = regexp.MustCompile(phonePattern).ReplaceAllString(log, phoneReplacer)

    // 替换身份证号
    idPattern := `(\d{6})\d{8}(\w{4})`
    idReplacer := `$1********$2`
    log = regexp.MustCompile(idPattern).ReplaceAllString(log, idReplacer)

    return log
}

上述代码通过正则表达式匹配敏感字段，并保留前缀与后缀用于识别，中间部分用星号替代，既满足审计需求又防止信息泄露。

第五章：构建高可用TypeScript应用的错误哲学

防御式编程与类型守卫

在大型TypeScript项目中，外部API响应或用户输入常带来不确定性。使用类型守卫可有效缩小类型范围，避免运行时错误。

function isUser(obj: any): obj is User {
  return typeof obj === 'object' && 
         typeof obj.name === 'string' && 
         typeof obj.id === 'number';
}

function processUserData(data: unknown) {
  if (isUser(data)) {
    console.log(`Processing user: ${data.name}`);
  } else {
    throw new Error('Invalid user data');
  }
}

统一错误处理中间件

在Node.js + Express项目中，集中处理异步操作中的错误能显著提升系统稳定性。通过自定义错误类区分业务异常与系统故障。

• 继承Error类实现ApplicationError和ValidationError
• 使用try/catch包裹控制器逻辑，或结合async wrapper
• 记录错误上下文用于追踪，但不暴露堆栈给客户端

空值的安全处理策略

TypeScript的strictNullChecks开启后，需主动处理null/undefined。可借助工具函数封装安全访问逻辑。

场景	推荐方案
深层对象取值	使用可选链 ?. 和 nullish coalescing ??
异步资源加载	初始化为undefined，UI层做loading/null判断

请求入口 → 业务逻辑层 → 领域服务 → 外部依赖

↑ 异常捕获 ← 日志记录 ← 熔断机制 ←