TypeScript SDK项目实战指南

hacker

为了创建一个能够编译出.min.js和.min.d.ts的TypeScript SDK项目，我们需要遵循以下步骤：

初始化项目
安装必要的依赖
编写TypeScript代码
配置TypeScript编译器（tsconfig.json）
配置构建脚本（例如使用webpack或rollup等打包工具）
生成声明文件（.d.ts）
压缩代码生成.min.js

于我们需要生成.min.js，通常我们会使用打包工具来打包和压缩代码。同时，TypeScript编译器可以生成声明文件（.d.ts）。

这里我们选择使用rollup作为打包工具，因为它对Tree Shaking和输出多种格式（如ESM、CJS、UMD）支持良好，并且可以方便地生成压缩代码。

步骤1：初始化项目
创建一个新目录，并初始化npm项目。

步骤2：安装依赖
我们需要安装TypeScript、rollup以及相关插件。

步骤3：配置TypeScript
创建tsconfig.json文件，配置TypeScript编译器选项。

步骤4：配置rollup
创建rollup配置文件，配置输入、输出、插件等。

步骤5：编写代码
编写SDK的TypeScript代码。

步骤6：构建
运行rollup构建命令，生成压缩的JS文件和声明文件。

下面我们详细操作：
步骤1：初始化项目

mkdir my-sdk
cd my-sdk
npm init -y

步骤2：安装依赖

# 安装TypeScript
npm install --save-dev typescript

# 安装rollup和相关插件
npm install --save-dev rollup rollup-plugin-typescript2 rollup-plugin-terser @rollup/plugin-node-resolve

# 注意：rollup-plugin-terser用于压缩代码，rollup-plugin-typescript2用于编译TypeScript，@rollup/plugin-node-resolve用于解析node_modules中的模块

步骤3：配置TypeScript
创建tsconfig.json文件：

