尚妆前端解决方案-SPON

相关资源

spon插件列表

一点说明

针对spon@0.3.1版本及以上,强制使用yarn进行安装,原因在于更好的管理相关依赖,提供用户更为方便、快捷的工具升级方案。

yarn工具是Facebook开发的旨在替代npm的依赖管理工具,我们可以使用npm全局安装yarn。为了快速安装npm仓库中各种模块,首先需要配置npm的源镜像。

配置npm的registry

使用公司内部的npm镜像,具体配置操作请看

尚妆npm源使用方法

yarn支持

首先在本机全局安装yarn,版本号在0.16.1及以上即可

npm install -g yarn@0.16.1  

设置yarn

设置yarn仓库为公司内部仓库

yarn config set registry http://npm.showjoy.net  

如果当前的spon使用npm安装,则需要首先使用npm删除,然后再使用yarn。

sudo npm uninstall -g spon  
yarn global add spon  

如果要更新spon,则需先删除再安装

yarn global remove spon  
yarn global add spon  

安装spon

尚妆前端开发的套件名称是spon,目前同时托管在公司的npm源和团队vps上。

安装spon有两种方式:第一种采用npm安装,第二种采用源码安装。这两种安装方式本质上差别并不大,不过采用源码安装更为灵活,针对依赖的处理更为方便。当采用npm安装失败的情况下,应考虑使用源码安装。

npm命令安装spon

在nrm工具的配合下可以轻而易举的设置npm的当前registry,设置成功后执行

  sudo npm install -g spon

即可安装spon到本地。如果在安装过程中遇到错误,请联系@欲休。

源码方式安装spon

源码安装并不复杂,目前spon已集成了发布源码操作(接口并未暴露,与使用者无关),因此打包发布源码也更为便利。需要提醒的是,源码安装依赖npm命令。

第一步,获取源码。登录warehouse,可以看出所有版本的spon。选择合适源码,下载。

第二步,解压。OS X默认已有解压工具,直接双击下载的tar包解压即可。在linux下安装spon,可使用命令行:

tar -xgvf ***.tar.gz  

第三步,构建。spon源码采用make构建。

cd spon.x.x.x  
make install  

通过简单的make命令,即可“编译构建”spon。默认执行过make命令之后删除所下载的源码和tar包。

spon初始化

spon安装完成之后,可以执行命令

spon  

查看相关的命令说明。在使用具体功能之前,先初始化spon的执行环境,它会检测当前系统有没有安装node,以及copy相关的npm组件。

这一切,通过

spon init  

运行。

mobi的使用

spon初始化完成之后,我们就可以使用针对移动端开发的spon的插件-mobi了。执行

spon mobi  

可以看到相关的子命令,这些命令与尚妆前端的开发流程以及规范密不可分,在下文中会着重讲解。

mobi工程

mobi工程是spon管理的移动端工程。

在mobi工程的当前路径下可以看到一些配置文件,这些文件根据mobi工程的类型不同而不同。那么,mobi工程有哪些类型呢:

  1. page工程
  2. component工程
  3. ReactNative工程

page工程就是页面工程,对应着一个java工程。一个page工程中可以有多个页面,每个页面根据名称区分;

component工程就是一个组件,它复用可充用的逻辑,我们可以在page工程的js文件中引用它;

ReactNative工程就是一个ReactNative组件,目前并没有对其进行开发,暂且不表。

以上三种类型的mobi工程,都属于git托管的本地仓库。因此,在gitlab上必须对应一个远程仓库,根据项目的需要,在

gitlab/group:

  showjoy-assets,
  ggl-assets,
  fecomponent,
  activity

中进行创建项目,命名规则同时也需要遵循规范:

"针对尚妆的项目,根据是否移动端或者pc端,在工程名后面加后缀"-m" or "-p"。如对于交易工程,我们在组 showjoy-assets中创建trade-m的移动端工程,trade-p的pc端工程"

"针对够给力的页面工程,同理"

"针对组件工程,在gitlab的fecomponent组中进行创建工程,工程名为组件名称,并且在创建仓库时,需要确保该工程是可见的,即为public权限"

再次强调,针对component工程,必须在创建gitlab仓库时确保工程可见,即public权限,否则在构建过程中肯定会报错!!

初始化工程

该命令的作用是初始化一个工程为mobi项目。

  1. spon mb init (初始化page工程)
  2. spon mb init -c (初始化component工程)
  3. spon mb init -r (初始化RN工程)
    执行该命令,会出现一系列的交互,需要用户填入

“对应gitlab的组”,“开发者”,“相关依赖”等,

据实填写,如果有不明白的地方,请联系欲休

spon mb add

add命令仅仅针对页面工程而言,在实际的页面工程中会有多个页面的情况,因此添加第二个页面或者更多页面的情况下,需要执行

