API Types CLI 使用说明

    ___    ____  ____   ______                      
   /   |  / __ \/  _/  /_  __/_  ______  ___  _____
  / /| | / /_/ // /     / / / / / / __ \/ _ \/ ___/
 / ___ |/ ____// /     / / / /_/ / /_/ /  __(__  ) 
/_/  |_/_/   /___/    /_/  \__, / .___/\___/____/  
                          /____/_/                 

🚀 API接口TypeScript类型生成器

📦 安装

# 全局安装
npm install -g api-types-cli

# 或本地安装
npm install api-types-cli
npx api-types --help

🚀 快速开始

接口命名规范

为了生成符合 TypeScript 规范的类型文件，接口名称需要遵循以下规则：

• 只能包含字母、数字、下划线和连字符
• 必须以字母或下划线开头
• 长度不超过 100 个字符
• 不能使用 TypeScript 关键字
• 会自动转换为 PascalCase 格式，并智能处理缩写词

示例转换：

用户输入: "github_user" 或 "githubUser" 或 "github-user"
实际生成: "GithubUser"

用户输入: "user_profile_data"
实际生成: "UserProfileData"

用户输入: "api_response" 或 "api-response"  
实际生成: "APIResponse"

用户输入: "xml_parser" 或 "xml-parser"
实际生成: "XMLParser"

用户输入: "user_id_mapping"
实际生成: "UserIDMapping"

智能缩写词处理： 系统会自动识别并正确处理常见的技术缩写词，包括：

• API, XML, HTML, CSS, JSON, URL, HTTP, HTTPS
• ID, UUID, SQL, DB, UI, UX, IO
• JWT, OAuth, CORS, CSRF, XSS 等

这确保了生成的接口名称既符合 TypeScript 规范，又保持了良好的可读性。

1. 单个接口生成

# 交互式生成单个接口类型
api-types generate

# 直接指定参数
api-types generate --output ./types --runtime

2. 批量生成（推荐）

步骤 1：生成配置文件

# 交互式生成配置
api-types config

# 或创建示例配置
api-types init --format json

步骤 2：编辑配置文件

[
  {
    "name": "User",
    "url": "https://jsonplaceholder.typicode.com/users/1",
    "method": "GET",
    "sampleOnly": false
  },
  {
    "name": "Users", 
    "url": "https://jsonplaceholder.typicode.com/users",
    "method": "GET",
    "sampleOnly": true
  },
  {
    "name": "Post",
    "url": "https://api.example.com/posts/1",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer your-token"
    }
  }
]

步骤 3：生成类型

api-types generate --config api-config.json --runtime --output ./src/types

🛠️ 命令参考

api-types generate

生成 API 类型文件

选项：

• -o, --output <dir> 输出目录 (默认: ./types)
• -c, --config <file> 配置文件路径
• -r, --runtime 生成运行时类型检查
• -f, --format <format> 输出格式 (typescript/typescript-zod/typescript-effect-schema)
• -p, --parallel <num> 并行处理数量 (默认: 3)
• -t, --timeout <seconds> 请求超时时间 (默认: 30)
• --retries <num> 重试次数 (默认: 2)
• -q, --quiet 静默模式
• -w, --watch 监听模式 (开发中)

api-types config

交互式生成配置文件

api-types init

初始化示例配置文件

选项：

• -f, --format <format> 配置格式 (json|yaml)

📝 配置文件格式

JSON 格式

[
  {
    "name": "User",
    "url": "https://api.example.com/users/1",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer token",
      "Content-Type": "application/json"
    },
    "body": null,
    "sampleOnly": false
  }
]

YAML 格式

- name: User
  url: https://api.example.com/users/1
  method: GET
  headers:
    Authorization: Bearer token
    Content-Type: application/json
  sampleOnly: false

- name: Users
  url: https://api.example.com/users
  method: GET
  sampleOnly: true

🎯 使用示例

1. GitHub API

# 创建配置
cat > github-config.json << 'EOF'
[
  {
    "name": "GitHubUser",
    "url": "https://api.github.com/users/octocat",
    "method": "GET"
  },
  {
    "name": "GitHubRepos",
    "url": "https://api.github.com/users/octocat/repos",
    "method": "GET",
    "sampleOnly": true
  }
]
EOF

# 生成类型
api-types generate --config github-config.json --runtime --output ./src/types/github

2. REST API 完整示例

