czh-api 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -2,11 +2,41 @@
 
 所有重要的版本更新都会记录在此文件中。
 
+## [1.0.3] - 2026-03-17
+
+### 新增
+- 添加 `pathPrefixes` 配置项，支持自定义路径前缀分组和二级分包
+- 支持配置多个路径前缀，每个前缀可指定自定义包名或自动驼峰命名
+- 自动按路径前缀后的第一级路径进行二级分包
+
+### 修复
+- 修复模块名包含斜杠时文件路径生成错误的问题
+- 修复二级分包时文件名重复的问题
+
+### 改进
+- 优化模块分组逻辑，支持更灵活的目录结构
+- 完善 README.md，添加 `pathPrefixes` 配置说明和示例
+
 ## [1.0.2] - 2025-12-25
 
 ### 新增
 - 添加 `includePaths` 配置项，支持白名单过滤 API 路径
 - 如果配置了 `includePaths`，则只同步以这些前缀开头的 API
+- 支持 FastAPI `anyOf` 联合类型解析，自动生成 TypeScript 联合类型（如 `string | null`）
+
+### 修复
+- 修复 OpenAPI 3.1.0 兼容性问题，自动转换为 3.0.x 格式
+- 解决 FastAPI 生成的 OpenAPI 3.1.0 文档解析失败的问题
+- 修复 FastAPI `anyOf` 数组默认为 `any` 的问题，现在正确生成联合类型
+- 修复 OpenAPI 类型到 TypeScript 类型的映射：`integer` → `number`，`object` → `any`
+- 增强错误处理，转换失败时自动回退到直接使用文档
+- 添加多层错误恢复机制，提高解析成功率
+
+### 改进
+- 完善 README.md，添加 FastAPI 兼容性说明和推荐配置
+- 优化错误提示，为 OpenAPI 3.1.0 问题提供具体解决方案
+- 增强解析器稳定性，支持更多边缘情况
+- 改进类型生成逻辑，更好地处理 FastAPI 的复杂类型定义
 
 ## [1.0.1] - 2025-12-25
 

package/README.md

@@ -5,6 +5,7 @@
 ## ✨ 功能特性
 
 - **多标准支持**: 完美兼容 Swagger v2, OpenAPI v3, 以及 Knife4j 风格的 JSON 文档。
+- **OpenAPI 3.1.0 支持**: 自动检测并转换 OpenAPI 3.1.0 规范到兼容的 3.0.x 版本，完美支持 FastAPI 生成的文档。
 - **智能模块生成**: 根据接口的 `x-package` 字段（例如 `com.czh.SysConfigController` -> `sysConfig` 模块）自动对 API 进行模块化分组，当该字段缺失时，则使用 URL 的第一段作为备用方案。
 - **清晰的命名规范**: API 函数名采用 `HTTP方法` + `驼峰式路径` 的方式生成（例如 `POST /sys/user/add` -> `postSysUserAdd`），确保了全局唯一性和代码的可读性。
 - **可定制化模板**: 提供 Handlebars (`.hbs`) 模板，覆盖 API、类型和模块索引文件，允许您完全自定义生成的代码风格。
@@ -67,6 +68,74 @@ npm install -g czh-api
 | `customImports`  | `string[]` | 否       | 一个自定义导入语句的数组，会被添加到每个生成的 API 文件的顶部。         |
 | `excludePaths`   | `string[]` | 否       | 一个 URL 路径前缀的数组。任何以此数组中前缀开头的 API 都将被忽略。     |
 | `includePaths`   | `string[]` | 否       | 一个 URL 路径前缀的数组。如果配置了此项，则只同步以这些前缀开头的 API。 |
+| `pathPrefixes`   | `array`    | 否       | 路径前缀配置数组，用于自定义模块分组和二级分包。详见下方说明。           |
+
+### 路径前缀配置 (`pathPrefixes`)
+
+`pathPrefixes` 允许您根据 API 路径前缀自定义模块分组和二级分包策略。
+
+**配置格式:**
+
+```json
+{
+  "pathPrefixes": [
+    {
+      "path": "/api/expert",
+      "packageName": "expert"
+    },
+    {
+      "path": "/api/user"
+      // 不指定 packageName，将自动使用驼峰命名: apiUser
+    }
+  ]
+}
+```
+
+**配置项说明:**
+
+| 字段          | 类型     | 是否必须 | 描述                                                                 |
+|---------------|----------|----------|----------------------------------------------------------------------|
+| `path`        | `string` | 是       | 要匹配的路径前缀，如 `/api/expert`                                   |
+| `packageName` | `string` | 否       | 自定义包名。如果不指定，将自动将路径转为驼峰命名（如 `/api/expert` -> `apiExpert`） |
+
+**分包规则:**
+
+1. **一级包名**: 由 `packageName` 指定，或自动从 `path` 转换为驼峰命名
+2. **二级包名**: 使用路径前缀后的第一级路径作为子模块名
+
+**示例:**
+
+假设配置了:
+```json
+{
+  "pathPrefixes": [
+    {
+      "path": "/api/expert",
+      "packageName": "expert"
+    }
+  ]
+}
+```
+
+API 路径分包结果:
+- `/api/expert/certification/submit` → `expert/certification`
+- `/api/expert/profile/update` → `expert/profile`
+- `/api/expert/info` → `expert` (没有二级路径时直接使用包名)
+
+**生成的目录结构:**
+
+```
+src/api/
+├── expert/
+│   ├── certification/
+│   │   ├── certification.ts
+│   │   ├── types.ts
+│   │   └── index.ts
+│   └── profile/
+│       ├── profile.ts
+│       ├── types.ts
+│       └── index.ts
+```
 
 ## 📝 模板配置
 
@@ -151,7 +220,47 @@ export const {{functionName}} = ({{#if hasParams}}params: {{requestParamsTypeNam
 ```
 
 
-## 👨‍💻 开发者指南
+## 🐍 FastAPI 兼容性
+
+`czh-api` 完全支持 FastAPI 生成的 OpenAPI 3.1.0 文档。工具会自动检测 OpenAPI 版本并进行必要的转换。
+
+### FastAPI 推荐配置
+
+如果您在使用 FastAPI 时遇到兼容性问题，可以在创建 FastAPI 应用时指定 OpenAPI 版本：
+
+```python
+from fastapi import FastAPI
+
+# 方法1: 指定 OpenAPI 版本为 3.0.2（推荐）
+app = FastAPI(openapi_version="3.0.2")
+
+# 方法2: 使用默认 3.1.0（czh-api 会自动转换）
+app = FastAPI()
+```
+
+### 常见问题解决
+
+如果遇到 "Missing $ref pointer" 错误，通常是由于 OpenAPI 3.1.0 到 3.0.x 转换过程中的引用问题。建议：
+
+1. **优先方案**: 在 FastAPI 中配置使用 OpenAPI 3.0.2
+2. **备选方案**: 检查 FastAPI 文档中是否有循环引用或复杂的 schema 定义
+3. **临时方案**: 使用 `excludePaths` 配置排除有问题的接口路径
+
+### 示例配置
+
+```json
+{
+  "url": "http://localhost:8000/openapi.json",
+  "outputDir": "./src/api",
+  "customImports": [
+    "import request from '@/utils/request';"
+  ],
+  "excludePaths": [
+    "/docs",
+    "/redoc"
+  ]
+}
+```
 
 如果您克隆了本仓库并希望进行二次开发、贡献或发布您自己的版本，请遵循以下步骤：