spon mb add  

命令,输入需要添加的页面的名称即可。

添加组件依赖

针对component/joyUI工程,需要

spon mb add -d jsbridge/0.0.1  
spon mb add --dependences 'tool/0.0.3 jsbridge/0.0.1'  

这种方式添加依赖

add命令只针对page和component工程

调试模式

dev命令在本地开启服务器,默认实现了livereload功能,在开发页面工程的时候可以在本地进行调试。

dev命令可以手动指定tcp端口号和livereload端口号:

 spon  mb dev -p 8080 -r 29909

dev命令只针对page工程

本地构建和测试

针对前端项目开发,采用commonJS规范,编写的格式完全按照npm模块的方式书写,这样不管在以后node模块复用还是进行后端(node端)模板渲染的情况下,更方便的迁移。但是commonJS规范是针对服务端的规范,而前端的代码都是通过网络加载,因此如果仅仅在浏览器端采用原始的commonJS肯定会出现“undefined”错误,所以,有了这步的build。当然,build并不仅仅是引入依赖,还有完成代码的相关检查,如js的书写规范,less的编译等。

本地build的作用就是将js中引用的其他模块合并到当前js的数组中,依次加载所有的依赖数组中的项即可完成依赖的加载。

命令很简单,就是执行

spon mb build  

即可。需要注意的是,在调试情况下,每次修改源码之后,都需要进行build,build之后再开启本地服务器进行浏览器端的测试。这样做的原因很简单,就是源码一旦改变,必须重新构建出新的代码进行测试,否则并没有更新。

build命令只针对page工程,对于component而言,没有必要进行构建,因为我们会在page工程中的js文件引用component,这样在page工程中构建就完全将component工程的代码引入并压缩了。

针对单一页面进行构建

spon mb build -n <name>  

可以对指定页面进行build,例子

spon pc build -n "pagename"  

页面源码搭建(新)

目前,基于组件化有了新的尝试,即JOYUI模块的探索。JOYUI模块是一种可复用的,可配置的以及未来可定制的UI模块,它仍采用fecomponent的编码规范,并加入了模板视图和数据配置,具体的JOYUI模块规范请参看JOYUI模块规范以及页面搭建

源码搭建页面最终的“聚合”仍由spon托管。开发人员需要制定对应的工程名称,进行聚合:

spon mb join -n {{name}}  

JOYUI模块调试及打包

JOYUI模块是基于CommonJS规范基础的适应于公司业务快速迭代之上的一种实现,因此无法直接在页面中使用单独的JOYUI模块。但是某些场景下为了快速产出页面需要复用一些复杂的JOYUI模块,这就需要使用打包功能。针对JOYUI模块打包,可以将打包后的相关文件(js和模板)直接使用在HTML中,一切兼容浏览器前端开发。

打包流程:

1, clone对应JOYUI工程至本地
2, 进入目录,执行

spon mb pack  

3, build目录下文件即为目标文件,同时依据dev.html文件调试模块
4, 在当前目录下执行

spon mb dev  

进行调试

测试

编写的代码不仅仅逻辑上需要打通,更需要高可靠性。所谓的单元测试往往针对后端的代码,如java的jUnit测试框架,保证接口的可靠性,以及高覆盖率。而针对前端的代码,我们也需要进行单元测试,前端的测试可以通过通过自己debug完成,但是更为规范的仍是采用测试框架来完成。目前已着手开始开发前端代码测试模块,未来可以通过spon mb test的命令完成某个模块的测试。

升级

在page工程的根目录,可以看到一个mobi.json文件,该文件作用就是记录了在初始化(spon mb init)该page工程时的所有的线上模块版本号,该文件保存在服务端。一旦有新的模块发布或者原有的模块发生改动,服务端的文件会更新,而我们当前的page工程的mobi.json并不会更新,意味着在该工程下,我们无法require新的模块。解决这种情况的方式有两种:

  1. 手动修改添加变动的模块及依赖
  2. 通过spon mb upgrade更新mobi.json

这样,完成了模块的版本控制,也实现了在原有的工程使用更新的模块。

发布

spon不在集成发布命令,具体发布方法,请看

如何进行前端资源发布

FAQ

1. 命令行spon的调用,必须在工程的根目录。

ex: gitlab上创建一个新的仓库abc,在客户端执行git clone git@git.showjoy.net:showjoy-assets/abc-m.git,会出现一个空的abc-m目录,
然后cd abc-m,在这里,就是所谓的工程的根目录。所有的命令行必须在根目录执行,否则会出现file not found等错误。

2. 组件的引用方式

require('fecomponent/mobi-${name}')  

向前兼容的规范设定,遵循即可。

3. component的修改

example:

