longjiarun/react-learn

react learn

hap脚手架

技术说明

目录

0. build 构建后的目录，遵循自动化发布目录规范。

   • pages 页面存放目录，只存放页面文件；
   • static 静态资源文件，包含css、js，图片等资源；

1. mock 数据模拟目录。

   存放*.json文件，为了方便切换环境，子目录保持与后端接口目录一致；

   访问目录为/mock/**/* ，不需要json后缀；

2. src 源码存放目录。

   • component 组件目录。在hap中只有组件的概念，没有模块的概念。组件包含了该功能完整的js、image，css等。；

   • lib 库目录。存放第三方库或者项目中可抽离出来的公共组件，利用bower进行管理；

   • pages 页面目录。存放所有页面，包含该页面需要使用的js、image、css，模板等；

页面

0. 页面模板引擎使用ejs，支持include功能；

1. 静态资源可配置成直接嵌入到页面中，语法可参照usemin，开发模式下不做处理；

2. 发布之前会采用htmlmin压缩处理，同时会压缩页面中嵌入的js与css；

js

0. js 模块支持 commonjs 规范与 es6 规范；

1. 利用webpack处理js；

2. 可使用react框架，默认useReact为false，设置为true可开启使用；

3. 模板引擎使用ejs，支持预编译处理；

4. 基础类库未做限制，可根据项目不同选型不同；

5. 组件中的js文件存放在组件目录下，确保一个组件目录有完整的资源文件；

6. 页面中的js文件存放在页面目录下，如该页面依赖其他组件，在页面js文件中需引入组件js；

7. 发布之前文件会压缩处理，压缩工具采用uglify；

css

0. css 预处理采用less；

1. 支持 import css 合并到文件中，可参照postcss-import；

2. 采用 autoprefixer 后处理；

3. 组件中的样式文件存放在组件目录下，确保一个组件目录有完整的资源文件；

4. 页面中的样式文件存放在页面目录下，如该页面依赖其他组件，在页面样式文件中需引入组件样式；

5. 发布之前文件会压缩处理，压缩工具采用postcss-clean；

图片

0. 组件的图片存放在相应组件目录下，页面图片存放在页面目录下，保持组件与组件、页面与页面相对独立；

1. 小图片建议采用base64处理，使用less的data-uri函数；

2. 在js中引用图片，hap对图片大小做了限制（默认8kb），小于8kb采用base64嵌入。可修改maxImageSize属性配置大小；

3. 大图片建议先上传到cdn，图片引用路径使用绝对路径；

4. png与jpg图片可采用tinypng优化处理；

5. hap采用spritesmith提供合并图片功能，可参考hap.config.js配置中的sprite参数；

静态资源版本管理

0. 版本管理默认采用路径版本管理，每次发布会生成一个唯一的hash字符串，所以每次发布所有资源路径会被替换；

1. 修改hash为true可配置成文件hash，但图片建议采用绝对路径（由于存在图片路径写法不一致，会存在图片路径替换不正确问题）；

适配方案，建议flex + rem + media query，可根据项目情况选型。

0. 采用flex解决弹性布局问题；

1. 采用rem结合media query解决间距与字体尺寸问题（字体根据项目需要决定采用rem或者px）；

2. 此方案会存在1px问题；

3. media query由media.less配置；

replace功能

0. 可动态替换html、js，css中的变量，用于修改资源路径，接口等，可参考hap.config.js配置中的replace参数；

concat功能

0. 支持合并js、css，less文件，newline属性可配置文件拼接符；

1. 对于js文件进行压缩处理；

2. 对于css文件进行autoprefixer及压缩处理；

3. 对于less文件进行预编译、autoprefixer及压缩处理；

代码校验

0. 代码文件编辑规范可参照.editorconfig；

1. 增加 eslint 与 csslint 代码校验，暂未强制使用。可使用 npm run eslint 与 npm run csslint 查看结果。

项目管理与发布

0. 采用git作为版本管理工具；

1. 项目版本开发规范遵循团队相关规范；

2. 发布采用自动化发布；

版本

0. 遵循语义化版本规范；

1. master分支为最新的稳定的发布版本；

2. tags中的分支对应每一个发布版本；

3. 其余分支为开发分支，为不稳定版本；

利用generator-hap 搭建与更新脚手架

0. 全局安装yo 与 generator-hap;

   sudo npm install -g yo
   
   sudo npm install -g generator-hap
   

1. 新建项目目录（project_name）；

   mkdir project_name
   
   cd project_name
   
   

2. 利用yo安装脚手架；

   //安装脚手架
   yo hap;
   
   //更新脚手架，忽略 npm install & bower install
   yo hap --update;
   
   //查看参数配置
   yo hap -h;
   

3. 添加本项目版本管理配置；

4. 修改 hap.config.js 配置文件中项目名称（name）、版本（version），服务器端口（port）等参数；

5. [可跳过]如果自动化安装依赖失败，可手动安装npm依赖包；

   npm install
   

6. [可跳过]如果自动化安装依赖失败，可手动安装bower依赖包

   bower install
   

7. 启动server；

   npm start
   

8. 新开终端选项卡，运行开发模式；

   npm run dev
   

访问

0. 绑定host 127.0.0.1 --> h5-dev.weidian.com；

1. 运行 npm start 启动服务；

2. 运行 npm run dev 开启开发模式；

3. 访问首页 http://h5-dev.weidian.com:3001/index.html ；

相关命令

由于环境不一样，生成的静态资源路径以及对静态资源的处理方式不一致，所以存在开发（0）、测试（1）、预发（2），线上环境（3）等开发命令。可运行命名查看各环境的处理方式。

遵循的原则是：1、开发环境性能优先。2、测试环境的处理方式与预发环境保持与线上环境一致。

0. 安装依赖包

   npm install
   

1. 启动server。为了避免端口冲突，可修改hap.config.js中port属性配置

   npm start
   

2. 开发模式

   npm run dev
   

3. 开发模式，模拟测试环境接口

   npm run dev-daily
   

4. 开发模式，模拟预发环境接口

   npm run dev-pre
   

5. 开发模式，模拟线上环境接口

   npm run dev-prod
   

6. 开发模式，模拟测试环境，压缩代码与模拟接口

   npm run mock-daily
   

7. 开发模式，模拟预发环境，压缩代码与模拟接口

   npm run mock-pre
   

8. 开发模式，模拟线上环境，压缩代码与模拟接口

   npm run mock-prod
   

9. 测试环境

   npm run daily
   

10. 预发环境

    npm run pre
    

11. 线上环境

    npm run prod
    

自动化生成文档

API文档采用 Docker 生成。语法可参照文档。

0. 安装 Docker；

   sudo npm install -g docker
   

1. 运行命令；

   //生成文档
   docker -i src -o documents -x lib,*.css,*.html,*.less
   
   //监听并生成文档
   docker -i src -o documents -x lib,*.css,*.html,*.less -w
   

待解决的问题

0. 嵌套模板无法进行压缩；

1. gulefile.js 与 hap.server.js 隐藏；

   后续 hap 脚手架将只提供 npm 包，使用 npm run scripts 执行构建命令；

最后

0. hap脚手架将持续更新与维护，任何bug或者建议可反馈给我；

1. test代码只是为了演示与说明，可删除；