enn-iot-oc-sdk 1.3.3

IoC数据SDK - 提供工业物联网数据查询接口

ENN IoC SDK Generator

🚀 工业物联网数据SDK自动化生成器 - 根据数据和实体定义完成SDK开发、发布、生成使用文档

📖 项目简介

ENN IoC SDK Generator 是一个专为工业物联网场景设计的SDK自动化生成工具。它能够根据JSON数据源和YAML配置定义，自动生成完整的数据访问SDK，包括实体类、Repository接口、数据关联处理和使用文档。

🎯 核心价值

• 🤖 全自动化: 从数据定义到SDK生成的完整自动化流程
• 📊 数据驱动: 基于实际JSON数据智能推断类型和结构
• 🔗 关系映射: 支持复杂的实体关系定义和自动数据关联
• 📦 开箱即用: 生成的SDK符合企业级标准，可直接投入使用
• 🛠️ 零配置: 无需手写代码，通过配置文件驱动整个开发流程

---

✨ 功能特性

🏗️ SDK生成功能

• ✅ 智能实体生成: 根据JSON数据自动生成@dataclass实体类
• ✅ 自动类型推断: 智能识别字段类型（str, int, float, bool, list, dict）
• ✅ Repository接口生成: 自动生成单行/多行实体的Repository接口
• ✅ 关系映射支持: 完整支持外键和嵌套对象关系
• ✅ 数据关联处理: 自动处理实体间的关联数据加载

📋 配置驱动开发

• ✅ YAML配置: 简洁明了的配置文件定义实体关系
• ✅ 主键验证: 强制主键定义，确保数据完整性
• ✅ 灵活映射: 支持表名映射和字段类型自定义
• ✅ 关系定义: 支持一对一、一对多等复杂关系

🔧 企业级特性

• ✅ 类型安全: 完全类型化的实体和Repository接口
• ✅ 错误处理: 统一的异常处理和错误提示
• ✅ 缓存机制: 内置数据缓存，提供高性能数据访问
• ✅ 标准兼容: 符合企业SDK开发规范

---

🚀 快速开始

1️⃣ 环境准备

# 克隆项目
git clone <repository-url>
cd ioc-sdk-generator

# 安装依赖
pip install -r requirements.txt

2️⃣ 准备数据

将JSON数据文件放入 data/your_project/source/ 目录：

data/
└── your_project/
    ├── relations.yaml          # 实体关系配置
    └── source/                 # JSON数据源
        ├── new_entity.json     # 实体数据
        └── ref_entity.json

3️⃣ 配置实体关系

详见 Relations配置指南.md 创建 relations.yaml 定义实体关系：

entities:
  NewEntity:                     # 主实体
    table: new_entity            # 对应JSON文件名
    row_type: multiple           # 多行实体
    fields:
      id: {type: string, role: pk}                    # 主键字段
      ref_id: {type: string, role: fk, to: RefEntity} # 外键字段
      refObject: {                                         # 嵌入字段
        type: object,
        from: NewEntity.ref_id,
        role: embed,
        to: RefEntity
      }

  RefEntity:                     # 关联实体
    table: ref_entity
    row_type: multiple
    fields:
      id: {type: string, role: pk}                    # 主键字段

4️⃣ 生成SDK

python main.py --data-dir data/your_project --output-dir output

5️⃣ 使用生成的SDK

# 导入生成的实体和Repository
from output.infrastructure.model import NewEntity, NewEntityRepoImpl

# 创建Repository实例
repo = NewEntityRepoImpl(eo_id="your_enterprise_id")

# 查询数据
entities = repo.list()
entity = repo.find_by_id("ENTITY_001")

# 使用关联数据
if entity and entity.refObject:
    print(f"关联对象: {entity.refObject.description}")

---

📁 项目结构

