Skip to content

Latest commit

 

History

History
662 lines (522 loc) · 16 KB

2013-09-14-your_first_application.md

File metadata and controls

662 lines (522 loc) · 16 KB
Raw
layout title categories tags avatarimg author
post
Luminus手册-第一个应用
luminus
clojure
luminus
/img/head.jpg
wangyifan

Guestbook应用

此文使用Luminus构建一个简单的guestbook应用。guestbook可以保存信息，展示信息。此应用将涉及到简单的HTML模板，数据库访问和项目结构.

安装Leiningen

首先你需要安装Leiningen才能使用Luminus。安装Leiningen非常的简单:

  • 下载脚本
  • 将其设置为可执行权限(chmod +x lein)
  • 将脚本放到你的PATH下面
  • 运行lein self-install ，然后等待安装结束
wget https://raw.github.com/technomancy/leiningen/stable/bin/lein
chmod +x lein
mv lein ~/bin
lein self-install

创建一个新应用

安装完Leiningen后，你就可以在命令行中输入如下的命令

lein new luminus guestbook +h2
cd guestbook

上面的命令将会创建一个使用了H2嵌入式数据库的模板项目。

剖析Luminus应用

新创建的项目的目录结构如下

guestbook
|____.gitignore
|____Procfile
|____project.clj
|____README.md
|
|____src
| |____guestbook
|   |____handler.clj
|   |____layout.clj
|   |____middleware.clj
|   |____session.clj
|   |____routes
|   | |____home.clj
|   |____db
|     |____core.clj
|
|____test
| |____guestbook
|   |____test
|     |____handler.clj
|
|____resources
| |____templates
| | |____about.html
| | |____base.html
| | |____home.html
| |____public
| | |____css
| | | |____screen.css
| | |____img
| | |____js
| |____docs
| | |____docs.md
| |____sql
|   |____queries.sql
|
|____migrations
  |____201501155317-add-users-table.down.sql
  |____201501155317-add-users-table.up.sql

我们先来看一看根目录下的文件的作用:

  • Procfile - 部署相关信息
  • README.md - 项目相关的文档
  • project.clj - 用于管理项目的配置以及Leiningen依赖关系
  • .gitignore - Git中不提交的文件记录在此文件中

源代码目录

所有的代码都在src目录下。我们的应用名称叫guestbook，这个名字同时也是源代码的根命名空间。让我们来看一下源代码目录下所有的命名空间。

guestbook

  • handler.clj - 定义了应用最基本的路由。这是应用的入口。我们自定义的所有的页面都需要在这里添加各自的路由定义。
  • layout.clj - 页面布局帮助命名空间
  • middleware.clj - 中间件命名空间
  • session.clj - 创建内存session

guestbook.db

db命名空间下定义的是应用所使用的model以及持久化相关操作.

  • core.clj - 包含一组可以和数据库交互的函数

guestbook.routes

routes命名空间是存放路由以及controller的地方。当你要添加路由的时候，比如安全验证，特殊流程等等，你需要在这里创建他们。

  • home.clj - 一个定义了home和about页面的命名空间

测试目录

这里是放置测试代码的地方。该目录下已经有样例测试代码。

资源目录

这里是存放静态资源的地方。包括css,javascript,images和markdown.

HTML模板

这个命名空间存放的是Selmer模板文件，用于应用页面的展示。

  • about.html - about页面
  • base.html - base页面
  • home.html - home页面

SQL查询

sql查询语句在resources/sql目录中。

  • queries.sql：定义sql查询以及关联的函数名称

数据迁移目录

Luminus使用Ragtime来管理数据迁移。数据通过使用up，down文件来进行迁移。文件通过日期来进行版本管理，并按顺序执行

  • 201501155317-add-users-table.up.sql - 创建表
  • 201501155317-add-users-table.down.sql - 删除表

project文件

上面已经说过了，项目所有的依赖关系都是由project.clj来管理的。这个文件看起来像这样。

