@tuoyuan/gateway-api-select-config 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 API Config Component
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,605 @@
+# API Config Component
+
+网关接口配置组件 - 可视化配置 API 接口数据映射
+
+## 简介
+
+**API Config Component** 是一个基于 Vue 3 的可视化配置组件，用于配置网关 API 接口的数据映射规则。
+
+### 核心功能
+
+1. **选择 API 接口** - 从树形结构中选择目标接口
+2. **配置入参映射** - 支持固定值、模板字符串、函数三种模式
+3. **配置输出结构** - 定义字段提取路径和格式化规则
+4. **输出标准配置** - 生成可存储、可解析的 JSON 配置
+
+### 应用场景
+
+- 网关接口数据适配
+- 多数据源统一输出格式
+- 动态表单/表格数据源配置
+- 低代码平台数据源配置
+
+## 特性
+
+- 🎯 **可视化配置** - 通过界面操作完成复杂的数据映射
+- 🌲 **树形 API 选择** - 支持多层级分类和搜索
+- 🔍 **智能过滤** - 支持 include/exclude 模式过滤 API
+- 🎨 **灵活的入参配置** - 固定值/模板字符串/函数三种模式
+- 📋 **Schema 驱动** - 基于 JSON Schema 定义输出结构
+- 🎛️ **字段格式化** - 支持日期、数字、货币等格式化
+- 💾 **标准输出** - 输出标准 JSON 配置
+- 🔄 **自动推断** - Schema 不完整时自动返回完整数据
+
+## 安装
+
+```bash
+npm install api-config-component
+```
+
+或
+
+```bash
+yarn add api-config-component
+```
+
+或
+
+```bash
+pnpm add api-config-component
+```
+
+## 快速开始
+
+### 最简单的使用方式
+
+```vue
+<template>
+  <ApiConfig
+    :api-loader="loadApiList"
+    @save="handleSave"
+  />
+</template>
+
+<script setup>
+import { ApiConfig } from 'api-config-component';
+import 'api-config-component/dist/style.css';
+
+// 加载 API 列表
+const loadApiList = async () => {
+  const response = await fetch('/api/gateway/list');
+  return response.json();
+};
+
+// 保存配置
+const handleSave = (config) => {
+  console.log('保存的配置：', config);
+  // 将配置保存到后端
+};
+</script>
+```
+
+### 使用工具函数测试配置
+
+```vue
+<template>
+  <ApiConfig
+    :api-loader="loadApiList"
+    @save="handleSave"
+  />
+</template>
+
+<script setup>
+import { ApiConfig, extractDataBySchema, executeReqMapping } from 'api-config-component';
+import 'api-config-component/dist/style.css';
+
+const loadApiList = async () => {
+  // 加载 API 列表
+};
+
+const handleSave = async (config) => {
+  // 1. 执行入参映射
+  const params = executeReqMapping(config.reqMapping, {
+    pageNum: 1,
+    pageSize: 100
+  });
+  
+  // 2. 调用 API
+  const response = await fetch(config.apiPath, {
+    method: 'POST',
+    body: JSON.stringify(params)
+  });
+  const data = await response.json();
+  
+  // 3. 提取数据
+  const result = extractDataBySchema(data, config.res_schema);
+  
+  console.log('提取后的数据：', result);
+};
+</script>
+```
+
+## API 文档
+
+### Props
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| apiLoader | Function | 是* | null | 自定义 API 列表加载函数 |
+| apiListUrl | String | 是* | '' | 网关 API 列表接口地址 |
+| resSchema | Object | 否 | null | 输出数据结构模板（JSON Schema） |
+| includePattern | Array | 否 | [] | 只显示匹配规则的 API，支持通配符 `*` |
+| excludePattern | Array | 否 | [] | 排除匹配规则的 API |
+| initialConfig | Object | 否 | null | 初始配置（编辑模式） |
+
+**注意**：`apiLoader` 和 `apiListUrl` 至少需要提供一个。
+
+### Events
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| save | config: Object | 保存配置时触发，返回完整配置对象 |
+| change | { api, config, resSchema } | 配置变化时触发 |
+
+### 导出的工具函数
+
+```javascript
+import { 
+  ApiConfig,              // 组件
+  extractDataBySchema,    // 根据 schema 提取数据
+  executeReqMapping,      // 执行入参映射
+  extractOutputFields,    // 提取输出字段信息
+  formatConfig           // 格式化配置显示
+} from 'api-config-component';
+```
+
+#### extractDataBySchema(data, schema)
+
+根据 res_schema 从原始数据中提取字段。
+
+**参数：**
+- `data` - 原始数据对象
+- `schema` - res_schema 配置
+
+**返回：** 提取后的数据
+
+**示例：**
+```javascript
+const data = {
+  code: 10000,
+  msg: '成功',
+  data: {
+    list: [
+      { id: 1, name: '张三' },
+      { id: 2, name: '李四' }
+    ]
+  }
+};
+
+const schema = {
+  type: 'object',
+  x_path: '@.data.list',
+  items: {
+    type: 'object',
+    properties: {
+      id: { type: 'integer', x_path: '@.id' },
+      name: { type: 'string', x_path: '@.name' }
+    }
+  }
+};
+
+const result = extractDataBySchema(data, schema);
+// 结果：[{ id: 1, name: '张三' }, { id: 2, name: '李四' }]
+```
+
+#### executeReqMapping(reqMapping, context)
+
+执行入参映射，将模板变量替换为实际值。
+
+**参数：**
+- `reqMapping` - 入参映射配置
+- `context` - 上下文数据对象
+
+**返回：** 执行后的参数对象
+
+**示例：**
+```javascript
+const reqMapping = {
+  page_no: '${pageNum}',
+  page_size: '${pageSize}',
+  keyword: '${searchText}'
+};
+
+const context = {
+  pageNum: 1,
+  pageSize: 100,
+  searchText: 'test'
+};
+
+const params = executeReqMapping(reqMapping, context);
+// 结果：{ page_no: 1, page_size: 100, keyword: 'test' }
+```
+
+## 使用示例
+
+### 示例 1：列表接口配置
+
+```vue
+<template>
+  <ApiConfig
+    :api-loader="loadApiList"
+    :include-pattern="['*.get_list', '*.query*']"
+    :exclude-pattern="['*.add', '*.remove', '*.delete']"
+    @save="handleSave"
+  />
+</template>
+
+<script setup>
+import { ApiConfig } from 'api-config-component';
+import 'api-config-component/dist/style.css';
+
+const loadApiList = async () => {
+  const response = await fetch('/api/gateway/list');
+  return response.json();
+};
+
+const handleSave = (config) => {
+  console.log('保存的配置：', config);
+  // 保存到后端
+  fetch('/api/config/save', {
+    method: 'POST',
+    body: JSON.stringify(config)
+  });
+};
+</script>
+```
+
+### 示例 2：树形结构配置
+
+```vue
+<template>
+  <ApiConfig
+    :api-loader="loadApiList"
+    :include-pattern="['*.get_tree', '*.get_list']"
+    @save="handleSave"
+  />
+</template>
+
+<script setup>
+import { ApiConfig } from 'api-config-component';
+import 'api-config-component/dist/style.css';
+
+const loadApiList = async () => {
+  // 加载 API 列表
+};
+
+const handleSave = (config) => {
+  console.log('保存配置', config);
+};
+</script>
+```
+
+### 示例 3：编辑已有配置
+
+```vue
+<template>
+  <ApiConfig
+    :api-loader="loadApiList"
+    :initial-config="existingConfig"
+    @save="handleSave"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { ApiConfig } from 'api-config-component';
+import 'api-config-component/dist/style.css';
+
+const existingConfig = ref({
+  apiPath: '/api/news/list',
+  reqMapping: {
+    page_no: '${pageNum}',
+    page_size: '${pageSize}'
+  },
+  res_schema: {
+    type: 'object',
+    x_path: '@.data.list',
+    items: {
+      type: 'object',
+      properties: {
+        id: { type: 'integer', x_path: '@.id' },
+        title: { type: 'string', x_path: '@.title' }
+      }
+    }
+  }
+});
+
+const loadApiList = async () => {
+  // 加载 API 列表
+};
+
+const handleSave = (config) => {
+  console.log('更新配置', config);
+};
+</script>
+```
+
+## 配置输出格式
+
+组件保存后输出标准 JSON 配置：
+
+```json
+{
+  "apiPath": "/api/news/list",
+  "reqMapping": {
+    "page_no": "${pageNum}",
+    "page_size": "${pageSize}",
+    "keyword": "${searchText}"
+  },
+  "res_schema": {
+    "type": "object",
+    "x_path": "@.data.list",
+    "items": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "integer",
+          "x_path": "@.id",
+          "format": ""
+        },
+        "title": {
+          "type": "string",
+          "x_path": "@.title",
+          "format": ""
+        },
+        "publishTime": {
+          "type": "string",
+          "x_path": "@.publish_time",
+          "format": "YYYY-MM-DD HH:mm:ss"
+        }
+      }
+    }
+  }
+}
+```
+
+## 入参配置模式
+
+### 1. 固定值模式
+
+直接使用固定值：
+
+```json
+{
+  "page_no": 1,
+  "page_size": 100,
+  "need_total": true
+}
+```
+
+### 2. 模板字符串模式
+
+使用 `${变量名}` 引用上下文变量：
+
+```json
+{
+  "page_no": "${pageNum}",
+  "page_size": "${pageSize}",
+  "keyword": "${searchText}"
+}
+```
+
+**不带引号的写法**（推荐，自动保持类型）：
+
+```json
+{
+  "page_no": ${pageNum},
+  "page_size": ${pageSize}
+}
+```
+
+### 3. 函数模式
+
+使用箭头函数进行复杂计算：
+
+```json
+{
+  "page_no": "(ctx) => Number(ctx.pageNum) || 1",
+  "page_size": "(ctx) => Math.min(ctx.pageSize, 100)",
+  "keyword": "(ctx) => ctx.searchText?.trim() || ''"
+}
+```
+
+## 字段格式化
+
+支持多种格式化类型：
+
+### 日期格式
+
+- `YYYY-MM-DD` - 2024-01-01
+- `YYYY-MM-DD HH:mm:ss` - 2024-01-01 12:00:00
+- `YYYY/MM/DD` - 2024/01/01
+- `timestamp` - 时间戳（毫秒）
+- `timestamp_s` - 时间戳（秒）
+
+### 数字格式
+
+- `number` - 数字
+- `integer` - 整数
+- `currency` - 货币（¥1,234.56）
+- `percent` - 百分比（12.34%）
+
+### 通用格式
+
+- `string` - 字符串
+- `boolean` - 布尔值
+- `json` - JSON 字符串
+
+## Schema 自动推断
+
+当 API 的 `res_schema` 不完整（`properties` 为空）时，组件会自动推断并返回完整的原始数据。
+
+**示例：**
+
+如果 API 的 schema 是：
+```json
+{
+  "type": "object",
+  "properties": {
+    "data": {
+      "type": "object",
+      "properties": {}
+    }
+  }
+}
+```
+
+组件会自动：
+1. 检测到 `data.properties` 为空
+2. 推测数据路径为 `@.data.list`
+3. 直接返回 `data.list` 的完整数据
+
+## API 树数据格式
+
+API 列表应返回以下格式：
+
+```javascript
+[
+  {
+    id: '1',                    // 节点 ID
+    name: '系统管理',            // 节点名称
+    isLeaf: false,              // 是否叶子节点
+    expanded: false,            // 是否展开
+    children: [                 // 子节点
+      {
+        id: '1-1',
+        name: '获取用户列表',
+        apiPath: '/api/system/user/get_list',  // API 路径
+        isLeaf: true,
+        _raw: {                 // 原始数据（包含 req_schema、res_schema）
+          req_schema: { /* ... */ },
+          res_schema: { /* ... */ }
+        }
+      }
+    ]
+  }
+]
+```
+
+或者使用 `funcs` 数组（会自动转换为 `children`）：
+
+```javascript
+[
+  {
+    id: '1',
+    name: '系统管理',
+    funcs: [                    // 接口列表
+      {
+        id: '1-1',
+        name: '获取用户列表',
+        tag: 'system.user.get_list',
+        req_schema: { /* ... */ },
+        res_schema: { /* ... */ }
+      }
+    ]
+  }
+]
+```
+
+## 过滤规则
+
+### includePattern
+
+只显示匹配的 API：
+
+```vue
+<ApiConfig
+  :include-pattern="['*.get_list', '*.query*', 'system.*']"
+/>
+```
+
+### excludePattern
+
+排除匹配的 API：
+
+```vue
+<ApiConfig
+  :exclude-pattern="['*.add', '*.remove', '*.delete', '*.update']"
+/>
+```
+
+### 通配符规则
+
+- `*` - 匹配任意字符
+- `*.get_list` - 匹配所有以 `.get_list` 结尾的 API
+- `system.*` - 匹配所有以 `system.` 开头的 API
+- `*user*` - 匹配包含 `user` 的 API
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 启动开发服务器
+npm run dev
+
+# 构建库
+npm run build
+
+# 预览
+npm run preview
+```
+
+## 浏览器支持
+
+- Chrome >= 87
+- Firefox >= 78
+- Safari >= 14
+- Edge >= 88
+
+## 常见问题
+
+### 1. 如何处理 Schema 不完整的 API？
+
+组件会自动检测并使用自动推断模式，直接返回完整的原始数据。
+
+### 2. 模板变量的类型如何保持？
+
+使用不带引号的写法：`{"page_no": ${pageNum}}`，会自动保持原始类型。
+
+### 3. 如何自定义 API 加载逻辑？
+
+使用 `apiLoader` prop 提供自定义加载函数：
+
+```javascript
+const loadApiList = async () => {
+  const response = await fetch('/your-api');
+  return response.json();
+};
+```
+
+### 4. 如何测试配置是否正确？
+
+使用导出的工具函数：
+
+```javascript
+import { extractDataBySchema, executeReqMapping } from 'api-config-component';
+
+// 执行入参映射
+const params = executeReqMapping(config.reqMapping, context);
+
+// 调用 API 获取数据
+const data = await callApi(config.apiPath, params);
+
+// 提取数据
+const result = extractDataBySchema(data, config.res_schema);
+```
+
+## License
+
+MIT
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！