# Easy-API

**Repository Path**: HackOwnLife485/api-easy

## Basic Information

- **Project Name**: Easy-API
- **Description**: 基于APIJSON的低代码开发平台
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 2
- **Created**: 2025-05-19
- **Last Updated**: 2025-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于APIJSON的第三方接口对接低代码开发平台

## 🚀 项目简介

这是一个基于APIJSON框架构建的第三方接口对接低代码开发平台，专门用于企业ERP系统与内部系统的数据集成。平台提供了可视化的配置界面，支持多种ERP系统类型，具备强大的数据转换能力和灵活的调度机制。

## ✨ 核心特性

### 🏢 ERP系统管理
- **多系统支持**: SAP、Oracle、用友、金蝶等主流ERP系统
- **灵活认证**: OAuth2、Basic Auth、Token等多种认证方式
- **连接测试**: 一键测试ERP系统连接状态
- **配置管理**: 完整的系统配置信息管理

### 🔌 接口定义管理
- **可视化配置**: 拖拽式接口配置界面
- **多协议支持**: RESTful、SOAP、OData等
- **参数配置**: 请求头、参数、请求体的灵活配置
- **响应映射**: 智能的响应数据映射和转换

### 📊 数据映射管理
- **字段映射**: 本地数据与ERP数据的字段映射
- **类型转换**: 自动数据类型转换和验证
- **规则引擎**: 支持自定义转换规则和验证规则
- **批量操作**: 支持批量字段映射配置

### ⏰ 同步任务管理
- **定时调度**: 基于Cron表达式的定时任务
- **多种策略**: 全量、增量、实时同步策略
- **错误处理**: 完善的错误处理和重试机制
- **监控日志**: 详细的执行日志和状态监控

### 🚀 低代码开发
- **零代码配置**: 无需编写代码即可配置ERP接口
- **可视化界面**: 直观的配置和管理界面
- **实时测试**: 接口配置完成后可立即测试
- **模板管理**: 支持接口配置模板的导入导出

## 🏗️ 技术架构

### 后端技术栈
- **框架**: Spring Boot 3.2.5 + APIJSON 7.1.0
- **语言**: Java 17
- **数据库**: MySQL 8.0+
- **认证**: OAuth2、Basic、Token
- **HTTP客户端**: Spring RestTemplate
- **任务调度**: Spring Task + 自定义调度器

### 前端技术栈
- **框架**: Vue 3 + Element Plus
- **样式**: CSS3 + Less
- **HTTP客户端**: Axios
- **构建工具**: 原生JavaScript

### 核心组件
```
src/main/java/com/xiyun/easyapi/
├── config/erp/           # ERP客户端配置
│   ├── ERPClient.java    # ERP客户端接口
│   ├── AbstractERPClient.java  # 抽象基类
│   ├── SAPClient.java    # SAP客户端实现
│   ├── OracleClient.java # Oracle客户端实现
│   ├── UFIDAClient.java  # 用友客户端实现
│   ├── KingdeeClient.java # 金蝶客户端实现
│   └── CustomERPClient.java # 自定义客户端实现
├── model/                # 数据模型
│   ├── ERPSystem.java   # ERP系统模型
│   ├── ERPInterface.java # ERP接口模型
│   ├── ERPDataMapping.java # 数据映射模型
│   └── ERPSyncTask.java # 同步任务模型
├── service/              # 业务服务层
│   ├── ERPService.java  # ERP服务接口
│   ├── DataTransformService.java # 数据转换服务
│   └── TaskSchedulerService.java # 任务调度服务
└── controller/           # 控制器层
    └── ERPController.java # ERP管理控制器
```

## 🚀 快速开始

### 环境要求
- **Java**: 17或更高版本
- **Maven**: 3.6或更高版本
- **MySQL**: 8.0或更高版本
- **操作系统**: Linux、Windows、macOS

### 安装步骤

1. **克隆项目**
```bash
git clone https://gitee.com/HackOwnLife485/api-easy
cd api-easy
```

2. **配置数据库**
```bash
# 创建数据库
mysql -u root -p
CREATE DATABASE easyapi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 修改配置文件
vim src/main/resources/application.yml
```

3. **编译项目**
```bash
mvn clean compile
```

4. **启动应用**
```bash
# Linux/macOS
chmod +x start.sh
./start.sh

# Windows
start.bat
```

5. **访问应用**
- 应用地址: http://localhost:8080
- API文档: http://localhost:8080/api/erp/stats
- 前端管理界面: http://localhost:8080/page/erp_manager/

## 📖 API文档

### ERP系统管理

#### 创建ERP系统
```http
POST /api/erp/system
Content-Type: application/json

{
  "systemName": "SAP生产系统",
  "systemType": "SAP",
  "baseUrl": "https://sap.example.com",
  "apiVersion": "v1",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "username": "admin",
  "password": "password",
  "authType": "OAuth2",
  "description": "SAP生产环境系统"
}
```

#### 查询ERP系统列表
```http
POST /api/erp/system/list
Content-Type: application/json

{
  "status": 1,
  "systemType": "SAP"
}
```

#### 测试ERP系统连接
```http
POST /api/erp/system/{id}/test
```

### ERP接口管理

#### 创建ERP接口
```http
POST /api/erp/interface
Content-Type: application/json

{
  "erpSystemId": 1,
  "interfaceName": "获取订单信息",
  "interfaceCode": "GET_ORDERS",
  "httpMethod": "GET",
  "endpoint": "/api/orders",
  "requestHeaders": "{\"Accept\": \"application/json\"}",
  "requestParams": "{\"status\": \"active\"}",
  "timeout": 30,
  "retryCount": 3,
  "description": "获取活跃订单列表"
}
```

