czh-api 1.0.2 → 1.0.4

package/src/commands/build.ts

@@ -3,7 +3,7 @@
  * @Author: czh
  * @Date: 2025-07-02 10:39:30
  * @LastEditors: Czh
- * @LastEditTime: 2025-12-25 12:40:34
+ * @LastEditTime: 2026-03-17 09:18:39
  */
 import chalk from 'chalk';
 import path from 'path';
@@ -15,8 +15,265 @@ import Handlebars from 'handlebars';
 import { rimraf } from 'rimraf';
 import axios from 'axios';
 import { compile } from 'json-schema-to-typescript';
+import { Converter } from '@apiture/openapi-down-convert';
 
-interface IConfig {
+// 统一的类型转换函数
+function convertOpenApiTypeToTypeScript(openApiType: string | undefined): string {
+    if (!openApiType) return 'any';
+    
+    switch (openApiType) {
+        case 'integer':
+            return 'number';
+        case 'object':
+            return 'any';
+        case 'array':
+            return 'any[]';
+        case 'boolean':
+            return 'boolean';
+        case 'string':
+            return 'string';
+        case 'number':
+            return 'number';
+        default:
+            return 'any';
+    }
+}
+
+// 改进类型定义的辅助函数
+function isValidTypeIdentifier(typeName: string | undefined): boolean {
+    if (!typeName) return false;
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(typeName);
+}
+
+function escapeRegex(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function resolveInterfaceTargetType(typeName: string | undefined): string | null {
+    if (typeof typeName !== 'string' || typeName.length === 0) return null;
+    if (isValidTypeIdentifier(typeName)) return typeName;
+
+    const arrayMatch = typeName.match(/^([A-Za-z_$][A-Za-z0-9_$]*)\[\]$/);
+    if (arrayMatch) {
+        return arrayMatch[1];
+    }
+
+    return null;
+}
+
+function findInterfaceBlockRange(content: string, typeName: string): { start: number; end: number } | null {
+    const startRegex = new RegExp(`export interface ${escapeRegex(typeName)}\\s*\\{`);
+    const match = startRegex.exec(content);
+    if (!match) return null;
+
+    const start = match.index;
+    const openBraceIndex = start + match[0].lastIndexOf('{');
+    let depth = 0;
+
+    for (let i = openBraceIndex; i < content.length; i++) {
+        const ch = content[i];
+        if (ch === '{') {
+            depth++;
+        } else if (ch === '}') {
+            depth--;
+            if (depth === 0) {
+                return { start, end: i + 1 };
+            }
+        }
+    }
+
+    return null;
+}
+
+function improveTypeDefinitions(typesContent: string, endpoints: any[]): string {
+    let improvedContent = typesContent;
+    
+    // 收集所有需要改进的类型定义
+    const typeImprovements: { [typeName: string]: string } = {};
+
+    // 辅助函数：将 jsdoc params 转换为接口字段
+    function buildFieldsFromJsdocParams(jsdocParams: any[]): string {
+        return jsdocParams
+            .filter((param: any) => param.name && param.type)
+            .map((param: any) => {
+                const optional = !param.required ? '?' : '';
+                let type = param.type;
+                
+                // 处理联合类型，确保正确的 TypeScript 语法
+                if (type && type.includes(' | ')) {
+                    if (type.includes('null')) {
+                        type = type.replace(/\s*\|\s*null/g, ' | null');
+                    }
+                } else {
+                    type = convertOpenApiTypeToTypeScript(type);
+                }
+                
+                const comment = param.description ? ` // ${param.description}` : '';
+                return `  ${param.name}${optional}: ${type};${comment}`;
+            })
+            .join('\n');
+    }
+    
+    endpoints.forEach(endpoint => {
+        // 改进 params 类型 - 使用 paramsJsdocParams（仅包含 path/query 参数）
+        const requestParamsTypeName = endpoint.requestParamsTypeName;
+        if (requestParamsTypeName && isValidTypeIdentifier(requestParamsTypeName) && endpoint.paramsJsdocParams && endpoint.paramsJsdocParams.length > 0) {
+            const paramsFields = buildFieldsFromJsdocParams(endpoint.paramsJsdocParams);
+            
+            if (paramsFields) {
+                typeImprovements[requestParamsTypeName] = `export interface ${requestParamsTypeName} {
+${paramsFields}
+}`;
+            }
+        }
+        
+        // 改进 requestBody 类型 - 使用 dataJsdocParams（仅包含 requestBody 参数）
+        const requestBodyTypeName = endpoint.requestBodyTypeName;
+        if (requestBodyTypeName && isValidTypeIdentifier(requestBodyTypeName) && endpoint.dataJsdocParams && endpoint.dataJsdocParams.length > 0) {
+            const dataFields = buildFieldsFromJsdocParams(endpoint.dataJsdocParams);
+            
+            if (dataFields) {
+                typeImprovements[requestBodyTypeName] = `export interface ${requestBodyTypeName} {
+${dataFields}
+}`;
+            }
+        }
+
+        // 改进 response 类型 - 使用 responseJsdocParams（包含响应字段信息）
+        const responseTargetType = resolveInterfaceTargetType(endpoint.responseTypeName);
+        if (responseTargetType && endpoint.responseTypeName !== 'void' && endpoint.responseJsdocParams && endpoint.responseJsdocParams.length > 0) {
+            const responseFields = buildFieldsFromJsdocParams(endpoint.responseJsdocParams);
+            
+            if (responseFields) {
+                typeImprovements[responseTargetType] = `export interface ${responseTargetType} {
+${responseFields}
+}`;
+            }
+        }
+    });
+    
+    // 替换现有的类型定义
+    Object.entries(typeImprovements).forEach(([typeName, newDefinition]) => {
+        // 查找并替换现有的接口定义
+        const blockRange = findInterfaceBlockRange(improvedContent, typeName);
+        if (blockRange) {
+            improvedContent =
+                improvedContent.slice(0, blockRange.start) +
+                newDefinition +
+                improvedContent.slice(blockRange.end);
+        } else {
+            // 如果没找到接口定义，添加到末尾
+            improvedContent += '\n\n' + newDefinition;
+        }
+    });
+    
+    return improvedContent;
+}
+
+// 移除无用的类型别名
+function removeUselessTypeAliases(typesContent: string): string {
+    let cleanedContent = typesContent;
+    
+    // 收集要删除的类型别名及其对应的基础类型
+    const typeAliasMap: { [aliasName: string]: string } = {};
+    
+    // 匹配简单的类型别名 (export type Name = string;)
+    const simpleTypeAliasRegex = /export type (\w+\d*) = (string|number|boolean)(\s*\|\s*null)?;?\n?/g;
+    let match;
+    while ((match = simpleTypeAliasRegex.exec(cleanedContent)) !== null) {
+        const aliasName = match[1];
+        const baseType = match[2] + (match[3] || '');
+        typeAliasMap[aliasName] = baseType;
+    }
+    
+    // 匹配带注释的类型别名
+    const commentedTypeAliasRegex = /\/\*\*[^*]*\*\/\nexport type (\w+\d*) = (string|number|boolean)(\s*\|\s*null)?;?\n?/g;
+    while ((match = commentedTypeAliasRegex.exec(cleanedContent)) !== null) {
+        const aliasName = match[1];
+        const baseType = match[2] + (match[3] || '');
+        typeAliasMap[aliasName] = baseType;
+    }
+    
+    // 匹配空的 JSON 类型别名 (export type Name = {};)
+    const jsonTypeAliasRegex = /export type (\w+) = \{\}(\s*\|\s*null)?;?\n?/g;
+    while ((match = jsonTypeAliasRegex.exec(cleanedContent)) !== null) {
+        const aliasName = match[1];
+        const baseType = 'any' + (match[2] || '');
+        typeAliasMap[aliasName] = baseType;
+    }
+    
+    // 安全地替换接口中对这些类型别名的引用
+    Object.entries(typeAliasMap).forEach(([aliasName, baseType]) => {
+        // 创建更精确的正则表达式，确保只替换完整的类型引用
+        const escapedAliasName = aliasName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        
+        // 替换接口字段中的类型引用 (fieldName: AliasName;)
+        const fieldTypeRegex = new RegExp(`(\\w+\\??:\\s*)${escapedAliasName}(\\s*;)`, 'g');
+        cleanedContent = cleanedContent.replace(fieldTypeRegex, `$1${baseType}$2`);
+        
+        // 替换接口字段中的类型引用，包括注释 (fieldName: AliasName; // comment)
+        const fieldTypeWithCommentRegex = new RegExp(`(\\w+\\??:\\s*)${escapedAliasName}(\\s*;\\s*//[^\\n]*)`, 'g');
+        cleanedContent = cleanedContent.replace(fieldTypeWithCommentRegex, `$1${baseType}$2`);
+    });
+    
+    // 移除类型别名定义（按行移除，避免破坏其他内容）
+    const lines = cleanedContent.split('\n');
+    const filteredLines = lines.filter(line => {
+        // 移除简单类型别名
+        if (/^export type \w+\d* = (string|number|boolean)(\s*\|\s*null)?;?\s*$/.test(line)) {
+            return false;
+        }
+        // 移除空对象类型别名
+        if (/^export type \w+ = \{\}(\s*\|\s*null)?;?\s*$/.test(line)) {
+            return false;
+        }
+        return true;
+    });
+    
+    cleanedContent = filteredLines.join('\n');
+    
+    // 清理多余的空行和孤立的注释
+    cleanedContent = cleanedContent.replace(/\n{3,}/g, '\n\n');
+    
+    // 移除孤立的类型注释（没有对应类型定义的注释）
+    cleanedContent = cleanedContent.replace(/\/\*\*\n \* [^\n]*\n \*\/\n(?!export)/g, '');
+    
+    return cleanedContent;
+}
+
+function normalizeRef(refValue: string): string {
+    const match = refValue.match(/^#\/components\/schemas\/([^/]+)$/);
+    if (match) {
+        return `#/definitions/${match[1]}`;
+    }
+    return refValue;
+}
+
+function normalizeSchemaRefs<T>(value: T): T {
+    if (Array.isArray(value)) {
+        return value.map(item => normalizeSchemaRefs(item)) as T;
+    }
+
+    if (value && typeof value === 'object') {
+        const obj = value as Record<string, unknown>;
+        const normalized: Record<string, unknown> = {};
+
+        for (const key in obj) {
+            const currentValue = obj[key];
+            if (key === '$ref' && typeof currentValue === 'string') {
+                normalized[key] = normalizeRef(currentValue);
+            } else {
+                normalized[key] = normalizeSchemaRefs(currentValue);
+            }
+        }
+
+        return normalized as T;
+    }
+
+    return value;
+}
+
+interface IConfig {
     url: string;
     outputDir: string;
     httpClientPath: string;
@@ -24,6 +281,7 @@ interface IConfig {
     customImports?: string[];
     excludePaths?: string[];
     includePaths?: string[];
+    pathPrefixes?: Array<{ path: string; packageName?: string }>;
 }
 
 export const handleBuild = async () => {
@@ -41,11 +299,58 @@ export const handleBuild = async () => {
         // Fetch and parse Swagger/OpenAPI document
         console.log(chalk.blue(`正在从 ${config.url} 获取 API 文档...`));
         const response = await axios.get(config.url);
-        const api = await SwaggerParser.bundle(response.data);
-        console.log(chalk.green('Swagger document fetched and bundled successfully.'));
+        let apiDoc = response.data;
+        let isConverted = false;
+        
+        // 检查是否为 OpenAPI 3.1.0，如果是则转换为 3.0.x
+        if (apiDoc.openapi && apiDoc.openapi.startsWith('3.1')) {
+            console.log(chalk.yellow('检测到 OpenAPI 3.1.0 规范，正在转换为 3.0.x...'));
+            try {
+                // 使用更保守的转换选项
+                const converter = new Converter(apiDoc, {
+                    verbose: false,
+                    allOfTransform: false, // 不使用 allOf 转换，避免引用问题
+                    deleteExampleWithId: false,
+                    convertSchemaComments: false
+                });
+                apiDoc = converter.convert();
+                isConverted = true;
+                console.log(chalk.green('OpenAPI 3.1.0 已成功转换为 3.0.x'));
+            } catch (convertError: any) {
+                console.warn(chalk.yellow('OpenAPI 版本转换失败，尝试直接解析原始文档...'));
+                console.warn(chalk.yellow('转换错误:'), convertError?.message || convertError);
+                // 如果转换失败，尝试直接使用原始文档
+                apiDoc = response.data;
+                isConverted = false;
+            }
+        }
+        
+        let api;
+        try {
+            api = await SwaggerParser.bundle(apiDoc);
+            console.log(chalk.green('Swagger document fetched and bundled successfully.'));
+        } catch (bundleError: any) {
+            console.warn(chalk.yellow('SwaggerParser.bundle 失败，尝试直接使用文档...'));
+            console.warn(chalk.yellow('Bundle 错误:'), bundleError?.message || bundleError);
+            
+            // 如果 bundle 失败，直接使用转换后的文档
+            if (isConverted) {
+                console.log(chalk.blue('使用转换后的文档继续处理...'));
+                api = apiDoc;
+            } else {
+                // 如果是 OpenAPI 3.1.0 且之前转换失败，提供更详细的错误信息
+                if (apiDoc.openapi && apiDoc.openapi.startsWith('3.1')) {
+                    console.error(chalk.red('建议解决方案:'));
+                    console.error(chalk.red('1. 检查 FastAPI 应用是否可以生成 OpenAPI 3.0.x 版本的文档'));
+                    console.error(chalk.red('2. 或者在 FastAPI 中配置: app = FastAPI(openapi_version="3.0.2")'));
+                    console.error(chalk.red('3. 或者使用 excludePaths 排除有问题的接口路径'));
+                }
+                throw bundleError;
+            }
+        }
 
         // Process the API document
-        const modules = processApi(api, config.excludePaths || [], config.includePaths || []);
+        const modules = processApi(api, config.excludePaths || [], config.includePaths || [], config.pathPrefixes || []);
         console.log(chalk.blue('API processed into modules.'));
 
         // Clean output directory
@@ -78,70 +383,303 @@ export const handleBuild = async () => {
             const module = modules[moduleName];
             const moduleDir = path.join(outputDir, moduleName);
             fs.mkdirSync(moduleDir, { recursive: true });
+            
+            // 提取模块的基础名称（用于文件名）
+            const moduleBaseName = moduleName.includes('/') 
+                ? moduleName.split('/').pop() 
+                : moduleName;
 
             let typesContent = '';
             // Generate types.ts
             if (Object.keys(module.schemas).length > 0) {
-                const schemasWithTitles: { [key: string]: OpenAPIV3.SchemaObject } = {};
-                for (const schemaName in module.schemas) {
-                    schemasWithTitles[schemaName] = {
-                        ...module.schemas[schemaName],
-                        title: schemaName, 
+                console.log(chalk.blue(`正在为模块 "${moduleName}" 生成类型文件，包含 ${Object.keys(module.schemas).length} 个 schema`));
+                try {
+                    const normalizedModuleSchemas = normalizeSchemaRefs(module.schemas);
+                    const schemasWithTitles: { [key: string]: OpenAPIV3.SchemaObject } = {};
+                    for (const schemaName in normalizedModuleSchemas) {
+                        schemasWithTitles[schemaName] = {
+                            ...normalizedModuleSchemas[schemaName],
+                            title: schemaName, 
+                        };
+                    }
+        
+                    const rootSchemaForCompiler = {
+                        title: 'schemas',
+                        type: 'object',
+                        properties: {},
+                        additionalProperties: false,
+                        definitions: schemasWithTitles,
+                        components: {
+                            schemas: schemasWithTitles
+                        }
                     };
-                }
-    
-                const rootSchemaForCompiler = {
-                    title: 'schemas',
-                    type: 'object',
-                    properties: {},
-                    additionalProperties: false,
-                    definitions: schemasWithTitles,
-                    components: {
-                        schemas: schemasWithTitles
+        
+                    console.log(chalk.blue(`开始编译 ${Object.keys(schemasWithTitles).length} 个类型定义...`));
+                    typesContent = await compile(rootSchemaForCompiler as any, 'schemas', {
+                        bannerComment: '/* eslint-disable */\n/**\n* This file was automatically generated by czh-api.\n* DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,\n* and run czh-api build to regenerate this file.\n*/',
+                        unreachableDefinitions: true,
+                        additionalProperties: false, 
+                    });
+        
+                    typesContent = typesContent.replace(/export interface \w+ \{\s*\}\n/g, '');
+                    const refCommentRegex = /\/\*\*\n \* This interface was referenced by `\w+`'s JSON-Schema[\s\S]*?\*\/\n/g;
+                    typesContent = typesContent.replace(refCommentRegex, '');
+                    typesContent = typesContent.replace(/:\s*\{\}\[\]/g, ': any[]'); 
+                    typesContent = typesContent.replace(/\[k: string\]: \{\}/g, '[k: string]: any'); 
+                    const inlineIndexSignatureRegex = /:\s*\{\s*\/\*\*[\s\S]*?\*\/[\s\n\r]*\[k: string\]: any;\s*\};/g;
+                    typesContent = typesContent.replace(inlineIndexSignatureRegex, ': any;');
+                    typesContent = typesContent.replace(/: \{\}/g, ': any'); 
+                    typesContent = typesContent.replace(/\}\n/g, '}\n\n');
+
+                    // 移除无用的类型别名
+                    typesContent = removeUselessTypeAliases(typesContent);
+
+                    // 改进类型定义：用 JSDoc 信息补充接口定义
+                    const improvedTypes = improveTypeDefinitions(typesContent, module.endpoints);
+                    if (improvedTypes !== typesContent) {
+                        typesContent = improvedTypes;
+                        console.log(chalk.blue(`✓ 使用 JSDoc 信息改进了类型定义`));
                     }
-                };
-    
-                 typesContent = await compile(rootSchemaForCompiler as any, 'schemas', {
-                    bannerComment: '/* eslint-disable */\n/**\n* This file was automatically generated by czh-api.\n* DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,\n* and run czh-api build to regenerate this file.\n*/',
-                    unreachableDefinitions: true,
-                    additionalProperties: false, 
-                 });
-    
-                typesContent = typesContent.replace(/export interface \w+ \{\s*\}\n/g, '');
-                const refCommentRegex = /\/\*\*\n \* This interface was referenced by `\w+`'s JSON-Schema[\s\S]*?\*\/\n/g;
-                typesContent = typesContent.replace(refCommentRegex, '');
-                typesContent = typesContent.replace(/:\s*\{\}\[\]/g, ': any[]'); 
-                typesContent = typesContent.replace(/\[k: string\]: \{\}/g, '[k: string]: any'); 
-                const inlineIndexSignatureRegex = /:\s*\{\s*\/\*\*[\s\S]*?\*\/[\s\n\r]*\[k: string\]: any;\s*\};/g;
-                typesContent = typesContent.replace(inlineIndexSignatureRegex, ': any;');
-                typesContent = typesContent.replace(/: \{\}/g, ': any'); 
-                typesContent = typesContent.replace(/\}\n/g, '}\n\n');
-
-                fs.writeFileSync(path.join(moduleDir, 'types.ts'), typesContent);
+
+                    fs.writeFileSync(path.join(moduleDir, 'types.ts'), typesContent);
+                    console.log(chalk.green(`✓ 模块 "${moduleName}" 类型文件生成成功`));
+                } catch (typeError: any) {
+                    // 检查是否是引用错误
+                    const errorMessage = typeError?.message || typeError;
+                    if (errorMessage.includes('Missing $ref pointer')) {
+                        console.warn(chalk.yellow(`警告: 模块 "${moduleName}" 存在 OpenAPI 引用错误，尝试过滤有问题的 schema...`));
+                        console.warn(chalk.yellow('引用错误:'), errorMessage);
+                        
+                        // 尝试逐个验证 schema，过滤掉有问题的
+                        const validSchemas: { [key: string]: OpenAPIV3.SchemaObject } = {};
+                        const invalidSchemas: string[] = [];
+                        const normalizedModuleSchemas = normalizeSchemaRefs(module.schemas);
+                        
+                        for (const schemaName in normalizedModuleSchemas) {
+                            try {
+                                // 尝试单独编译每个 schema
+                                const testSchema = {
+                                    title: 'test',
+                                    type: 'object',
+                                    properties: {},
+                                    additionalProperties: false,
+                                    definitions: { [schemaName]: normalizedModuleSchemas[schemaName] },
+                                    components: { schemas: { [schemaName]: normalizedModuleSchemas[schemaName] } }
+                                };
+                                await compile(testSchema as any, 'test', { unreachableDefinitions: true });
+                                validSchemas[schemaName] = {
+                                    ...normalizedModuleSchemas[schemaName],
+                                    title: schemaName
+                                };
+                            } catch (schemaError) {
+                                invalidSchemas.push(schemaName);
+                            }
+                        }
+                        
+                        if (Object.keys(validSchemas).length > 0) {
+                            console.log(chalk.blue(`找到 ${Object.keys(validSchemas).length} 个有效 schema，${invalidSchemas.length} 个无效 schema`));
+                            if (invalidSchemas.length > 0) {
+                                console.warn(chalk.yellow('无效的 schema:'), invalidSchemas.join(', '));
+                            }
+                            
+                            try {
+                                const rootSchemaForCompiler = {
+                                    title: 'schemas',
+                                    type: 'object',
+                                    properties: {},
+                                    additionalProperties: false,
+                                    definitions: validSchemas,
+                                    components: { schemas: validSchemas }
+                                };
+                                
+                                typesContent = await compile(rootSchemaForCompiler as any, 'schemas', {
+                                    bannerComment: '/* eslint-disable */\n/**\n* This file was automatically generated by czh-api.\n* DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,\n* and run czh-api build to regenerate this file.\n*/',
+                                    unreachableDefinitions: true,
+                                    additionalProperties: false, 
+                                });
+                                
+                                // 应用相同的后处理
+                                typesContent = typesContent.replace(/export interface \w+ \{\s*\}\n/g, '');
+                                const refCommentRegex = /\/\*\*\n \* This interface was referenced by `\w+`'s JSON-Schema[\s\S]*?\*\/\n/g;
+                                typesContent = typesContent.replace(refCommentRegex, '');
+                                typesContent = typesContent.replace(/:\s*\{\}\[\]/g, ': any[]'); 
+                                typesContent = typesContent.replace(/\[k: string\]: \{\}/g, '[k: string]: any'); 
+                                const inlineIndexSignatureRegex = /:\s*\{\s*\/\*\*[\s\S]*?\*\/[\s\n\r]*\[k: string\]: any;\s*\};/g;
+                                typesContent = typesContent.replace(inlineIndexSignatureRegex, ': any;');
+                                typesContent = typesContent.replace(/: \{\}/g, ': any'); 
+                                typesContent = typesContent.replace(/\}\n/g, '}\n\n');
+                                
+                                typesContent = removeUselessTypeAliases(typesContent);
+                                
+                                const improvedTypes = improveTypeDefinitions(typesContent, module.endpoints);
+                                if (improvedTypes !== typesContent) {
+                                    typesContent = improvedTypes;
+                                    console.log(chalk.blue(`✓ 使用 JSDoc 信息改进了类型定义`));
+                                }
+                                
+                                fs.writeFileSync(path.join(moduleDir, 'types.ts'), typesContent);
+                                console.log(chalk.green(`✓ 模块 "${moduleName}" 部分类型文件生成成功 (${Object.keys(validSchemas).length}/${Object.keys(module.schemas).length} 个 schema)`));
+                            } catch (partialError) {
+                                console.warn(chalk.yellow(`部分 schema 编译也失败，回退到 JSDoc 类型生成`));
+                                throw typeError; // 回退到原来的错误处理逻辑
+                            }
+                        } else {
+                            console.warn(chalk.yellow(`所有 schema 都无效，回退到 JSDoc 类型生成`));
+                            // 继续执行 JSDoc 类型生成逻辑
+                        }
+                    } else {
+                        // 非引用错误，继续执行 JSDoc 类型生成逻辑
+                    }
+                    
+                    // JSDoc 类型生成逻辑
+                    console.warn(chalk.yellow(`警告: 模块 "${moduleName}" 的类型生成失败，跳过类型文件生成`));
+                    console.warn(chalk.yellow('类型生成错误:'), typeError?.message || typeError);
+                    console.warn(chalk.yellow('Schema 列表:'), Object.keys(module.schemas));
+                    
+                    // 生成基于 JSDoc 参数的类型文件作为备选方案
+                    const allReferencedTypes = [...new Set(module.endpoints.flatMap(e => e.referencedTypes))];
+                    if (allReferencedTypes.length > 0) {
+                        console.log(chalk.blue(`为模块 "${moduleName}" 生成基于 JSDoc 的类型定义...`));
+                        
+                        // 创建类型定义映射
+                        const typeDefinitions: { [typeName: string]: string } = {};
+                        
+                        // 从 endpoints 中提取类型定义
+                        module.endpoints.forEach(endpoint => {
+                            // 辅助函数：将 jsdoc params 转换为字段
+                            const buildFields = (params: any[]) => params
+                                .filter((param: any) => param.name && param.type)
+                                .map((param: any) => {
+                                    const optional = !param.required ? '?' : '';
+                                    let type = param.type;
+                                    
+                                    if (type && type.includes(' | ')) {
+                                        if (type.includes('null')) {
+                                            type = type.replace(/\s*\|\s*null/g, ' | null');
+                                        }
+                                    } else {
+                                        type = convertOpenApiTypeToTypeScript(type);
+                                    }
+                                    
+                                    const comment = param.description ? ` // ${param.description}` : '';
+                                    return `  ${param.name}${optional}: ${type};${comment}`;
+                                })
+                                .join('\n');
+
+                            // 处理 params 类型 - 使用 paramsJsdocParams
+                            const requestParamsTypeName = endpoint.requestParamsTypeName;
+                            if (requestParamsTypeName && isValidTypeIdentifier(requestParamsTypeName) && endpoint.paramsJsdocParams && endpoint.paramsJsdocParams.length > 0) {
+                                const paramsFields = buildFields(endpoint.paramsJsdocParams);
+                                
+                                if (paramsFields) {
+                                    typeDefinitions[requestParamsTypeName] = `export interface ${requestParamsTypeName} {
+${paramsFields}
+}`;
+                                }
+                            }
+                            
+                            // 处理 data 类型 (requestBody) - 使用 dataJsdocParams
+                            const requestBodyTypeName = endpoint.requestBodyTypeName;
+                            if (requestBodyTypeName && isValidTypeIdentifier(requestBodyTypeName) && endpoint.dataJsdocParams && endpoint.dataJsdocParams.length > 0) {
+                                const dataFields = buildFields(endpoint.dataJsdocParams);
+                                
+                                if (dataFields) {
+                                    typeDefinitions[requestBodyTypeName] = `export interface ${requestBodyTypeName} {
+${dataFields}
+}`;
+                                }
+                            }
+
+                            // 处理 response 类型 - 使用 responseJsdocParams
+                            const responseTargetType = resolveInterfaceTargetType(endpoint.responseTypeName);
+                            if (responseTargetType && endpoint.responseTypeName !== 'void' && endpoint.responseJsdocParams && endpoint.responseJsdocParams.length > 0) {
+                                const responseFields = buildFields(endpoint.responseJsdocParams);
+                                
+                                if (responseFields) {
+                                    typeDefinitions[responseTargetType] = `export interface ${responseTargetType} {
+${responseFields}
+}`;
+                                }
+                            }
+                        });
+                        
+                        // 为没有定义的类型添加基本定义
+                        allReferencedTypes.forEach(typeName => {
+                            if (!isValidTypeIdentifier(typeName)) {
+                                return;
+                            }
+                            if (!typeDefinitions[typeName]) {
+                                typeDefinitions[typeName] = `export interface ${typeName} {
+  [key: string]: any;
+}`;
+                            }
+                        });
+                        
+                        const basicTypesContent = `/* eslint-disable */
+/**
+ * This file was automatically generated by czh-api.
+ * Type definitions based on JSDoc parameters (fallback when schema compilation fails)
+ */
+
+${Object.values(typeDefinitions).join('\n\n')}
+`;
+                        fs.writeFileSync(path.join(moduleDir, 'types.ts'), basicTypesContent);
+                        typesContent = basicTypesContent;
+                        console.log(chalk.green(`✓ 模块 "${moduleName}" 基于 JSDoc 的类型文件生成成功`));
+                    } else {
+                        typesContent = '';
+                    }
+                }
+            } else {
+                console.log(chalk.yellow(`模块 "${moduleName}" 没有 schema，跳过类型文件生成`));
             }
             
             // Generate API file
             const allReferencedTypes = [...new Set(module.endpoints.flatMap(e => e.referencedTypes))];
             const customImports = config.customImports || [`import http from "${config.httpClientPath}";`];
             
-            let apiFileContent = '';
+            try {
+                let apiFileContent = '';
 
-            if (module.description) {
-                apiFileContent += `/**\n * @description ${module.description}\n */\n\n`;
-            }
-            
-            apiFileContent += `${customImports.join('\n')}\n`;
-    
-            if (allReferencedTypes.length > 0) {
-                apiFileContent += `import type { ${allReferencedTypes.join(', ')} } from './types';\n\n`;
+                if (module.description) {
+                    apiFileContent += `/**\n * @description ${module.description}\n */\n\n`;
+                }
+                
+                apiFileContent += `${customImports.join('\n')}\n`;
+        
+                // 只导入存在的类型（包括 interface 和 type）
+                const existingTypes = allReferencedTypes.filter(type => 
+                    typesContent && (
+                        typesContent.includes(`export interface ${type}`) ||
+                        typesContent.includes(`export type ${type}`)
+                    )
+                );
+                
+                if (existingTypes.length > 0) {
+                    apiFileContent += `import type { ${existingTypes.join(', ')} } from './types';\n\n`;
+                }
+        
+                apiFileContent += module.endpoints.map(endpoint => {
+                    try {
+                        return apiTemplate(endpoint);
+                    } catch (templateError: any) {
+                        console.warn(chalk.yellow(`警告: 生成函数 "${endpoint.functionName}" 时出错，跳过此函数`));
+                        console.warn(chalk.yellow('模板错误:'), templateError?.message || templateError);
+                        return `// 函数 ${endpoint.functionName} 生成失败`;
+                    }
+                }).join('\n\n');
+                
+                fs.writeFileSync(path.join(moduleDir, `${moduleBaseName}.ts`), apiFileContent);
+        
+                // Generate index.ts
+                const exportTypes = typesContent ? `\nexport * from './types';` : '';
+                fs.writeFileSync(path.join(moduleDir, 'index.ts'), `export * from './${moduleBaseName}';${exportTypes}\n`);
+                
+                console.log(chalk.green(`✓ 模块 "${moduleName}" 生成成功 (${module.endpoints.length} 个接口)`));
+            } catch (moduleError: any) {
+                console.warn(chalk.yellow(`警告: 模块 "${moduleName}" 生成失败，跳过此模块`));
+                console.warn(chalk.yellow('模块生成错误:'), moduleError?.message || moduleError);
             }
-    
-            apiFileContent += module.endpoints.map(endpoint => apiTemplate(endpoint)).join('\n\n');
-            fs.writeFileSync(path.join(moduleDir, `${moduleName}.ts`), apiFileContent);
-    
-            // Generate index.ts
-            const exportTypes = typesContent ? `\nexport * from './types';` : '';
-            fs.writeFileSync(path.join(moduleDir, 'index.ts'), `export * from './${moduleName}';${exportTypes}\n`);
         }
 
         console.log(chalk.green.bold('API code generated successfully!'));
@@ -149,4 +687,4 @@ export const handleBuild = async () => {
     } catch (error) {
         console.error(chalk.red('An error occurred during build process:'), error);
     }
-}; 
+};