# magic-cube

**Repository Path**: salemanager/magic-cube

## Basic Information

- **Project Name**: magic-cube
- **Description**: 数据魔方，目标是做到数据自由变换。
- **Primary Language**: Java
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2021-11-08
- **Last Updated**: 2021-11-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MagicCube

#### 介绍
数据魔方，数据可以像魔方一样可以自由变换。MagicCube是一款数据处理工具，根据自定义的变换规则，从原数据结构变换为目标数据结构。数据源A到数据源A'变换，包括数据裁剪、节点重命名、结构层次调整等变换，主要为解决基于领域模型设计中数据模型的变换问题。

#### 设计思想
软件设计奉行化繁为简的基本设计思想，最大程度的剥离了具体业务对数据变换的影响。数据源A->数据源A'是一个大而复杂的逻辑，复杂度随着数据源自身量级n/m增加而倍数增加（n*m），传统的方式在解决这种量级数据变换时显得有些心有意而力不足。magic-cube打破了传统的解决思路，把数据源A->数据源A'的问题分解为数据节点n1,n2,n3...nx->n1',n2',n3',nx'的问题，由数据源问题降维为数据节点的问题。简言之，数据源是由数据节点的集合，数据源A->数据源A'，就是一系列Nx->Nx'的集合。
业务是什么？宏观层面是一个个的Story，从微观角度看，是一系列数据节点的集合，加上时间维度上数据节点值的变化。业务面对的是人，数据面对的计算机，程度员就是人与计算机的桥梁。

#### 项目结构
+ magic-cube-core
> 核心功能，定义了MagicCube的核心组件及各种辅助功能。通常只需要在Maven中依赖该包即可实现数据自由变换，但是只支持通过配置文件的方式配置变换规则。
> ##### 核心组件
>> - Filter 数据筛选
>> - Strategy  变换策略
>> - Processor  流程处理器，默认策略流程处理器。
> ##### 辅助功能
>> - 运行时组件管理
>> - 运行时上下文管理
>> - 静态资源管加载
>> - 外部资源扩展
>> - 其他辅助组件
+ magic-cube-data
> 运行时规则相关的数据库扩展。MagicCube在运行时依赖的数据资源：
> - Schedule：数据源A到目标数据源A'的详细变换计划。
> - Rule：数据节点a到a'的变换规则。
> - Code：码表C到C'的映射。
> - Trigger：动态规则触发器。
+ magic-cube-app
> 一个简单的MagicCube Example。如何配置变换规则。

#### 软件架构
##### 1.总体设计
![Magic Cube类图](./images/Magic%20Cube.png "Magic Cube类图")

##### 2.核心功能：
+ Processor 
> 流程处理器，总体控制数据变换的流程及数据在不同组件间的流转，同时根据请求的planCode把关联的资源加载到上下文中。

+ Filter
> 数据筛选器，用户可以根据需要自定义多个筛选器，运行时会根据planCode构建一个筛选器链，数据在筛选链依次流转。注意，最后一个筛选链一定是`StrategyFilter`，根据规则Rule找到指定的`Strategy`。

+ Strategy
> 变换策略，具体的数据变换规则实现。可根据自己的需要实现`RuleStrategy`接口，并在实现类加上注解`@Strategy`，并指定名称。

##### 3.辅助功能
+ ResultStrategy
> 结果处理策略，数据变换完成后，有时需要对结果做二次处理后再输出，如结果集中节点名称大小写或是首字母大写及去除空值等操作。

+ Context
> 变换运行时的上下文，包括了运行时所需要的一切资源，如组件、静态资源等。

+ ResourceLoader 
> 外部资源加载，在启动时，加载指定目录下的静态资源文件，并保存到`ResourceManager`资源管理器中。

##### 4.数据流转过程

**TODO**

#### 环境依赖

1.  java：1.8+，Maven：3.6
2.  SpringBoot：2.2.7.RELEASE
3.  开发工具IntelliJ IDEA

#### 使用说明
> MagicCube的根本原则是问题分解及降维，每一个原子问题经过`MagicFilter`数据筛选器和`RuleStrategy`变换策略后，产生期望结果，通过`ResultCollector`结果收集器汇总问题的结果，最后输出最终结果。
1.  数据筛选器
> 数据筛选器在`@Filter#conditions`中指定了触发条件，触发条件为正则表达式，匹配原数据源中数据（正则匹配数据的全路径）。数据筛选器在运行时是一条单身链表，最后一节一定是`StrategyFilter`。
> + 动态规则筛选器，实现`DynamicRuleMagicFilter`抽象类，通常用于处理原数据中带有List结构的节点，触发后会到`PlanSchedule`筛选出符合条件的Rule，并一一执行变换策略。
> + 自定义筛选器，实现`MagicFilter`接口。
> + DynamicTriggerMagicFilter，内置触发器式数据筛选器，通过外部定义触发器方式实现数据筛选，可见`DynamicTrigger`.
    
