TypeScript 教學：深入了解 `ConstructorParameters<T>` 工具型別

簡介

在大型 TypeScript 專案中，型別安全與程式碼可維護性往往是開發團隊最關注的兩大課題**。**
當我們需要根據已存在的類別或建構子 (constructor) 產生相對應的參數型別時，手動維護參數列表既繁瑣又容易出錯。這時，TypeScript 內建的 Utility Types 就顯得格外重要，而 ConstructorParameters<T> 正是其中專門用來抽取建構子參數型別的工具。

ConstructorParameters<T> 能讓我們 自動推斷 任意類別或建構子簽名的參數型別，進而在函式、工廠模式、依賴注入等情境下，保持型別一致、減少重複代碼。本篇文章將從概念說明、實作範例、常見陷阱到最佳實踐，完整呈現 ConstructorParameters<T> 的使用方法，讓你在日常開發中活用這個強大的型別工具。

核心概念

1. `ConstructorParameters<T>` 是什麼？

ConstructorParameters<T> 是 TypeScript 提供的 條件型別，它接受一個 建構子型別 T，回傳一個 元組型別，該元組的元素依序對應建構子的參數型別。

type ConstructorParameters<T extends new (...args: any) => any> =
    T extends new (...args: infer P) => any ? P : never;

簡單來說，當 T 為 new (...args: infer P) => any 時，P 就會被「推斷」出來，最終結果是 P（即參數的型別陣列）。若 T 不是建構子型別，則回傳 never。

2. 為什麼要使用它？

避免手動同步：類別的建構子參數若改變，只要使用 ConstructorParameters，相關型別會自動更新，減少漏改的風險。
提升可讀性：直接以 ConstructorParameters<typeof MyClass> 表示參數型別，讓程式碼意圖更清晰。
支援高階函式：在工廠函式、DI 容器、測試工具等需要「傳遞建構子參數」的情況下，能保證型別正確。

3. 基本使用方式

class User {
  constructor(public name: string, private age: number) {}
}

// 取得 User 建構子的參數型別
type UserCtorParams = ConstructorParameters<typeof User>;
// 等價於: [string, number]

UserCtorParams 現在是一個元組，第一個元素是 string（name），第二個元素是 number（age）。

程式碼範例

以下示範 5 個常見且實用的範例，從最基礎到較進階的情境，說明 ConstructorParameters<T> 的多元應用。

範例 1：簡單的工廠函式

利用 ConstructorParameters 讓工廠函式的參數型別自動對應目標類別。

class Point {
  constructor(public x: number, public y: number) {}
}

/**
 * genericFactory：根據給定的類別建構子，回傳新實例。
 * @param Ct 類別建構子
 * @param args 建構子參數，型別自動推斷
 */
function genericFactory<Ct extends new (...args: any) => any>(
  Ctor: Ct,
  ...args: ConstructorParameters<Ct>
): InstanceType<Ct> {
  return new Ctor(...args);
}

// 使用
const p = genericFactory(Point, 10, 20);
// p 的型別為 Point，且 x=10, y=20

重點：...args: ConstructorParameters<Ct> 讓 genericFactory 的參數型別緊跟 Ctor，任何變更都會即時反映。

範例 2：依賴注入 (DI) 容器的型別安全

在 DI 容器中，我們常需要根據註冊的類別自動解析建構子參數。ConstructorParameters 能確保解析過程的型別正確性。

type Provider<T> = new (...args: any[]) => T;

class Container {
  private map = new Map<Function, any>();

  register<T>(token: Provider<T>, instance: T) {
    this.map.set(token, instance);
  }

  resolve<T>(Ctor: Provider<T>): T {
    // 取得建構子參數型別
    type Params = ConstructorParameters<Provider<T>>;

    // 假設所有依賴都是已註冊的單例
    const deps = (Ctor.length ? [] : []) as Params; // 這裡僅示意

    // 直接 new，實務上會從 map 中取出實例
    return new Ctor(...deps);
  }
}

// 範例類別
class ServiceA {
  constructor(public apiUrl: string) {}
}

