@gogenger/go-gen 1.0.0

package/core/writer.js

@@ -0,0 +1,413 @@
+const path = require('path');
+const shell = require('shelljs');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const os = require('os');
+const ora = require('ora');
+const fs = require('fs');
+const { loadConfig } = require('./config');
+
+const desktopPath = path.join(os.homedir(), 'Desktop');
+const currentPath = process.cwd();
+
+function generateApiFile({
+  apiName,
+  typeName,
+  url,
+  method = 'GET',
+  hasRequestBody = false,
+}) {
+  const config = loadConfig();
+  const requestModule = config.requestModule;
+  const finalTypeName = typeName.charAt(0).toUpperCase() + typeName.slice(1);
+  const methodLower = method.toLowerCase();
+
+  let imports = `import type { ${finalTypeName}`;
+  let params = '';
+  let requestCall = '';
+
+  if (hasRequestBody) {
+    imports += `, ${finalTypeName}Request`;
+    params = `data: ${finalTypeName}Request`;
+    requestCall = `request.${methodLower}<${finalTypeName}>("${url}", data)`;
+  } else {
+    requestCall = `request.${methodLower}<${finalTypeName}>("${url}")`;
+  }
+
+  imports += ` } from "./types";`;
+
+  return `
+import request from "${requestModule}";
+${imports}
+
+export function ${apiName}(${params}) {
+  return ${requestCall};
+}
+`.trim();
+}
+
+function parseExistingTypes(typesFilePath) {
+  if (!fs.existsSync(typesFilePath)) {
+    return { types: [], content: '' };
+  }
+
+  const content = fs.readFileSync(typesFilePath, 'utf-8');
+  const typeRegex = /export\s+(?:interface|type)\s+(\w+)/g;
+  const types = [];
+  let match;
+
+  while ((match = typeRegex.exec(content)) !== null) {
+    types.push(match[1]);
+  }
+
+  return { types, content };
+}
+
+function parseExistingApis(apiFilePath) {
+  if (!fs.existsSync(apiFilePath)) {
+    return { functions: [], content: '' };
+  }
+
+  const content = fs.readFileSync(apiFilePath, 'utf-8');
+  const funcRegex = /export\s+function\s+(\w+)\s*\(/g;
+  const functions = [];
+  let match;
+
+  while ((match = funcRegex.exec(content)) !== null) {
+    functions.push(match[1]);
+  }
+
+  return { functions, content };
+}
+
+function extractTypeDefinitions(newTypesContent) {
+  const lines = newTypesContent.split('\n');
+  const definitions = [];
+  let currentDef = [];
+  let inDefinition = false;
+  let braceCount = 0;
+
+  for (const line of lines) {
+    if (/export\s+(?:interface|type)\s+\w+/.test(line)) {
+      inDefinition = true;
+      currentDef = [line];
+      braceCount =
+        (line.match(/{/g) || []).length - (line.match(/}/g) || []).length;
+
+      if (braceCount === 0 && line.includes('=')) {
+        definitions.push(currentDef.join('\n'));
+        inDefinition = false;
+        currentDef = [];
+      }
+      continue;
+    }
+
+    if (inDefinition) {
+      currentDef.push(line);
+      braceCount += (line.match(/{/g) || []).length;
+      braceCount -= (line.match(/}/g) || []).length;
+
+      if (braceCount === 0) {
+        definitions.push(currentDef.join('\n'));
+        inDefinition = false;
+        currentDef = [];
+      }
+    }
+  }
+
+  return definitions;
+}
+
+function resolveTypeNameConflict(existingTypes, typeName) {
+  let finalTypeName = typeName;
+  let suffix = 1;
+
+  while (existingTypes.includes(finalTypeName)) {
+    finalTypeName = `${typeName}${suffix}`;
+    suffix++;
+  }
+
+  return { finalTypeName, hasConflict: finalTypeName !== typeName };
+}
+
+function mergeTypesContent(existingContent, newTypesContent, typeName) {
+  const typeRegex = /export\s+(?:interface|type)\s+(\w+)/g;
+  const existingTypes = [];
+  let match;
+
+  while ((match = typeRegex.exec(existingContent)) !== null) {
+    existingTypes.push(match[1]);
+  }
+
+  const { finalTypeName, hasConflict } = resolveTypeNameConflict(
+    existingTypes,
+    typeName,
+  );
+
+  if (hasConflict) {
+    newTypesContent = newTypesContent.replace(
+      new RegExp(`\\b${typeName}\\b`, 'g'),
+      finalTypeName,
+    );
+  }
+
+  const newDefinitions = extractTypeDefinitions(newTypesContent);
+
+  const uniqueDefinitions = newDefinitions.filter(def => {
+    const typeMatch = def.match(/export\s+(?:interface|type)\s+(\w+)/);
+    if (!typeMatch) return false;
+    return !existingTypes.includes(typeMatch[1]);
+  });
+
+  if (uniqueDefinitions.length === 0) {
+    return { merged: existingContent, isDuplicate: true, finalTypeName };
+  }
+
+  // 确保有换行分隔
+  const merged =
+    existingContent.trim() + '\n\n' + uniqueDefinitions.join('\n\n');
+
+  return { merged, isDuplicate: false, finalTypeName, hasConflict };
+}
+
+function extractImportedTypes(apiContent) {
+  const importMatch = apiContent.match(/import\s+type\s+{\s*([^}]+)\s*}/);
+  if (!importMatch) return [];
+
+  return importMatch[1]
+    .split(',')
+    .map(t => t.trim())
+    .filter(Boolean);
+}
+
+function mergeApiContent(existingContent, newApiContent, newApiName) {
+  const funcRegex = /export\s+function\s+(\w+)\s*\(/g;
+  const existingFunctions = [];
+  let match;
+
+  while ((match = funcRegex.exec(existingContent)) !== null) {
+    existingFunctions.push(match[1]);
+  }
+
+  if (existingFunctions.includes(newApiName)) {
+    return { merged: existingContent, isDuplicate: true };
+  }
+
+  const newTypes = extractImportedTypes(newApiContent);
+
+  const existingImportMatch = existingContent.match(
+    /import\s+type\s+{\s*([^}]+)\s*}/,
+  );
+  const existingTypes = existingImportMatch
+    ? existingImportMatch[1]
+        .split(',')
+        .map(t => t.trim())
+        .filter(Boolean)
+    : [];
+
+  const allTypes = [...new Set([...existingTypes, ...newTypes])];
+
+  const newFunctionMatch = newApiContent.match(/(export\s+function[\s\S]+)/);
+  const newFunction = newFunctionMatch ? newFunctionMatch[1] : '';
+
+  let merged = existingContent;
+
+  if (allTypes.length > existingTypes.length) {
+    const importStatement = `import type { ${allTypes.join(', ')} } from "./types";`;
+    merged = merged.replace(
+      /import\s+type\s+{[^}]+}\s+from\s+"\.\/types";/,
+      importStatement,
+    );
+  }
+
+  if (newFunction) {
+    merged = merged.trim() + '\n\n' + newFunction;
+  }
+
+  return { merged, isDuplicate: false };
+}
+
+function validatePath(inputPath) {
+  const resolved = path.resolve(inputPath);
+
+  // Windows 系统路径（C:\Windows, C:\Program Files 等）
+  const windowsDangerousPaths = [
+    'C:\\Windows',
+    'C:\\Program Files',
+    'C:\\System',
+  ];
+
+  // Unix/Linux 系统路径
+  const unixDangerousPaths = ['/System', '/usr', '/bin', '/sbin', '/etc'];
+
+  // 检查 Windows 路径
+  for (const dangerousPath of windowsDangerousPaths) {
+    if (resolved.toUpperCase().startsWith(dangerousPath.toUpperCase())) {
+      throw new Error('⛔ 不允许写入系统目录');
+    }
+  }
+
+  // 检查 Unix 路径
+  for (const dangerousPath of unixDangerousPaths) {
+    if (resolved.startsWith(dangerousPath)) {
+      throw new Error('⛔ 不允许写入系统目录');
+    }
+  }
+
+  return resolved;
+}
+
+async function writeFiles({
+  apiName,
+  typeName,
+  url,
+  typesContent,
+  method = 'GET',
+  hasRequestBody = false,
+  interactive = true,
+}) {
+  const config = loadConfig();
+
+  let baseDir;
+
+  if (interactive) {
+    const { outputPath } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'outputPath',
+        message: '📂 输出目录：',
+        default: config.defaultOutputPath,
+        choices: [
+          { name: '💻 桌面', value: desktopPath },
+          { name: '📁 当前目录', value: currentPath },
+          { name: '🔍 自定义路径', value: 'custom' },
+        ],
+      },
+    ]);
+
+    baseDir = outputPath;
+    if (outputPath === 'custom') {
+      const { customPath } = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'customPath',
+          message: '📁 请输入保存路径：',
+          default: config.customPath || currentPath,
+          validate: input => {
+            try {
+              validatePath(input);
+              return shell.test('-d', input) || '路径不存在';
+            } catch (error) {
+              return error.message;
+            }
+          },
+        },
+      ]);
+      baseDir = customPath;
+    }
+  } else {
+    baseDir = currentPath;
+  }
+
+  const outputDir = path.join(baseDir, apiName);
+  const dirExists = fs.existsSync(outputDir);
+
+  if (dirExists && interactive) {
+    console.log(chalk.yellow(`\n📁 目录已存在，将进行增量写入: ${outputDir}`));
+  }
+
+  shell.mkdir('-p', outputDir);
+
+  const typesFilePath = path.join(outputDir, 'types.ts');
+  const apiFilePath = path.join(outputDir, 'api.ts');
+
+  let finalTypesContent = typesContent;
+  let finalTypeName = typeName;
+  let typeSkipped = false;
+  let typeConflict = false;
+
+  if (fs.existsSync(typesFilePath)) {
+    const existingTypes = fs.readFileSync(typesFilePath, 'utf-8');
+    const {
+      merged,
+      isDuplicate,
+      finalTypeName: resolvedName,
+      hasConflict,
+    } = mergeTypesContent(existingTypes, typesContent, typeName);
+
+    if (hasConflict && interactive) {
+      console.log(
+        chalk.yellow(
+          `⚠️  类型名冲突，已自动重命名: ${typeName} → ${resolvedName}`,
+        ),
+      );
+      typeConflict = true;
+      finalTypeName = resolvedName;
+    }
+
+    if (isDuplicate && !hasConflict && interactive) {
+      console.log(chalk.yellow(`⚠️  类型 ${typeName} 已存在，跳过写入`));
+      typeSkipped = true;
+    }
+
+    finalTypesContent = merged;
+  }
+
+  fs.writeFileSync(typesFilePath, finalTypesContent);
+
+  const newApiContent = generateApiFile({
+    apiName,
+    typeName: finalTypeName,
+    url,
+    method,
+    hasRequestBody,
+  });
+  let finalApiContent = newApiContent;
+  let apiSkipped = false;
+
+  if (fs.existsSync(apiFilePath)) {
+    const existingApi = fs.readFileSync(apiFilePath, 'utf-8');
+    const { merged, isDuplicate } = mergeApiContent(
+      existingApi,
+      newApiContent,
+      apiName,
+    );
+
+    if (isDuplicate && interactive) {
+      console.log(chalk.yellow(`⚠️  API 函数 ${apiName} 已存在，跳过写入`));
+      apiSkipped = true;
+    }
+
+    finalApiContent = merged;
+  }
+
+  fs.writeFileSync(apiFilePath, finalApiContent);
+
+  if (interactive) {
+    const spinner = ora();
+    spinner.text = chalk.cyan('📂 输出目录：') + outputDir;
+
+    if (typeSkipped && apiSkipped) {
+      spinner.warn('⚠️  内容已存在，无新增内容');
+    } else if (typeConflict) {
+      spinner.succeed(`✨ 生成成功！（类型已重命名为 ${finalTypeName}）`);
+    } else if (dirExists) {
+      spinner.succeed('✨ 增量写入成功！');
+    } else {
+      spinner.succeed('🎉 文件生成成功！');
+    }
+  }
+
+  return { success: true, outputDir, finalTypeName };
+}
+
+module.exports = {
+  writeFiles,
+  generateApiFile,
+  parseExistingTypes,
+  parseExistingApis,
+  mergeTypesContent,
+  mergeApiContent,
+  resolveTypeNameConflict,
+  validatePath,
+};

