全局类型定义

全局类型定义的基本概念

全局类型定义允许在TypeScript项目中跨文件使用类型而无需显式导入。这种机制特别适合大型项目或需要共享类型定义的场景。全局类型定义通常通过.d.ts声明文件实现，这些文件不包含具体实现，只包含类型声明。

// types/global.d.ts
declare namespace MyGlobal {
  interface User {
    id: number;
    name: string;
    email: string;
  }
}

声明文件的创建与使用

创建全局类型定义需要遵循特定规则。声明文件必须以.d.ts为扩展名，并且通常放置在项目类型定义目录中。TypeScript会自动识别这些文件中的类型声明。

// src/utils.ts
function getUser(): MyGlobal.User {
  return { id: 1, name: 'Alice', email: 'alice@example.com' };
}

全局接口与类型

全局作用域中可以定义接口和类型别名。这些定义在整个项目中可用，无需导入语句。这对于应用程序核心模型特别有用。

// types/global.d.ts
interface Product {
  sku: string;
  price: number;
  inventory: number;
}

type DiscountStrategy = (price: number) => number;

扩展全局命名空间

可以通过声明合并来扩展全局命名空间。这种技术常用于为第三方库添加类型定义或扩展现有全局接口。

// types/global.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: 'development' | 'production' | 'test';
    API_URL: string;
  }
}

全局变量声明

当需要在全局作用域中访问某些变量时，可以使用declare var、declare let或declare const来声明它们的类型。

// types/global.d.ts
declare const __VERSION__: string;
declare let DEBUG: boolean;

// src/app.ts
if (DEBUG) {
  console.log(`App version: ${__VERSION__}`);
}

全局函数声明

全局可用的函数也可以通过声明文件定义。这对于在多个模块中使用的工具函数特别有用。

// types/global.d.ts
declare function formatCurrency(value: number, currency?: string): string;

// src/components/Price.tsx
const priceDisplay = formatCurrency(99.99, 'USD');

全局枚举定义

虽然枚举在TypeScript中通常具有模块作用域，但可以通过全局声明使其在整个项目中可用。

// types/global.d.ts
declare enum LogLevel {
  Error,
  Warn,
  Info,
  Debug
}

// src/logger.ts
function log(message: string, level: LogLevel = LogLevel.Info) {
  // 实现省略
}

全局类声明

全局类声明允许在不导入的情况下使用类类型。这对于框架或库的核心类定义很有帮助。

// types/global.d.ts
declare class Observable<T> {
  subscribe(observer: (value: T) => void): void;
  unsubscribe(observer: (value: T) => void): void;
  next(value: T): void;
}

// src/store.ts
const userObservable = new Observable<MyGlobal.User>();

全局模块增强

通过模块增强技术，可以为现有模块添加全局类型定义。这对于扩展第三方模块的类型特别有用。

// types/global.d.ts
import { Vue } from 'vue/types/vue';

declare module 'vue/types/vue' {
  interface Vue {
    $myGlobalMethod: (arg: string) => void;
  }
}

全局类型与模块系统的交互

在同时使用全局类型和模块系统时，需要注意作用域规则。模块中的类型默认具有模块作用域，除非显式导出。

// types/global.d.ts
declare module '*.svg' {
  const content: string;
  export default content;
}

// src/components/Icon.tsx
import logo from './logo.svg'; // 类型自动推断为string

全局类型定义的最佳实践

组织全局类型定义需要遵循一些约定。通常建议将全局类型集中管理，按功能或领域分组。

// types/global.d.ts
declare namespace App {
  namespace Models {
    interface Post {
      id: number;
      title: string;
      content: string;
    }
  }
  
  namespace Services {
    interface ApiResponse<T> {
      data: T;
      status: number;
    }
  }
}

全局类型定义的测试与验证

确保全局类型定义正确工作需要进行类型检查。可以通过创建测试文件或使用TypeScript编译器验证。

// test/globalTypes.test.ts
const testUser: MyGlobal.User = {
  id: 1,
  name: 'Test',
  email: 'test@example.com'
  // 缺少email属性将导致类型错误
};

全局类型与第三方库

当集成第三方库时，全局类型定义可以帮助简化类型管理。特别是对于那些没有提供类型定义的库。

// types/global.d.ts
declare module 'legacy-library' {
  export function doSomething(config: {
    timeout?: number;
    retries?: number;
  }): Promise<void>;
}

// src/app.ts
import { doSomething } from 'legacy-library';
doSomething({ timeout: 1000 });

全局类型定义的局限性

全局类型虽然方便，但也有其限制。过度使用可能导致命名冲突和类型定义难以追踪。

// types/global.d.ts
declare interface Window {
  myApp: {
    version: string;
    init: () => void;
  };
}

// 如果多个声明文件都扩展了Window接口，可能导致冲突

全局类型在现代TypeScript项目中的角色

随着模块系统的发展，全局类型的使用有所减少，但在特定场景下仍然不可或缺。特别是在配置类型和环境变量定义方面。

// types/global.d.ts
declare module 'config' {
  export const apiEndpoint: string;
  export const featureFlags: {
    newDashboard: boolean;
    darkMode: boolean;
  };
}

// src/api.ts
import { apiEndpoint } from 'config';
fetch(`${apiEndpoint}/users`);