D2Server汇集了许多实用的模块,而且这些模块只要进行一些简单的配置,就可以帮你节约许多时间。同时,D2Server也针对外部模块进行了一些功能性地拓展,让他们更好地服务于前端开发工作。


如果你还不了解D2Server,请先查看说明文档,判断D2Server是否你所需要的。

如果你还不知道如何使用D2Server,请先阅读我们的快速部署教程

通过DataAPI,可以很方便的地组织动态数据,配合wget,自动将线上资源缓存到本地,尽可能地节约开发者时间。

DataAPI的配置放置在每个项目MainConfigFile文件中,对应的配置参数为DataAPI,在ProjConfigFile中定义无效。

针对每个接口数据的配置信息,存放在项目的DynamicDataFile文件中,以JSON的格式保存。


参数配置

DataAPI的配置方案,经历了3次大重写,我们力求用最简单的入口控制实现他的功能。从最开始的直接使用function进行流程控制,到现在的JSON格式,定义几个参数就可以完成功能的配置,我们希望能让大家看到我们的进步。

项目配置文件中的DataAPI参数主要定义如何从请求地址中,获取所需要的参数,来拼接临时文件名;以及定义wget所需的参数。

如果你希望关闭DataAPI功能,直接设置参数值为false即可。

// 项目配置文件 DataAPI参数的配置
{
	"hostname": undefined,		// 定义wget从何处下载数据
	"port": undefined,		// 定义wget下载数据时使用的端口
	"update": true,			// 是否使用wget下载最新的数据
	"excludeQuery": [],		// 拼接缓存文件名时,忽略这些参数
	"defaultMime": "text/plain",	// 在没指明文件类型的情况下,默认的mime返回值
	"formatQueryName": "format"	// 根据这个请求参数来定义文件拓展名
}

针对每个接口数据,可以配置mime extname wait参数(后续会增加更多可以自定义的参数)。

这些参数一般都是继承DataAPI配置中的默认值,同时也会根据wget请求结果做调整。

  • mime:指明数据返回给浏览器的mime信息
  • extname:指明文件保存的格式
  • wait:设置返回值的延迟时间

文件管理

DataAPI的数据文件,都保存在DynamicDataPath目录下。

具体数据文件以请求路径+文件名 / 请求参数组成的文件名的路径进行保存,保证所有数据文件均有一层且只有一层文件夹。

针对wget自动下载的数据文件,文件名会加上[CACHE]的前缀(注:用户修改过的数据文件,请删除[CACHE]前缀,防止被覆盖)。


wget

通过wget可以很方便地下载线上资源到本地,但目前尚未提供相应的调用接口,同时不支持https的请求

如果有你许多文件需要下载,又希望能保持线上的目录结构,那么你可以访问http://test.com:81/download。将你需要下载的文件列表填入文本框中(以换行分割),提交之后,D2Server会自动将文件下载到指定的项目文件夹中。

是否设想过,将开发的页面中的CSS样式命名也进行压缩呢,让源码显得更加简单。国外很多网站都开始做这一块的优化,例如Gmail;国内知乎等也在做这一块的尝试。而现在,你只要通过D2Server管理项目,就可以很方便地将这一特性运用于生产中。

MinCssName的配置放置在每个项目所有项目的配置中,对应的配置参数为MinCssName

如果需要关闭MinCssName功能,可以直接在MainConfigFile配置文件设置参数值为false

  • 配置参数类型的为JSONMainConfigFile配置文件的参数也可以设置成true),格式是原样式名前缀(不带"."或则"#")=>替换之后的前缀名。
  • CSS样式命名的压缩操作已经整合到export导出过程中,无需执行其他额外的命令。
  • 使用MinCssName必须遵循预设的CSS前缀命名规则,样式或则id必须以前缀开头,后跟大写字母开头的样式命名。
    D2Server检索HTML、CSS、JS代码,并以字符串的形式进行替换。所以,在其他方面,请不要使用样式前缀来命名HTML标签、JS函数以及变量等,也不要使用固有的变量来定义原样式名前缀。

项目开发少不了团队协作,通常我们也会使用SVN、Git这些快速有效的文件管理工具来管理我们的开发项目。但如果因为使用D2Server而导致MainConfigFile成了文件冲突的重灾区,这是我们所不愿看到的。为此,D2Server有ExtraConfigFile这样一个专门的模块,将MainConfigFile分割,可以为每个成员创建独自占有的配置文件。

ExtraConfigFile的配置放置在每个项目MainConfigFile文件中,对应的配置参数为extra,在ProjConfigFile中定义无效。

  • extra的格式为数组,保存内容为子配置文件的路径,路径相对于MainConfigFile文件所在目录。
  • extra中定义的顺序,将影响配置文件的合并顺序,直接表现为FileMap上,会影响js css等文件的合并顺序。
  • (经验)将共用的配置信息写入MainConfigFile配置文件,而针对成员各自分配的页面配置信息,写到每个人的ProjConfigFile子配置文件,然后通过MainConfigFileextra进行子配置文件的整合。