# 创建 REST API 配置
cat > rest-api-config.json << 'EOF'
[
  {
    "name": "User",
    "url": "https://jsonplaceholder.typicode.com/users/1"
  },
  {
    "name": "Users",
    "url": "https://jsonplaceholder.typicode.com/users",
    "sampleOnly": true
  },
  {
    "name": "Post",
    "url": "https://jsonplaceholder.typicode.com/posts/1"
  },
  {
    "name": "Posts",
    "url": "https://jsonplaceholder.typicode.com/posts",
    "sampleOnly": true
  }
]
EOF

# 生成类型（带运行时验证）
api-types generate --config rest-api-config.json --runtime --parallel 4 --output ./types

3. 需要认证的 API

cat > auth-api-config.json << 'EOF'
[
  {
    "name": "Profile",
    "url": "https://api.example.com/me",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer your-jwt-token",
      "X-API-Key": "your-api-key"
    }
  },
  {
    "name": "Orders",
    "url": "https://api.example.com/orders",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer your-jwt-token"
    },
    "sampleOnly": true
  }
]
EOF

📊 生成的文件结构

types/
├── index.ts              # 索引文件，导出所有类型
├── User.ts               # User 类型定义和转换器
├── Posts.ts              # Posts 类型定义和转换器
├── ...                   # 其他类型文件
└── usage-example.ts      # 使用示例代码

🔧 在项目中使用

1. 导入类型

import { User, Post, UserConvert, PostConvert } from './types';

// 或者分别导入
import { User } from './types/User';
import { Convert as UserConvert } from './types/User';

2. 使用转换器（带运行时验证）

async function fetchUser(id: number): Promise<User | null> {
  try {
    const response = await fetch(`/api/users/${id}`);
    const jsonText = await response.text();
    
    // 使用生成的转换器，包含运行时验证
    return UserConvert.toUser(jsonText);
  } catch (error) {
    console.error('用户数据解析失败:', error);
    return null;
  }
}

3. 集成到构建流程

{
  "scripts": {
    "generate-types": "api-types generate --config api-config.json --runtime --output ./src/types",
    "prebuild": "npm run generate-types",
    "build": "tsc"
  }
}

🎛️ 高级配置

环境变量支持

在配置文件中使用环境变量：

[
  {
    "name": "Profile",
    "url": "${API_BASE_URL}/me",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}"
    }
  }
]

条件配置

[
  {
    "name": "User",
    "url": "https://api.example.com/users/1",
    "enabled": true
  },
  {
    "name": "AdminUser", 
    "url": "https://api.example.com/admin/users/1",
    "enabled": false
  }
]

复杂请求体

[
  {
    "name": "CreateUser",
    "url": "https://api.example.com/users",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "name": "Test User",
      "email": "[email protected]",
      "role": "user"
    }
  }
]

📁 目录结构

api-types-cli/
├── src/
│   ├── cli/
│   │   ├── index.ts              # CLI 入口文件
│   │   ├── commands/             # 命令处理器
│   │   │   ├── generate.ts       # generate 命令
│   │   │   ├── config.ts         # config 命令  
│   │   │   └── init.ts           # init 命令
│   │   └── utils/
│   │       ├── help-formatter.ts # 自定义帮助格式
│   │       └── banner.ts         # Banner 显示
│   ├── core/
│   │   ├── generator.ts          # 核心生成器类
│   │   ├── config-generator.ts   # 配置生成器
│   │   ├── api-client.ts         # API 请求处理
│   │   └── type-generator.ts     # TypeScript 类型生成
│   ├── utils/
│   │   ├── logger.ts             # 增强日志工具
│   │   ├── validator.ts          # 验证工具
│   │   ├── formatter.ts          # 格式化工具
│   │   ├── file-utils.ts         # 文件操作工具
│   │   └── constants.ts          # 常量定义
│   ├── types/
│   │   ├── config.ts             # 配置相关类型
│   │   ├── generator.ts          # 生成器相关类型
│   │   └── common.ts             # 通用类型
│   └── templates/
│       └── index.template.ts     # 索引文件模板
├── dist/                         # 编译输出
├── tests/                        # 测试文件
├── examples/                     # 示例配置
├── package.json
├── tsconfig.json
└── README.md

🔄 CI/CD 集成

GitHub Actions

name: Generate API Types

on:
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨2点运行
  workflow_dispatch:

jobs:
  generate-types:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Generate API types
        run: |
          npx api-types generate \
            --config api-config.json \
            --runtime \
            --output ./src/types
        env:
          API_TOKEN: ${{ secrets.API_TOKEN }}
          API_BASE_URL: ${{ vars.API_BASE_URL }}
          
      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v5
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          commit-message: 'chore: update API types'
          title: 'Update API Types'
          branch: update-api-types

GitLab CI