我刚刚接到一个需求,即"针对fecomponent组的jswebview组件做一次升级:原来的jswebview中require了两个模块,即zepto-callbacks和zepto-deferred。但是由于去全局化的需要,针对mobile段的global.js做拆分,将UA判断的逻辑拿出来放在了一个新的模块下,即detect-ua组件。而jswebview组件也依赖detect-ua组件,因此我们再在代码中require(fecomponent/detect-ua),认为这样就大功告成了。这样是错误的,在构建引入jswebview组件的page工程中会出现错误,原因是找不到'fecomponent/detect-ua'组件。"

解决方案:这是由于服务端的mobi.json并没有更新jswebview组件的依赖。在初始化jswebview组件的时候,我们输入了该组件的依赖,即zepto-callbacks和zepto-deferred。服务端的mobi.json记录了这两个依赖,而当我们手动添加了另一个依赖fecomponent/detect-ua的情况下,jswebview根目录的package.json的dependencies属性并没有改变,因此服务端的mobi.json也就没有更新。所以我们仅需在根目录的package.json中添加正确格式和版本的detect-ua,在执行publish操作,就完成了服务端配置文件的更新!

4. .DS_Store文件夹(文件)造成的spon mb build失败

在使用spon mb build进行本地构建的过程中,有可能会出现错误,错误信息中提到了由于src/pages/.DSStore的存在,导致无法解析该目录的文件。.DSStore文件时Mac os中用于记录文件夹现实属性的隐藏文件,对于我们的spon而言,这个隐藏目录的存在是不必要的,因此执行 rm -rf .DS_Store命令即可。  

5. 引用带有版本号的组件

example:

仍以fecomponent/mobi-jswebview组件为例,当前最新的版本为0.0.5,暴露了$.JSBridge的相关接口;而我们的项目却依赖0.0.1版本的jswebview组件,该版本组件并没有$.JSBridge,而是$.Operate接口,此时该如何做呢?

解决方案:由于服务端的mobi.json中记录的jswebview的版本号为最新的0.0.5,因此在业务逻辑的js中以require('fecomponent/mobi-jswebview')方式引入会默认引入最新版本,可以通过附加版本号的方式 -require('fecomponent/mobi-jswebview/0.0.1')引入制定版本号的模块,引入的格式一定要规范!

6. spon版本升级到0.1.2后build之前创建的工程出错

解决方案:是由于版本升级后,对根目录下spon.json做了些扩展。为了保证build旧工程成功,请在根目录下重新执行spon mb init,更新spon.json配置文件即可。

7. fecomponent模块进阶

回顾:

之前针对组件的开发,主要逻辑都在index.js文件中,而且针对有css(less)引用的组件无能为力。为了保证软件工程中的“单一功能”作用,我们可以将单一的功能拆分成诸多功能模块,放在某个文件夹下,如lib,而在index.js中以相对路径方式引用,这样在组件内部解耦,容易分工开发组件。具体的复杂组件编写模式,可以查看线上实例:fecomponent/mobi-withcss

要点:关于在组件中以引用css(less)和模块,必须以相对路径方式引用,即“./sth.less”的方式。

8. 异步渲染模板的功能

针对移动端,目前h5页面并为采用模版异步渲染的机制,这对于开发长列表展示页的性能很不友好。现在在page工程中,集成了模板功能,模板的书写语法就是大家在用的art-template简单语法,这样每次build之后我们就可以在页面上看到引用的模板。

在spon中,规定模板的后缀为.tmpl,也就是说spon会对src目录下的所有.tmpl文件进行解析,并生成对应的js文件。建议每个目录下只有一个tmpl文件,这样做到模板的模块化。 在js中,可以这样引用模板:

showjoy模板:

<h1>{{title}}</h1>  
<p>{{titleDesc}}</p>  
var tmpl = require('./showjoy');  
$('main').html(tmpl({
  title: 'this is the art-template example',
  titleDesc: 'nothing to say!'
}));

9. spon开发活动页面

营销页面目前没有统一的远程仓库地址,在本地执行spon mb init命令创建工程时会出现错误。正确方式是先去gitlab的activity组中创建一个仓库并clone下来。本地进入这个仓库就可执行spon mb init命令创建工程。

10. rem布局规范

spon的rem插件,请看使用spon方便的完成rem布局开发

11. pc端工具链打通

命令一览:

  spon pc init (-c);
  spon pc add;
  spon pc build
  spon pc dev -p 8888 -l 12334;
  spon pc upgrade;

12. spon的发布,spon插件和别名服务

请看 spon插件规范及别名使用

13. spon commit(cmt)替代git commit

目前公司制定了提交信息的规范,为了支持该需求,spon也进行了升级。

使用方法仍然同git commit类似,不过每次提交使用

spon commit(cmt)  

