EmuReady 项目错误处理系统详解：构建健壮的 TRPC 应用

2025-06-07 16:15:23作者：胡易黎Nicole

引言

在现代化应用开发中，优雅且一致地处理错误是保证系统健壮性的关键。EmuReady 项目实现了一套集中式的错误处理系统，专为 TRPC 过程调用设计，本文将深入解析这套系统的设计理念、实现方式以及最佳实践。

错误处理系统概述

传统方式的痛点

传统 TRPC 错误处理方式存在几个明显问题：

错误代码以字符串形式硬编码，容易拼写错误
错误消息格式不统一，维护困难
缺乏类型安全，IDE 无法提供智能提示
相同语义的错误在不同地方可能有不同表达

EmuReady 解决方案

EmuReady 的错误处理系统通过以下方式解决上述问题：

类型安全的错误代码枚举
标准化的错误消息模板
资源专属的错误方法
统一的错误抛出接口

核心错误类解析

1. AppError - 通用错误处理

AppError 提供应用层面的通用错误方法，涵盖常见场景：

// 认证授权类
AppError.unauthorized()  // 未授权访问
AppError.forbidden()     // 权限不足
AppError.insufficientPermissions('ADMIN') // 特定权限不足

// 资源操作类
AppError.notFound('User')  // 资源不存在
AppError.alreadyExists('User', 'email "test@example.com"') // 资源已存在
AppError.resourceInUse('user', 5)  // 资源被引用

// 系统错误类
AppError.internalError()  // 服务器内部错误
AppError.databaseError('user creation') // 数据库操作错误

2. ResourceError - 资源专属错误

ResourceError 为每种业务资源提供专属错误方法，确保语义一致性：

// 设备品牌相关错误
ResourceError.deviceBrand.notFound()  // 设备品牌不存在
ResourceError.deviceBrand.alreadyExists('Apple') // 品牌已存在

// 游戏相关错误
ResourceError.game.notFound()  // 游戏不存在
ResourceError.game.inUse(5)    // 游戏被5个列表引用

// 用户相关错误
ResourceError.user.emailExists()  // 邮箱已存在
ResourceError.user.cannotDeleteSelf() // 不能删除自己账户

3. ValidationError - 验证错误

专门处理表单和字段验证场景：

ValidationError.requiresOptions('SELECT')  // 选择类型必须提供选项
ValidationError.invalidOptions('SELECT')  // 选项无效

系统优势详解

类型安全

所有错误代码都定义为常量枚举，彻底告别字符串拼写错误：

export const ERROR_CODES = {
  UNAUTHORIZED: 'UNAUTHORIZED',
  FORBIDDEN: 'FORBIDDEN',
  // ...其他代码
} as const

一致性保障

系统强制执行标准化的错误消息格式：

错误类型	消息模板
资源不存在	"{Resource} not found"
资源已存在	"{Resource} with {id} exists"
资源被引用	"Used in {count} records"

开发体验提升

IDE 能提供完整的自动补全：

资源类型自动提示
错误方法智能感知
参数类型检查

迁移指南

步骤一：替换导入语句

// 旧方式
import { TRPCError } from '@trpc/server'

// 新方式
import { AppError, ResourceError } from '@/lib/errors'

步骤二：重构错误抛出

权限检查示例

// 旧方式
if (!isAdmin) {
  throw new TRPCError({
    code: 'FORBIDDEN',
    message: 'Admin required'
  })
}

// 新方式
if (!isAdmin) {
  AppError.insufficientPermissions('ADMIN')
}

资源冲突示例

// 旧方式
if (exists) {
  throw new TRPCError({
    code: 'CONFLICT',
    message: `Device ${id} exists`
  })
}

// 新方式
if (exists) {
  ResourceError.device.alreadyExists(id)
}

扩展自定义错误

添加新资源错误

// 在错误类中添加
static newResource = {
  notFound: () => AppError.notFound('NewResource'),
  customError: (param: string) => 
    new TRPCError({
      code: 'CUSTOM_CODE',
      message: `Custom error: ${param}`
    })
}

添加全局错误类型

static maintenanceMode = (endTime: string): never => {
  throw new TRPCError({
    code: 'SERVICE_UNAVAILABLE',
    message: `Maintenance until ${endTime}`
  })
}

测试策略

错误处理系统支持完善的测试验证：

it('should throw conflict for duplicate', () => {
  expect(() => ResourceError.user.emailExists())
    .toThrow('User with this email already exists')
})

it('should have correct error code', () => {
  try {
    ResourceError.game.notFound()
  } catch (e) {
    expect(e.code).toBe('NOT_FOUND')
  }
})