【PMS】开发文档

设计与编码

一、代码管理

• 远程仓库地址是：
  xxxx

• 代码规范与建议

  • 安装SwiftLint，全程按照Swift推荐的设计规范约束代码。
  • 使用//MARK: - 对代码进行分割，常用的有UI、Event、各种Delegate、LifeCycle（生命周期）、Data、Other。带横杠有分割线，不带横杠没有分割线
  • 使用//TODO: 对未完成或存疑的功能进行标记，加上名字日期等标注就更好了
  • 合理使用extension给控制器和功能强大的工具类瘦身
  • 在循环引用的闭包中，使用[weak self]避免循环引用
  • 合理使用///三斜杠进行文档注释
  • 合理使用iflet和guardlet进行可选值或条件判断
  • 合理使用fileprivate、private、internal、public、open、final等权限关键字，对方法、变量的作用域进行控制，详见参考文档
  • 尽量少用三方库，用的话尽量使用cocoapods；目前pod部分未在git中忽略
  • 图片资源以模块划分目录，如图片较多可根据模块的子功能继续划分，使用R.image设置图片，好处是在编译时可以检查图片名是否存在
  • 尽量避免在模块中使用字面量，适当抽取到配置文件中。目前的通知名在NotificationName（扩展），接口名在ApiFile中（结构体），域名在NetWorkFile中，业务常用的枚举等在VariableDefineFile中（枚举、全局变量等）

• 命名规范

  • 以优雅，简练，易读为原则。
  • 使用驼峰，避免使用拼音，文件名避免使用下划线，图片资源可适当使用下划线。
  • 控制器后缀为VC，视图后缀为View，实体类模型后缀为Model，工具类后缀可以是Util、Tool、Manager
  • 不需要固定前缀
  • Class、Struct、Enum、全局变量、文件名首字母大写，其他首字母小写，变量名可酌情使用汉字

二、分支与版本控制

• branch：
  • master：稳定的主分支，在开发分支稳定后可合并到此分支
  • dev：日常的开发分支，可以在此分支直接进行arc操作，也可以分出特性分支
  • release：最新发布的版本在此分支。
  • 其他特性分支：使用arc feature xxx创建xxx分支，用来开发特定的功能或者修复bug
• tag：

为里程碑打上标签，比如版本上线：

git tag -a v1.4 -m ‘version 1.4 completed’

查看所有标签：

git tag

把本地标签推送到远程服务器：

git push origin --tags

三、项目文件架构

• App：AppDelegate、Assets、Info、LaunchScreen、语言桥接文件等应用级别的文件
• Common：公共配置文件
• Frame：容器，如TabbarVC、NavigationVC等
• BaseClasses：基类，目前包括BaseVC、BaseModel、BaseTableView、BaseTableVC、BaseWebVC、BasePageVC、BaseFormVC、BaseSearchVC
• NetWorkFile：接口主机地址和网络相关的配置项
• NotificationName：通知名
• VariableDefineFile：常用的常量或方法，目前包括屏幕尺寸、机型信息、颜色和字体（详见第八条）、某些字符串（包括文案、图片名、三方配置、偏好设置键名、URL）
• OCUtils：OC中使用的工具和宏定义等
• Utils：好用的工具们，比如一些扩展、实现特定功能的工具类
• QHUtil：最常用的工具，包含持久存储、格式判断、日期转化、控件创建、图片处理、字符串处理、获取当前控制器、显示和隐藏HUD等功能，还能继续加功能，记得归类。
• Modules：业务模块
• ContactBook：通讯录
• Message：消息
• Project：项目/线索
• WorkBench：工作台
• Enterprise: 企业
• Task：任务
• LoginRegister：登录注册
• Profile：个人中心
• Lib：不方便使用pod但是好用的三方库

四、文件创建与基类

• 所有控制器继承BaseVC，其中集成了空白页、导航栏样式、系统弹窗等功能，供子类实现的方法有拦截返回按钮、刷新失败页、配置UI、设置状态栏样式等
• 所有实体类继承BaseModel，直接添加字段即可
• 所有网页控制器继承BaseWebVC，其中集成了页面加载HUD提示、显示JS弹窗功能，提供了通过URL和Title创建的便利构造方法
• BaseTableVC：仅供常规的列表页面使用，其中较深入地集成了上下拉刷新加载、智能分页请求、列表数据处理、通用空白页。如需要更多或不同的功能，可继承它或者使用BaseVC
• BaseTableView：仅供参考，目前只提供了一些通用属性
• BaseFormVC：表单控制器的基类，继承于BaseTableVC，详见文档

