包结构规范
该文档主要的设计目标是商业体系前端
资源分包进行约定规范,使开发资源容易被共享和复用。
要求
在本文档中,使用的关键字会以中文+括号包含的关键字英文表示:必须(MUST)。关键字"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"被定义在rfc2119中。
规范说明约定
以下规范文档中,以${root}
表示包的根目录。
包开发说明
包定义
包
是实现某个独立功能,有复用价值的代码集。在具体的实现过程中, 必须(MUST) 按照模块和加载器规范来开发和管理模块。
模块定义
包
中的模块定义时 必须(MUST) 采用匿名iddefine( factory )
进行定义, 不允许(MUST NOT) 使用define( moduleId, factory )
。
依赖管理
包
中的模块对其他模块的依赖分成两种:内部模块依赖
和外部包依赖
。下面是关于模块依赖的管理说明:
- 对
内部模块依赖
的情况, 必须(MUST) 保证内部模块id与路径的对应关系。require依赖引用 必须(MUST) 使用relative id
, 不允许(MUST NOT) 使用top-level id
。 - 对
外部包依赖
的情况,require依赖引用 必须(MUST) 使用top-level id
。
开发时,我们通常会做一些测试用例或示例,此时需要通过AMD Loader将当前包粘合到页面环境,并使其可运行。这时我们需要遵守一些规则:
- 对
内部模块依赖
,AMD Loader配置 推荐(RECOMMENDED) 通过packages
将location
配置到${root}
下的src
目录, 不允许(MUST NOT) 通过paths
进行路径映射。 - 对
外部包依赖
,请参照项目目录结构规范将相关依赖包导入,并且 必须(MUST) 通过packages
项配置AMD Loader。
// 示例:ER package的test配置
require.config({
packages: [
{
name: 'er',
location: '../src',
main: 'main'
},
{
name: 'mini-event',
location: '../dep/mini-event/1.0.0/src',
main: 'main'
},
{
name: 'etpl',
location: '../dep/etpl/2.0.2/src',
main: 'main'
}
]
});
资源
允许(SHALL) 包含如下类型的资源:
脚本, 样式以及样式相关图片, 直接引用图片, html, 模板, 文档, 测试套件。
包描述文件
包描述文件 必须(MUST) 置于${root}
下,命名为package.json, 必须(MUST) 是一个UTF-8编码的严格JSON格式的文本文件。
必选字段
name
: 包名。 必须(MUST) 为由camel命名法产生的字母组成的字符串。version
: 版本号。版本号 必须(MUST) 为字符串,需要符合SemVer的格式约定。maintainers
: 维护者列表。该字段 必须(MUST) 是一个数组,数组中每项 必须(MUST) 包含维护者的名称字段"name"与电子邮件字段"email"。
可选字段
main
: 模块名,用来说明当前包
的入口文件。如果包名为foo
,那么执行require("foo")
的时候,返回的内容就是当前模块exports
的内容。description
: 描述信息。 必须(MUST) 为字符串。dependencies
: 依赖声明。该字段 必须(MUST) 是一个JSON Object
,其中key
为依赖的包名,value
为版本号,支持如下的格式:version
>version
>=version
<version
<=version
*
: 任意版本
devDependencies
: 类似dependencies
的角色,但不是当前包
必须的,只是在开发和调试的时候一些依赖的内容。contributors
: 贡献者列表。该字段 必须(MUST) 是一个数组,数组中每项 必须(MUST) 包含维护者的名称字段name
与电子邮件字段email
。homepage
: 该字段 必须(MUST) 为URL格式的字符串。
示例
{
"name": "zrender",
"version": "0.0.1",
"maintainers": [
{"name": "foo", "email": "foo@baidu.com"},
{"name": "bar", "email": "bar@baidu.com", "url": "http://www.baidu.com/bar"}
],
"dependencies": {
"foo": "0.0.1",
"bar": "*"
},
"devDependencies": {
"uglify-js": "*"
}
}
包目录结构
示例
${root}/
package.json
README.md
src/
css/[?]
img/
main.js
dep/
foo/
bar/
jquery/
tangram/
mustache/
...
test/
doc/
package.json
package.json
必须(MUST) 直接放在包顶层目录${root}
中。
src
按照通常的理解,一个包项目
不应该特别复杂。下面是一个简单的例子,详细的目录划分方法和原则请参考 项目目录结构规范 。
${root}/
src/
main.js
Control.js
Button.js
css/
button.css
package.json
README.md
dep
用来存放dependencies package
的代码, 不允许(MUST NOT) 放置任何其它的内容。
参考资料
如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱,如果其他用户或者作者回复了您的评论,将不能在第一时间通知您!
发布评论