const container = new Container();
container.register(ServiceA, new ServiceA('https://api.example.com'));

const service = container.resolve(ServiceA); // 型別為 ServiceA

說明：Ctor.length 取得建構子參數數量，配合 ConstructorParameters 可在未來擴充自動解析依賴的邏輯。

範例 3：測試工具 – 自動產生 mock 參數

在單元測試時，我們常需要為類別建立 mock 實例。ConstructorParameters 能協助產生符合型別的假資料。

import { faker } from '@faker-js/faker';

function mockArgs<T>(Ctor: new (...args: any) => T): ConstructorParameters<typeof Ctor> {
  // 依據參數型別產生假資料（簡化示範）
  // 假設所有參數都是基本型別或可以用 faker 產生
  const paramTypes = [] as any[];
  // 這裡僅示意，實務上可利用反射或手動映射
  return paramTypes as ConstructorParameters<typeof Ctor>;
}

class Order {
  constructor(public id: string, public amount: number, public createdAt: Date) {}
}

// 產生 mock 參數
const mock = mockArgs(Order);
// mock 會是 [string, number, Date]，可直接使用 faker 填值
const order = new Order(...mock);

技巧：雖然 TypeScript 本身無法在編譯階段取得參數的「具體型別」資訊，但結合 ConstructorParameters 與外部工具（如 faker）可建立可重用的測試資料產生器。

範例 4：與 `Partial`、`Pick` 結合使用

有時我們想要部分或挑選建構子參數來建立物件。透過 ConstructorParameters 搭配其他 Utility Types，可實現靈活的型別組合。

class Config {
  constructor(public host: string, public port: number, public secure: boolean) {}
}

// 取得參數型別
type ConfigParams = ConstructorParameters<typeof Config>; // [string, number, boolean]

// 轉換為物件型別
type ConfigTupleToObject<T extends any[]> = {
  [K in keyof T as K extends `${infer N}` ? N : never]: T[N];
};

type ConfigObj = ConfigTupleToObject<ConfigParams>;
// 等價於: {0: string, 1: number, 2: boolean}

// 只挑選前兩個參數，建立 Partial 物件
type ConfigPartial = Partial<Pick<ConfigObj, '0' | '1'>>;
// {0?: string; 1?: number}

說明：雖然此範例較為技巧性，但展示了 ConstructorParameters 可以作為 型別轉換 的起點，進一步配合 Partial、Pick 等工具型別，滿足更細緻的需求。

範例 5：在 `React` 中使用 `ConstructorParameters` 產生 Props

對於 Class Component，有時需要根據建構子參數自動生成相對應的 Props 型別。

import React from 'react';

class Counter {
  constructor(public start: number, public step: number = 1) {}
}

// 取得建構子參數型別
type CounterParams = ConstructorParameters<typeof Counter>; // [number, number?]

// 轉換為 Props
type CounterProps = {
  start: CounterParams[0];
  step?: CounterParams[1];
};

export class CounterComponent extends React.Component<CounterProps> {
  private counter = new Counter(this.props.start, this.props.step);

  render() {
    return <div>{this.counter.start}</div>;
  }
}

重點：透過 ConstructorParameters，CounterComponent 的 Props 永遠與 Counter 建構子保持同步，避免手動更新時遺漏。

常見陷阱與最佳實踐