{
  "compilerOptions": {
    "target": "ES5",
    "module": "ESNext",
    "declaration": true,
    "outDir": "./dist",
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

注意："declaration": true会生成.d.ts声明文件。
步骤4：配置rollup
创建rollup.config.js文件：

import typescript from 'rollup-plugin-typescript2';
import { terser } from 'rollup-plugin-terser';
import { nodeResolve } from '@rollup/plugin-node-resolve';

export default {
  input: 'src/index.ts', // 入口文件
  output: {
    file: 'dist/sdk.min.js', // 输出文件
    format: 'umd', // 通用模块定义，同时支持AMD、CommonJS和全局变量
    name: 'SDK', // 全局变量名
    sourcemap: true // 生成sourcemap
  },
  plugins: [
    nodeResolve(), // 解析node_modules中的模块
    typescript({ // TypeScript编译
      tsconfig: './tsconfig.json',
      useTsconfigDeclarationDir: true // 使用tsconfig中的声明输出目录
    }),
    terser() // 压缩代码
  ]
};

步骤5：编写代码
创建src目录，并在其中创建index.ts文件，编写你的SDK代码。例如：

export class GameSDK {
  // 示例方法
  public init(): void {
    console.log('SDK initialized');
  }

  // 可以添加更多方法
}

步骤6：修改package.json的构建脚本
在package.json中添加build脚本：

"scripts": {
  "build": "rollup -c"
}

步骤7：构建
运行构建命令：

npm run build

构建完成后，在dist目录下应该会生成sdk.min.js和sdk.min.js.map（sourcemap文件）以及对应的声明文件（在dist目录下，可能是index.d.ts，具体取决于你的入口文件）。

注意：上面的rollup配置中，我们使用了rollup-plugin-typescript2，它会使用tsconfig.json中的配置，因此声明文件也会由TypeScript编译器生成。默认情况下，声明文件会输出到dist目录（由tsconfig.json中的outDir指定）。

但是，注意rollup的打包过程只会处理JS代码，声明文件是由TypeScript编译器直接生成的。因此，我们实际上会同时有rollup打包生成的JS和TypeScript编译器生成的声明文件。

但是，上面的配置中，TypeScript编译器会将声明文件输出到dist目录，而rollup打包的JS也会输出到dist目录，所以它们会在同一个目录。

补充：生成.min.d.ts
通常，我们不需要对声明文件进行压缩，因为声明文件本身不需要被运行，只需要被TypeScript编译器读取。所以，我们只需要生成普通的.d.ts文件即可。

但是，有时候我们可能希望将所有的声明文件合并为一个文件。可以使用rollup插件如rollup-plugin-dts来打包声明文件。但通常，如果我们的SDK只有一个入口，TypeScript会自动为我们生成一个对应的声明文件。如果有多个模块，可能会生成多个声明文件。如果我们希望合并为一个声明文件，可以考虑使用其他工具。

不过，为了简单起见，我们这里不额外处理声明文件，就使用TypeScript编译器生成的声明文件。

最终文件结构
完成后的项目结构大致如下：

使用SDK
其他开发者可以通过引入dist目录下的sdk.min.js和index.d.ts来使用你的SDK。

将sdk.min.js通过script标签引入，会在全局挂载你设置的name（如SDK）。

或者通过模块引入（如果开发者使用模块系统）。

将index.d.ts放在与sdk.min.js同一目录，或者通过配置TypeScript的typePath来指向声明文件。

注意：如果开发者使用TypeScript，他们需要能够找到声明文件。通常，你可以将声明文件与JS文件一起发布，这样只要在同一目录下，TypeScript会自动获取。

发布
你可以将整个项目发布到npm，或者将dist目录下的文件提供给其他开发者。

如果你发布到npm，其他开发者可以通过npm安装，然后通过import或require引入。

希望这个流程对你有所帮助！

创建 TypeScript SDK 项目实战指南

我将指导你如何创建一个 TypeScript SDK 项目，最终生成 .min.js 和 .min.d.ts 文件。下面是一个完整的实现方案，包括项目设置、构建配置和示例代码。

项目结构和实现思路

初始化 TypeScript SDK 项目
配置构建工具（Webpack + TSC）
编写 SDK 核心代码
配置类型声明生成
设置压缩和打包流程

创建示例使用页面

完整代码实现

下面是完整的项目实现，包括所有必要的文件和配置：

1. package.json

{
  "name": "game-platform-sdk",
  "version": "1.0.0",
  "description": "TypeScript SDK for Game Platform API",
  "main": "dist/sdk.min.js",
  "types": "dist/sdk.min.d.ts",
  "scripts": {
    "build": "webpack --mode=production",
    "dev": "webpack --mode=development --watch",
    "type-check": "tsc --noEmit",
    "type-declaration": "tsc --emitDeclarationOnly --declaration --outDir dist"
  },
  "devDependencies": {
    "typescript": "^4.9.5",
    "webpack": "^5.88.0",
    "webpack-cli": "^5.1.4",
    "ts-loader": "^9.4.4",
    "terser-webpack-plugin": "^5.3.9",
    "html-webpack-plugin": "^5.5.3"
  }
}

2. tsconfig.json

{
  "compilerOptions": {
    "target": "ES5",
    "module": "ESNext",
    "lib": ["DOM", "ES6"],
    "declaration": true,
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "examples"]
}

3. webpack.config.js

const TerserPlugin = require('terser-webpack-plugin');
const path = require('path');

module.exports = (env, argv) => {
  const isProduction = argv.mode === 'production';
  
  return {
    entry: './src/index.ts',
    output: {
      path: path.resolve(__dirname, 'dist'),
      filename: isProduction ? 'sdk.min.js' : 'sdk.js',
      library: 'GamePlatformSDK',
      libraryTarget: 'umd',
      globalObject: 'this',
      clean: true
    },
    resolve: {
      extensions: ['.ts', '.js']
    },
    module: {
      rules: [
        {
          test: /\.ts$/,
          use: 'ts-loader',
          exclude: /node_modules/
        }
      ]
    },
    optimization: {
      minimize: isProduction,
      minimizer: [
        new TerserPlugin({
          terserOptions: {
            format: {
              comments: false
            }
          },
          extractComments: false
        })
      ]
    },
    devtool: isProduction ? false : 'source-map'
  };
};

4. SDK 核心代码 (src/index.ts)

// 类型定义
export interface User {
  id: string;
  username: string;
  avatar?: string;
}

export interface GameData {
  score: number;
  level: number;
  achievements: string[];
}

export interface PlatformConfig {
  apiKey: string;
  debug?: boolean;
  version?: string;
}

// 游戏平台SDK主类
class GamePlatformSDK {
  private apiKey: string;
  private debug: boolean;
  private version: string;
  private isInitialized: boolean = false;

  constructor(config: PlatformConfig) {
    this.apiKey = config.apiKey;
    this.debug = config.debug || false;
    this.version = config.version || '1.0.0';
  }

  /**
   * 初始化SDK
   */
  async initialize(): Promise<boolean> {
    try {
      // 模拟API调用
      if (this.debug) {
        console.log(`Initializing SDK v${this.version} with API key: ${this.apiKey}`);
      }

      // 这里应该是实际的平台API验证
      await this.validateApiKey();

      this.isInitialized = true;
      
      if (this.debug) {
        console.log('SDK initialized successfully');
      }
      
      return true;
    } catch (error) {
      console.error('Failed to initialize SDK:', error);
      return false;
    }
  }

  /**
   * 验证API密钥
   */
  private async validateApiKey(): Promise<void> {
    // 模拟API验证
    return new Promise((resolve, reject) => {
      setTimeout(() => {
        if (this.apiKey && this.apiKey.length > 10) {
          resolve();
        } else {
          reject(new Error('Invalid API key'));
        }
      }, 500);
    });
  }

  /**
   * 获取用户信息
   */
  async getUserInfo(userId: string): Promise<User> {
    this.checkInitialized();
    
    // 模拟API调用
    return new Promise((resolve) => {
      setTimeout(() => {
        resolve({
          id: userId,
          username: `user_${userId}`,
          avatar: `https://api.example.com/avatars/${userId}.png`
        });
      }, 300);
    });
  }

  /**
   * 提交游戏成绩
   */
  async submitScore(score: number): Promise<boolean> {
    this.checkInitialized();
    
    // 模拟API调用
    return new Promise((resolve) => {
      setTimeout(() => {
        if (this.debug) {
          console.log(`Score submitted: ${score}`);
        }
        resolve(true);
      }, 400);
    });
  }

  /**
   * 获取游戏数据
   */
  async getGameData(): Promise<GameData> {
    this.checkInitialized();
    
    // 模拟API调用
    return new Promise((resolve) => {
      setTimeout(() => {
        resolve({
          score: 1000,
          level: 5,
          achievements: ['First Win', 'Speed Runner', 'Completionist']
        });
      }, 400);
    });
  }

  /**
   * 检查SDK是否初始化
   */
  private checkInitialized(): void {
    if (!this.isInitialized) {
      throw new Error('SDK is not initialized. Call initialize() first.');
    }
  }

  /**
   * 显示平台UI
   */
  showPlatformUI(): void {
    this.checkInitialized();
    
    // 创建模拟UI元素
    const overlay = document.createElement('div');
    overlay.style.position = 'fixed';
    overlay.style.top = '0';
    overlay.style.right = '0';
    overlay.style.width = '300px';
    overlay.style.height = '100%';
    overlay.style.background = 'white';
    overlay.style.boxShadow = '-2px 0 10px rgba(0,0,0,0.2)';
    overlay.style.zIndex = '10000';
    overlay.style.padding = '20px';
    overlay.style.overflowY = 'auto';
    
    overlay.innerHTML = `
      <h2>Game Platform</h2>
      <div id="sdk-content">
        <p>Welcome to the game platform!</p>
        <button id="sdk-close" style="position: absolute; top: 10px; right: 10px;">X</button>
        <div id="user-data">Loading user data...</div>
      </div>
    `;
    
    document.body.appendChild(overlay);
    
    // 添加关闭按钮事件
    const closeBtn = document.getElementById('sdk-close');
    if (closeBtn) {
      closeBtn.addEventListener('click', () => {
        document.body.removeChild(overlay);
      });
    }
    
    // 加载用户数据
    this.getUserInfo('12345').then(user => {
      const userDataEl = document.getElementById('user-data');
      if (userDataEl) {
        userDataEl.innerHTML = `
          <h3>User Info</h3>
          <p><strong>ID:</strong> ${user.id}</p>
          <p><strong>Username:</strong> ${user.username}</p>
        `;
      }
    });
  }
}

// 导出SDK实例创建函数
export function createSDK(config: PlatformConfig): GamePlatformSDK {
  return new GamePlatformSDK(config);
}

// 默认导出
export default GamePlatformSDK;

5. 构建和生成类型声明
在 package.json 中我们已经添加了构建脚本，执行以下命令：

# 安装依赖
npm install

# 生成压缩的JS文件
npm run build

# 生成类型声明文件
npm run type-declaration

6. 示例页面 (index.html)

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Game Platform SDK Example</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            max-width: 800px;
            margin: 0 auto;
            padding: 20px;
            background-color: #f5f5f5;
        }
        .container {
            background: white;
            padding: 20px;
            border-radius: 8px;
            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
        }
        h1 {
            color: #333;
        }
        .btn {
            background-color: #4CAF50;
            border: none;
            color: white;
            padding: 10px 20px;
            text-align: center;
            text-decoration: none;
            display: inline-block;
            font-size: 16px;
            margin: 10px 5px;
            cursor: pointer;
            border-radius: 4px;
            transition: background-color 0.3s;
        }
        .btn:hover {
            background-color: #45a049;
        }
        .btn-secondary {
            background-color: #008CBA;
        }
        .btn-secondary:hover {
            background-color: #007B9A;
        }
        .log {
            background-color: #f8f8f8;
            border-left: 4px solid #4CAF50;
            padding: 10px;
            margin-top: 20px;
            font-family: monospace;
            white-space: pre-wrap;
            max-height: 200px;
            overflow-y: auto;
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>Game Platform SDK Demo</h1>
        <p>This demo shows how to use the Game Platform SDK in a web application.</p>
        
        <div>
            <button id="initBtn" class="btn">Initialize SDK</button>
            <button id="userBtn" class="btn" disabled>Get User Info</button>
            <button id="scoreBtn" class="btn" disabled>Submit Score</button>
            <button id="dataBtn" class="btn" disabled>Get Game Data</button>
            <button id="uiBtn" class="btn" disabled>Show Platform UI</button>
        </div>
        
        <div id="output" class="log">SDK output will appear here...</div>
    </div>

    <!-- 加载SDK -->
    <script src="./dist/sdk.min.js"></script>
    <script>
        // 使用SDK
        const sdk = new GamePlatformSDK.GamePlatformSDK({
            apiKey: 'my_secret_api_key_12345',
            debug: true
        });

        const outputEl = document.getElementById('output');
        const initBtn = document.getElementById('initBtn');
        const userBtn = document.getElementById('userBtn');
        const scoreBtn = document.getElementById('scoreBtn');
        const dataBtn = document.getElementById('dataBtn');
        const uiBtn = document.getElementById('uiBtn');

        function log(message) {
            outputEl.textContent += message + '\n';
            outputEl.scrollTop = outputEl.scrollHeight;
        }

        initBtn.addEventListener('click', async () => {
            log('Initializing SDK...');
            const success = await sdk.initialize();
            
            if (success) {
                log('SDK initialized successfully!');
                userBtn.disabled = false;
                scoreBtn.disabled = false;
                dataBtn.disabled = false;
                uiBtn.disabled = false;
            } else {
                log('Failed to initialize SDK.');
            }
        });

        userBtn.addEventListener('click', async () => {
            log('Getting user info...');
            try {
                const user = await sdk.getUserInfo('12345');
                log(`User info: ${JSON.stringify(user, null, 2)}`);
            } catch (error) {
                log(`Error: ${error.message}`);
            }
        });

        scoreBtn.addEventListener('click', async () => {
            const score = Math.floor(Math.random() * 1000);
            log(`Submitting score: ${score}`);
            try {
                const success = await sdk.submitScore(score);
                log(`Score submission ${success ? 'successful' : 'failed'}`);
            } catch (error) {
                log(`Error: ${error.message}`);
            }
        });

        dataBtn.addEventListener('click', async () => {
            log('Getting game data...');
            try {
                const gameData = await sdk.getGameData();
                log(`Game data: ${JSON.stringify(gameData, null, 2)}`);
            } catch (error) {
                log(`Error: ${error.message}`);
            }
        });

        uiBtn.addEventListener('click', () => {
            log('Showing platform UI...');
            try {
                sdk.showPlatformUI();
                log('Platform UI displayed');
            } catch (error) {
                log(`Error: ${error.message}`);
            }
        });
    </script>
</body>
</html>

使用说明
按照上面的文件结构创建项目

运行 npm install 安装依赖
运行 npm run build 构建压缩的 SDK 文件
运行 npm run type-declaration 生成类型声明文件
打开 index.html 查看示例使用情况
发布SDK

发布时，你只需要将以下文件提供给其他开发者：

dist/sdk.min.js - 压缩后的SDK代码

dist/sdk.min.d.ts - TypeScript类型声明文件

其他开发者可以通过script标签引入SDK，或者通过模块加载器使用，同时可以获得完整的TypeScript类型支持。

这个实现提供了完整的SDK开发工作流程，包括类型安全、压缩打包和示例使用。你可以根据实际游戏平台的API需求扩展SDK的功能。