Skip to content

whole

Jump to bottom Edit New page
aloysious edited this page Nov 8, 2013 · 13 revisions

概述

本页介绍视频前端团队的标准开发环境搭建和开发流程方法。我们的前端js库为KISSY，我们采用yeoman+grunt完成项目的目录结构生成和构建，整合flex-combo搭建轻量级的前端combo服务器，并基于git进行代码的管理和发布。我们的愿景是提供一个易上手、自动化、可扩展的前端开发流程，让你只在代码中畅游。

开发环境搭建

开发环境依赖于node、npm、git。必须保证你所处的系统环境中预装了这些工具包。

工具安装

首先安装yeoman和grunt：

    sudo npm install yo grunt-cli -g

然后安装generator-clam：

    sudo npm install generator-clam generator-kissy-gallery -g

generator-clam是由淘宝北京前端团队开发的一个公共的KISSY项目构建工具，其自定义了标准的KISSY项目结构代码生成器，整合了相关的grunt插件，提供前端开发脚手架功能。视频团队的构建工具作为一个分支，依附于generator-clam。

基本命令

generator-clam本身提供了众多的命令，我们只需要关注与视频项目相关的命令：

  • yo clam:video，初始化一个标准的视频项目，生成其目录结构
  • yo clam:page，初始化一个page的目录结构
  • yo clam:mod，初始化一个业务模块（对应于视频项目里的一个widget）的目录结构
  • yo clam:widget，初始化一个标准KISSY组件的目录结构，需首先创建组件空目录，再进入空目录后执行该命令
  • yo clam:h，打印帮助

初始化完成的项目中包含了Gruntfile.js脚本文件，对外提供以下功能：

  • grunt info，查看当前库的git地址
  • grunt setbranch:x.y.z，修改配置文件中的版本号为x.y.z
  • grunt server或grunt server:dev，开启开发模式的前端服务器
  • grunt server:stage，开启生产模式的前端服务器
  • grunt build，进行项目构建

以上的基本命令此处只做罗列，具体的使用场景参见后续内容。

项目目录结构

一个标准的视频前端项目结构应该如下：

├── project root
    ├── Gruntfile.js     // grunt的构建脚本
    ├── abc.json         // 存放项目的基本信息
    ├── package.json     // 存放node的依赖关系配置
    ├── README.md        // 项目说明文档
    ├── docs             // 存放生成项目API文档
    ├── node_modules     // 存放项目的node模块
    └── src              // 项目源文件目录
        ├── config.js    // kissy配置文件
        ├── mod.js       // 模块依赖关系文件
        ├── page         // 存放demo页面和入口文件，可执行`yo clam:page`生成一个page
        ├── mock         // 存放假数据接口
        ├── service      // 存放封装好的ajax调用接口
        ├── widget       // 存放页面级别的业务模块，可执行`yo clam:mod`生成一个widget
        ├── util         // 存放应用级别的可重用组件，可执行`yo clam:widget`生成一个util
        └── lib          // 存放第三方的组件
    └── build            // 项目构建目录，目录结构与src保持一致

初始化项目

我们接管一个项目主要有两种场景：开发原有的项目、开发新项目。

  • 开发原有的项目，需要从gitlab上克隆项目的主干代码，然后执行npm install安装依赖的node包，便可以进入项目的开发。

  • 开发新项目，首先在本地创建项目空目录，进入目录后执行yo clam:video，初始化的界面如下：

    init project

    完成初始化配置后，会在项目目录下生成标准的项目结构。如果在项目初始化阶段没有安装node包，请手动执行npm install。

开发约定

开发过程中有一些约定需要注意：

  • 原则上不能随意修改项目目录结构
  • page、mock、service、widget、util、lib这些目录下的文件结构可以自己组织，但强烈建议使用generator-clam的基本命令来生成标准的结构
  • 请遵循KISSY模块化规范编写项目的js模块和组件，应避免模块和组件的匿名定义
  • 请使用less编写样式文件
  • 所有的demo页面对静态资源文件的引用地址必须为线上的绝对地址，带-min
  • mod.js文件应由构建脚本自动生成
  • build目录下的文件只能通过构建阶段自动生成，原则上只包含线上访问的-min文件及其源文件

前端服务器

