Hello spm：使用 spm 和 SeaJS 开发一个中型项目

来源：https://github.com/spmjs/spm/wiki/Hello-spm%EF%BC%9A%E4%BD%BF%E7%94%A8-spm-%E5%92%8C-SeaJS-%E5%BC%80%E5%8F%91%E4%B8%80%E4%B8%AA%E4%B8%AD%E5%9E%8B%E9%A1%B9%E7%9B%AE

现在我们要正儿八经开始开发一个叫 hello-spm 的项目了，别笑，虽然只是个为了让你更好的了解 SPM 而杜撰出来的项目，但也五脏俱全。

我们提供了在线演示：http://fool2fish.github.com/hello-spm 。毫不犹豫的猛击空格键，就会有有趣的事情发生了。

你可以检出源码：https://github.com/spmjs/hello-spm 。

在正式开始之前，我还是要啰嗦一句，所有的范例代码都是基于 SeaJS 的，请确保你已经知道该怎么使用 SeaJS 了。

创建项目目录

我们先来看看项目的整体结构

hello-spm/
	assets/
		hello/
		util/
		sea-modules/
		package.json
	index.html

考虑到真实的项目通常包含前后端的代码，所有前端代码放在 assets/ 。
hello 和 util 是为本项目编写的模块。
sea-modules/ 用于存放安装和部署的模块。如果你的项目基本都是基于 SeaJS 和 SPM 的，你可以把这个目录放置在和项目目录平级的路径下，以便各项目公用。
package.json 为模块打包部署的总体配置。
index.html 为项目页面。

安装需要的模块

显然，我们需要用到 seajs 和 jquery，所以要使用 spm install 来安装他们。

打开命令行工具，将路径切换至 sea-modules/ ，运行：

spm install seajs
spm install gallery.jquery@1.8.3

这时你会发现 sea-module/ 中多了 seajs 和 jquery 两个模块。其中 seajs 为最新版本，而 jquery 则是我们安装时指定的 1.8.3 版本。其中 jquery 目前的 root 是 gallery，所以会增加一个 gallery 目录。

创建模块

回想一下 index.html 运行的效果，多处用到了随机数，例如 "hello spm !" 的单个字符大小，字符串出现在页面中的位置以及字符串在页面上停留的时间。

我们把这样一个可产生指定范围的随机整数的工具方法放到 util 模块中。

下面我们来 初始化 这个模块。

命令行工具路径切换至 util/ ，运行：

spm init

spm 会在 util/ 中创建以下文件：

util/
	examples/
	src/
	tests/
	package.json
	README.md

其中：

examples/ 用于存放演示文件。
src/ 为模块源码，打包后的文件会存放到和 src/ 平级的 dist/ 目录下。
test/ 用于存放测试用例，你可以使用 jasmine 等工具来保障代码的质量。
package.json 为本模块打包部署的配置。

我们的 hello-spm 实在有点简单，所以演示代码仅保留了 src/ 和 package.json 这两个必备部分。

src/ 中只有 util.js 一个文件，源码非常简单，如下：

define(function(require, exports) {
    exports.random = function(min, max){
        return min + Math.round(Math.random() * (max - min))
    }
})

拆分子模块

接下来我们处理相对复杂一些的 hello 模块，他要做这么几件事情：

创建字符大小随机的 "Hello SPM !" 字符串。
随机显示到页面上。
一段时间后自动消失。

这个模块复杂到需要拆分成多个子模块来进行开发 (好吧，我承认这纯粹是教程需要)。

命令行工具路径切换至 hello/ ，运行：

spm init

使用 spm init 初始化后，在 src/ 中除了默认创建的 hello.js，还需要手工创建一个 handle-text.js 文件。

hello.js 完成大部分的主体功能，而 handle-text.js 专门负责处理传入字符串的随机字符大小。

hello.js 的源码如下：

define(function(require, exports, module) {
    var $ = require('$')
    var random = require('util').random
    var handleText= require('./handle-text')

    function Hello(){
        this.render()
        this.bindAction()
        seajs.log('new Hello() called.')
    }

    Hello.prototype.render = function(){
        this.el = $('<div style="position:fixed;' 
            + 'left:' + random(0,70) + '%;'
            + 'top:' + random(10,80)+ '%;">'
            + handleText('Hello SPM !')
            + '</div>').appendTo('body')
    }

    Hello.prototype.bindAction = function(){
        var el = this.el
        setTimeout(function(){ el.fadeOut() }, random(500,5000))
    }

    module.exports = Hello
})

注意：

var random = require('util').random 是模块方法的引用。
var handleText= require('./handle-text') 是子模块的引用。
在 Hello 类的构造器中，我们还使用 seajs.log 打了一句日志。

更多 require 的说明可查看 SeaJS 的模块标识

handle-text.js 的源码如下：