(defproject guestbook "0.1.0-SNAPSHOT"
  :description "FIXME: write description"
  :url "http://example.com/FIXME"

  :dependencies [[org.clojure/clojure "1.6.0"]
                 [ring-server "0.3.1"]
                 [selmer "0.8.0"]
                 [com.taoensso/timbre "3.3.1"]
                 [com.taoensso/tower "3.0.2"]
                 [markdown-clj "0.9.62"]
                 [environ "1.0.0"]
                 [im.chit/cronj "1.4.3"]
                 [ring/ring-defaults "0.1.3"]
                 [ring/ring-session-timeout "0.1.0"]
                 [ring-middleware-format "0.4.0"]
                 [noir-exception "0.2.3"]
                 [bouncer "0.3.2"]
                 [prone "0.8.0"]
                 [ragtime "0.3.8"]
                 [yesql "0.5.0-rc1"]
                 [com.h2database/h2 "1.4.182"]]

  :min-lein-version "2.0.0"
  :uberjar-name "guestbook.jar"
  :repl-options {:init-ns guestbook.handler}
  :jvm-opts ["-server"]

  :plugins [[lein-ring "0.9.0"]
            [lein-environ "1.0.0"]
            [lein-ancient "0.5.5"]
            [ragtime/ragtime.lein "0.3.8"]]

  :ring {:handler guestbook.handler/app
         :init    guestbook.handler/init
         :destroy guestbook.handler/destroy
         :uberwar-name "guestbook.war"}

  :ragtime
  {:migrations ragtime.sql.files/migrations
   :database "jdbc:h2:./site.db"}

  :profiles
  {:uberjar {:omit-source true
             :env {:production true}
             :aot :all}
   :production {:ring {:open-browser? false
                       :stacktraces?  false
                       :auto-reload?  false}}
   :dev {:dependencies [[ring-mock "0.1.5"]
                        [ring/ring-devel "1.3.2"]
                        [pjstadig/humane-test-output "0.6.0"]]
         :injections [(require 'pjstadig.humane-test-output)
                      (pjstadig.humane-test-output/activate!)]
         :env {:dev true}}})

project.clj就是个简单的Clojure的list，这个list中包含了键值对，描述了应用的方方面面。如果你要添加自定义依赖，只需要简单的将需要的依赖添加到:dependencies这个vector内。

:plugins后的vector可以用来添加额外的函数，比如说Ragtime这个数据迁移插件。

:profiles包含不同的项目配置，可以以开发模式还是部署模式来进行启动。

请到Leiningen官方文档中查看完整的project.clj文件。

创建数据库

首先，我们可以通过在数据迁移目录中新建-add-users-table.up.sql文件来创建一个model。文件中包含了如下内容:

CREATE TABLE users
(id VARCHAR(20) PRIMARY KEY,
 first_name VARCHAR(30),
 last_name VARCHAR(30),
 email VARCHAR(30),
 admin BOOLEAN,
 last_login TIME,
 is_active BOOLEAN,
 pass VARCHAR(100));

我们将users表修改为适合我们应用的名称:

CREATE TABLE guestbook
(id INTEGER PRIMARY KEY AUTO_INCREMENT,
 name VARCHAR(30),
 message VARCHAR(200),
 timestamp TIMESTAMP);

guestbook表将保存所有的信息描述。我们保存上面的sql，并通过在项目根目录运行如下的命令来创建数据库:

lein ragtime migrate

访问数据库

接着我们来看看src/guestbook/db/core.clj文件。我们发现里面已经有了数据库链接的相关配置.

(ns guestbook.db.core
  (:require
    [yesql.core :refer [defqueries]]
    [clojure.java.io :as io]))

(def db-store (str (.getName (io/file ".")) "/site.db"))

(def db-spec
  {:classname   "org.h2.Driver"
   :subprotocol "h2"
   :subname     db-store
   :make-pool?  true
   :naming      {:keys   clojure.string/lower-case
                 :fields clojure.string/upper-case}})

(defqueries "sql/queries.sql" {:connection db-spec})

这个数据库将数据库文件保存在相对应用目录的site.db文件中。

在执行defqueries这个函数时，会自动生成执行数据库查询的函数，这些函数是与查询相对应的。相关的查询在sql/queries.sql文件中。

--name: create-user!
-- creates a new user record
INSERT INTO users
(id, first_name, last_name, email, pass)
VALUES (:id, :first_name, :last_name, :email, :pass)

--name: update-user!
-- update an existing user record
UPDATE users
SET first_name = :first_name, last_name = :last_name, email = :email
WHERE id = :id

-- name: get-user
-- retrieve a used given the id.
SELECT * FROM users
WHERE id = :id

可以看到，所有的函数名称都定义在--name:后面。接下来的一行注释定义了函数说明，最后是sql。sql参数使用:加变量名的形式来传递。

下面我们来添加自定义sql

--name:save-message!
-- creates a new message
INSERT INTO guestbook
(name, message, timestamp)
VALUES (:name, :message, :timestamp)

--name:get-messages
-- selects all available messages
SELECT * from guestbook

运行项目

lein ring server
guestbook started successfully...
2013-03-01 19:05:30.389:INFO:oejs.Server:jetty-7.6.1.v20120215
Started server on port 3000
2013-03-01 19:05:30.459:INFO:oejs.AbstractConnector:Started SelectChannelConnector@0.0.0.0:3000

浏览器会自动打开，你将能看到运行的应用。如果你不想浏览器自动打开，你可以用下面的命令来启动项目.

lein ring server-headless

你也可以自定义端口号，命令如下:

lein ring server-headless 8000

创建表单页面

应用的路由是定义在guestbook.routes.home命名空间下的。我们来打开它，并添加一些逻辑。首先，需要添加db命名空间以及Bouncer验证和ring.util.response.

(ns guestbook.routes.home
  (:require
    ...
    [guestbook.db.core :as db]
    [bouncer.core :as b]
    [bouncer.validators :as v]
    [ring.util.response :refer [redirect]))

然后创建一个函数来验证form参数

(defn validate-message [params]
  (first
    (b/validate
      params
      :name v/required
      :message [v/required [v/min-count 10]])))

上面的函数使用Bouncer根据我们编写的逻辑来验证:name和:message。在这里name为必填，message必须最少包含10个字符。可以通过嵌套vector来对一个字段构建多个验证。

我们添加一个函数来验证和保存信息：

(defn save-message! [{:keys [params]}]
  (if-let [errors (validate-message params)]
    (-> (redirect "/")
        (assoc :flash (assoc params :errors errors)))
    (do
      (db/save-message! (assoc params :timestamp (java.util.Date.)))
      (redirect "/"))))

上面的函数通过:params从request中获取表单参数。当validate-message返回错误信息时将重定向到"/"，并将错误信息通过:flash来返回。否则保存信息。

接着，我们会修改home-page这个controller:

(defn home-page [{:keys [flash]}]
  (layout/render
   "home.html"
   (merge {:messages (db/get-messages)}
          (select-keys flash [:name :message :errors]))
   :name (:name flash)))

我们所做的就是多传递了几个参数给模板，其中一个是从数据库中查询到的信息.

最后呢，在home-routes定义里面添加这个controller的路由定义。

(defroutes home-routes
  (GET "/" request (home-page request))
  (POST "/" request (save-message! request))
  (GET "/about" [] (about-page)))

别忘了引入POST

(ns guestbook.routes.home
  (:require ...
            [compojure.core :refer [defroutes GET POST]]
            ...))

controller已经编写OK。我们打开处于resources/templates下的home.html模板,目前只是简单的显示内容：

{ % extends "templates/base.html" %}
{ % block content %}
 <div class="jumbotron">
    <h1>Welcome to guestbook</h1>
    <p>Time to start building your site!</p>
    <p><a class="btn btn-primary btn-lg" href="http://luminusweb.net">Learn more &raquo;</a></p>
 </div>

 <div class="row-fluid">
    <div class="span8">
    { {content|safe}}
    </div>
 </div>
{ % endblock %}

我们改为如下代码：

{ % extends "templates/base.html" %}
{ % block content %}
 <div class="jumbotron">
    <h1>Welcome to guestbook</h1>
 </div>

 <div class="row-fluid">
    <div class="span8">
      <ul>
      { % for item in messages %}
        <li>
          <time>{ {item.timestamp|date:"yyyy-MM-dd HH:mm"}}</time>
          <p>{ {item.message}}</p>
          <p> - { {item.name}}</p>
        </li>
      { % endfor %}
      </ul>
    </div>
 </div>
{ % endblock %}

我们使用了迭代器来遍历信息。而每个迭代结果都是一个包含了信息的map。我们能通过名字来访问它们。同时，我们使用了一个日期过滤器来生成一个适于人类阅读的时间. 接着我们来添加错误信息的展示.

{ % if error %}
    <p>{ {error}}</p>
{ % endif %}

我们只是简单的检查了一下是否有错误信息，如果有就展示。最后我们创建一个form来接受用户提交留言.

<form action="/" method="POST">
    <p>
       Name:
       <input type="text" name="name" value={ {name}}>
    </p>
    <p>
       Message:
       <textarea rows="4" cols="50" name="message">
           { {message}}
       </textarea>
    </p>
    <input type="submit" value="comment">
</form>

最后，home.html看起来像这样

{ % extends "guestbook/views/templates/base.html" %}

{ % block content %}
    <ul>
    { % for item in messages %}
      <li>
          <time>{ {item.timestamp|date:"yyyy-MM-dd HH:mm"}}</time>
          <p>{ {item.message}}</p>
          <p> - { {item.name}}</p>
      </li>
    { % endfor %}
    </ul>

{ % if error %}
    <p>{ {error}}</p>
{ % endif %}

<form action="/" method="POST">
    <p>
       Name:
       <input type="text" name="name" value={ {name}}>
    </p>
    <p>
       Message:
       <textarea rows="4" cols="50" name="message">
           { {message}}
       </textarea>
    </p>
    <input type="submit" value="comment">
</form>
{ % endblock %}

我们可以修改位于resources/public/css目录下的screen.css来使得页面更好看一些.

body {
	height: 100%;
	padding-top: 70px;
	font: 14px 'Helvetica Neue', Helvetica, Arial, sans-serif;
	line-height: 1.4em;
	background: #eaeaea;
	color: #4d4d4d;
	width: 550px;
	margin: 0 auto;
	-webkit-font-smoothing: antialiased;
	-moz-font-smoothing: antialiased;
	-ms-font-smoothing: antialiased;
	-o-font-smoothing: antialiased;
	font-smoothing: antialiased;
}

input[type=submit] {
	margin: 0;
	padding: 0;
	border: 0;
  line-height: 1.4em;
	background: none;
	vertical-align: baseline;
}

input[type=submit], textarea {
	font-size: 24px;
	font-family: inherit;
	border: 0;
	padding: 6px;
	border: 1px solid #999;
	box-shadow: inset 0 -1px 5px 0 rgba(0, 0, 0, 0.2);
	-moz-box-sizing: border-box;
	-ms-box-sizing: border-box;
	-o-box-sizing: border-box;
	box-sizing: border-box;
}

input[type=submit]:hover {
	background: rgba(0, 0, 0, 0.15);
	box-shadow: 0 -1px 0 0 rgba(0, 0, 0, 0.3);
}

textarea {
	position: relative;
	line-height: 1em;
	width: 100%;
}

.error {
  font-weight: bold;
	color: red;
}

.jumbotron {
	position: relative;
	background: white;
	z-index: 2;
	border-top: 1px dotted #adadad;
}

h1 {
	width: 100%;
	font-size: 70px;
	font-weight: bold;
	text-align: center;
}

ul {
	margin: 0;
	padding: 0;
	list-style: none;
}

li {
	position: relative;
	font-size: 16px;
	padding: 5px;
	border-bottom: 1px dotted #ccc;
  box-shadow: 0 2px 6px 0 rgba(0, 0, 0, 0.2),
	            0 25px 50px 0 rgba(0, 0, 0, 0.15);
}

li:last-child {
	border-bottom: none;
}

li time {
	font-size: 12px;
	padding-bottom: 20px;
}

form:before, .error:before {
	content: '';
	position: absolute;
	top: 0;
	right: 0;
	left: 0;
	height: 15px;
	border-bottom: 1px solid #6c615c;
	background: #8d7d77;
}

form, .error {
	width: 520px;
	padding: 30px;
	margin-bottom: 50px;
	background: #fff;
	border: 1px solid #ccc;
	position: relative;
	box-shadow: 0 2px 6px 0 rgba(0, 0, 0, 0.2),
	            0 25px 50px 0 rgba(0, 0, 0, 0.15);
}

form input {
	width: 50%;
	clear: both;
}

现在刷新页面就可以看到我们修改的内容了。试试留个言！

打包应用

要打包程序，可输入

lein ring uberjar

这将会创建一个可运行的jar。通过下面的命令来运行

java -jar target/guestbook-0.1.0-SNAPSHOT-standalone.jar

如果我们想把应用部署到tomcat这样的服务器上，你可以运行

lein ring uberwar

这将会打包一个war包。

完整的源代码可以到这里下载。