项目中的grunt构建脚本封装了flex-combo，提供一种最基本的前端服务，即将线上CDN环境映射到本地目录，同时对资源文件进行动态combo。我们提供两种模式的前端服务器：开发模式和生产模式。其中开发模式用于开发阶段的demo展示和功能调试，使用频率较高。生产模式则用于线上问题的快速debug。请先绑定host127.0.0.1 g.tbcdn.cn。

  • 执行grunt server或grunt server:dev（linux下需加sudo），开启开发模式的前端服务，默认端口为80（请在abc.json中自行修改）。此时对线上资源的访问会映射到本地src目录下对应的源文件，并且开启KISSY的combo功能。如果在访问地址上带上?ks-debug则会关闭combo功能。

  • 执行grunt server:stage（linux下需加sudo），开启生产模式的前端服务。此时对线上资源的访问会映射到本地build目录下对应的文件，并且开启KISSY的combo功能。如要需要快速debug，请在访问地址上带上?ks-debug，将线上的-min文件映射到build目录下的源文件，同时关闭combo功能。此时在src目录下的对应文件打断点，可以自动同步到build目录，实现快速debug。

项目构建

通过grunt build执行项目构建。我们约定的构建流程是：把src目录下的less文件解析为css文件；拷贝src目录下所有的js、css文件到build目录下的对应路径，并对文件进行压缩。build目录下的js、css文件保留一份源文件和一份-min文件，线上直接访问-min文件。

代码管理和发布

项目代码的管理和发布与淘系大前端的方向保持一致，我们同时维护三套环境的代码：

  • gitlab（用于存放源代码和本版控制）
  • 日常环境g.assets.daily.taobao.net（测试阶段的CDN环境）
  • 生产环境g.tbcdn.cn（线上的CDN环境）

通过gitlab提供的接口，我们可以方便地对三个环境的代码进行版本控制和非覆盖发布，具体可参考前端Assets发布体系优化方案 workflow

代码管理

  • 每一个项目的代码在git仓库中都隶属于一个group，比如视频前端的group名为video

  • 如果是开发全新的项目，需在gitlab对应的group下新建项目的仓库。

  • 如果是开发原有的项目，需要先抓取项目在gitlab上的主干（master）代码：

      git clone git@gitlab.alibaba-inc.com:video/projectName.git
  git pull origin master

  • 每一个开发周期(通常指从开发开始到上线的一次日常）都必须从主干上拉分支进行开发，并确保开发阶段只对该分支进行修改。分支的命名规则为daily/x.y.z，x、y、z为数字，且版本号（x.y.z）必须大于线上最新版本号：

      git checkout -b daily/x.y.z

    注意，每次递增新分支后，请务必执行一次grunt setbranch:x.y.z，以修改配置文件中的分支号

  • 开发阶段记住时刻提交你的代码到gitlab中：

      git add .
  git commit
  git push origin daily/x.y.z

    此时，gitlab会把build目录下的文件自动同步到日常环境下。

线上发布

  • 发布前先构建项目grunt build

  • 假设要发布的版本号为x.y.z，请先确保gitlab中存在分支daily/x.y.z，并且x.y.z大于线上最新的版本号

  • 打标，然后把代码发布到线上环境，打标的命名规则为publish/x.y.z：

      git tag publish/x.y.z
  git push origin publish/x.y.z

    此时gitlab会自动把分支daily/x.y.z合并到主干，并删除该分支，从而确保主干与线上最新代码保持一致。

前端host绑定

在整个开发阶段我们可能要在本地开发环境、日常环境、线上环境中来回切换。保证所有页面中的静态资源文件引用线上的绝对地址，加上host绑定，可以帮助我们实现环境的快速切换：

  • 本地开发环境，127.0.0.1 g.tbcdn.cn
  • 日常环境，10.235.136.37 g.tbcdn.cn
  • 线上环境，无需绑定host

（TODO）扩展阅读

  • KISSY模块化规范
  • 实用的grunt插件列表，可以根据项目实际需求扩展你的grunt构建脚本
  • 如何开发grunt插件，如果社区里所有的插件都满足不了你的需求，请猛戳这里
  • generator-clam
  • flex-combo

TODO list

  • 整理扩展阅读的内容
  • 扩充h5项目的开发流程（重点在调试）
  • grunt插件：图片自动压缩和上传，动态合并html（抽取css至头部，整合模块js入口到页面级别的js入口）

Change log

  • 2013-11-08, 第一版
Add a custom footer
Add a custom sidebar

Clone this wiki locally