2.  变换策略
> `RuleStrategy`是数据节点A到数据节点A'的具体变换实现，如对日期的格式化，数字的格式化、值拷贝等操作，也可能是一个复杂的操作，如A'需要数据A、B、C...等通过一系列的变换过产生的结果。
> + 每个`RuleStrategy`都应该是针对某一具体问题，不建议多个问题揉合在一起。
> + `@Strategy#value`指定了变换策略的名称，这个名称应该是全局唯一，且与`RuleDescriptor#strategy`保持一致，区分大小写。
> 
3.  结果收集器
> 结果与变换策略息息相关，策略不同，产生的结果也不同，结果收集器`ResultCollector`把每个变换策略中产生的结果收集起来，整体变换结束后，输出最终结果。特别注意结果或是数据源中包含多层次List结构时，每层List下标的变化。

#### 相关API
##### 变换测试API
> 这是一个用于测试变换结果的api
- URL:`/magic-cube/json`
- RequestBody :
```
{
    "planCode":"test",//指定变换的模板，即PlanSchedule
    "sourceData":{//原数据集
        "aaaa":{
            "bbb":{
                "ccc":"6666rrrrrr",
                "number":12425546,
                "date":"2021-08-23 21:30:23"
            },
            "gg":[
                {
                    "ccc":999,
                    "code":"F",
                    "magic":[
                        {
                            "from":"Art",
                            "to":"ball"
                        },
                        {
                            "from":"second",
                            "to":"apple"
                        }
                    ]
                },{
                    "ccc":88888,
                    "code":"N",
                    "magic":[
                        {
                            "from":"one",
                            "to":"99"
                        },
                        {
                            "from":"ppppp",
                            "to":"kkllll"
                        }
                    ]
                }
            ],
            "dynamic":[
                {
                    "name":"test1",
                    "age":34
                },
                {
                    "name":"test2",
                    "age":22
                }
            ]
        }
    }
}
```

- Response:
```
{
    "result": {//结果集
        "dddd": {
            "jj": [
                {
                    "ccc": 999,
                    "code": "Fast"
                },
                {
                    "ccc": 88888,
                    "code": "North"
                }
            ],
            "mc": [
                {
                    "test": [
                        {
                            "from": "Art",
                            "to": "ball"
                        },
                        {
                            "from": "second",
                            "to": "apple"
                        }
                    ]
                },
                {
                    "test": [
                        {
                            "from": "one",
                            "to": "99"
                        },
                        {
                            "from": "ppppp",
                            "to": "kkllll"
                        }
                    ]
                }
            ]
        }
    },
    "exceptionManager": null//变换过程中哪果发生异常，此处会返回异常
}
```

- PlanSchedule配置：
[PlanSchedule](./magic-cube-app/src/main/resources/magic-cube/schedules/map-test.json "变换规则Schedule配置")
  
- 码表配置
[码表配置](magic-cube-app/src/main/resources/magic-cube/code-map/map-code.json "变换规则中相关码表映射配置")

##### 规则配置API
> 需要在项目中依赖**magic-cube-data**
+ 新增`PlanSchedule`：`/magic-cube/data/plan/save`
```
{
    "planCode":"test",//PlanSchedule唯一标识
    "version": 1.0
}
```

+ 新增变换规则`RuleDescriptor`：`/magic-cube/data/rule/save`
```
  {
      "key": "dddd#k2#date",
      "name": "date",
      "strategy": "dateFormat",
      "input": "aaaa#bbb#date",
      "format": "yyyy-MM-dd'T'HH:mm:ss"
    }
```

+ Rule与Schedule关联：`/magic-cube/data/plan/{planScheduleId}/{ruleId}`

+ 向Schedule中添加多个Rule:`/magic-cube/data/plan/{planScheduleId}`
```
[
    884122664066879488,//RuleId
    884122845231452160,
    884122953297694720,
    884123005743271936
]
```

+ 新增码表 `/magic-cube/data/code/save`
```
{
    "codeName":"test",
    "description":"test code"
}
```

+ 新增码表映射项 `/magic-cube/data/code/item/save`
```
{
    "codeId":886388386491011072,//码表ID
    "codeName": "test",
    "srcItemName": "SN",
    "srcValue": "N",
    "targetItemName": "SN2",
    "targetValue": "North"
}
```

+ 新增触发器 `/magic-cube/data/trigger/save`
```
{
    "planCode":"test",//指定PlanSchedule
    "trigger":"aaaa#gg-[\\d+]#ccc",//原数据触发器规则
    "patterns":["dddd#jj-[\\d+]#[\\w]+"]//Rule匹配规则
}
```