Skip to content

Latest commit

 

History

History
393 lines (249 loc) · 8.96 KB

项目设计文档规范.md

File metadata and controls

393 lines (249 loc) · 8.96 KB
Raw

项目设计文档规范

时间 版本 内容 修改人
2020/05/20 1.0.0 首次编写 史守峰

前言

设计文档规范必须遵循以下规则：

  • 设计文档必须使用 Markdown语法编写
  • 设计文档必须将模块设计大致思想、如何实现、及拓展性、可维护性等阐述清楚。
  • 复杂的业务、功能或流程。请使用流程图、设计类图、核心方法或插入少量代码进行辅助理解
  • 设计公共模块或基础服务时、请编写使用章节辅助开发者进行使用。
  • 将所依赖的模块或SDK描述清楚
  • 模块或功能开发完成后、如与设计文档不符需完善设计文档。

设计文档编写步骤

以下是编写设计文档的步骤。请按照以下步骤进行编写、遵循设计规范和流程。

注：以下规范按照文档顺序进行排版。

我是文档标题

// 1. 文档标题使用 一级标签 #

// 2. 使用表格列举文档维护时间

时间 版本 内容 修改人
2019/10/20 1.0.0 首次编写 史守峰

// 3. 使用Markdown语法生成简易目录

[TOC]

// 4. 使用二级标签 ## 列举需求要求

注：章节内部如何划分请自主选择、但务必简洁清晰、表述准确。

例：

需求

需求概述

一个标签支持 多种样式 例：list-age 类型标签既可以显示在 list-red 位置 或 wiki-3 位置 或 list-age 位置

需求文档位置

/18.V1.x.1/input/产品需求/内容服务_V1.x.x

项目版本

V6.6.1

修改范围

主页面

// 4. 使用二级标签 ## 列举设计部分章节

注：按照具体的项目设计章节进行划分并加以描述

// 例：以xxx设计文档为例

设计

根据产品需求特性特设计出动态化布局框架和策略。

具体策略如下：

概述

// 注：可以此处简明扼要的表述设计的原理和相关概念等。

设计思想

// 注：请在此章节阐述设计的思想或使用的设计模式、原理等

// 例：

动态化布局需要达到以下要求：

  • 结构尽量扁平化
  • 异步布局渲染流程，解放主线程计算量；
  • 回收与复用组件，减少内存开销

使用到的设计模式：

  • 使用观察者模式 解决事件交互和传递问题
  • 使用模板设计模式+桥接设计模式 完成内部绑定器设计
  • 使用原型设计模式 解决回收资源和清除数据问题
  • 使用建造者设计模式 解决框架传参和管理问题

设计流程图：

设计内容

// 注：以下是设计文档的正文，也是设计文档的核心。根据各自设计文档的内容进行划分具体章节进行描述即可

设计正文部分遵循以下规则：

  • 复杂的业务或使用章节 可以插入少量代码示例。
  • 复杂的流程需按步骤进行讲解。

XXX初始化

例：略

参数组织

例：略

参数校验

例：略

数据整理

例：略

绑定RootLayer层

// 例：

rootLayer 层是时光集制作的根view，所以需要首先进行布局，Z 值为 0

rootLayer Json 数据如下：

"rootLayer": {
			"level": 0,
			"backgroundColor": "#FFF",
			"image": {
				"imageUrl": "http://gw.szytest.com/FsiVY9r3e51em3VZMl4nseLWyKoZ",
				"width": 110,
				"height": 111
			},
			"width": 2000,
			"height": 3000
		}

项目中对应 Java 对象时 MRootLayer, 绑定rootlayer 需要经过一下步骤：

  1. 创建View绑定器。继承 AbstractBindLayer<T, V extends View, R extends AbstractRefresh> 类实现 IViewDataLayer<T,V> onBindDataLayer(T t) 绑定方法。
  2. 创建要绑定的具体View。并实现 IViewDataLayer<T,V> 接口，并实现其内部方法
  3. 调用 IBinderLayer<T,V extends View> 接口中 V onBindLayer(T t) 方法返回绑定的具体View
  4. 将具体View添加至 View 承接类中。AbstractMakePageView 类中定义了添加view的具体方法

示例代码：

// 创建绑定器
mRootLayerBinder = new RootBindLayer(mContext);
mRootLayerBinder.setOriginScale(mOriginScale);
// 开始绑定
MRootLayerView rootLayerView = mRootLayerBinder.onBindLayer(rootLayer);
// 添加rootView 到具体view上
mPageView.addRootLayerView(rootLayerView);

绑定子View Layer层

子view Layer 层包含以下类型:

文字
多媒体
音频