HTML是D2Server最基础的两个模块之一。HTML模块主要是负责为开发文件中的HTML文件,创建访问路径,配置相关EJS参数;在项目文件管理上,主要是将单个HTML开发文件依据EJS的逻辑,拆分成多个导出文件。

HTML的配置放置在每个项目所有项目的配置中,对应的配置参数为HTML

HTML模块的操作,除了EJS的语法之外,其他的内容都体现在项目配置的属性设置上。


参数配置

(示例)项目配置文件中HTML的配置如下(涵盖所有用户可定义参数)

{
	"HTML": {
		"header": "common/header1.html",		// 自动引入的header文件1
		"footer": "common/footer1.html",		// 自动引入的footer文件1
		"index/index.html": {
			"extJS": ["/mjs1.js"],				// 页面需要额外引入的JS文件路径1
			"extCSS": ["/mcss1.css", "/mless1.less"],	// 页面需要额外引入的CSS文件路径1
			"header": "common/header2.html",		// 自动引入的header文件2
			"footer": "common/footer2.html",		// 自动引入的footer文件2
			'index.html': {
				"extJS": ["/mjs2.js"],				// 页面需要额外引入的JS文件路径2
				"extCSS": ["/mcss2.css", "/mless2.less"],	// 页面需要额外引入的CSS文件路径2
				"header": "common/header3.html",		// 自动引入的header文件3
				"footer": "common/footer3.html",		// 自动引入的footer文件3
				"title": "D2Server",
				"block": "index",
				"data": {					// 在这里定义EJS的参数
					"param1": "value1",
					"param2": "value2",
				}
			},
			"somepage.html": {
				"title": "xxxx",				// 页面标题
				"block": "some some2"				// block参数
			}
		},

		"page/page.html": {				// 该路径相对于.source目录,是开发文件的路径
			"mypage.html": {			// 该路径相对于项目根目录,是导出文件(浏览器访问)路径
				"footer": false,			// 定义false,则取消引入footer文件
				"title": "NAME"
			}
		},

		// 最简单的配置
		"page/page2.html": {
			"mypage2.html": {}
		}
	}
}

配置参数结构说明
  • HTML的配置参数分成三层,分别是:开发文件路径=>浏览器访问及导出路径=>页面配置参数。
  • 在这三层中,均可以定义header footer变量,后两层还可以定义extJS extCSS变量。定义变量所在的层数越大,变量权重越高。
  • 为了更好的管理子配置文件中HTMLheader footer 的定义,在MainConfigFile配置文件中,可以设置defaultHeader defaultFooter参数。
    这两个参数,会被所有的子配置文件继承;这两个参数处于最外层,所以权重也最低;在ProjConfigFile中定义无效。
  • 使用header footer定义HTML的头部,不需要在HTML文件中再使用EJS的include去读取文件,D2Server会自动将头部和尾部内容包含到正文的开头和结尾。
  • 传递给EJS的变量,除了用户自定义的参数之后,还会附加一些系统参数,详见EJS的变量
  • block参数与EJS拓展语法中的block 密切相关;以空格间隔定义多个block

FileMap是D2Server最基础的两个模块之一。FileMap模块在DevServ中,是将原始的访问路径进行拆分的数据来源;在SpliceServer中,将分散在各个文件夹中的开发文件进行整合拼接输出。

FileMap的配置放置在每个项目所有项目的配置中,对应的配置参数为FileMap

FileMap在进行子配置文件属性拼接时,受extra定义的子配置文件顺序影响,详情见ExtraConfigFile

  • DevServ中,D2Server会将JS CSS LESS的源文件路径拆分成许多子路径;其他文件类型,则直接进行字节流的合并。
  • fileMap中,资源文件名以.test结尾(不包含文件拓展名)的文件,不会合并到最终文件中。
  • 为更好组织文件,请避免使用.m+数字的后缀命名资源文件。

Catalog模块主要是在浏览器访问路径和项目文件存储之间建立对应关系过程中,缩减目录结构。简单的理解,就是一个超级简单的伪静态规则。

具体是怎么一个效果呢?

如果MainConfigFile中定义catelog参数为“mySite/”(在ProjConfigFile中定义无效),那么在浏览器中请求“/mySite/js/jq.min.js”文件,实际对应项目“/js/jq.min.js”文件。

CSS、JS代码能很好的复用,那么在开发HTML的时候,能不能实现代码的重用呢?

PHP版的D2Server,我们自己写了一个类似于PHPTAL的模版引擎;换成NodeJS重写之后,为了更好地兼容后台模版引擎,我们选择更加主流的标签语法。而在模版引擎的选择上,我们使用当前NodeJS中的成熟型代表——EJS。