ioc-sdk-generator/
├── README.md                      # 项目主介绍 📖
├── main.py                        # SDK生成器入口 🚀
├── requirements.txt               # 项目依赖 📦
├── setup.py                       # 包配置和元数据 📦
│
├── generator/                     # 生成器模块 🔧
│   ├── config_parser.py          # 配置解析器
│   ├── repository_generator.py   # Repository生成器
│   ├── type_inferencer.py        # 类型推断器
│   └── entity_generator.py       # 实体生成器
│
├── enn_iot_oc/                   # SDK基础框架 🏗️
│   ├── infrastructure/           # 基础设施层
│   │   ├── repository/          # Repository基类
│   │   │   ├── single_repo_base.py
│   │   │   └── multi_repo_base.py
│   │   └── util/                # 工具类
│   └── __init__.py
│
├── data/                        # 数据和配置 📊
│   ├── demo/                    # 示例数据
│   │   ├── relations.yaml       # 示例关系配置
│   │   └── source/              # 示例JSON数据
│   └── copy/                    # 用户数据目录
│
├── output/                      # 生成的SDK输出 📦
│   ├── infrastructure/
│   │   └── model/               # 生成的实体和Repository
│   └── __init__.py
│
├── pre_release_check.sh         # 发布前检查脚本 🔍
├── release.sh                   # 完整发布脚本 🚀
├── tt.py                        # 功能测试脚本 🧪
│
└── docs/                        # 文档目录 📚
    ├── Relations配置指南.md      # 配置文件详细说明
    └── ...                       # 其他文档

---

🛠️ 详细使用指南

配置文件说明

relations.yaml 核心原则

只定义必要字段：

• role: pk - 主键字段（必需）
• role: fk - 外键字段
• role: embed - 嵌入字段

字段类型说明：

# 主键字段
id: {type: string, role: pk}

# 外键字段
ref_id: {type: string, role: fk, to: TargetEntity}

# 一对一嵌入
refObject: {
  type: object,
  from: CurrentEntity.ref_id,
  role: embed,
  to: TargetEntity
}

# 一对多嵌入
children: {
  type: "list[object]",
  from: ChildEntity.parent_id,
  role: embed,
  to: ChildEntity
}

支持的实体类型

实体类型	row_type	Repository方法	使用场景
单行实体	single	find(), save()	配置信息、系统设置
多行实体	multiple	list(), find_by_id(), save_all()	业务数据、记录列表

自动类型推断

JSON数据自动映射为Python类型：

JSON示例	推断类型	Python类型
"text"	string	str
123	int	int
123.45	float	float
true/false	boolean	bool
[1,2,3]	list	List[T]
{}	dict	Dict[str, Any]

---

📊 生成的内容

运行生成器后，将在 output/ 目录生成：

1. 实体类 (output/infrastructure/model/EntityName.py)

@dataclass
class NewEntity:
    """新实体"""
    id: str = ""
    ref_id: str = ""
    name: str = ""
    refObject: Optional[RefEntity] = None

2. Repository实现 (output/infrastructure/model/EntityName.py)

class NewEntityRepoImpl(MultiRepoBase[NewEntity]):
    """新实体Repository实现"""

    def __init__(self, eo_id: str = "", instance_id: str = "") -> None:
        super().__init__(model_code="new_entity", eo_id=eo_id, instance_id=instance_id, id_field="id")

    def to_domain(self, row: Dict[str, Any]) -> NewEntity:
        # 数据转换逻辑

    def from_domain(self, entity) -> Dict[str, Any]:
        # 实体转换逻辑

    def empty_object(self) -> NewEntity:
        # 空对象创建

3. 模块导出 (output/__init__.py)

自动生成模块导入和导出，方便使用。

4. 使用示例和测试

自动生成使用示例代码和测试脚本。

---

🧪 测试和验证

运行测试脚本

# 生成测试脚本
python main.py --data-dir data/copy --output-dir output

# 运行测试
python tt.py

测试内容