陷阱	可能的問題	解決方式 / 最佳實踐
傳入非建構子型別	`ConstructorParameters<number>` 會回傳 `never`，導致型別錯誤。	確保 `T` 為 `new (...args:any) => any`，或使用條件型別包裝：`type SafeCtor<T> = T extends abstract new (...args:any) => any ? T : never;`
可選參數與預設值	參數若有預設值，型別仍會保留為可選 (`?`)，但在使用時忘記提供會產生編譯錯誤。	在呼叫 `new` 時，明確傳入 `undefined` 或使用 `...args as ConstructorParameters<T>` 以保證型別正確。
重載建構子	多個建構子簽名只會取最後一個 overload 的參數型別。	若需要支援多種參數組合，可自行建立聯合型別：`type OverloadParams = ConstructorParameters
泛型類別	`ConstructorParameters<typeof GenericClass>` 會得到 `[any]`，失去型別資訊。	使用具體化（instantiation）後再取得：`type Params = ConstructorParameters<new (arg: string) => GenericClass<string>>;`
與 `any` 混用	若建構子參數含 `any`，會削弱型別安全。	儘量避免在公共 API 中使用 `any`，改用具體型別或 `unknown`，配合型別守衛進行檢查。

最佳實踐：

封裝成泛型工具型別：將常見的 ConstructorParameters 搭配 InstanceType 包裝成一個易於呼叫的工具，例如 type CtorFactory<T> = (...args: ConstructorParameters<T>) => InstanceType<T>;。
與 as const 搭配：在需要固定參數陣列的情況下，使用 as const 讓 TypeScript 推斷出 字面量型別，避免寬鬆的 string[]。
在測試框架中建立通用工廠：把 genericFactory 放在測試共用程式碼庫，讓所有測試皆能受益於型別同步。
保持文件同步：在類別的 JSDoc 中標註建構子參數說明，讓 IDE 能同時顯示型別與說明，提升開發體驗。

實際應用場景

1. 微服務間的 DTO 轉換

在微服務架構中，前端或其他服務常透過 JSON 取得資料，然後需要映射成內部的類別實例。使用 ConstructorParameters 可自動產生對應的參數陣列，避免手動對應每個欄位。

// 伺服器回傳的原始資料
type UserDTO = { name: string; age: number };

// 類別模型
class User {
  constructor(public name: string, public age: number) {}
}

// 通用映射函式
function mapDtoToInstance<T>(Ctor: new (...args: any) => T, dto: any): T {
  const args: ConstructorParameters<typeof Ctor> = Object.values(dto) as any;
  return new Ctor(...args);
}

const user = mapDtoToInstance(User, { name: 'Alice', age: 30 });

2. 插件系統 (Plugin System)

開發一套插件框架時，插件往往以類別形式註冊，框架需要根據插件的建構子自動注入依賴。ConstructorParameters 能讓框架在 編譯期 即確定每個插件需要的參數型別，減少執行期錯誤。

interface Plugin {
  init(): void;
}

class LoggerPlugin implements Plugin {
  constructor(private logger: Console) {}
  init() { this.logger.log('Logger ready'); }
}

// 框架核心
function loadPlugin<P extends Plugin>(PluginCtor: new (...args: any) => P) {
  const deps: ConstructorParameters<typeof PluginCtor> = [console];
  const plugin = new PluginCtor(...deps);
  plugin.init();
}

3. 自動化 CLI 命令產生器

對於 CLI 工具，常會根據不同指令建立對應的「執行類別」。使用 ConstructorParameters 可以在 命令註冊 時自動推斷所需參數，並從命令行解析結果直接傳入。

class DeployCommand {
  constructor(public env: string, public version: string) {}
}

// 假設 args 已由 yargs 解析
const args = { env: 'prod', version: '1.2.3' };

function registerCommand<C extends new (...args: any) => any>(Cmd: C) {
  const ctorArgs: ConstructorParameters<C> = [args.env, args.version] as any;
  const cmdInstance = new Cmd(...ctorArgs);
  // 執行
}
registerCommand(DeployCommand);

總結

ConstructorParameters<T> 是 TypeScript Utility Types 中極具威力的一員，它讓我們可以 從建構子自動抽取參數型別，從而在工廠模式、依賴注入、測試工具、插件系統等多種情境下，保持 型別一致性、減少重複代碼，並提升 開發效率 與 程式碼可維護性。
在使用時，務必注意：

確保傳入的 T 為合法的建構子型別；
處理好可選參數與預設值的情況；
針對重載或泛型類別，適度自行定義輔助型別。

只要掌握上述概念與最佳實踐，你就能在日常開發中自如運用 ConstructorParameters<T>，寫出更加安全、可讀、可擴充的 TypeScript 程式碼。祝你在 TypeScript 的世界裡玩得開心，寫出更好的程式！ 🚀

TypeScript 教學：深入了解 ConstructorParameters<T> 工具型別

簡介