[回到首页](../) | [上一章：7.规模化](./7.规模化.md)

# 8.原理与API文档

* [原理剖析](#原理剖析)
    * [带路径信息的 immutable state](#带路径信息的-immutable-state)
    * [为什么要使用 immutable 数据？](#为什么要使用-immutable-数据)
    * [为什么要带路径信息？](#为什么要带路径信息)
    * [pastate imState 内部操作机制](#pastate-imstate-内部操作机制)
    * [响应式 state 镜像](#响应式-state-镜像)
    * [视图响应引擎](#视图响应引擎)
* [API 文档](#api-文档)

## 原理剖析
Pastate 的核心是一个管理不变式和响应式 state 的 pastore, 下面来详细介绍 pastore 的内容。

### 带路径信息的 immutable state
Pastore 内部使用一种独特的带路径信息且不可变（[immutable](https://en.wikipedia.org/wiki/Immutable_object)）的 state 作为应用的数据源, 挂载在 store 的 imState 属性上。在实现上，Pastore 把非空数据源都转化为**包装类型**，具体流程如下图，以 string 类型的节点为例：

![ state 包装](https://upload-images.jianshu.io/upload_images/1234637-6e7895970cc5a301.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)

其中 `__store__` 为 state 所在的 store 实例的引用，`__xpath__` 为该 state 节点在当前 store 的 state 的路径，如 `__xpath__ == '.foo.bar.baz'`。

#### 为什么要使用 immutable 数据？
Pastate 使用一种自定义的具有 immutable 特性的数据类型， 而不是 [immutable.js](http://facebook.github.io/immutable-js/) 的数据类型。 Immutable 特性指的是数据是不可变的，新的数据只能根据老的不可变数据去重新组合而成，下面举个例子：
```javascript
/** 可变数据 */
let mutableData = {
    foo: 'good',
    bar: 'very good'
}
// 可以使用直接赋值的模式去改变数据
mutableData.foo = 'so good'
newData = mutableData

/** 不可变数据 */
let immutableData = {
    foo: 'good',
    bar: 'very good'
}
// 不可修改老数据，需要根据老数据去构建新数据
newData = Object.assgin({}, immutableData, {foo: 'so good'}) // 可以使用 ES6 的 Object.assgin 函数
newData = {...immutableData, foo: 'so good'} // 也可以使用 ES7 的对象扩展符
```
immutableData 实现了两种效果：
1. 可以把 state 变化过程的每个状态保存起来，这为应用的调试带来了很多新的方法，如时间旅行调试
2. 对象内部的数据发生改变时，该对象的引用需要进行更新，这符合函数式编程的要求，可以启用 react 的 pure render ( PureComponent ) 按需快速渲染功能，使应用的性能得到极大提高

#### 为什么要带路径信息？
如果我们手动实现 immutable state 的更新逻辑，会非常麻烦，假设有这样一个 state ：
```
let state = {
    foo: {
        bar: {
            baz: {
                name: 'Peter'
            }
        }
    },
}

// 我们手动来修改 name 属性的值

// 1. 如果是 mutable data
state.foo.bar.baz.name = 'Tom'
newData = state

// 2. 如果是 immutable data 
newData = Object.assgin({}, state, 
    Object.assgin({}, state.foo, 
        Object.assgin({}, state.foo.bar, 
            Object.assgin({}, state.foo.bar.baz, {
                name: 'Tom'
            })
        )
    )
)
```
可见，在手动更新 immutble data 的深层嵌套数据时，非常麻烦！而且如果有多个相同或不同嵌套深度的 state 节点需要更改，且这些更改时在运行上连续进行的但是在代码上是封装开的，容易导致重复进行没意义的引用更新：

```
let state = {
    foo: {
        bar: {
            baz: {
                name: 'Peter'
            },
            id: '1234'
        }
    },
}

// 我们封装 name 的修改逻辑
function changeName(){
    Object.assgin..., Object.assgin..., Object.assgin..., Object.assgin...
}
// 我们封装 age 的修改逻辑
function changeAge(){
    Object.assgin..., Object.assgin..., Object.assgin...
}

function handleClick(){
    shouldChangeName && changeName()
    shouldChangeAge && changeAge() 
}
```
上面的代码，在 handleClick 的实现逻辑中，是否修改 name 或 age 是有可能单独或同时发生的，一般我们会把修改逻辑独立封装并按需调用。如果某个情况下需要连续运行 changeName 和 changeAge， 那么在 changeAge 中的 3 个 Object.assgin 是重复的，没有实际意义。

你可能会考虑使用  [immutable.js](http://facebook.github.io/immutable-js/)  库的数据结构，immutable.js 提供完善的 immutable 数据类型和操作方式支持，但在 react 项目中使用 immutable.js 有以下不足：  
- immutable.js 的数据格式与原生 JS 格式互不兼容，在渲染时，经常需要在合适的位置使用 xxx.get() 或 xxx.toJS() 获取原生 js 格式（使用 toJS() 会使**所有**子节点的引用更新，如果直接使用 fromJS(state).toJS() 只是对 state 进行 "深层复制", 不能实现用 immutable 数据来实现快速按需渲染的效果）
- immutable.js 的数据操作模式是基于"节点名称 / 节点名称数组" 来索引节点的，如`imState.setIn(['info', 'basic', 'name'], 'new Name')`，而不是用原生 JS 对象属性模式来索引节点, 如 `state.info.basic.name`。因此编辑器无法分析可选属性，也无法索引结果的类型，这使得编程起来效率低，而且比较容易出错。
- immutable.js 确实完备，但过于庞大复杂，学习成本高，许多功能在一般的实际开发中不需要使用到，对初学者不太友好。

因此，Pastate 在每个 state 节点附加了 **节点路径信息** ，并实现 state 的自动化 immutable 且**按需更新引用**的功能！让我们可以享受 immutable 数据的优势的同时，抛开使用 immutable 数据的复杂性。

### pastate imState 内部操作机制

Pastore 内部实现了一个异步操作(operation)列表，并定义了一套 operation 压入方法:
- set: 设置值 `set(imState.foo.bar, newValue)`
- merge: 合入新值 `merge(imState.foo, {bar: newValue})`
- update: 更新值 `update(imState.foo.bar, n => n+ '!')`

这三个方法会向 store 提交一个 operation, store 把收到 operation 后，暂时存在一个 operation 队列中，在下一个事件循环([event loop](https://www.youtube.com/watch?v=8aGhZQkoFbQ))时对 operation 队列进行统一处理，再批量处理中实现按需引用更新，具体流程图如下：

![operation 生成和处理流程](https://upload-images.jianshu.io/upload_images/1234637-76ab13073eeeb794.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)

在每个 operation 被 push 的前后及在 operation 被 reduce 的前后，pastate 都设计了相应的生命周期函数，你可以通过这些生命周期函数接收、过滤或控制operation，实现自定义逻辑。
- `stateWillAddOperation` 将要增加 operation 时会被调用
- `stateWillReduceOperations` 将要执行 operations 时会被调用
- `stateWillApplyOperation` 将要执行一个 operation 时会被调用
- `stateDidAppliedOperation` 执行完一个 operation 后会被调用
- `stateDidReducedOperations` 执行完 operations 时执行

详见 API文档。
 
### 响应式 state 镜像

直接使用 `set(imState.foo.bar, newValue)` 或 `merge(imState.foo, {bar: newValue})` 等来进行 immutable state 的操作虽然已经挺方便，但和我们平时修改 js 变量的模式还是不太一样，因此 pastate 为 immutable state 构建了一套响应式的镜像 state 来自动调用 set、merge、或 update 来生成 operation, 使得我们可以用赋值符号 `=` 或数组操作参数如 `push` 、`pop` 等来间接地对 immutable state 进行操作，对于处学者来说无需任何学习成本。 Pastate 内部使用 Object.defineProperty 的方式为响应式 state 节点定义相应的 getter 和 setter, 以实现通过赋值或数组函数发起 set, merge 或 update operation，对接 pastate 异步 operation 处理引擎，流程图如下:

![ 响应式流程 ](https://upload-images.jianshu.io/upload_images/1234637-d4ed31dff2368e5b.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)

### 视图响应引擎
当 pastore 完成一批 operations 的 reduce 过程时，会对外发出一个视图更新信号，通过 pastore 的 dispatch 成员函数发出。Pastate 内部实现了 pastate-redux 连接器, 默认使用 redux 作为 state 发生改变时的响应器，并由 react-redux 去连接 react 组件组件，从而实现 pastate-react。同时， pastate 使用 redux 的基本规则实现多模块逻辑，因此，你可以使用 redux 生态系统相关组件或开发工具类配合 pastate 应用，我们非常拥抱 redux 生态系统。  

另一方面，你完全可以自行实现一套视图响应逻辑, 甚至实现 pastore 与 vue 或 angular 对接，欢迎尝试。

## API 文档
- [pastore](https://github.com/BirdLeeSCUT/pastate/blob/master/dist/pastore.d.ts)
- [pastate-redux](https://github.com/BirdLeeSCUT/pastate/blob/master/dist/pastate-redux.d.ts) 
- [pastate 工具](https://github.com/BirdLeeSCUT/pastate/blob/master/dist/tools.d.ts) 
- [pastate 内置中间件](https://github.com/BirdLeeSCUT/pastate/blob/master/dist/built-in-middleware.d.ts) 
- [HOC 高阶组件](https://github.com/BirdLeeSCUT/pastate/tree/master/dist/HOC)
  - [Bind](https://github.com/BirdLeeSCUT/pastate/blob/master/dist/HOC/Bind.d.ts)
  - [Input](https://github.com/BirdLeeSCUT/pastate/blob/master/dist/HOC/Input.d.ts "Input.d.ts")
  - [Checkbox](https://github.com/BirdLeeSCUT/pastate/blob/master/dist/HOC/Checkbox.d.ts "Checkbox.d.ts")
  - [RadioGroup](https://github.com/BirdLeeSCUT/pastate/blob/master/dist/HOC/RadioGroup.d.ts "RadioGroup.d.ts")
  - [Select](https://github.com/BirdLeeSCUT/pastate/blob/master/dist/HOC/Select.d.ts "Select.d.ts")


其他相关信息，请见[最后一章](9.其他资源.md)。