@gogenger/go-gen 1.0.0

package/docs/CONFIGURATION.md

@@ -0,0 +1,161 @@
+# ⚙️ 配置系统详解
+
+## 双层配置设计
+
+因为 CLI 工具安装在全局，但会在不同项目中使用：
+
+- **全局配置** (`~/.apirc.json`) - 你的个人习惯
+- **项目配置** (`./.apirc.json`) - 项目团队规范
+
+**配置优先级：** 项目配置 > 全局配置 > 默认配置
+
+## 初始化配置
+
+```bash
+# 初始化项目配置
+go-gen init
+
+# 设置全局配置
+go-gen config --global
+
+# 查看当前配置
+go-gen config --show
+```
+
+## 配置示例
+
+### 全局配置 (`~/.apirc.json`) - 个人偏好
+
+```json
+{
+  "defaultOutputPath": "current",
+  "timeout": 15000,
+  "autoRetry": true,
+  "maxRetries": 5
+}
+```
+
+### 项目配置 (`.apirc.json`) - 团队规范
+
+```json
+{
+  "requestModule": "@/utils/request",
+  "typePrefix": "I",
+  "apiPrefix": "api"
+}
+```
+
+## 配置项说明
+
+| 配置项              | 类型    | 默认值              | 说明                 |
+| ------------------- | ------- | ------------------- | -------------------- |
+| `defaultOutputPath` | string  | `'current'`         | 默认输出路径         |
+| `timeout`           | number  | `10000`             | 请求超时时间（毫秒） |
+| `autoRetry`         | boolean | `true`              | 失败是否自动重试     |
+| `maxRetries`        | number  | `3`                 | 最大重试次数         |
+| `requestModule`     | string  | `'@/utils/request'` | request 模块路径     |
+| `typePrefix`        | string  | `''`                | 类型名前缀           |
+| `apiPrefix`         | string  | `''`                | API 方法名前缀       |
+| `defaultMethod`     | string  | `'GET'`             | 默认 HTTP 方法       |
+
+## 配置使用场景
+
+### 场景 1：个人习惯配置（全局）
+
+```bash
+go-gen config --global
+```
+
+设置你常用的配置：
+
+```json
+{
+  "timeout": 20000,
+  "maxRetries": 5,
+  "defaultOutputPath": "desktop"
+}
+```
+
+### 场景 2：团队项目规范（项目）
+
+```bash
+cd your-project
+go-gen init
+```
+
+编辑 `.apirc.json`：
+
+```json
+{
+  "requestModule": "@/api/request",
+  "typePrefix": "I",
+  "apiPrefix": "api"
+}
+```
+
+提交到 Git：
+
+```bash
+git add .apirc.json
+git commit -m "chore: add api generator config"
+```
+
+### 场景 3：多项目维护
+
+```bash
+# 项目 A（使用 axios）
+cd project-a
+cat .apirc.json
+# { "requestModule": "axios" }
+go-gen fetch
+
+# 项目 B（使用自定义 request）
+cd project-b
+cat .apirc.json
+# { "requestModule": "@/utils/http" }
+go-gen fetch
+```
+
+每个项目自动使用各自的配置，无需手动切换。
+
+## 配置优先级示例
+
+假设有以下配置：
+
+**默认配置：**
+
+```json
+{
+  "timeout": 10000,
+  "maxRetries": 3,
+  "requestModule": "@/utils/request"
+}
+```
+
+**全局配置 (`~/.apirc.json`)：**
+
+```json
+{
+  "timeout": 15000,
+  "maxRetries": 5
+}
+```
+
+**项目配置 (`.apirc.json`)：**
+
+```json
+{
+  "maxRetries": 2,
+  "requestModule": "axios"
+}
+```
+
+**最终生效的配置：**
+
+```json
+{
+  "timeout": 15000, // 来自全局配置
+  "maxRetries": 2, // 来自项目配置（优先级最高）
+  "requestModule": "axios" // 来自项目配置
+}
+```

package/docs/FEATURES.md

