人人都会AI编程

16.3 类型定义：接口、泛型、工具类型、声明文件

更新时间：2026-07-10

TypeScript 的类型系统是它在工程化项目中的灵魂。在 Node.js 后端开发中，合理定义类型不仅能依靠编译期检查降低低级错误，还能让代码成为团队最好的“文档”。本节聚焦四种核心类型机制：接口、泛型、工具类型和声明文件，并围绕实际的服务端开发场景给出具体用法与建议。

16.3.1 接口（Interface）：描述数据的契约

接口是 TypeScript 中最基础也是最常用的类型定义方式，它用来描述对象的形状——包括属性、类型以及是否可选。在 Node.js 开发中，我们频繁需要定义 API 的请求体、响应体、数据库模型和服务函数的参数。接口让这些结构一目了然。

典型用法：定义 API 数据模型

假设我们有一个创建用户的接口，前端会发送如下 JSON：

{
  "username": "alice",
  "email": "alice@example.com",
  "age": 28
}

后端可以定义一个接口来表达这个请求体：

interface CreateUserDto {
  username: string;
  email: string;
  age?: number;        // 可选属性
  role: 'admin' | 'user'; // 字面量联合类型
}

在 Express 路由处理函数中使用时，就能获得类型提示和校验：

app.post('/users', (req, res) => {
  const dto: CreateUserDto = req.body;  // 运行时并不会校验，但开发时有智能提示
  // 后续调用 service 层时也都保持类型安全
});

接口的继承与组合

接口可以继承另一个接口，方便为不同场景复用基础结构：

interface UserBase {
  username: string;
  email: string;
}

interface UserCreate extends UserBase {
  password: string;    // 创建时需要密码
}

interface UserResponse extends UserBase {
  id: number;
  createdAt: Date;
}

这样 Service 层的 createUser 函数就能清晰地声明它接收 UserCreate 并返回 UserResponse，而不需要混用同一个类型。

用接口描述类和依赖注入

在 NestJS 等企业级框架中，接口可用于定义服务契约，实现依赖倒置：

interface IUserRepository {
  findById(id: number): Promise<UserResponse | null>;
  save(user: CreateUserDto): Promise<UserResponse>;
}

class UserService {
  constructor(private readonly userRepo: IUserRepository) {}
  // ...
}

这种方式让单元测试时可以轻松 Mock 一个符合 IUserRepository 的对象，而不依赖真实数据库。

实用建议：

  • 业务实体、DTO、响应体都用 interface 描述，并尽量分开文件，如 user.dto.ts、user.entity.ts。
  • 对于需要后期扩展的类型，优先使用接口（因为接口可以多次声明合并）。
  • 保持属性类型简单明确，过于复杂的嵌套建议拆分成更小的接口。

16.3.2 泛型（Generics）：编写可复用的类型安全函数

泛型让函数、类或接口可以保持类型“未知”直到使用时才确定，这在编写工具库、通用仓储层、数据处理管道时特别有价值。

常见场景一：通用仓储层

Node.js 后端经常需要为不同实体编写相似的数据库操作——查、增、改、删。可以用泛型类提供类型安全的基类：

class Repository<T> {
  async findOne(id: number): Promise<T | null> {
    const result = await db.query('SELECT * FROM ... WHERE id = ?', [id]);
    return result as T;
  }

  async list(): Promise<T[]> {
    // ...
  }
}

// 使用时指定实体类型
const userRepo = new Repository<UserResponse>();
const orderRepo = new Repository<OrderResponse>();

const user = await userRepo.findOne(1);  // 类型为 UserResponse | null

这样既避免了为每张表重写几乎一样的代码，又保留了返回值的准确类型。

常见场景二：工具函数的类型约束

很多通用函数需要对传入的参数做约束，例如记录日志时需要保证对象有 id 属性：

function logEntity<T extends { id: number }>(entity: T): void {
  logger.info(`Entity #${entity.id} updated`);
}

泛型约束 extends { id: number } 确保了传入任何对象都包含数字类型的 id 字段，否则编译报错。这个函数可同时用于 User、Order 等不同实体。

泛型在中间件和请求扩展中

Express 的中间件经常需要扩展 Request 对象，比如附加当前用户信息。通过声明文件与泛型结合，可以让后续路由安全地访问：

interface AuthenticatedRequest extends Request {
  user: {
    id: number;
    role: string;
  };
}

app.get('/profile', (req: AuthenticatedRequest, res) => {
  const userId = req.user.id; // 完全类型安全
});

更高级的自定义泛型可以用于构建类型安全的校验函数：

function pick<T, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> {
  const result = {} as Pick<T, K>;
  keys.forEach(key => result[key] = obj[key]);
  return result;
}

const user = await getUser();          // 类型 UserResponse
const safe = pick(user, ['id', 'email']); // 类型 { id: number; email: string }

实用建议：

  • 不要为了泛型而泛型。当函数逻辑对类型确实没有特定要求但又需要保持输出与输入一致时，泛型是最佳选择。
  • 泛型命名尽量有意义：T 适用于单一类型，K 和 V 用于键值，更复杂时可使用 TEntity、TResult 等。
  • 过度嵌套的泛型会降低代码可读性，需要权衡复杂度。