#### 测试ERP接口
```http
POST /api/erp/interface/{id}/test
Content-Type: application/json

{
  "orderId": "12345",
  "status": "active"
}
```

### 数据映射管理

#### 创建数据映射
```http
POST /api/erp/mapping
Content-Type: application/json

{
  "erpInterfaceId": 1,
  "sourceField": "order_id",
  "targetField": "orderNo",
  "fieldType": "String",
  "isRequired": true,
  "isPrimaryKey": true,
  "fieldOrder": 1,
  "description": "订单号映射"
}
```

### 同步任务管理

#### 创建同步任务
```http
POST /api/erp/task
Content-Type: application/json

{
  "taskName": "订单数据同步",
  "taskCode": "SYNC_ORDERS",
  "erpInterfaceId": 1,
  "syncType": "INCREMENTAL",
  "cronExpression": "0 0/30 * * * ?",
  "syncDirection": "FROM_ERP",
  "syncStrategy": "UPSERT",
  "batchSize": 1000,
  "timeout": 300,
  "retryCount": 3,
  "description": "每30分钟同步一次订单数据"
}
```

#### 执行同步任务
```http
POST /api/erp/task/{id}/execute
```

## 🔧 配置说明

### 应用配置
```yaml
server:
  port: 8080
  servlet:
    context-path: /api

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/easyapi
    username: root
    password: your-password
    database: easyapi

# APIJSON配置
apijson:
  debug: false
  log-level: INFO
  enable-remote-function: false
  enable-verify-role: false
  enable-verify-content: false

# ERP系统配置
erp:
  default-timeout: 30000
  default-retry-count: 3
  auth-token-expire: 7200
  sync-batch-size: 1000
```

### 数据库配置
```sql
-- 创建数据库
CREATE DATABASE easyapi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建用户（可选）
CREATE USER 'easyapi'@'localhost' IDENTIFIED BY 'your-password';
GRANT ALL PRIVILEGES ON easyapi.* TO 'easyapi'@'localhost';
FLUSH PRIVILEGES;
```

## 📊 使用示例

### 1. 配置SAP系统
```json
{
  "systemName": "SAP生产系统",
  "systemType": "SAP",
  "baseUrl": "https://sap.example.com",
  "authType": "OAuth2",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret"
}
```

### 2. 配置订单接口
```json
{
  "interfaceName": "获取订单信息",
  "httpMethod": "GET",
  "endpoint": "/api/orders",
  "requestHeaders": "{\"Accept\": \"application/json\"}",
  "requestParams": "{\"status\": \"active\"}"
}
```

### 3. 配置字段映射
```json
[
  {
    "sourceField": "order_id",
    "targetField": "orderNo",
    "fieldType": "String",
    "isRequired": true,
    "isPrimaryKey": true
  },
  {
    "sourceField": "order_date",
    "targetField": "orderDate",
    "fieldType": "Date",
    "transformRule": "{\"type\": \"date_format\", \"sourceFormat\": \"yyyy-MM-dd\", \"targetFormat\": \"yyyyMMdd\"}"
  }
]
```

### 4. 配置同步任务
```json
{
  "taskName": "订单数据同步",
  "cronExpression": "0 0/30 * * * ?",
  "syncType": "INCREMENTAL",
  "syncDirection": "FROM_ERP",
  "batchSize": 1000
}
```

## 🛠️ 开发指南

### 添加新的ERP系统支持

1. **创建客户端实现类**
```java
@Component
public class NewERPClient extends AbstractERPClient {
    
    public NewERPClient(ERPSystem erpSystem) {
        super(erpSystem);
    }
    
    @Override
    public boolean refreshAuthToken() {
        // 实现认证令牌刷新逻辑
        return true;
    }
    
    @Override
    public JSONObject getSystemInfo() {
        // 实现系统信息获取逻辑
        return new JSONObject();
    }
}
```

2. **在工厂类中添加支持**
```java
case "NEW_ERP":
    return new NewERPClient(erpSystem);
```

### 自定义数据转换规则

```java
// 在DataTransformService中添加新的转换类型
case "custom_transform":
    return customTransform(sourceValue, rule);
```

### 扩展任务调度策略

```java
// 在TaskSchedulerService中添加新的调度策略
private void executeCustomTask(ERPSyncTask task) {
    // 实现自定义任务执行逻辑
}
```

## 📝 常见问题

### Q: 如何解决ERP系统连接超时？
A: 检查网络连接，调整timeout配置，确保ERP系统可访问。

### Q: 数据同步失败如何处理？
A: 查看执行日志，检查数据映射配置，验证ERP接口返回数据格式。

### Q: 如何优化同步性能？
A: 调整batchSize参数，使用增量同步策略，优化数据库查询。

### Q: 支持哪些ERP系统？
A: 目前支持SAP、Oracle、用友、金蝶等主流系统，可通过扩展支持更多系统。

## 🤝 贡献指南

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目采用 Apache License 2.0 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 联系我们

- 项目主页: https://gitee.com/HackOwnLife485/api-easy
- 问题反馈: https://gitee.com/HackOwnLife485/api-easy/issues
- 邮箱: 485114286@qq.com

## 🙏 致谢

感谢以下开源项目的支持：
- [APIJSON](https://github.com/Tencent/APIJSON) - 强大的JSON接口框架
- [Spring Boot](https://spring.io/projects/spring-boot) - 企业级Java开发框架
- [Vue.js](https://vuejs.org/) - 渐进式JavaScript框架
- [Element Plus](https://element-plus.org/) - Vue 3组件库

---

⭐ 如果这个项目对您有帮助，请给我们一个星标！