@@ -0,0 +1,136 @@
+# 📖 完整特性文档
+
+## 1. 支持多种 HTTP 方法
+
+自动识别 POST、PUT、PATCH 方法需要请求体，并生成对应的 Request 类型：
+
+```typescript
+// GET 请求
+export function getUser() {
+  return request.get<UserResponse>('/api/user');
+}
+
+// POST 请求（带请求体）
+export function createUser(data: CreateUserRequest) {
+  return request.post<UserResponse>('/api/user', data);
+}
+```
+
+## 2. 请求体类型生成
+
+当选择需要请求体时，可以输入示例 JSON 数据：
+
+```bash
+📦 该接口是否需要请求体? Yes
+
+💡 提示: 请输入请求体的 JSON 示例数据
+📝 请输入请求体 JSON: {"name": "John", "email": "john@example.com"}
+
+✅ Request 类型生成完成
+```
+
+生成的类型：
+
+```typescript
+export interface CreateUserRequest {
+  name: string;
+  email: string;
+}
+
+export interface CreateUserResponse {
+  id: number;
+  message: string;
+}
+```
+
+## 3. 增量写入
+
+智能检测已存在的文件，自动合并新内容：
+
+```typescript
+// 第一次生成
+export function getUsers() { ... }
+
+// 第二次生成到同一目录
+export function getUsers() { ... }
+export function createUser(data: CreateUserRequest) { ... }  // 新增
+```
+
+## 4. 类型冲突自动处理
+
+检测到重复类型名时自动重命名：
+
+```
+⚠️  类型名冲突，已自动重命名: ApiResponse → ApiResponse1
+✨ 生成成功！（类型已重命名为 ApiResponse1）
+```
+
+## 5. 认证支持
+
+### Bearer Token
+
+```bash
+🔐 是否需要认证? Bearer Token
+🔑 请输入 Bearer Token: ********
+```
+
+自动添加请求头：`Authorization: Bearer xxx`
+
+### Cookie
+
+```bash
+🔐 是否需要认证? Cookie
+🍪 请输入 Cookie: sessionid=abc123
+```
+
+自动添加请求头：`Cookie: sessionid=abc123`
+
+## 6. 自动重试机制
+
+网络请求失败时自动重试：
+
+```
+🚀 请求 API 数据中...
+⚠️  请求失败 (尝试 1/3)，2秒后重试...
+⚠️  请求失败 (尝试 2/3)，2秒后重试...
+✅ API 数据获取完成
+```
+
+## 7. 批量生成优化
+
+OpenAPI 批量模式特点：
+
+- ✅ 只询问一次输出目录
+- ✅ 显示进度 (1/10, 2/10...)
+- ✅ 统计成功和失败数量
+- ✅ 自动命名（基于 operationId）
+
+```
+⚡ 批量生成中... (1/10): GET /users
+⚡ 批量生成中... (2/10): POST /users
+...
+✅ 批量生成完成！成功: 10，失败: 0
+```
+
+## 8. 自定义输出路径
+
+支持三种输出方式：
+
+```bash
+# 输出到桌面
+# 选择 "💻 桌面"
+
+# 输出到当前目录
+# 选择 "📁 当前目录"
+
+# 自定义路径
+# 选择 "🔍 自定义路径"
+# 输入: /path/to/output
+```
+
+## 9. 友好的错误提示
+
+```
+❌ 请求失败: HTTP 401: Unauthorized
+💡 提示: 请检查 Token 是否正确
+```

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,386 @@
+# 🚨 故障排查
+
+## 问题 1：请求超时
+
+### 症状
+
+```
+❌ 请求失败: Request timeout after 10000ms
+```
+
+### 原因
+
+- API 响应慢
+- 网络不稳定
+- 服务器负载高
+
+### 解决方案
+
+**方案 1：增加超时时间（全局配置）**
+
+```bash
+go-gen config --global
+# 设置 timeout: 30000
+```
+
+**方案 2：增加超时时间（项目配置）**
+
+编辑 `.apirc.json`：
+
+```json
+{
+  "timeout": 30000
+}
+```
+
+**方案 3：增加重试次数**
+
+```json
+{
+  "timeout": 20000,
+  "autoRetry": true,
+  "maxRetries": 5
+}
+```
+
+## 问题 2：在不同项目生成的代码不一致
+
+### 症状
+
+- 项目 A 生成的是 `axios`
+- 项目 B 生成的是 `@/utils/request`
+- 团队成员代码风格不统一
+
+### 原因
+
+没有使用项目配置
+
+### 解决方案
+
+**使用项目配置：**
+
+```bash
+cd your-project
+go-gen init
+```
+
+编辑 `.apirc.json`：
+
+```json
+{
+  "requestModule": "@/utils/request",
+  "typePrefix": "I",
+  "apiPrefix": "api"
+}
+```
+
+**提交到 Git：**
+
+```bash
+git add .apirc.json
+git commit -m "chore: add api generator config"
+```
+
+团队成员 `git pull` 后会自动使用相同配置。
+
+---
+
+## 问题 3：认证失败
+
+### 症状
+
+```
+❌ 请求失败: HTTP 401: Unauthorized
+```
+
+### 原因
+
+- Token 过期
+- Token 格式错误
+- 权限不足
+
+### 解决方案
+
+**检查 Token：**
+
+```bash
+# 重新输入正确的 Token
+go-gen fetch
+🔐 是否需要认证? Bearer Token
+🔑 请输入 Bearer Token: <新的token>
+```
+
+**检查 Token 格式：**
+
+- Bearer Token: `Bearer xxxxx` 或 `xxxxx`
+- Cookie: `key=value; key2=value2`
+
+**测试 Token：**
+
+```bash
+# 使用 curl 测试
+curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/users
+```
+
+---
+
+## 问题 4：OpenAPI 文档解析失败
+
+### 症状
+
+```
+❌ OpenAPI 解析失败: Invalid schema format
+```
+
+### 原因
+
+- OpenAPI 文档格式不正确
+- 版本不支持（仅支持 2.0 和 3.0）
+- URL 访问失败
+
+### 解决方案
+
+**方案 1：检查文档格式**
+
+```bash
+# 使用在线验证器
+https://editor.swagger.io/
+```
+
+**方案 2：本地文件**
+
+```bash
+# 下载文档到本地
+curl -o swagger.json https://api.example.com/swagger.json
+
+# 使用本地文件
+go-gen openapi ./swagger.json
+```
+
+**方案 3：检查版本**
+
+支持的版本：
+
+- OpenAPI 3.0.x ✅
+- OpenAPI 2.0 (Swagger) ✅
+- OpenAPI 3.1.x ❌（暂不支持）
+
+---
+
+## 问题 5：生成的代码有语法错误
+
+### 症状
+
+```typescript
+// 生成的代码
+export interface UserResponse {
+  id: number;
+  name: ;  // 语法错误
+}
+```
+
+### 原因
+
+- API 响应数据不规范
+- JSON 格式错误
+- 空值处理问题
+
+### 解决方案
+
+**检查 API 响应：**
+
+```bash
+# 使用 curl 检查响应
+curl https://api.example.com/users
+```
+
+**检查 JSON 格式：**
+
+```json
+// ✅ 正确
+{
+  "name": "John",
+  "age": 30
+}
+
+// ❌ 错误
+{
+  "name": "John",
+  "age": ,  // 缺少值
+}
+```
+
+**手动修复：**
+
+生成后手动检查和修复类型定义。
+
+---
+
+## 问题 6：类型名冲突
+
+### 症状
+
+```
+⚠️  类型名冲突，已自动重命名: UserResponse → UserResponse1
+```
+
+### 原因
+
+- 同一目录已存在相同类型名
+- 多次生成相同接口
+
+### 解决方案
+
+**方案 1：接受自动重命名**
+
+自动重命名为 `UserResponse1`, `UserResponse2` 等。
+
+**方案 2：手动合并**
+
+```typescript
+// 检查是否是重复定义
+// 如果是，删除其中一个
+export interface UserResponse { ... }
+export interface UserResponse1 { ... }  // 删除
+```
+
+**方案 3：使用不同的输出目录**
+
+```bash
+go-gen fetch
+📂 输出目录: 🔍 自定义路径
+# 输入不同的路径
+```
+
+---
+
+## 问题 7：找不到 request 模块
+
+### 症状
+
+```typescript
+// 生成的代码
+import request from '@/utils/request'; // 找不到模块
+```
+
+### 原因
+
+项目中没有对应的 request 模块
+
+### 解决方案
+
+**方案 1：创建 request 模块**
+
+```typescript
+// src/utils/request.ts
+import axios from 'axios';
+
+const request = axios.create({
+  baseURL: '/api',
+  timeout: 10000,
+});
+
+export default request;
+```
+
+**方案 2：修改配置**
+
+```json
+{
+  "requestModule": "axios" // 直接使用 axios
+}
+```
+
+**方案 3：手动修改导入**
+
+生成后手动修改 import 路径。
+
+---
+
+## 问题 8：批量生成失败
+
+### 症状
+
+```
+⚡ 批量生成中... (1/50): GET /users
+❌ 生成失败: 5 个接口
+```
+
+### 原因
+
+- 部分接口定义不完整
+- operationId 缺失
+- 响应格式不标准
+
+### 解决方案
+
+**查看详细错误：**
+
+检查控制台输出，找到失败的接口。
+
+**逐个生成：**
+
+```bash
+go-gen openapi ./swagger.json
+# 选择 "逐个生成"
+# 跳过有问题的接口
+```
+
+**修复 OpenAPI 文档：**
+
+确保每个接口都有：
+
+- operationId
+- responses
+- 正确的 schema 定义
+
+---
+
+## 问题 9：配置不生效
+
+### 症状
+
+设置了配置，但生成的代码没有使用配置。
+
+### 原因
+
+配置文件路径错误或格式错误
+
+### 解决方案
+
+**检查配置文件位置：**
+
+```bash
+# 项目配置
+ls .apirc.json
+
+# 全局配置
+ls ~/.apirc.json
+```
+
+**检查 JSON 格式：**
+
+```bash
+# 验证 JSON 格式
+cat .apirc.json | jq .
+```
+
+**查看当前配置：**
+
+```bash
+go-gen config --show
+```
+
+**重新初始化：**
+
+```bash
+go-gen init --force  # 强制重新创建
+```
+
+---
+
+## 获取帮助
+
+如果以上方案都无法解决问题：
+
+发邮件到：bg2582266166@gmail.com