generate-types:
  stage: build
  image: node:18
  script:
    - npm ci
    - npx api-types generate --config api-config.json --runtime --output ./src/types
  artifacts:
    paths:
      - src/types/
    expire_in: 1 week
  only:
    - schedules
    - web

🛡️ 错误处理和最佳实践

1. 网络错误处理

# 设置重试和超时
api-types generate \
  --config api-config.json \
  --timeout 60 \
  --retries 3 \
  --parallel 2

2. 大型 API 响应处理

[
  {
    "name": "LargeDataset",
    "url": "https://api.example.com/large-dataset",
    "sampleOnly": true,
    "timeout": 120
  }
]

3. 版本化类型管理

# 为不同版本的 API 生成类型
api-types generate --config api-v1-config.json --output ./src/types/v1
api-types generate --config api-v2-config.json --output ./src/types/v2

🧪 测试生成的类型

创建测试文件

// types.test.ts
import { UserConvert, User } from './types/User';

describe('User Types', () => {
  test('should parse valid user data', () => {
    const validJson = '{"id": 1, "name": "John", "email": "[email protected]"}';
    const user: User = UserConvert.toUser(validJson);
    
    expect(user.id).toBe(1);
    expect(user.name).toBe('John');
    expect(user.email).toBe('[email protected]');
  });

  test('should throw error for invalid data', () => {
    const invalidJson = '{"id": "not-a-number", "name": "John"}';
    
    expect(() => UserConvert.toUser(invalidJson)).toThrow();
  });
});

📚 常见使用模式

1. React Hook 集成

// hooks/useApiData.ts
import { useState, useEffect } from 'react';
import { UserConvert, User } from '../types/User';

export function useUser(id: number) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    async function fetchUser() {
      try {
        setLoading(true);
        const response = await fetch(`/api/users/${id}`);
        const jsonText = await response.text();
        const userData = UserConvert.toUser(jsonText);
        setUser(userData);
        setError(null);
      } catch (err) {
        setError(err instanceof Error ? err.message : 'Unknown error');
        setUser(null);
      } finally {
        setLoading(false);
      }
    }

    fetchUser();
  }, [id]);

  return { user, loading, error };
}

2. Express.js 中间件

// middleware/validateResponse.ts
import { PostConvert } from '../types/Post';

export function validateApiResponse(req: Request, res: Response, next: NextFunction) {
  const originalSend = res.send;
  
  res.send = function(data: any) {
    try {
      // 验证响应数据格式
      if (req.path.includes('/posts/')) {
        PostConvert.toPost(JSON.stringify(data));
      }
      return originalSend.call(this, data);
    } catch (error) {
      console.error('Response validation failed:', error);
      return originalSend.call(this, data); // 或者返回错误
    }
  };
  
  next();
}

3. 数据转换管道

// utils/dataTransformer.ts
import { UserConvert, PostConvert } from '../types';

type DataConverter = {
  [key: string]: (json: string) => any;
};

const converters: DataConverter = {
  user: UserConvert.toUser,
  post: PostConvert.toPost,
  // 添加更多转换器...
};

export function transformApiData(type: string, jsonData: string) {
  const converter = converters[type];
  if (!converter) {
    throw new Error(`No converter found for type: ${type}`);
  }
  
  return converter(jsonData);
}

// 批量转换
export function batchTransform(items: Array<{type: string, data: string}>) {
  return items.map(item => ({
    type: item.type,
    data: transformApiData(item.type, item.data)
  }));
}

🔧 故障排除

常见问题

1. 网络连接问题

# 检查网络连接
curl -I https://api.example.com/users/1

# 使用代理
export HTTP_PROXY=http://proxy.example.com:8080
api-types generate --config api-config.json

2. 认证问题

# 测试 API 访问
curl -H "Authorization: Bearer your-token" https://api.example.com/users/1

# 在配置中添加正确的认证头

3. JSON 格式问题

# 验证 API 返回的 JSON
curl -s https://api.example.com/users/1 | jq '.'

# 检查是否有额外的字符或格式问题

4. 类型生成失败

# 启用详细输出
api-types generate --config api-config.json --verbose

调试技巧

1. 保存中间文件

# 保存下载的 JSON 数据以供调试
mkdir -p debug-data
api-types generate --config api-config.json --save-temp --temp-dir debug-data

2. 分步执行

# 只下载数据，不生成类型
api-types download --config api-config.json --output debug-data

# 从已下载的数据生成类型
api-types generate --from-files debug-data --output types

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

开发环境设置

# 克隆仓库
git clone https://github.com/your-username/api-types-cli.git
cd api-types-cli

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建
npm run build

# 测试
npm test

添加新功能

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

📄 许可证

MIT License - 详见 LICENSE 文件