docs/development/3.0-upgrade-guidelines.md
这篇教程，主要介绍Hippy 2.0升级3.0版本如何进行适配以及2.0和3.0在使用上的一些差异化。
</br>
如果业务目前使用 React 来开发 Hippy，可以参考当前章节升级指引。
</br>
如果当前 @hippy/react 版本小于 2.12.0, 且 React 使用的 16 的版本，则需要升级如下版本：
（1）删除 react-reconciler 依赖
（2）@hippy/react 升级到 3.0.2-beta 以上
（3）新增 @hippy/react-reconciler 依赖，使用react17的tag，即 @hippy/react-reconciler: react17
（4）React 版本升级到 17，即 react: "^17.0.2"
（5）如果使用了 @hippy/react-web 包做h5同构，则需要升级 @hippy/react-web 到 3.0.2-beta 以上
如果当前 @hippy/react 版本大于 2.12.0, 且 React 使用的 17 的版本，则需要升级如下版本：
（1）@hippy/react 升级到 3.0.2-beta 以上
（2）升级 @hippy/react-reconciler 依赖，使用react17的tag，即 @hippy/react-reconciler: react17
（3）如果使用了 @hippy/react-web 包做h5同构，则需要升级 @hippy/react-web 到 3.0.2-beta 以上
Hippy-React 在升级3.0可以完全兼容之前的版本，除了升级如上依赖，业务代码不需要做修改。
验证关注点：
如果业务目前使用 Vue 2.x 来开发 Hippy，可以参考当前章节升级指引。
</br>
需要升级如下版本依赖：
（1）@hippy/vue 升级到 3.0.2-beta 以上
（2）@hippy/vue-native-components 升级到 3.0.2-beta 以上
（3）@hippy/vue-router 升级到 3.0.2-beta 以上
（4）@hippy/vue-css-loader 升级到 3.0.2-beta 以上
（5）@hippy/vue-loader 升级到 3.0.2-beta 以上
（6）vue 和 vue-router等vue相关依赖无需升级
Hippy-Vue 在升级3.0可以完全兼容之前的版本，除了升级如上依赖，业务代码不需要做修改。
验证关注点：（同Hippy React）
如果业务目前使用 Vue 3.x 来开发 Hippy，可以参考当前章节升级指引。
</br>
需要升级如下版本依赖：
（1）@hippy/vue-next 升级到 3.0.2-beta 以上
（2）@hippy/vue-router-next-history 升级到 3.0.2-beta 以上
（3）@hippy/vue-css-loader 升级到 3.0.2-beta 以上
（4）vue 和 vue-router 等vue相关依赖无需升级
Hippy-Vue-Next 在升级3.0可以完全兼容之前的版本，除了升级如上依赖，业务代码不需要做修改。
验证关注点：（同Hippy React）
废弃HippyImageLoader相关实现
HippyImageLoader在2.0中作为引擎初始化必设项是不合理的，在3.0版本中由于图片数据的网络拉取和解码解耦为不同的子模块，HippyImageLoader已经被移除，图片请求会和其它所有IO相关的资源请求统一走vfs模块进行分发，网络请求vfs最终会分发到HttpAdapter完成请求的处理。
获取到图片数据后，解码模块新增加ImageDecoderAdapter可选项设置（引擎初始化时候新增imageDecoderAdapter参数设置），用于支持开发者有自定义格式图片的解码需求，ImageDecoderAdapter的具体接口描述如下：
// 解码image原始数据，解码的结果可以通过 image data holder提供的setBitmap或者setDrawable接口
// 置到holder中，如果宿主decode adapter不处理，返回false由SDK走默认解码逻辑
boolean preDecode(@NonNull byte[] data,
@Nullable Map<String, Object> initProps,
@NonNull ImageDataHolder imageHolder,
@NonNull BitmapFactory.Options options);
// 解码结束后，宿主通过该接口回调还可以获得二次处理bitmap的机会，比如要对bitmap做高斯模糊。
void afterDecode(@Nullable Map<String, Object> initProps,
@NonNull ImageDataHolder imageHolder,
@NonNull BitmapFactory.Options options);
// 引擎退出销毁时调用，释放adapter可能占用的资源
void destroyIfNeeded();
引擎初始化完成callback线程变更
2.0中initEngine初始化结果SDK内部会切换到UI线程再callback onInitialized给宿主，但我们发现在很多APP内业务反馈的使用场景下，callback切UI线程执行具有很大的延迟，所以3.0中callback onInitialized直接在子线程回调并继续执行loadModule会有更好的效率，之前2.0在callback中对hippyRootView相关的UI操作需要开发者自己来切UI线程保证。
引擎销毁
3.0中destroyModule增加了回调接口，destroyEngine需要等destroyModule执行完成回调以后才能调用，否则可能有CRASH的风险，宿主可以参考下面代码示例进行引擎销毁：
fun destroyEngine(hippyEngine: HippyEngine?, hippyRootView: ViewGroup?) {
hippyEngine?.destroyModule(hippyRootView,
Callback<Boolean> { result, e -> hippyEngine.destroyEngine() })
}
HippyEngine中的接口不再直接引用HippyRootView
destroyModule接口参数以及loadModule接口返回值均使用系统ViewGroup类型替代，尽量减少对SDK的耦合。
loadModule接口参数ModuleListener接口有所变更
引擎初始化参数增加资源请求自定义processor的设置
public List<Processor> processors;
关于vfs特性以及Processor接口使用的介绍可以详见 VFS。
关于UI Component事件发送
Hippy终端事件的发送分为全局事件和UI Component事件2种，全局事件和2.0保持一致，使用HippyEngine中暴露的sendEvent接口发送，而UI Component事件的发送可以使用在3.0新增工具类EventUtils中封装的事件发送接口:
@MainThread
public static void sendComponentEvent(@Nullable View view,
@NonNull String eventName,
@Nullable Object params);
HippyInstanceContext已经被废弃
2.0中基于系统ContextWrapper封了Hippy自己的HippyInstanceContext，并将其作为所有Hippy view的初始化参数，随着3.0 framework和renderer两个子模块的解耦，我们发现HippyInstanceContext设计过于臃肿，已经不再适用于最新的3.0架构，所以我们在最新的3.0版本中废弃了HippyInstanceContext，改用更加轻量化的NativeRenderContext取代，也就是说3.0中所有Hippy相关的view中保存的context都是NativeRenderContext类型。
HippyEngine中新增render node缓存特性接口
2.0中我们支持了dom node缓存特性，但dom node缓存针对复杂页面场景性能还是存在一定的性能瓶颈，所有我们在3.0重新实现了性能更好的render node缓存特性，关于render node缓存特性与接口使用的介绍可以详见 RenderNode Snapshot。
关于自定义UI组件的Controller中dispatchFunction参数说明 在2.0中dispatchFunction接收事件属性的参数类型为HippyArray类型，由于在2.0的后续版本中HippyMap和HippyArray就已经被标记为@Deprecated，所以在3.0的重构中，SDK内部也逐渐替换一些使用HippyMap或HippyArray类型参数的接口，所以针对Controller的dispatchFunction接口SDK内部默认替换成List类型参数
public void dispatchFunction(@NonNull T view,
@NonNull String functionName,
@NonNull List params);
public void dispatchFunction(@NonNull T view,
@NonNull String functionName,
@NonNull List params,
@NonNull Promise promise)；
为了减低3.0升级的成本原来使用HippyArray类型的接口还是保留，只是标记为@Deprecated，所以升级3.0对于原来定义的dispatchFunction接口不需要做任何修改，但建议后续升级到3.0版本的同学，定义新UI组件的时候，直接Override使用List参数类型的新接口。
从设计上，Hippy3.0尽可能保持了与Hippy2.0的兼容性。大部分Hippy2.0的自定义组件和自定义模块均可无需任何修改，兼容Hippy3.0。
同时在SDK接入API方面，Hippy3.0也尽可能保持了一致。因此，如果您未曾在业务中深度扩展Hippy内置组件或模块，升级SDK的过程将非常简单，一般情况下仅会遇到少许编译问题，甚至无需修改任何代码。
然而由于3.0的架构改进和一致性优化等原因，部分内在实现会不可避免的发生变化。如果您在业务中存在较多深度定制的自定义组件，如对ListView组件、Image组件进行了深度扩展，那将可能会遇到一些编译问题，本文将做详细说明。
改动较大的组件/模块的说明如下：
删除了HippyVirtualNode、HippyVirtualList、HippyVirtualCell等相关类和API：HippyVirtualNode在2.0中作为列表等组件的虚拟对象和数据源，其作用与HippyShadowView存在重复，因此Hippy3.0删除了这一冗余虚拟对象。
ListView组件：为支持横滑(horizontal: true)相关特性，ListView的渲染实现从UITableView切换为了UICollectionView。相应的，列表中Cell的基类也由UITableViewCell变更为了UICollectionViewCell。
Image组件source属性：由于3.0中关于image source的调用约定发生了变化（从 NSArray 类型的 source 调整为了 NSString 类型的 src），因此，如自定义了Image组件，请注意在对应的ViewManager中补充实现 src 属性，否则图片可能无法正常显示。
Image组件内置图片缓存：删除了2.0中内置的背景图片缓存管理类，即HippyBackgroundImageCacheManager，图片缓存逻辑交由业务方自行定制。