clam

Clam 是什么

Clam是一套基于 Node.js 的前端工程项目开发环境。

Clam内部集成了本地开发服务器、前端模块化开发管理、打包和发布管理等功能。Clam志在为前端工程师提供更简单和一致的项目开发体验。

Clam 的安装

安装Clam最简单的方式是通过 Node.js 提供的包管理工具npm来安装：

npm -g install clam

# Mac 和 Linux 环境下可能需要 sudo 权限
# 注意：Windows 平台下请使用原生命令行环境，不要在 Cygwin 下安装。

开始使用 Clam

Clam的使用非常简单，首先我们需要新建一个空的项目目录，例如hello_clam：

mkdir hello_clam
cd hello_clam

然后在此目录下执行Clam的项目初始化命令：

clam init

这条命令会在项目目录下生成一套标准的Clam项目目录结构：

hello_clam
    - build
    - src
        - pages
        - mods
        - widgets
    - tests
    - .clam
        - project.json

其中，src目录用来开发/维护项目源文件，包括页面模板、样式、脚本、图片资源等；tests目录用来存放测试脚本；build目录用来存放Clam打包发布上线的项目目标文件；.clam隐藏目录是Clam用来维护一些元信息的地方，此目录下的project.json文件是该项目的一些配置信息。稍候我们可以通过Clam提供的 GUI 界面或直接更改此文件来配置项目环境。

项目开发阶段我们的核心工作目录是src。

src的目录结构对应了Clam提供的一套标准的前端模块化开发的项目结构。拿一个最简单也最常见的场景：

• 我们要开发一个页面hello_clam.html
• 这个页面需要一份样式文件hello_clam.css
• 还需要两份脚本文件hello_clam_a.js和hello_clam_b.js

我们需要做的只是在hello_clam.html文件里以相对路径引入这些样式和脚本文件，然后把所有文件都丢到pages目录即可。

OK，非常好，现在除了一堆乱七八糟的目录和配置文件外，使用Clam开发跟我直接在硬盘上建个文件夹没任何区别。别骂人先，现在Clam提供给了我们第一个最不起眼的功能：

Clam打包功能提供了一致的发布路径

它试图解决的问题是：我们在开发阶段往往使用相对路径较为方便，但是再交给后端工程师书写模板或发布上线时，必须将相对路径改为线上路径。当项目变的庞杂的时候，这是个很繁琐的工作。在Clam里我们可以通过一个简单的配置项cdnPath来完成这个工作：

# 通过更改项目配置文件 .clam/project.json 配置 cdnPath
"cdnPath": "http://yourcdn.com/yourproject"

# 注意：结尾不要附加斜杠

也可以通过Clam提供的 GUI 管理界面来配置：

clam ui     // 开启 GUI 配置管理界面

# 注意：可能需要 sudo 权限
# >> 此命令会在浏览器里打开 Clam 的 GUI 配置管理界面，修改里面的 cdnPath 项即可。

保存配置后，我们就可以在src工作目录下使用相对路径开发，完成后执行Clam打包命令，Clam将在build目录下生成包含绝对路径的模板文件。除此之外，在项目的打包阶段Clam又为我们提供了第二个贴心的功能：

Clam提供了一致的线上版本管理

为了避免覆盖线上文件，我们经常采取的方式是在开发时升级目录或文件版本号。这样做的弊端是时间一长我们的代码库里同一个文件或目录可能有几十个新老不同的版本，给代码维护和版本控制带来极大不便。而Clam打包工具给我们提供了方便的发布版本管理支持：

# Clam 打包
clam build project v0.0.1

# >> 此命令会在项目的 build 目录生成一个名为 v0.0.1 的目录
# >> 并将所有打包后的文件放置到此目录下

通过这种机制我们既可以保持代码仓库里src目录的干净整洁，又实现了发布版本控制。

至此我们就使用Clam走完了一个最基本的前端项目的开发流程。当然，这还远不能符合一个苦逼前端工程师对一把趁手工具的期待。好在Clam还为我们提供了这些功能：

• 本地资源文件代理（支持combo功能）
• 接口模拟
• 模块化开发管理
• 打包和发布管理
• 嗯，还有一个专为不喜欢命令行操作的工程师打造的 GUI 配置管理界面

我们可以根据需要选择感兴趣的功能点做详细了解。

Clam 本地文件代理

Clam 本地文件代理提供了一个方便我们调试测试或线上环境问题的机制。其工作原理很简单，当我们需要调试一个测试或线上页面如hello_clam.html时，首先我们找到该页面所属的项目hello_clam。确保我们已经配置了项目的cdnPath，并将文件服务器域名指向本机：

# 在 hosts 文件中将文件服务器指向本机
127.0.0.1 yourcdn.com

然后开启或切换到此项目的 Clam 环境：

cd hello_clam
clam on

此时再访问 hello_clam.html 页面时，Clam 内置的本地服务器会将此文件所引用的样式和脚本资源替换为该项目目录的源文件。我们就可以在 src 目录调试代码并在浏览器里做实时预览。