package/docs/BEST_PRACTICES.md

@@ -0,0 +1,327 @@
+# 🎓 最佳实践
+
+## 1. 团队规范化
+
+### 推荐做法
+
+在项目根目录创建 `.apirc.json`：
+
+```json
+{
+  "requestModule": "@/api/request",
+  "typePrefix": "I",
+  "apiPrefix": "api"
+}
+```
+
+### 优势
+
+- ✅ 团队成员自动使用统一配置
+- ✅ 新成员无需额外培训
+- ✅ 代码风格高度一致
+- ✅ 减少 Code Review 时间
+
+### 提交规范
+
+```bash
+git add .apirc.json
+git commit -m "chore: add api generator config"
+```
+
+---
+
+## 2. 命名规范
+
+### 类型名：PascalCase + Response 后缀
+
+✅ **推荐：**
+
+```typescript
+UserResponse;
+CreateOrderResponse;
+UpdateProfileResponse;
+```
+
+❌ **不推荐：**
+
+```typescript
+userResponse; // 首字母小写
+User; // 缺少后缀
+user_response; // 下划线命名
+```
+
+### API 方法名：camelCase + 动词前缀
+
+✅ **推荐：**
+
+```typescript
+getUsers();
+createOrder();
+updateUserProfile();
+deletePost();
+```
+
+❌ **不推荐：**
+
+```typescript
+Users(); // 缺少动词
+GetUsers(); // 首字母大写
+user_list(); // 下划线命名
+```
+
+### 动词建议
+
+| HTTP 方法 | 推荐动词前缀           |
+| --------- | ---------------------- |
+| GET       | get, fetch, query      |
+| POST      | create, add            |
+| PUT       | update, replace        |
+| PATCH     | update, modify         |
+| DELETE    | delete, remove, revoke |
+
+---
+
+## 3. 目录组织
+
+### 推荐结构
+
+```
+src/api/
+├── user/
+│   ├── api.ts          # 用户相关 API
+│   └── types.ts        # 用户相关类型
+├── order/
+│   ├── api.ts          # 订单相关 API
+│   └── types.ts        # 订单相关类型
+├── product/
+│   ├── api.ts          # 产品相关 API
+│   └── types.ts        # 产品相关类型
+└── common/
+    ├── api.ts          # 通用 API
+    └── types.ts        # 通用类型
+```
+
+### 优势
+
+- ✅ 模块化清晰
+- ✅ 便于维护和查找
+- ✅ 减少命名冲突
+- ✅ 支持按需导入
+
+---
+
+## 4. 版本控制
+
+### 应该提交的文件
+
+```bash
+# ✅ 生成的代码（推荐提交）
+git add src/api/
+
+# ✅ 项目配置（强烈推荐）
+git add .apirc.json
+
+# ✅ 文档更新
+git add docs/
+```
+
+### 不应该提交的文件
+
+```bash
+# ❌ 全局配置（个人配置）
+# ~/.apirc.json 不要提交
+
+# ❌ 临时文件
+# *.tmp, *.bak 等
+```
+
+### Commit 规范
+
+```bash
+# 新增接口
+git commit -m "feat: add user api"
+
+# 更新接口
+git commit -m "feat: update order api"
+
+# 添加配置
+git commit -m "chore: add api-gen config"
+
+# 修复问题
+git commit -m "fix: correct api type definition"
+```
+
+---
+
+## 5. 类型安全
+
+### 使用泛型
+
+```typescript
+// ✅ 推荐：使用泛型
+export function getUsers() {
+  return request.get<UserResponse>('/api/users');
+}
+
+// ❌ 不推荐：不指定类型
+export function getUsers() {
+  return request.get('/api/users');
+}
+```
+
+### 避免 any
+
+```typescript
+// ✅ 推荐：明确类型
+export interface CreateUserRequest {
+  name: string;
+  email: string;
+}
+
+// ❌ 不推荐：使用 any
+export interface CreateUserRequest {
+  [key: string]: any;
+}
+```
+
+---
+
+## 6. 错误处理
+
+### 统一错误处理
+
+在 `request` 模块中统一处理：
+
+```typescript
+// @/utils/request.ts
+import axios from 'axios';
+
+const request = axios.create({
+  baseURL: '/api',
+  timeout: 10000,
+});
+
+// 统一错误处理
+request.interceptors.response.use(
+  response => response.data,
+  error => {
+    console.error('API Error:', error);
+    return Promise.reject(error);
+  },
+);
+
+export default request;
+```
+
+---
+
+## 7. 增量开发
+
+### 新增接口时
+
+```bash
+# 输出到已存在的目录
+go-gen fetch
+# 选择相同的输出目录
+```
+
+### 注意事项
+
+- ✅ 新接口会自动追加
+- ✅ 已有代码不会被覆盖
+- ⚠️ 类型名冲突会自动重命名
+- ⚠️ 检查是否有重复的 API 方法
+
+---
+
+## 8. 性能优化
+
+### 批量生成时
+
+```bash
+# OpenAPI 批量模式
+go-gen openapi https://api.example.com/swagger.json
+# 选择 "批量生成"
+```
+
+### 单个生成时
+
+```bash
+# 只生成需要的接口
+go-gen fetch
+```
+
+### 建议
+
+- ✅ 大型项目用批量模式
+- ✅ 小型项目或单个接口用 fetch 模式
+- ✅ 定期清理不用的接口
+
+---
+
+## 9. 团队协作流程
+
+### 步骤 1：项目负责人
+
+```bash
+# 初始化配置
+go-gen init
+
+# 编辑 .apirc.json
+vim .apirc.json
+
+# 提交配置
+git add .apirc.json
+git commit -m "chore: setup api generator config"
+git push
+```
+
+### 步骤 2：团队成员
+
+```bash
+# 拉取配置
+git pull
+
+# 直接使用
+go-gen fetch
+```
+
+### 步骤 3：代码审查
+
+```bash
+# 检查生成的代码
+git diff src/api/
+
+# 确认无误后提交
+git add src/api/
+git commit -m "feat: add new api endpoints"
+```
+
+---
+
+## 10. 文档维护
+
+### 在 README 中说明
+
+```markdown
+## API 生成
+
+本项目使用 `go-gen` 生成 API 代码。
+
+### 生成新接口
+
+\`\`\`bash
+go-gen fetch
+\`\`\`
+
+### 配置
+
+查看 `.apirc.json` 了解项目配置。
+\`\`\`
+```
+
+### 保持文档同步
+
+- 更新 API 时更新文档
+- 记录重要的配置变更
+- 说明特殊的使用方式