EJS的标签语法非常普及,标志性符号是<% %>(可在Server的conf.js中更改开始结束标签)。具体的EJS标签语法见Github项目说明。


模版参数

使用D2Server,可以很方便地定义变量赋值给EJS。定义变量通过在项目配置文件HTML参数的data进行赋值。

除了用户自定义的变量外,D2Server还会附加sys root两个变量给EJS。

  • sys包含Server运行过程中的一些状态属性,包括title extJS extCSS href catalog srcFile outFile block htmlVirtualFileDirname projConf可以引用这些变量,但不要修改值,避免出现未知错误。
  • root参数是对data变量的引用,方便在EJS中做变量定义情况的判断。

语法拓展

EJS的语法相当灵活,但却不适合进行一些日常开发。为了更好地处理工作中的零碎日常。我们又对EJS进行了定制化的标签语法封装。

block标签语法

block顾名思义,就是将HTML代码碎片化。通过block可以定义一个代码块,然后根据HTML配置中的block参数进行页面是否需要这一块代码的判断。

定义block非常简单,只要完成一个闭合标签即可。

<% block block命名 %>
<!-- ...HTML代码片段... -->
<% endBlock %>

loop标签语法

loop顾名思义,就是循环其中内容。通过loop可以定义一个用于循环的代码块,从而解放copy,HTML代码也更加简明。

定义loop也只需要一个闭合标签。

<% loop times( : timeVar 可选) %>
<!-- ...HTML代码片段... -->
<% endLoop %>

关于LESS不想多说什么,工作中已经离不开他,LESS包含到D2Server也是情理之中的事。

如果你还不知道如何使用LESS处理你的CSS代码,请访问LESS中文


BEM命名规则

如果写CSS是一门技术活,那么给CSS命名则是一项艺术创作工作。很多时候,我们不是在纠结CSS效果怎么写,而是在苦恼到底如何命名才能做到CSS之间不冲突,而又能尽可能多地实现样式的复用。

BEM在众多CSS命名规范中,通用性和灵活性都非常赞,使用BEM之后,HTML代码结构也变得非常清晰容易理解。但BEM有一个非常严重的弊端,按照标准版的写法产生出来的CSS命名会异常的长,这就导致编写过程中,需要频繁地进行复制黏贴。

还不了解BEM的童鞋可以阅读这篇文章《BEM思想之彻底弄清BEM语法》

为了更好享受BEM的便捷之处,D2Server针对LESS文件的编译进行了优化。所有以.__ .--开头的样式,会自动和前面的样式名合并,形成一个符合BEM命名的样式。

例如

.ex_main {
	.__lt {
		float: left;
	}
	.__gt {
		float: right;
	}
	.__tag {
		border-bottom: 1px solid #ccc;
		.--ed {
			border-color: #333;
		}
	}
}

上面的代码经过D2Server处理之后的结果如下:

.ex_main__lt {
  float: left;
}
.ex_main__gt {
  float: right;
}
.ex_main__tag {
  border-bottom: 1px solid #ccc;
}
.ex_main__tag--ed {
  border-color: #333;
}

使用BEM命名规则来规范书写CSS的习惯,再使用D2Server的MinCssName对CSS命名进行压缩。


BaseLess

在进行项目开发过程中,难免会遇到一些变量或则函数需要全局共享,可惜LESS没有带这个功能,所以D2Server又来插一脚了。

在项目的MainConfigFile配置文件中,通过baseLess参数来定义全局的LESS文件。

注意:全局LESS文件的内容,在编译的时候会累加到所有LESS文件的头部,所以请不要定义会输出具体CSS代码的LESS语句。

D2Server在6月份之前,还是自己写着玩的一个项目,一些功能由于测试的项目有限,可能还存在问题,欢迎在使用后给我们反馈

D2Server的功能相对而言比较杂。项目也只是业余爱好,测试和开发时间并不怎么宽裕,请关注更新记录,部分更新会存在不能向下兼容的问题。

我们也在积极开发更多方便D2er工作和使用的功能模块,你可以在TODO List找到我们的开发计划。 也欢迎在Github上Fork D2Server项目,让我们一起把D2Server做得更好。


关于JavaScript的编译器CoffeeScript为什么没有包含进D2Server

CoffeeScript的确对简写JS代码做出了不可抹灭的功勋,以至于1.85版的JavaScript标准中,也可以看到CoffeeScript的影子。但CoffeeScript在国内貌似非常非常的不普及,也在MDN看到一些反对的声音,毕竟JavaScript也不是脚本语言。

Designed by @mdo and @fat. Built by Bacra.

Code licensed under Apache License v2.0 , documentation under CC BY 3.0.