命令,而放弃“git commit -m '内容'”的格式。因此,完整的提交流程如下: git add . spon cmt //第一次提交,根据提示撰写相应格式的内容

git add . spon cmt //第二次提交

git add . spon cmt //第三次提交

通过这样的方式,更加规范化和制度化提交内容!另外,十分建议大家在修改了一个新的bug或者在开发中遇到的比较特殊的问题后,在采用spon cmt提交中写上一些心得(在“提交详情”中写),为后来人也为自己做个记录!

CHANGELOG

  • v0.1.3 添加了版本号引用组件;
  • v0.1.4 增加模版渲染引擎,针对src/pages下的所有.tmpl文件进行预编译 可创建ui组件,并相对路径引用模块
  • v0.1.5 针对src下的less文件进行watcher,方便开发时调试样式
  • v0.1.6 针对尚未重构的showjoy-assets/portal 工程添加发布功能
  • v0.1.7 针对pages工程,添加了src/components中的模块引用线上组件的功能 内部实现了线上组件缓存功能
  • v0.1.8 针对fecomponent组件中的less,可以循环引用,即less中可通过@import递归加载
  • v0.1.9 完成部分重构,集成rem插件(待修改,做过渡使用,建议不要采用该版本的rem插件)
  • v0.1.10 丰富了rem插件,集成许多复杂功能
  • v0.1.11 修改了rem插件的小问题,并完美适配当前前端切图规范(在使用rem插件时,必须修改引用的flexibal.js,使用新的布局脚本)
  • v0.1.12(不要使用该版本,作为过渡) bug修复,task顺序重新调整
  • v0.1.13 bug修复
  • v0.1.14 pc端工具链打通,针对pc端的操作和mobile端对应
  • v0.2.0 spon彻底重构,添加插件选项,并且配置别名服务,另外,该版本下的发布publish操作默认取消了build选项,这意味着每次发布之前需要手动进行构建page工程,不要疏忽! 另外,spon插件规范及别名使用!!!
  • v0.2.1 添加相关依赖
  • v0.2.2 解决模块解析遗留问题(注释删除)
  • v0.2.3 解决js解析时的AST构建问题(注释模块)
  • v0.2.4 增加维护者“南洋”
  • v0.2.5 增加对指定页面进行build工程
  • v0.2.6 针对rem插件做了diff对比,目前仍在测试阶段,欢迎找bug 修改重构后的遗留问题,spon主目录创建问题
  • v0.2.7 1、添加js,less文件代码规范检查 2、更新新添加page时的初始html文件
  • v0.2.8 修改 eslint.json 配置文件,放宽规则限制
  • v0.2.9 添加 eslint的依赖
  • v0.2.10 lint规则放宽 sourceMap链接错误解决 spon commit(cmt)集成,规范化提交内容 spon性能优化,采用懒加载 tty输出信息优化
  • v0.2.11 该版本发布时同时发布了两个XSS检测组件,欢迎大家使用 修复了模板编译产生临时文件的bug 修复了因存在隐藏文件导致构建失败的隐藏问题
  • v0.2.12 修复less编译的似有前缀消失的问题,该版本之后可以在less中只写原属性,不用再写其他的私有头部,如“-webkit-,-ms-”
  • v0.2.13 修复less文件watcher编译的似有前缀问题
  • v0.2.14 针对组件初始化添加README.md spon插件安装使用npm,放弃原先的cnpm 针对page工程,初始化img文件夹,用于存放开发过程中的图片 放松eslint的规范限定 修复加载spon插件出现“加载插件失败,请检查插件目录”文字的错误
  • v0.2.15 eslint.json语法修改
  • v0.2.16 rem插件重新实现,放弃diff算法,直接正则匹配
  • v0.2.17 删除初始化安装操作 修复sj-conventional-changelog包
  • v0.2.18 插件系统兼容npm@3.x.x
  • v0.2.19 集成MidProxy工程套件、React工程套件和JOYUI套件
  • v0.2.20 添加pack,join功能
  • v0.2.21 修复webpack配置文件加载依赖路径出错 优化JOYUI开发流程 错误日志后台化,记录至log.showjoy.net
  • v0.2.22 修复npm3.x.x下插件无法更新(升级) rem插件使用规范更新,增加配置和源码声明(/@norem/)两种转换方式
  • v0.2.23 rem操作集成至构建序列
  • v0.2.24 修改rem转换的配置方式(在less文件中,放弃使用rem.json文件)
  • v0.3.1 强制使用yarn管理依赖,安装性能大大提升 组件加载策略升级,放弃之前低效、费时且版本号依赖处理不完善的方案,性能提升 修复线上日志记录系统 修改全局依赖引用路径,编码方式更为简单通用

欲休

继续阅读此作者的更多文章

海创园尚妆