五、图片

• 设置本地图片（例如图片在Assets中的名字是more）

let image = R.image.more()

• 设置网络图片

imageView.kf_setImage(urlString: "http://image")

• 设置头像网络图片

//此方法内置了不同性别下的头像占位图片
imageView.kf_setHeaderImage(urlString: "http://image", sex: 0)

• 压缩图片大小

QHUtil.compressOriginalImage

六、网络请求

• QHNetwork：管理网络请求，处理通用的异常情况
• QHNetWorkTool：管理业务层的网络请求，处理公用数据，比如用HUD显示异常情况下的信息
• 返回数据为数组时，将会赋值到result中的array，我们用mj解析它，示例代码如下：

        let param:Params = [
            "id":335,
            "code":3423,
            "content":"方式防守打法"
        ]
        QHNetworkTool.share.requestWith(Method: .get, Api: Api.Module.root, Param: param, showHud: false) { result in
            if result.finish {
                if let dataArray = result.array {
                    let modelArray = XXXXModel.mj_objectArray(withKeyValuesArray:  dataArray) as! [XXXXModel]
                    //use modelArray
                }
            }
        }

• 返回数据为对象时，将会赋值到result中的data，我们用mj解析它，示例代码如下：

        QHNetworkTool.share.requestWith(Method: .post, Api: Api.Module.root Param: param) { result in
            if result.finish {
                if let data = result.data {
                    let model = XXXXModel.mj_object(withKeyValues: data)
                    //use model
                }
            }
        }

七、页面布局

以自动布局为主，根据情况也可以使用frame或者xib。

• 自动布局
  使用SnapKit，用法类似Masonry

view.snp.makeConstraints { (make) in
     make.left.equalTo(3)
     make.top.equalTo(view2.snp.bottom).offset(66)
}

• Frame
  除了直接使用frame或bound属性，也可以使用在UIViewExtension中实现的设置单一属性
• xib

一些布局简单的控制器（如登录注册）或UITableViewCell、UICollectionViewCell或者普通的UIView都可以使用xib，

• 控制器不需要做任何处理
  • cell在awakeFromNib()方法中实现布局，在相应控制器中使用registernib方法即可
  • UIView的子类，默认不能在创建时同时添加xib文件，可以在创建swift文件后，创建同名的xib文件，然后在xib中修改它的File’s Owner为已创建的view类名，然后在代码中，添加如下方法

    override init(frame: CGRect) {
        super.init(frame: frame)
        
        contentView = loadXib()
        addSubview(contentView)
    }
    func loadXib() ->UIView {
        let className = type(of:self)
        let bundle = Bundle(for:className)
        let name = NSStringFromClass(className).components(separatedBy: ".").last
        let nib = UINib(nibName: name!, bundle: bundle)
        let view = nib.instantiate(withOwner: self, options: nil).first as! UIView
        
        return view
    }

• 常用的常量
  • 屏幕宽度和高度分别使用ScreenWidth和ScreenHeight
  • 底部菜单栏高度使用TabBarHeight
  • 状态栏高度使用StatusBarHeight
  • 导航栏（不含状态栏）高度使用NavBarHeight
  • 状态栏加导航栏高度使用StatusNavBarHeight
  • 尺寸比例使用H_multiple作为系数

八、字体与颜色

常用的字体和颜色都配置在VariableDefineFile.swift中

• 字体使用示例
  FONT(16)：系统字体（苹方）的16号尺寸，根据屏幕宽度的比例计算
  BOLDFONT(18, NoMultiple: true)：系统加粗字体（苹方）的18号尺寸，无视屏幕宽度比例，就是18个pt
• 颜色使用规范
  TEXT_COLOR：常用的文字黑色
  TEXT_GRAY_COLOR：常用的文字灰色
  BACKGROUND_COLOR：常用的背景灰色
  SEPARATOR_COLOR：常用的分割线颜色
  THEME_COLOR：常用的主题颜色

测试与发布

• 使用EditScheme-Archive切换编译模式，以匹配NetWorkFile中的接口主机地址

学习与参考

EventKit框架的应用
腾讯云IM
private等权限关键字的区别
Swift中Struct和Class的区别
贴一段Json转成Model代码
Eureka快速表单的用法
SwiftLint——代码规范工具
R.swift使用

产品文档