值得一提的是Clam的文件代理功能提供了combo支持，其中默认支持的combo格式为以?作为servlet，以,作为文件分隔符。如果需要定制combo，可以到用户根目录的~/.flex-combo/config.json配置文件里更改flex-combo的配置。

flex-combo是一个提供本地combo服务的Node.js模块。
Clam本身的combo功能也是基于此模块实现的。
关于flex-combo的详细信息参见 flex-combo官方文档。

Clam 接口模拟

依托于Node.js，Clam提供了方便且强大的接口模拟能力。

要在Clam里模拟一个接口，我们需要在配置文件project.json的json字段增加如下信息：

"json": [
    {
        "url":      "/api/fake_api",    // 需要模拟的接口路径
        "enabled":  "local",            // 转发到远程服务器或者本地处理
        "remote":   "remotehost.com",   // 远程服务器
        "local":    "local_a.js"        // 本地处理脚本
    },
    {
        "url":      "/api/",            // 需要模拟的接口路径
        "enabled":  "remote",           // 转发到远程服务器或者本地处理
        "remote":   "remotehost.com",   // 远程服务器
        "local":    "local_b.js"        // 本地处理脚本
    }
]

其中url是需要匹配的接口路径（最长路径匹配）；enabled用来控制接口本地处理还是做远程转发；remote和local字段分别指定了远程转发服务器地址和本地处理脚本的文件名。本地处理脚本需要放置在项目的.clam/json/目录下。

如果此时我们的项目请求/api/fake_api接口，Clam会调用.clam/json/local_a.js处理；若请求/api/another_fake_api则会将此请求转发到远程服务器remotehost.com。

本地处理脚本使用Node.js内置的http模块来实现，它提供了一个传递http request和http response对象的处理函数：

exports = module.exports = function(req, res){
    res.end('this is a fake api response~')
    return true
}

详细用法请参考Node.js官方文档对于http模块的内容。

Clam 模块化开发

待续...

Clam 打包和发布管理

待续...

Clam 项目Hosts管理

在实际前端工作中，前端开发者一般会同时几个项目。这些项目对Host配置有不同的需求。 Clam 允许在启动clam on或者clam ui时自动修改系统hosts文件，完成hosts切换。 有两种方式为Clam设置Hosts切换规则。

1. 执行sudo clam ui,通过GUI设置项目的host。
2. 修改.clam/project.json中hosts字段的值。

修改完毕后无需重新启动clam，即刻生肖。 如果你使用clam管理所有前端项目，当你打开Clam时，系统各种环境就已经准备妥当，可以立即开始开发。 有时候，你只是想让Clam管理部分项目，此时你需要用命令sudo clam gc恢复hosts到正常状态。

Clam 基于模板创建页面和模块

Clam提供两个命令行用来自动创建框架页面和模块。以页面为例

clam page <页面名> [模板] 其中<页面名>为必填字段。在输入时，Clam建议你省去.html的扩展名。当然如果你输入也没关系，clam会处理好。 执行该命令将在项目目录下src/page创建一个html文件和一个css文件，文件名正是你输入的名称。文件内容已经搭建好一些基本框架： 同理，你可以执行clam mod <模块名> [模板] 或者 clam wideget <组件名> [模板]来帮助你创建模板和组件框架。

如果你对生成的html文件内容不满意，可以自定义模板。以mac为例，自定义的模板放置在~/.clam/templates/<模板名>中。 这个目录包含了3个子目录

<模板名>
       -page
       -mod
       -widget

其中page中存放页面模板，也就是执行clam page ...命令用到的模板。mod中存放页面模板，也就是执行clam mod ...命令用到的模板。widget中存放页面模板，也就是执行clam widget ...命令用到的模板。

当执行clam page <页面名> [模板名]命令后，Clam将：

1. 复制~/.clam/templates/<模板名>/page/下所有文件到项目目录下src/pages.
2. 修改所有命名为template.*的文件名为<页面名>.*。
3. 替换所有文件中的变量。模板支持的变量格式如下
   1. clam page { project:{项目信息}, page:{name:'', description:'',jsns:'', cssns:''} }
   2. clam mod { project:{项目信息}, mod:{name:'', description:'',jsns:'', cssns:''} }
   3. clam widget { project:{项目信息}, widget:{name:'', description:'',jsns:'', cssns:''} } 其中{项目信息}的格式请参考项目目录/.clam/project.json中的格式。
4. 在模板中引用变量的格式是完全的Juicer语法。例如：
   • 引用项目名称 ${project.name}
   • 引用页面名称 ${page.name}
   • 引用项目的最终编码 ${project.charset[0]}
   • 支持循环和判断语句，详情请参考地球上最快的前端模板引擎Juicer的语法。

最后

如有疑问，请关注我的新浪微博 魏凡哲-陶清 或者到前端开发社区F2E上发帖求助。