• ✅ Repository接口功能测试
• ✅ 数据关联关系测试
• ✅ 类型安全性验证
• ✅ 错误处理测试

---

🚀 发布指南

快速发布

项目提供了完整的自动化发布脚本，支持版本参数自动发布：

# 完整发布流程 (推荐)
./release.sh [version_type]

# 仅执行发布前检查
./pre_release_check.sh [version_type]

版本参数说明

版本类型	说明	示例
patch	补丁版本 - 修复bug	1.1.0 → 1.1.1
minor	次要版本 - 新功能	1.1.0 → 1.2.0
major	主要版本 - 重大变更	1.1.0 → 2.0.0

发布流程

方法1: 一键发布 (推荐)

# 发布补丁版本 (默认)
./release.sh

# 发布次要版本
./release.sh minor

# 发布主要版本
./release.sh major

# 试运行 (不实际上传PyPI)
./release.sh patch true

方法2: 分步发布

# 1. 执行发布前检查
./pre_release_check.sh minor

# 2. 构建分发包
python setup.py sdist bdist_wheel

# 3. 检查构建文件
ls -la dist/

# 4. 上传到PyPI
twine upload dist/*

# 5. 创建Git标签
git tag v1.2.0
git push origin v1.2.0

自动化功能

发布脚本会自动完成：

✅ 版本管理

• 自动递增版本号
• 更新 setup.py 和相关文件
• 创建 Git 标签

✅ 质量检查

• 验证数据文件存在
• 检查 Repository 代码生成
• 运行完整测试套件
• 验证 setup.py 配置

✅ 构建发布

• 清理旧的构建文件
• 构建源码包和 wheel 包
• 检查包完整性
• 试运行上传到 TestPyPI

✅ 文档生成

• 生成 CHANGELOG 条目
• 创建发布摘要
• 生成发布报告

发布后检查

发布完成后，可以：

1. 验证PyPI包: pip install enn-iot-oc-sdk==新版本
2. 查看发布报告: release_report_v版本号.md
3. 创建GitHub Release: 上传构建文件和更新日志
4. 更新文档: 如果有API变更

---

⚠️ 重要注意事项

配置文件要求

1. 主键必需: 每个实体必须定义一个 role: pk 的主键字段
2. 文件匹配: JSON文件名必须与 table 值对应
3. 关系完整: 外键引用的目标实体必须在配置中定义

数据完整性

• 外键值在目标实体中必须存在
• 关联字段名称拼写必须正确
• 避免循环引用（A→B→A）

错误处理

生成器提供详细的错误提示：

• ❌ 主键缺失告警
• ❌ 配置语法错误
• ❌ 数据文件不存在
• ❌ 关系定义错误

---

🔧 高级配置

自定义类型推断

可通过修改 generator/type_inferencer.py 自定义类型推断规则。

扩展Repository功能

在 enn_iot_oc/infrastructure/repository/ 目录下扩展基础Repository功能。

批量处理

支持批量处理多个项目和配置：

# 批量生成多个项目的SDK
for project in project1 project2 project3; do
    python main.py --data-dir data/$project --output-dir output/$project
done

---

📚 相关文档

• 📋 Relations.yaml配置指南 - 详细的配置文件说明
• 🏗️ SDK架构设计 - 系统架构说明
• 🧪 测试指南 - 测试方法和最佳实践

---

🤝 贡献指南

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

---

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

---

🎉 总结

ENN IoC SDK Generator 通过配置驱动的方式，彻底简化了IoC数据SDK的开发流程。您只需要：

1. 📊 准备JSON数据
2. ⚙️ 编写relations.yaml配置
3. 🚀 运行生成器
4. 📦 使用生成的SDK

无需手写任何实体类和Repository代码，自动获得类型安全、功能完整的企业级SDK！

💡 开始使用: python main.py --data-dir data/your_project --output-dir output

---

⬆ 返回顶部

Made with ❤️ by ENN Energy IoT Team