View绑定器

view绑定器部分设计使用 模板设计模式 + 桥接设计模式 的混合

一共共分为一下步骤：

绑定器接口

绑定器接口是 数据绑定到 view 上的抽象定义，抽取公共业务和数据到接口层次，内部定义了view绑定的公共业务逻辑，子类必须实现其公共方法才能实现view绑定。

public interface IBinderLayer<T,V extends View> extends IRecyclerListener {
    /**
     *
     * 绑定数据到 layer 层
     *
     *
     * @param t 数据
     * @return  具体View
     */
     V onBindLayer(T t);
     
    /**
     *
     * 将view layer层中数据转换成 具体数据
     *
     *
     * @return T
     */
     T onViewToData();
}
绑定器抽象层实现

绑定器的抽象层实现是基于 IBinderLayer 接口的进一步实现和具体封装。内部默认实现了 其公共方法并提供了其默认实现。内部定义了 IViewDataLayer<T,V> 接口封装了具体 桥接的实现和模型。

public abstract class AbstractBindLayer<T, V extends View, R extends AbstractRefresh> implements IBinderLayer<T, V>, IRefreshBinderLayer<R> {
    
    /**view layer 层 数据转换接口*/
    private IViewDataLayer<T,V> mViewDataLayer;
    protected AbstractBindExtra mBindExtra;
    /**原始缩放比例*/
    private float mOriginScale = 1.0f;
    
    /**页面类型*/
    @MPageType
    protected int mPageType;
    
    public void setBindExtraData(AbstractBindExtra bindExtra){
        this.mBindExtra = bindExtra;
    }

    private void setViewDataLayer(IViewDataLayer<T,V> mViewDataLayer) {
        this.mViewDataLayer = mViewDataLayer;
    }
    protected IViewDataLayer<T,V> getViewDataLayer() {
        return mViewDataLayer;
    }
    /**
     *
     * 将数据绑定到 指定 view layer 层上
     *
     * 本类是 {@link IBinderLayer} 接口默认实现类、本类提供了实现view绑定的基本方式
     * 抽象层实现了绑定数据的基本方法、所以子类不允许复写本方法。
     *
     * 子类可实现 {@link AbstractBindLayer#onBindDataLayer(T)}已实现数据绑定
     *
     *
     * @param t 数据
     * @return V 具体view
     */
    @Override
    public final V onBindLayer(T t) {
        // step 1: 绑定view
        IViewDataLayer<T,V> v = onBindDataLayer(t);
        // step 2: 将 view 层接口绑定到抽象数据绑定层
        setViewDataLayer(v);
        // step 3: 返回绑定的具体view
        return v == null ? null : v.getBindView();
    }
    /**
     *
     * 绑定数据到 具体 view layer 层上
     *
     * @param t 具体数据
     * @return View
     */
    protected abstract IViewDataLayer<T,V> onBindDataLayer(T t);
    /**
     *
     *
     * 将view 层数据转换成 具体数据
     *
     * 注：
     * 1.抽象层定义了基本的实现逻辑、子类无特殊需求可以不进行复写
     * 2.若子类复写此方法需主动回调 抽象层
     *
     * @return T
     */
    @CallSuper
    @Override
    public T onViewToData() {
        return getViewDataLayer().onViewLayerToData();
    }
    /**
     *
     * 回收资源
     *
     * 抽象层定义了基本的实现逻辑、子类无特殊需求可以不进行复写
     *
     * @throws Exception 主动抛出异常等
     */
    @CallSuper
    @Override
    public void onRecycler() throws Exception {
        RecyclerUtils.recycler(mViewDataLayer);
        RecyclerUtils.recycler(this.mBindExtra);
        mBindExtra = null;
        mContext = null;
    }

子类需实现 IViewDataLayer<T,V> onBindDataLayer(T t) 方法实现绑定逻辑。

绑定器实现类图

制作管理类

例： 略

特殊场景处理

// 5. 特殊场景处理 在做设计时需要考虑以下情况并做好相应正确处理

注：特殊场景列举了 设计中必须要要考虑的项目中一些特殊场景如：

App端

网络环境处理

  • WiFi 和 移动网络切换
  • 无网络处理
  • 网络请求超时

.....

网络环境处理

  • WiFi 和 移动网络切换
  • 无网络处理
  • 网络请求超时

.....

参考

// 6. 参考章节 列举在做设计过程中参考的 文档、blog、或者相关设计 等在此处列举可以方便后续查找。

例：

参考： 天猫动态化布局解决方案 http://pingguohe.net/2017/12/07/Tangram-2.html

附录：

本文列举做设计所使用的工具等