define(function(require, exports, module) {
    var $ = require('$')
    var random = require('util').random

    function handleText(text){
        var min = random(30,70)
        var max = random(50,120)
        var rt = ''
        for(var i = 0, len = text.length; i < len; i++){
            rt += '<span style="font-size:' + random(min, max) + 'px;">' + text[i] + '</span>'
        }
        return rt
    }

    module.exports = handleText
})

编写开发时页面

开发过程中，我们就常常需要编写一些测试用例，或者演示页面。

这种情况下我们希望模块是不需要打包的，并且可以查看日志，以便调试。

本例中，我们并没有为单个模块创建单元测试或者演示页面。简单起见，我们在 index.html 页面中编写了一些开发时的代码，代码如下：

<div style="text-align:center;font-size:48px;color:#999;"> Press the space key !</div>
<script src="assets/sea-modules/seajs/1.3.0/sea-debug.js"></script>
<script>
    seajs.config({
        alias:{
            '$':'gallery/jquery/1.8.3/jquery.js',
            'util':'http://www.cnblogs.com/util/src/util.js'
        }
    })
    seajs.use(['$','./assets/hello/src/hello.js'],function($, Hello){
         $(document).keypress(function(ev){
            if(ev.which == 32){
                new Hello()
            }
        })
    })
</script>

注意：

引用 sea-debug.js，可以开启 debug 功能。
jquery（即 $ ）作为 DOM 操作最常使用的模块，总是需要通过 seajs.config 手工配置别名，确保项目内的统一。比如 1.8.3 版本。
seajs.use 中的 '$' 为顶级模块标识，相对于 seajs 的 base 路径, './assets/hello/src/hello.js' 为相对标识，相对于当前页面 url。

现在运行 index.html 就能看到效果了，源码上做任何的改动也能立马体现，打开调试工具，你还能看到打出的 log。

打包部署

打包配置

结束编码测试工作后，我们就要准备将模块打包部署，以供正式环境使用了。打包相关的配置都写在每个模块的 package.json 中了。

先来看看 util 模块的 package.json

{
    "name":"util",
    "parent":"../package.json",
    "output":{"util.js":"."}
}

name 为模块名
parent 指定用于继承的父级配置，路径相对于该配置文件。当你项目中的模块有大量公共配置的时候推荐使用此项.
output 指定了将 src/util.js 及其模块内的依赖打包为 dist/util.js 。当然，这里 src/util.js 没有模块内依赖。

再接着看 hello 模块的 package.json

{
    "name":"hello",
    "parent":"../package.json",
    "output":{"hello.js":"."},
    "dependencies": {
        "$": "$",
        "util":"hellospm/util/0.0.1/util"
    }
}

然后我们还有一个 parent package.json

{
    "root": "hellospm",
    "version": "0.0.1"
}

其中由于我们 hello 和 util 模块的 root 和 version 是一样的，我们就可以把他放到 parent 的配置中。

绝大部分和 util 模块的配置一样，只是多了一项 dependencies，需要注意的是：

jquery 作为一个特殊的模块，打包的时候并不指定具体的依赖，仅写上 "$": "$" 即可。

回顾一下，就是因为这个原因，我们在刚刚创建的 index-debug.html 中，还需要为 jquery 配置别名： '$':'gallery/jquery/1.8.3/jquery.js' 。

接下来我们将以 util 模块为例讲解模块的打包部署（hello 模块的打包部署方式完全一样）。

打包

命令行进入到 util/ ，运行：

spm build

SPM 会在 util/dist/ 目录创建 util.js 和 util-debug.js 两个文件。有兴趣的读者可以打开 util-debug.js 看看打包后的文件和源码有何不同。

部署

为了方便演示，我们准备把打包好的模块部署到本地。

进入 util/ ，运行命令：

spm deploy --to=../sea-modules

这时 sea-modules/ 会新增 util 模块：

sea-modules/
    hellospm/
	    util/
		0.0.1/
		    util.js
		    util-debug.js
	...

编写正式页面

胜利就在眼前，我们终于要完成这个项目了。现在我们要把测试用的 index.html 转换成线上正式运行的 index.html，代码如下：

<div style="text-align:center;font-size:48px;color:#999;"> Press the space key !</div>
<script src="assets/sea-modules/seajs/1.3.0/sea.js"></script>
<script>
    seajs.config({
        alias:{
            '$':'gallery/jquery/1.8.3/jquery.js'
        }
    })
    seajs.use(['$','./assets/sea-modules/hellospm/hello/0.0.1/hello.js'],function($, Hello){
         $(document).keypress(function(ev){
            if(ev.which == 32){
                new Hello()
            }
        })
    })
</script>

注意 index.html 前后的一些区别：

index 引用的是 sea.js。
SPM 在对模块进行打包部署后，依赖关系已经处理好了，所以这里我们只用在 seajs.config 中配置 jquery($) 。

结束语

如果你耐心的看到这，那么恭喜你！现在你已经很了解 SeaJS 和 SPM 最常用的功能了。接下来，赶紧去自己的工作中去实践一把吧，有任何建议和反馈欢迎反馈给我们：）