16.3.3 工具类型（Utility Types）：利用内置工具处理常见变换

TypeScript 内置了一系列工具类型，可以基于已有类型创建新的类型。它们在后端开发中能显著减少重复的类型定义，并提高代码灵活性。

Partial<T> 与 Required<T> —— 部分更新与强制完整

更新用户信息时，前端可能只发送部分字段。如果复用创建时的 DTO 类型，则所有字段都被要求必填。此时可以使用 Partial：

interface UpdateUserDto extends Partial<CreateUserDto> {
  id: number; // 更新必须指定 id
}

这样 UpdateUserDto 中的 username、email、age 等都变成可选的，业务更新逻辑只更新递交的字段。相反，Required<T> 可以将所有属性转为必填，适合在某个服务层确保数据完备性。

Pick<T, K> 与 Omit<T, K> —— 挑选与排除

这两个工具非常适合从实体或大接口中裁剪出特定用途的子集。

  • 从用户实体中挑选 id 和 email 用于发送通知邮件：
type NotifiableUser = Pick<UserResponse, 'id' | 'email'>;
  • 避免敏感字段暴露：从响应中排除 password 字段：
type SafeUser = Omit<UserResponse, 'password'>;

这在接口数据组装和返回时非常实用，完全避免手动编写“又一个简化版”的 DTO 接口。

Record<K, V> —— 构造键值对映射

当需要定义一组固定的状态代码与中文描述的映射时，Record 简洁有力：

type StatusMap = Record<'active' | 'inactive' | 'banned', string>;

const statusText: StatusMap = {
  active: '已激活',
  inactive: '未激活',
  banned: '已封禁',
};

在权限系统中定义角色与权限集合的映射，或者配置对象的类型时，都可以用 Record。

ReturnType<T> 与 Parameters<T> —— 从函数获取类型

在编写中间件或装饰器时，经常需要获取某个函数的返回值类型或者参数类型，而无需手动导出：

function getUser(id: number) {
  return db.users.find(id);
}

type UserFromDB = ReturnType<typeof getUser>; // 自动推断为 Promise<User | null>

这在编写高阶函数、包装器时非常有用，可以确保包装后的函数保持类型一致。

自定义工具类型实战

很多业务需求需要组合内置工具类型，或者编写自己的工具类型。例如，将实体的某个字段的类型改为 string：

type ReplaceType<T, K extends keyof T, NewType> = Omit<T, K> & Record<K, NewType>;

// 将用户实体中的 createdAt 字段由 Date 改为 string（便于序列化）
type UserSerialized = ReplaceType<UserResponse, 'createdAt', string>;

16.3.4 声明文件（Declaration Files）：让第三方代码类型可用

Node.js 生态中的很多库是用 JavaScript 编写的，并不自带类型定义。TypeScript 社区通过 DefinitelyTyped 项目维护了大量的 .d.ts 声明文件，可以通过 @types/xxx 安装。但仍有部分冷门库或内部工具需要开发者自行编写声明文件。

安装与使用社区类型

npm install express
npm install -D @types/express

安装后，TypeScript 会自动从 node_modules/@types 中解析类型，无需手动引入。如果库未提供 @types 包，也可以通过声明文件自行补充。

编写简单的模块声明

假设团队内部有一个通用的日志工具 my-logger，返回一个对象，但是没有类型定义。可以创建一个 types/my-logger.d.ts 文件：

declare module 'my-logger' {
  export interface Logger {
    info(message: string, meta?: Record<string, unknown>): void;
    error(message: string, error?: Error): void;
  }

  const logger: Logger;
  export default logger;
}

然后在 tsconfig.json 中配置 include 或 typeRoots 包含这个目录，所有地方都可以直接 import logger from 'my-logger' 并获得类型提示。

扩展已有模块的类型

有时需要为已有的第三方模块扩展属性（例如给 Express 的 Request 对象添加 user 属性）。可以使用声明合并：

// types/express.d.ts
declare namespace Express {
  interface Request {
    user?: {
      id: number;
      role: string;
    };
  }
}

这样在所有路由中 req.user 都有了类型，无需每次强制造型。

全局类型与变量的声明

如果项目中有通过环境变量注入的全局配置，也可以用声明文件形容其类型：

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      NODE_ENV: 'development' | 'production' | 'test';
      DATABASE_URL: string;
      JWT_SECRET: string;
    }
  }
}

这样 process.env.DATABASE_URL 就有确切类型，避免写错变量名或不必要的非空断言。

注意事项：

  • 声明文件只用于类型描述，绝不能在里面包含有实际执行的代码。
  • 自定义的 .d.ts 文件应放在一个统一目录（如 @types 或 types），并确保 tsconfig 能正确引用。
  • 为组件提供声明文件也是一种团队贡献，特别是当你使用了开源库后，向 DefinitelyTyped 提交类型定义会帮助整个社区。

类型定义是 TypeScript 与 Node.js 结合后“生产力红利”的集中体现。接口让你的代码本身成为结构清晰的文档；泛型让通用模块在保持类型安全的同时高度复用；工具类型大幅减少重复的类型声明；声明文件则让整个 npm 生态的类型能力为你所用。掌握这四种机制，日常开发中不必再在各处使用 any 来逃避类型，也能借助编译器的力量大幅降低潜在错误。