λ

读取和写入文件

数据一般都是存储在纯文本文件当中，存储的形式多种多样。本文，我会介绍如何在Clojure中读取和写入这些数据。

1. 打开文件

新建文件hello.txt，放到resources目录，内容如下：

1
2
3

hello world!
hello lambeta!
hello life!

新建4io.clj，输入程序：

1
2
3
4
5
6

(ns the-way-to-clojure.4io
  (:require [clojure.java.io :as io]
            [clojure.string :as str]))

(def data-file (io/resource "hello.txt"))
(slurp data-file) 

运行程序，输出如下：

1

"hello world! \nhello lambeta!\nhello life!\n"

读取所有行

1
2

(line-seq (io/reader data-file))
;;=> ("hello world!" "hello lambeta!" "hello life!")

with-open宏

with-open宏用于自动关闭打开的文件。

1.1 读取一行，如下：

1
2
3

(with-open [rdr (io/reader data-file)]
  (when-let [line (.readLine rdr)]
    (println line)))

1.2 读取多行，如下：

1
2
3
4
5
6

;;; read multiple lines
(with-open [rdr (io/reader data-file)]
  (loop [line (.readLine rdr)]
    (when line
      (println line)
      (recur (.readLine rdr)))))

2. 读取文件的技巧

想想读取文件可能有哪些场景？

• 读取整个文本

1

(slurp data-file)

• 读取一行

1
2
3
4
5
6

(with-open [rdr (io/reader data-file)]
  (first (line-seq rdr)))
;; 或者
(with-open [rdr (io/reader data-file)]
  (take 1 (line-seq rdr)))
-> "hello world!"

• 读取前n行

1
2
3

(with-open [rdr (io/reader data-file)]
  (doall (take 2 (line-seq rdr))))
-> ("hello world!" "hello lambeta!")

这里使用了(doall )方法，如果不用这个方法，在repl中求值的时候会表达式导致抛出Unhandled java.io.IOException Stream closed异常。究其缘由是(take 2 )返回了一个惰性序列，详细解释参见文末备注。

• 读取前n个字符

1
2
3
4
5
6
7
8
9

with-open [rdr (io/reader data-file)]
  (loop [ch (.read rdr) len 20]
    (when-not (or (= -1 ch) (zero? len))
      (println (char ch))
      (recur (.read rdr) (dec len)))))
| h
| e
| ...
-> nil

• 跳过特定的行

在resources目录下，新建records.txt，内容即代码注释所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

(defn read-records [input-file]
  "Coloured fox fur production, HOPEDALE, Labrador, 1834-1842
  #Source: C. Elton (1942) \"Voles, Mice and Lemmings\", Oxford Univ. Press
  #Table 17, p.265--266
  22
  29
  2
  16
  12
  35
  8
  83
  166"
  (letfn [(skip [lines]
            (next lines))]
         (with-open [rdr ((comp io/reader io/resource) input-file)]
           (->>
            (for [line (skip (line-seq rdr))
                  :when (not (.startsWith line "#"))]
              (read-string line))
            (apply +)))))

(read-records "records.txt")
-> 373

我们在read-records内部新建一个skip方法，顾名思义，跳过第一个元素，然后返回后面的列表。这里旨在跳过文本的声明头。:when (not ...)过滤了文本的注释部分（以#开头的行），并使用read-string转换字符串到数字类型，(for )求值完成后返回只包含数字的列表。最后，我们对列表做了一次累加操作。

我们试试非过滤而是跳过（删除）以”#”开头行的方式获取数字列表，这样更符合要求。重写with-open部分，如下：

1
2
3
4
5
6

(with-open [rdr ((comp io/reader io/resource) input-file)]
      (apply +
             (let [lines (skip (line-seq rdr))]
               (->> lines
                    (remove (set (for [line lines :while (.startsWith line "#")] line)))
                    (map read-string)))))

或者

1
2
3
4
5
6

(with-open [rdr ((comp io/reader io/resource) input-file)]
      (apply +
             (let [lines (skip (line-seq rdr))]
               (->> lines
                    (drop (count (for [line lines :while (.startsWith line "#")] line)))
                    (map read-string)))))

3. 读取网络文件

通过slurp读取字符串

1
2
3

(slurp "http://robjhyndman.com/tsdldata/ecology1/hopedale.dat" :encoding "utf-8")

-> "Coloured fox fur production, HOPEDALE, Labrador,, 1834-1925\n#Source: C. Elton (1942) \"Voles, Mice and Lemmings\", Oxford Univ. Press\n#Table 17, p.265--266\n      22   \n...

注意，这个网页上的数据是用UTF-8编码的，所以解码读取时，也应该使用UTF-8。

4. 写入文件

• 使用spit方法

1

(spit "world.txt" "Hello, lambeta!" :append true)

运行程序之后，项目的根目录下会生成world.txt文件，内容是Hello, lambeta。spit方法其实就是向Java的BufferedWriter中写入内容。

• 使用clojure.java.io/writer

我们在项目的根目录新建numbers.txt，内容是多行的数字对，如下：

1
2
3

1.3 2.7
10000 1
-1 1

我们需要把每行两个数字，和它们相加的结果写入到sum-of_numbers.txt文件中。也就是注释中的描述。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

(defn sum-number-pairs [input-file output-file]
  "Read the data from input-file, which contains two floats per line
   separated by a space.  Open file named output-file and, for each line in
   input-file, write a line to the output file that contains the two floats
   from the corresponding line of input-file plus a space and the sum of the
   two floats."
(with-open [rdr (io/reader input-file) wtr (io/writer output-file :append true)]
    (loop [line (.readLine rdr)]
      (when line
        (let [pair (map read-string
                        (str/split line #"\s"))
              first (first pair)
              second (second pair)
              sum (+ first second)]
          (.write wtr (str first " " second " " sum "\n")))
        (recur (.readLine rdr))))))

(sum-number-pairs "numbers.txt" "sum-of-numbers.txt")

with-open同时打开了一个用于读取、名为input-file的文件以及一个用于写入、名为output-file的文件，写入方式是追加:append true。随后循环读取input-file中的每行内容。若line不是nil（即存在），那么用空格分隔这行内容，得到一个数组，如：”1.3 2.7” -> [“1.3” “2.7”]。此时数组的元素类型还不是数字（Number），我们使用(map read-string )将元素转换为对应的数字类型，如：[“1.3” “2.7”] -> [1.3 2.7]。之后，分别提取数组的第一、二个元素以及两者的和。最后，写入到wtr中。

注意：程序中的str/split是通过(:require [clojure.string :as str])方式引入str命名空间的。

运行程序之后，sum-of-numbers.txt中的内容如下：

1
2
3

1.3 2.7 4.0
10000 1 10001
-1 1 0

5. 多行记录

5.1 有结束标识

有时候，记录并不是以一行一行的方式存储在文件当中的，而是以多行数据描述一条记录。比如下面的蛋白质数据：
清单 5.1 multimol.pdb

1
2
3
4
5
6
7
8
9
10
11
12
13
14

COMPND      AMMONIA
ATOM      1  N  0.257  -0.363   0.000
ATOM      2  H  0.257   0.727   0.000
ATOM      3  H  0.771  -0.727   0.890
ATOM      4  H  0.771  -0.727  -0.890
END
COMPND      METHANOL
ATOM      1  C  -0.748  -0.015   0.024
ATOM      2  O  0.558   0.420  -0.278
ATOM      3  H  -1.293  -0.202  -0.901
ATOM      4  H  -1.263   0.754   0.600
ATOM      5  H  -0.699  -0.934   0.609
ATOM      6  H  0.716   1.404   0.137
END

第一行描述的是分子的名字，接下来到END为止的每行代表原子的ID、类型以及在分子中分布的[x y z]坐标。
我们需要一个函数，将数据读取出来并且以规定的格式输出，格式如下：

1
2
3
4
5
6
7
8
9
10
11
12

(("AMMONIA" 
    ("N" "0.257" "-0.363" "0.000")
    ("H" "0.257" "0.727" "0.000")
    ("H" "0.771" "-0.727" "0.890")
    ("H" "0.771" "-0.727" "-0.890")) 
 ("METHANOL" 
    ("C" "-0.748" "-0.015" "0.024")
    ("O" "0.558" "0.420" "-0.278")
    ("H" "-1.293" "-0.202" "-0.901")
    ("H" "-1.263" "0.754" "0.600")
    ("H" "-0.699" "-0.934" "0.609")
    ("H" "0.716" "1.404" "0.137")))

也就是说，我们需要把每条记录读入单个列表中，每个列表由分子的名称和多个(Type X Y Z)的原子列表组成。

1
2
3
4
5
6
7
8
9
10
11

(defn read-all-molecules [input-file]
  (map (fn [molecules]
         (let [[_ name] (str/split (first molecules) #"\s+")
               atoms (map (comp #(drop 2 %) #(str/split % #"\s+"))
                          (rest molecules))]
           (concat [name] atoms)))
       ;; 分割成多条记录
       (remove #(= % ["END"]) 
               (partition-by #(= % "END") (line-seq (io/reader input-file))))))

(read-all-molecules "multimol.pdb")

(remove #(= % ["END"]) (partition-by #(= % "END") (line-seq (io/reader input-file))))这行代码做的事情就是把文件读取出来变成一个lazy-seq，然后使用parttition-by以END进行分组，最后使用remove方法剔除掉*[“END”]*这样的分组，得到如下中间结果：

1
2
3
4
5
6
7
8
9
10
11
12

(("COMPND      AMMONIA" 
  "ATOM      1  N  0.257  -0.363   0.000"
  "ATOM      2  H  0.257   0.727   0.000"
  "ATOM      3  H  0.771  -0.727   0.890"
  "ATOM      4  H  0.771  -0.727  -0.890") 
 ("COMPND      METHANOL" 
  "ATOM      1  C  -0.748  -0.015   0.024"
  "ATOM      2  O  0.558   0.420  -0.278"
  "ATOM      3  H  -1.293  -0.202  -0.901" 
  "ATOM      4  H  -1.263   0.754   0.600"
  "ATOM      5  H  -0.699  -0.934   0.609" 
  "ATOM      6  H  0.716   1.404   0.137"))

这样离我们的目标已经很近了。观察上述结果，不难发现分子的名称处于列表的第一个(first )，而原子列表可以使用(rest )获取。然后，借助(map )函数遍历所有的记录。

(let )中的第一个binding是[_ name] (str/split (first molecules) #"\s+")，首先用(split )函数分割，再使用了解构提取出分子的名称；第二个binding是原子列表的提取，我们在(split )的基础之上，使用(drop 2 )函数剔除了不用的字段，如：ATOM和1。最后使用(concat )函数将名称和原子列表的列表拼接到一起。

5.2 无结束标识

5.1中的记录项通过END标识分隔，但是事实上这是一个多余的字段，记录项可以更简练，如下：
清单 5.2 multimol-without-end-marker.pdb

1
2
3
4
5
6
7
8
9
10
11
12

COMPND      AMMONIA
ATOM      1  N  0.257  -0.363   0.000
ATOM      2  H  0.257   0.727   0.000
ATOM      3  H  0.771  -0.727   0.890
ATOM      4  H  0.771  -0.727  -0.890
COMPND      METHANOL
ATOM      1  C  -0.748  -0.015   0.024
ATOM      2  O  0.558   0.420  -0.278
ATOM      3  H  -1.293  -0.202  -0.901
ATOM      4  H  -1.263   0.754   0.600
ATOM      5  H  -0.699  -0.934   0.609
ATOM      6  H  0.716   1.404   0.137

现在的问题变成了没有END标识符，如何进行分组？观察不难发现以COMPND开头的数据行可以作为记录的分隔符。
使用(partition-by #(.startsWith % "COMPND") (line-seq (io/reader input-file)))进行分组，得到的结果如下：

1
2
3
4
5
6
7
8
9
10
11
12

(("COMPND      AMMONIA") 
  ("ATOM      1  N  0.257  -0.363   0.000" 
   "ATOM      2  H  0.257   0.727   0.000" 
   "ATOM      3  H  0.771  -0.727   0.890"
   "ATOM      4  H  0.771  -0.727  -0.890") 
 ("COMPND      METHANOL") 
  ("ATOM      1  C  -0.748  -0.015   0.024" 
   "ATOM      2  O  0.558   0.420  -0.278" 
   "ATOM      3  H  -1.293  -0.202  -0.901"
   "ATOM      4  H  -1.263   0.754   0.600"
   "ATOM      5  H  -0.699  -0.934   0.609"
   "ATOM      6  H  0.716   1.404   0.137"))

此时，我们对比5.1中中间结果，会发现它们极为相似。也就是说，我们稍加转换就能让两者一致，而一致的好处就是可以复用原来(map )中的逻辑。

稍稍修改原来的分组逻辑，如下：

1
2
3
4
5

(map (fn [[name atoms]] (concat name atoms))
       (partition 2
                  (partition-by
                   #(.startsWith % "COMPND")
                   (line-seq (io/reader input-file)))))

我们先使用(partition 2 )将第一步得到的列表每隔两个元素划为一组，如下：

1
2
3
4
5
6
7
8
9
10
11
12

((("COMPND      AMMONIA") 
  ("ATOM      1  N  0.257  -0.363   0.000" 
   "ATOM      2  H  0.257   0.727   0.000" 
   "ATOM      3  H  0.771  -0.727   0.890"
   "ATOM      4  H  0.771  -0.727  -0.890")) ; 多出一对括号
 (("COMPND      METHANOL") 
  ("ATOM      1  C  -0.748  -0.015   0.024" 
   "ATOM      2  O  0.558   0.420  -0.278" 
   "ATOM      3  H  -1.293  -0.202  -0.901"
   "ATOM      4  H  -1.263   0.754   0.600"
   "ATOM      5  H  -0.699  -0.934   0.609"
   "ATOM      6  H  0.716   1.404   0.137")))

然后使用(map (fn [[name atoms]] ...)将每组里面的两个列表合成为一个列表，这样就得到和原来5.1一模一样的中间结果。

接下来，我们把转换的逻辑从(read-all-molecules )中提取出来，以便复用。改造如下：

1
2
3
4
5
6
7

(defn read-all-molecules [f input-file]
  (let [data (f input-file)]
    (map (fn [molecules]
           (let [[_ name] (str/split (first molecules) #"\s+")
                 atoms (map (comp #(drop 2 %) #(str/split % #"\s+"))
                            (rest molecules))]
             (concat [name] atoms))) data)))

定义转换逻辑，如下：

1
2
3
4
5
6

(defn file-without-markers->multi-records [input-file]
  (map (fn [[name atoms]] (concat name atoms))
       (partition 2
                  (partition-by
                   #(.startsWith % "COMPND")
                   (line-seq (io/reader input-file))))))

最后，我们来调用的改造之后的方法：

1
2

(read-all-molecules 
        file-without-markers->multi-records "multimol-without-end-marker.pdb")

此时，5.1中的转换逻辑也可以提取出一个函数：

1
2
3

(defn file->multi-records
  (remove #(= % ["END"]) 
               (partition-by #(= % "END") (line-seq (io/reader input-file)))))

原来的程序就重构成了如下的模样：

1

(read-all-molecules file->multi-records "multimol.pdb")

备注

为了清楚定位这个问题，我们需要提前了解两个知识点

1. 什么是惰性序列？
2. 惰性序列在repl中什么时候变现（realizes）？

惰性序列是用(lazy-seq [& body] )宏创建出来的。lazy-seq仅在需要的时候才会去调用它的body。
当repl尝试pretty-print惰性序列的结果时，才会进行变现操作。

有了上面的知识点，我们来考察with-open和(take 2 (line-seq ))的关系。with-open是宏，我们使用clojure.walk/macroexpand-all展开下：

1
2
3
4
5
6
7
8

(clojure.walk/macroexpand-all 
    '(with-open [rdr (io/reader data-file)]
                      (take 2 (line-seq rdr))))
                      
-> (let* [rdr (io/reader data-file)] 
        (try (do 
                (take 2 (line-seq rdr))) 
        (finally (. rdr clojure.core/close))))                      

使用(doc line-seq)查看文档，得到

1
2
3
4
5

clojure.core/line-seq
 [rdr]
Added in 1.0
  Returns the lines of text from rdr as a lazy sequence of strings.
  rdr must implement java.io.BufferedReader.

可以确认line-seq返回一个惰性的字符串序列。
再看看(doc take)的文档，得到

1
2
3
4
5
6
7

clojure.core/take
 [n]
 [n coll]
Added in 1.0
  Returns a lazy sequence of the first n items in coll, or all items if
  there are fewer than n.  Returns a stateful transducer when
  no collection is provided.

所以take返回的也是一个惰性序列，那么(do (take 2 (line-seq rdr)))（等价于(take 2 (line-seq rdr))）整个返回的就是一个惰性序列。

当我们通过repl求值with-open时，它并没有真的变现(take 2 (line-seq rdr))，而是在运行完try...finally之后，直接返回这个惰性序列作为结果。此时，repl开始尝试pretty-print (take 2 (line-seq rdr))，变现发生，但是rdr已经被关闭了，所以抛出Stream closed异常。

到这里，解决了一大半问题，但是还有一个逻辑上解释不过去的点，就是

1
2

(with-open [rdr (io/reader data-file)]
  (take 1 (line-seq rdr)))

当我们尝试(take 1 )时并不会抛出异常！也就是说(take 1 )和(take 2 )的行为不同，但是(take )明明都是返回惰性序列啊？

带着这个疑惑，看看line-seq的源代码

1
2

(when-let [line (.readLine rdr)]
    (cons line (lazy-seq (line-seq rdr)))))

是不是有种豁然开朗的感觉？没有也没关系，我来解释一下。
line-seq的when-let语句并没有包在(lazy-seq )（这点可以和take的源码比较）中，这说明[line (.readline rdr)]是需要立即求值的。也就是说，我们在求值with-open时，rdr中第一行的内容会被(line-seq )给抓住了。那么当try...finally运行结束之后，pretty-print变现惰性序列时，发现第一行根本不需要从rdr中读，当然就不会抛出异常了。

明确这几点之后，我们看看(doall )为何能解决惰性序列延迟求值的问题？(doall )其实强制变现了整个惰性序列（不断调用序列的next方法），所以并不会等到with-open求值完成之后才求值。

换个角度，我们知道之所以抛出异常，是因为repl对返回的惰性序列求值了。那么如果我们不在repl中求值，程序还会抛出异常吗？

1
2
3
4
5
6
7

(ns the-way-to-clojure.core
  (:require [clojure.java.io :as io])
  (:gen-class))

(defn -main [& args]
  (with-open [rdr (io/reader "hello.txt")]
    (take 100 (line-seq rdr))))

接着，我们使用lein run来运行main方法。程序运行良好，因为根本没有人用到返回的惰性序列。

如果我们加一句打印语句如下：

1
2
3
4

(defn -main [& args]
  (println          ; 变现
      (with-open [rdr (io/reader "hello.txt")]
        (take 100 (line-seq rdr)))))

再用lein run跑一个main方法，异常又不期而遇了。因为此处的println等价于repl的pretty print。

插件不好写？！

插件确实不好写，因为插件是插入庞大的系统当中工作的，那也就意味着写插件需要具备一定的领域知识，包括系统架构、扩展点、业务共性及差异、API及其业务模型对应、安装和测试。而对于开发者而言，学习这些知识的代价绝对是昂贵的。
在《函数式编程思想》一书中，作者Neal Ford提到开发过程当中的两种抽象方式——composable and contextual abstract. 谈及contextual抽象的时候，他把插件系统列为这一抽象中最经典的例子。

Plugin-based architectures are excellent examples of the contextual abstraction. The plug-in API provides a plethora of data structures and other useful context that developers inherit from or summon via already existing methods. But to use the API, a developer must understand what that context provides, and that understanding is sometimes expensive.

大意是开发者能够借助已存在的方法来使用Plugin API中提供的大量数据结构和有用的上下文信息。但是，理解起这些上下文信息有时是很昂贵的。

基于一个共识：开发者的时间都是宝贵的。知道插件难写之后，我的这篇文章才有价值。

理解领域模型

一说写插件，估计大家都会上官网寻找开发指南或者google大量博客来快速完成开发任务。这里不是说这种方式不好，其实一开始我也是这么做的，但是着手开发以后，很快就遭遇处处掣肘。比如：开发sonar plugin，会用到Profile、Rule、Language和Repository等概念。单从代码层面上看，我们很难理清这些概念所代表的模型和它们之间的关系。所以需要从用户的视角来感受这些领域知识。

而用户视角大部分情况下就是UI界面。

规则（Rules）

我们先看看Rules导航栏，左边的单选框是这些规则的过滤条件。
说明规则包含或者被包含这些属性之下：

• Language：规则对应的某种编程语言。
• Type：规则的类型，比如：缺陷（Bug）、代码坏味道（Code Smell）、易受攻击（Vulnerability）。
• Tag：规则设置的标签，易于检索。
• Repository：承载特定语言下各种规则的容器；通过它可以通过规则的键值（ruleKey）检索。
• Default Severity：触犯规则的严重程度。
  • Blocker：最高等级，阻碍的
  • Critical：高等级，极为严重的
  • Major：较高等级，主要的；默认级别。
  • Minor：较低等级
  • Info：低等级
• Status：规则现在的状态，可用、废弃还是实验版（Beta）。
• Avaiable Since：什么时候开始可用。
• Template：规则模板：比如某些参数可以运行时传入。
• Quality Profile：挑选特定语言下各种规则组成的配置；其中可以启用或禁用一部分规则。

质量Profile（Quality Profile）

再看看Quality Profiles导航栏，左侧栏显示的是某种语言包含的所有Profiles.

从关系型数据库的角度，Language和Profile是1对多（one-to-many）关系，但是从领域建模的角度，Profile其实和Language是1对1的关系。所以可以是Profile包含Language属性。利用领域建模的思考方式，可以联想到Repository和Rules是1对多的关系，所以Repository包含一个Rules的集合。Repository和Language是1对1的关系，Repository包含Language属性。那么Rules和Profiles的对应关系呢？多对多。但是我们更关心Profile到Rules这一层的关系，所以选择Profile包含一个Rules的集合。

我整理出这样一份对应关系图：

1
2
3
4
5
6

profile
    - language
    - [rules]
respository
    - lanuage
    - [rules]

现在，缺少Profile和Repository的关系。不过既然有了Rule这一层联系，那么就可以这样考虑，Rule和Repository是1对1的关系（为什么呢？因为每个Rule显然只能存在于一个特定的Repository当中）。所以原图可以修改为：

1
2
3
4
5
6
7
8

profile
    - language
    - [rules]
      - rule
        - respository
respository
    - language
    - [rules]

好了。梳理完这些领域知识，我们可以开始依照官方的教程Developing a Plugin.

扫描特定领域语言（DSL）的SonarQube插件

SonarQube 5.6现在只支持Java 8、Maven 3.1以上。当然也支持Gradle。

第一步 创建一个Maven工程

这里有两种方式。第一种方式就是从头开始写起，包括创建工程；另一种就是拷贝官方的样例程序。我自然是推荐第二种做法，不过这里我从零开始开发。

1

$ mvn archetype:create -DgroupId=com.lambeta -DartifactId=sonar-lambeta -DarchetypeArtifactId=maven-archetype-quickstart

依照官方文档将pom.xml修改如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.lambeta</groupId>
    <artifactId>sonar-custom</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>sonar-plugin</packaging>

    <name>sonar-custom</name>
    <url>https://www.lambeta.com</url>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.sonarsource.sonarqube</groupId>
            <artifactId>sonar-plugin-api</artifactId>
            <!-- minimal version of SonarQube to support. Note that the groupId was "org.codehaus.sonar" before version 5.2 -->
            <version>5.6</version>
            <!-- mandatory scope -->
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>net.sourceforge.pmd</groupId>
            <artifactId>pmd-xml</artifactId>
            <version>5.4.2</version>
        </dependency>
        <dependency>
            <groupId>dom4j</groupId>
            <artifactId>dom4j</artifactId>
            <version>1.6.1</version>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>3.8.1</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.sonarsource.sonar-packaging-maven-plugin</groupId>
                <artifactId>sonar-packaging-maven-plugin</artifactId>
                <version>1.16</version>
                <extensions>true</extensions>
                <configuration>
                    <pluginClass>com.lambeta.CustomPlugin</pluginClass>
                    <pluginDescription>how to write sonar plugin</pluginDescription>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

注意： pmd-xml、dom4j会在后面的编程当中使用到。

依据标准的代码结构，新建CustomPlugin.java文件。

1
2
3
4
5
6

├── src
│   ├── main
│   │   ├── java
│   │   │   └── com
│   │   │       └── lambeta
│   │   │           ├── CustomPlugin.java

第二步 识别扩展点

此时，该去查看API Basics了。不过在写代码之前，还得先了解所谓的扩展点（Extension Points）。

Scanner, which runs the source code analysis
Compute Engine, which consolidates the output of scanners, for example by
computing 2nd-level measures such as ratings
aggregating measures (for example number of lines of code of project = sum of lines of code of all files)
assigning new issues to developers
persisting everything in data stores
Web application

翻译如下

• 扫描器：分析源代码
• 计算引擎：聚合扫描器的输出。举例：计算第二轮measures，如打分；聚合measures（举例：工程中所有代码的行数 = 所有文件的代码行的综合）；给开发者安排新的问题；持久化。
• Web应用程序。
  翻译还不如不翻译！一言不合，去看例子程序…的注释

这三个扩展点，其实对应于API中的三个接口。

1
2
3

扫描器 -> Sensor
计算引擎 -> MeasureComputer
Web应用程序 -> Widget

第三步 定义Sensor（Scanner)

基于扫描DSL源码的需求，我们需要扩展Sensor这个接口。新建CustomSensor.java如下：

1
2
3
4
5
6

public class CustomSensor implements Sensor

    public void describe(SensorDescriptor descriptor) 
    ...
    public void execute(SensorContext context)
    ...

接下来，我们需要定义这门DSL语言的某些属性，以便于识别以及扫描时过滤相关的源文件（通过文件的后缀）。

第四步 定义语言（Language）

新建CustomLanguage如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package com.lambeta;
import org.sonar.api.resources.AbstractLanguage;

public class CustomLanguage extends AbstractLanguage {
    public static final String KEY = "custom-key";
    public static final String NAME = "custom-name";

    public CustomLanguage() {
        super(KEY, NAME);
    }

    public String[] getFileSuffixes() {
        return new String[] {"csm.xml"}; //custom这门基于xml的内部DSL的文件后缀
    }
}

我定义了一门基于xml语法的内部DSL，其文件的后缀是csm.xml。比如：right-syntax.csm.xml

Language定义出来了，我们还得定义rule、profile和repository. 回到上文提及的language、rule、profile以及repository的关系图：

1
2
3
4
5
6
7
8

profile
    - language
    - [rules]
      - rule
        - respository
respository
    - language
    - [rules]

第五步 定义规则（Rule）

1
2
3

respository
    - language
    - [rules]

我们需要实现接口RulesDefinition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

package com.lambeta;
import org.apache.commons.io.Charsets;
import org.apache.commons.io.IOUtils;
import org.sonar.api.server.rule.RulesDefinition;
import org.sonar.api.server.rule.RulesDefinitionXmlLoader;

import java.io.InputStream;

public class CustomRulesDefinition implements RulesDefinition {

    public static final String REPOSITORY_KEY = "custom-repo";
    private final RulesDefinitionXmlLoader xmlLoader;

    public CustomRulesDefinition(RulesDefinitionXmlLoader xmlLoader) {
        this.xmlLoader = xmlLoader;
    }

    public void define(Context context) {

        final InputStream stream = getClass().getResourceAsStream("/rules.xml");
        final NewRepository repository = context.createRepository(REPOSITORY_KEY, CustomLanguage.KEY);

        try {
            if (stream != null) {
                xmlLoader.load(repository, stream, Charsets.UTF_8);
            }
            repository.done();
        } finally {
            IOUtils.closeQuietly(stream);
        }
    }
}

我们通过context新建出一个repository。respository需要一个唯一key作为其标识（可以通过setName方法设置名称）以及一个language key来关联（从UI上可以看出来）。然后，通过DI进来的RulesDefinitionXmlLoader将rules.xml中定义的rules加载进repository中。最后，调用*reposiotory.done()*宣告加载完成。

定义的rules.xml内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<?xml version="1.0" encoding="UTF-8" ?>
<rules>
    <rule>
        <key>ComponentsMustNotBeFollowedByComponentsRule</key>

        <name>Components标签后不能跟随Components标签规则</name>
        <description>
            <![CDATA[
                Components标签后不能跟随Components标签
            ]]>
        </description>
        <severity>MINOR</severity>
        <cardinality>SINGLE</cardinality>
        <status>READY</status>
        <tag>custom</tag>
        <example>
            <![CDATA[
                <components>
                <!-- Error, components must be here! -->
                    <components/>
                </components>
            ]]>
        </example>
    </rule>
</rules>

包含了rule的key和其他相关的属性。它们最终显示在UI上，会是这样：

第六步 定义Profile

1
2
3
4
5

profile
    - language
    - [rules]
      - rule
        - respository

我们需要实现接口ProfileDefinition.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

package com.lambeta;
import org.apache.commons.io.IOUtils;
import org.sonar.api.profiles.ProfileDefinition;
import org.sonar.api.profiles.RulesProfile;
import org.sonar.api.profiles.XMLProfileParser;
import org.sonar.api.utils.ValidationMessages;

import java.io.InputStreamReader;

public class CustomProfileDefinition extends ProfileDefinition {
    private final XMLProfileParser xmlProfileParser;

    public CustomProfileDefinition(XMLProfileParser xmlProfileParser) {
        this.xmlProfileParser = xmlProfileParser;
    }

    @Override
    public RulesProfile createProfile(ValidationMessages validation) {
        final InputStreamReader reader = new InputStreamReader(getClass().getResourceAsStream("/profile.xml"));

        try {
            return xmlProfileParser.parse(reader, validation);
        } finally {
            IOUtils.closeQuietly(reader);
        }
    }
}

使用DI注入的XMLProfileParser解析profile.xml文件，并生成RulesProfile对象。我们来看看profile.xml的内容：

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="utf-8" ?>
<profile>
    <language>custom-key</language>
    <name>Custom Quality</name>
    <rules>
        <rule>
            <repositoryKey>custom-repo</repositoryKey>
            <key>ComponentsMustNotBeFollowedByComponentsRule</key>
            <priority>MAJOR</priority>
        </rule>
    </rules>
</profile>

这里定义一个名为Custom Quality的profile，它关联CustomLanguage的键值：custom-key. 同时包含了多条rules，每条rule拥有自己的标识key以及其所在的repository（事实上，profile会在repository中通过ruleKey来查找rule）。

写到这里，一个DSL的SonarQube Plugin已经几近完善。但是，我们还缺少至关重要的一环——规则的执行！

第七步 运行PMD扫描代码

PMD简介

我们需要一个静态扫描工具来扫描源代码，发现这些代码存在的缺陷和坏味道。PMD就是这么一款好用的工具。

PMD is a source code analyzer. It finds common programming flaws like unused variables, empty catch blocks, unnecessary object creation, and so forth. It supports Java, JavaScript, PLSQL, Apache Velocity, XML, XSL.

翻译：
PMD是一款源码分析工具。它会发现编程中的普遍缺陷，如未使用的变量、空的catch块、不必要的对象创建等等。它支持分析Java、Javascript、PLSQL、Apache Velocity、XML、XSL语言。

前面提到我定义的是一门基于XML的DSL，那么理所当然，可以借助PMD，扩展XML的扫描规则来满足自己的需求。

PMD在命令行中执行的方式如下：

1

pmd -d src/ -f xml -R myrule.xml -r dest/report.xml

• -d 代表要扫描的源码目录
• -f 代表报告输出的格式
• -R 代表采用哪些规则来扫描源代码
• -r 代表报告的输出路径

注意：这里PMD的规则和SonarQube中的规则其实没有太大关系，属于两种事物。不过，为方便后续提取PMD输出的报告，需要将PMD规则的名字和Sonar规则的键值保持一致。

我们定义PMD需要使用到的规则集custom-pmd-rules.xml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

<?xml version="1.0"?>
<ruleset name="ExamplePmdRuleset"
         xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd">

    <description>
        Example set of configured PMD rules
    </description>

    <rule name="ComponentsMustNotBeFollowedByComponentsRule"
          message="Components tags followed by components tag found!"
          language="xml"
          class="net.sourceforge.pmd.lang.rule.XPathRule">

        <description>
            Tag components must not be followed by components tag.
        </description>

        <priority>1</priority>

        <properties>
            <property name="xpath">
                <value>//components/components</value>
            </property>
        </properties>

        <example>
            <![CDATA[
                <components>
                    <components>
                </components>
            ]]>
        </example>
    </rule>
</ruleset>

这里的类net.sourceforge.pmd.lang.rule.XPathRule来自于我们先前在pom.xml中声明的pmd-xml这个依赖包。它可以让我们通过设置xpath这一属性的值来构建各种不同规则。扫描中XML文件一旦匹配这些xpath规则，就会输出错误报告。

以ComponentsMustNotBeFollowedByComponentsRule这个自定义的规则为例。顾名思义，Components元素下不能再跟着Components元素。它在PMD扫描过程中如果被匹配上，会输出这样的报告：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<?xml version="1.0" encoding="UTF-8"?>
<pmd version="5.4.2" timestamp="2016-06-23T23:06:04.120">
    <file name="/Users/qianyan/github/sonar/sonar-custom/src/test/resources/wrong-syntax-but-not-csm.xml">
        <violation beginline="4"
                   endline="4"
                   begincolumn="5"
                   endcolumn="17"
                   rule="ComponentsMustNotBeFollowedByComponentsRule"
                   ruleset="ExamplePmdRuleset"
                   priority="1">
            Components tags followed by components tag found!
        </violation>
    </file>
    <file name="/Users/qianyan/github/sonar/sonar-custom/src/test/resources/wrong-syntax.csm.xml">
        <violation beginline="4"
                   endline="4"
                   begincolumn="5"
                   endcolumn="17"
                   rule="ComponentsMustNotBeFollowedByComponentsRule"
                   ruleset="ExamplePmdRuleset"
                   priority="1">
            Components tags followed by components tag found!
        </violation>
    </file>
</pmd>

PMD报告转化为Sonar的Issue

由于PMD是由Java编写的，所以我们可以在代码中调用PMD这个类net.sourceforge.pmd.PMD根据我们写好的PMD规则，来扫描Sonar指定的目录及其文件。最后，将PMD输出的XML格式的报告转化成Sonar能够理解的Issue。

代码如下：

1
2
3
4
5

public void execute(SensorContext context) {
        File reportFile = new File(context.fileSystem().workDir(), "report.xml"); // 1
        runPMD(context, reportFile); // 2
        convertToIssues(context, doc(reportFile)); // 3
}

1. 指定PMD输出文件的路径；
2. 运行PMD，输出XML格式的报告到1指定的文件当中；
3. 解析报告，并转化为Issue。

下面我们一步步来解释对应的代码：

• runPMD

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

  private void runPMD(SensorContext context, File reportFile) { final String dir = context.settings().getString("sonar.sources"); final File file = new File(dir); String[] pmdArgs = { "-f", "xml", "-R", "custom-pmd-rules.xml", "-d", dir, "-r", reportFile.getAbsolutePath(), "-e", context.settings().getString("sonar.sourceEncoding"), "-language", "xml", "-version", "1.0" }; final ClassLoader loader = Thread.currentThread().getContextClassLoader(); try { Thread.currentThread().setContextClassLoader(getClass().getClassLoader()); PMD.run(pmdArgs); } finally { Thread.currentThread().setContextClassLoader(loader); } }

  我们通过PMD这个类运行pmdArgs。这里值得注意的是自SonarQube 5.6之后，我们可以通过context.settings()来获取工程的配置了，而不像以前那样依赖注入Settings对象了。

至于 Thread.currentThread().setContextClassLoader(getClass().getClassLoader());这步操作和Sonar使用独立的classLoader加载自己的类有关。

• convertToIssues

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30

  private void convertToIssues(SensorContext context, Document doc) { final Element root = doc.getRootElement(); final List<Element> files = root.elements("file"); for (Element file : files) { final List<Element> violations = file.elements("violation"); final String filePath = file.attributeValue("name"); final FileSystem fs = context.fileSystem(); final InputFile inputFile = fs.inputFile(fs.predicates().hasAbsolutePath(filePath)); if (inputFile == null) { LOG.info("fs predicates that there is no {}", filePath); continue; } for (Element violation : violations) { final String rule = violation.attributeValue("rule"); final int beginLine = Integer.parseInt(violation.attributeValue("beginline")); final int endLine = Integer.parseInt(violation.attributeValue("endline")); final int beginColumn = Integer.parseInt(violation.attributeValue("begincolumn")); final int endColumn = Integer.parseInt(violation.attributeValue("endcolumn")); final NewIssue newIssue = context.newIssue() .forRule(RuleKey.of(CustomRulesDefinition.REPOSITORY_KEY, rule)); final NewIssueLocation newIssueLocation = newIssue .newLocation() .on(inputFile) .at(inputFile.newRange(beginLine, beginColumn, endLine, endColumn)) .message(violation.getText()); newIssue.at(newIssueLocation).save(); } } }

  这里主要是对PMD生成XML报告的解析和转换。比较需要关注是这块代码：

  1 2 3 4 5

  final InputFile inputFile = fs.inputFile(fs.predicates().hasAbsolutePath(filePath)); if (inputFile == null) { LOG.info("fs predicates that there is no {}", filePath); continue; }

  InputFile这是Sonar定义的合法的待扫描文件。举个例子：我们定义了一门基于XML的DSL，其文件的后缀是csm.xml，那么合法的待扫描文件就只能是这个后缀的文件了。像上述PMD输出的那份报告中出现的

  1	<file name="/Users/qianyan/github/sonar/sonar-custom/src/test/resources/wrong-syntax-but-not-csm.xml">

  就是不合法的。这个文件是以xml作为后缀的，PMD肯定可以扫描它，但是对于Sonar而言，它并不是InputFile（如果不作处理，就会返回null），所以我们需要在转换为Issue之前剔除掉。

最后，不要忘记保存，newIssue.at(newIssueLocation).save();。

Issue呈现在UI上，是这样的：

第八步 注册所有组件

现在所有的组件已经就绪，是时候将这些组件注册进插件当中了。还记得第一步我们创建的CustomPlugin.java? 所有上述组件，包括Language、Rules、Profiles以及Sensor都得在这个类中进行注册。代码如下：

1
2
3
4
5
6
7
8
9
10
11
12

package com.lambeta;

import org.sonar.api.Plugin;

public class CustomPlugin implements Plugin {
    public void define(Context context) {
        context.addExtension(CustomLanguage.class)
                .addExtension(CustomRulesDefinition.class)
                .addExtension(CustomProfileDefinition.class)
                .addExtension(CustomSensor.class);
    }
}

到此，这个插件算是写完了。那么接下来的问题就是如何运行它？

使用插件扫描工程

下载sonarqube docker镜像

最易于调试的地方莫过于本地了。如果机器是Mac，建议使用Kitematic这个Docker的客户端下载sonarqube的官方镜像，同时将映射的Port定在9000端口上，启动该镜像的容器实例。

构建和Copy插件包

在插件的工程根目录下，运行

1

mvn clean package

然后执行

1

cp target/sonar-custom-1.0-SNAPSHOT.jar /Users/your-name/Documents/Kitematic/sonarqube/opt/sonarqube/extensions/plugins

如果plugins目录不存在，可以手动创建。执行完命令之后，重启容器。

安装Maven的sonar插件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

<!-- settings.xml -->
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
    https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository/>
    <interactiveMode/>
    <usePluginRegistry/>
    <offline/>
    <pluginGroups>
        <pluginGroup>org.sonarsource.scanner.maven</pluginGroup>
    </pluginGroups>
    <profiles>
        <profile>
            <id>sonar</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <properties>
                <!-- Optional URL to server. Default value is http://localhost:9000 -->
                <sonar.host.url>
                  http://192.168.99.100:9000
                </sonar.host.url>
            </properties>
        </profile>
     </profiles>
    <servers/>
    <mirrors/>
    <proxies/>
    <activeProfiles/>
</settings>

将这个settings.xml的文件放到~/.m2下。

运行Maven sonar:sonar

1

mvn sonar:sonar -Dsonar.sources=src/test/resources/ -Dsonar.language=custom-key -X

src/test/resources目录展开如下：

1
2
3
4

src/test/resources
├── right-syntax.csm.xml
├── wrong-syntax-but-not-csm.xml
└── wrong-syntax.csm.xml

然后，根据输出提示，访问
http://192.168.99.100:9000/dashboard/index/com.lambeta:sonar-custom

总结

[1] 官方教程
[2] 博客
[3] 官方样例
[4] 本文样例

记忆用的Mindmap

标准的leiningen的工程目录结构

当我们使用lein new your-project-name之后，工程目录结构如下：

问题

本地使用maven编译和运行时一切都正常，但是通过ci的方式，编译、打包、发布到部署环境，运行时抛出了一条一眼便知是关于JDK版本的错误。

错误是这个样子：

1
2

java.lang.NoSuchMethodError: java.util.concurrent.ConcurrentHashMap.keySet() 
Ljava/util/concurrent/ConcurrentHashMap$KeySetView;

报的是的NoSuchMethodError的错误，且是关于java.util.concurrent.ConcurrentHashMap的。所以不难排查出原因是ci使用了JDK 8来进行编译，导致生成的字节码包含了JDK 8更改的新方法keySet——ConcurrentHashMap$KeySetView这个新增内部类作为其返回值的类型。

为了进一步验证部署服务器上的class文件都是JDK 8编译的，我使用javap这个JDK自带的工具做了如下的验证：

1

javap -v a.class |grep major

返回的结果是

1

major version: 51

问题初露端倪，51对应的JDK版本号应该是1.7（或者7），52才是JDK 8的major版本。这里出现了两个疑惑：

• 为什么ci使用JDK 8编译的class会是JDK 7的编译结果？
• 既然是JDK 7编译的class文件，那为何会出现JDK 8才有的内部类？

先看第一个疑惑。之前说到ci也是通过maven compiler plugin进行编译的，pom.xml中可以配置language level如下：

1
2
3
4
5
6
7
8
9

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.5.1</version>
    <configuration>
      <source>1.7</source>
      <target>1.7</target>
    </configuration>
</plugin>

这实际对应于javac的-source和-target参数，那么这两个参数具体代表什么呢？

1
2
3

$ javac -help
-source <release>          Provide source compatibility with specified release
-target <release>          Generate class files for specific VM version

source参数指的是源代码级别的语法兼容，而target参数指的是生成release版本的兼容性的class文件，不过只确保目标VM能够加载class文件，却无法保证运行时的正确性。接下来，我们尝试使用javac加上这些参数来编译源码。

首先我们写一段程序，如下：

1
2
3
4
5
6
7
8
9
10

// App.java
package com.lambeta;
import java.util.concurrent.ConcurrentHashMap;

public class App {
    public static void main(String[] args) {
        ConcurrentHashMap map = new ConcurrentHashMap();
        map.keySet();
    }
}

我本机的java版本是1.8，直接使用javac来编译App.java，结果如下

1
2
3

$ javac App.java
$ javap -v App.class |grep major
 major version: 52

如果指定source和target参数，再用javac编译App.java

1
2
3
4
5
6
7
8

$ java -version
java version "1.8.0_45"
...
$ javac -source 7 -target 7 App.java
warning: [options] bootstrap class path not set in conjunction with -source 1.7
1 warning
$ ls
App.class App.java

这里有个警告，我们暂时不看。先使用javap反编译App.class，观察major version以及keySet()这个方法的返回值。

1
2
3
4
5
6
7
8

$ javap -v App.class
...
major version: 51
...
9: invokevirtual #4                  
// Method java/util/concurrent/ConcurrentHashMap.keySet:()
Ljava/util/concurrent/ConcurrentHashMap$KeySetView;
...

这样，第二个疑惑也解开了。可以初步得出一个结论。

小结

在javac指定了这些参数，降低版本号来编译，会导致生成class文件被标识为较低版本以供指定的JVM加载。但是，基于JDK 8的bootstrap class编译而成的keySet()方法，其返回值依旧是JDK 8中ConcurrentHashMap$KeySetView这个新增内部类。运行时，1.7的JVM尝试加载这个class文件，一定找不到KeySetView作为返回值的keySet()方法，出错。

解决方式

既然知道错在那里，就比较容易寻找到解决方案了。

• 编译期间，替换掉bootstrap class
• 使用父类/接口替换子类，即ConcurrentMap替换ConcurrentHashMap声明

编译期间，替换掉bootstrap clas

javac编译时，可以指定bootclasspath，来替换默认的加载路径，如下：

1
2
3
4
5

javac -bootclasspath /Library/Java/JavaVirtualMachines/jdk1.7.0_60.jdk/Contents/Home/jre/lib/rt.jar \
-source 7 -target 7 App.java
// or
javac -Xbootclasspath:/Library/Java/JavaVirtualMachines/jdk1.7.0_60.jdk/Contents/Home/jre/lib/rt.jar \
-source 7 -target 7 App.java

这时候，再去看看反编译的结果，就会是这样：

1
2
3
4
5

...
major version: 51
...
9: invokevirtual #4                  
// Method java/util/concurrent/ConcurrentHashMap.keySet:()Ljava/util/Set;

此时major是51(JDK 7），而keySet()的返回值也是JDK 7中的java.util.Set类型了。

使用父类/接口替换子类，即ConcurrentMap替换ConcurrentHashMap声明

上一种方案虽然可行，但是却不实用——因为不能要求ci服务器上有两个不同版本的JDK，也不能要求在maven构建时传递与安装路径如此紧耦合的值作为bootclasspath的参数值。所以可以采取将具体实现类的声明替换成为其接口的方式，如下：

1
2
3
4
5
6
7
8
9
10

package com.lambeta;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;

public class App {
    public static void main(String[] args) {
        ConcurrentMap map = new ConcurrentHashMap();
        map.keySet();
    }
}

这样编译好的字节码中就不会有ConcurrentHashMap$KeySetView这样的返回值类型了。在JDK 7上运行时，JVM动态调用的一定是ConcurrentHashMap的keySet():java.util.Set方法了。

结论

• 保证编译、打包环境和最终部署环境JDK版本的一致性
• 如果无法保证，就尽量面向接口编程，尤其是JDK中提供的类。原因是接口不易改变，而实现类遵循“宽收严发”原则，方法的入参和出参都是易变的。

参考链接
[1] Using Java 7 to target much older JVMs

问题

最近遇到一个问题，使用Java写某个DSL标记语言X的parser（解析器）Maven插件的时候，对外暴露一个名为Callback的接口和一个待实现的方法*getHTML()*——基于调用处传入的文件名srcX构造出HTML文件的输出路径（其实此处的Callback就是一个闭包，文件名是一个自由变量）。大致代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

parser.parse(srcX, new Callback() {
    @Override
    public FileWriter getHTML() {
        return new FileWriter(outputPath(suffix(srcX, "html")));
    }
});

private String suffix(String filename, String suffix) {
	return Joiner.on(".").join(filename, suffix);
}

//这里假设输入和输出根路径地址已知
private File outputPath(String file) {
	return new File(
	           file.replace(srcDir.getAbsolutePath(), //srcDir: File
	             outputDir.getAbsolutePath())); //outputDir: File
}

目前为止还没有任何问题。但若是运行时，这段程序很可能抛出异常java.io.FileNotFoundException: your-file-name (No such file or directory)。原因在于file的路径当中可能存在多级父级目录，例如：outputDir/p1/p2/srcX.html，那么当FileWriter尝试创建srcX.html就会失败。此时最简单的方法就是提前创建好所有的父级目录，于是*outputPath()*方法会变成下面这样：

1
2
3
4
5
6
7
8

private File outputPath(String file) {
    File outputFile = new File(
            file.replace(srcDir.getAbsolutePath(),
                    outputDir.getAbsolutePath()));
    outputFile.getParentFile().mkdirs(); //创建可能不存在的父级目录

    return outputFile;
}

似乎这段程序可以正常工作了，但是创建文件夹这样的操作是可能失败的。所以我们需要关注是否创建成功，若失败，则写入Log文件当中。修改程序如下：

1
2
3
4
5
6
7
8
9
10
11
12

private File outputPath(String file) {
    File outputFile = new File(
            file.replace(srcDir.getAbsolutePath(),
                    outputDir.getAbsolutePath()));
    final File parentDirs = outputFile.getParentFile();
    if (!parentDirs.exists()) {
        if (!parentDirs.mkdirs()) {//创建可能不存在的父级目录
            getLog().error("Cannot create parent dirs for {}", outputFile);
        }
    }
    return outputFile;
}

注意
这里我们需要先判断父级目录是否存在，即parentDirs.exists()？可是*parentDirs.mkdirs()不是直接返回boolean值来表示是否创建成功吗？是这样么？这儿有mkdirs()*方法的说明：

public boolean mkdirs()
Creates the directory named by this abstract pathname, including any necessary but nonexistent parent directories. Note that if this operation fails it may have succeeded in creating some of the necessary parent directories.
Returns:
true if and only if the directory was created, along with all necessary parent directories; false otherwise

也就是说只有当这个目录及其所有的父级目录都被创建时，才返回true，反之返回false。照这个推论，如果所有目录事先已经存在了，这个方法应该也会返回true，毕竟都被创建过了嘛。但是只要稍微看一眼源码，你就会发现事实并非如此：

1
2
3
4

//mkdirs源码
if (exists()) {
    return false;
}

所以这里需要特别强调was created是一种操作，如果没有进行这个操作，那就不能算这个方法成功。

前面已经提到过，我需要写一个maven的插件，所以最好在这种导致程序崩溃的地方抛出一个maven中通用的异常MojoExecutionException。这样，更改代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13

private File outputPath(String file) {
    File outputFile = new File(
            file.replace(srcDir.getAbsolutePath(),
                    outputDir.getAbsolutePath()));
    final File parentDirs = outputFile.getParentFile();
    if (!parentDirs.exists()) {
        if (!parentDirs.mkdirs()) {//创建可能不存在的父级目录
            getLog().error("Cannot create parent dirs for {}", outputFile);
            throw new MojoExecutionException("Cannot create parent dirs");
        }
    }
    return outputFile;
}

此时，问题才显出端倪——异常MojoExecutionException是一个受检的异常(checked Exception)，它间接继承自java.lang.Exception。可是我们的getHTML()方法并没有在签名中抛出任何异常，编译无法通过。那唯一的办法就是try…catch了，但是我不应该捕获自己刚刚抛出来的异常，否则抛出受检异常的意义何在？

这时，自然而然会想到，将方法签名改成getHTML() throws MojoExecutionException。确实可行，但是并不合适，因为MojoExecutionException只是Maven插件规定的异常，而getHTML()则是一个对外暴露的API，不应该依赖于某个具体的异常。所以我将异常扩大化：getHTML() throws Exception，这样做的好处很明显，坏处也很显眼。

好处

1. 牢记《Unix编程艺术》中的“宽收严发”原则。即子类实现父类、接口的方法，入参可以扩大，出参可以缩小。举个例子：父类、接口有个方法

1

public Object something(HashMap map) throws Exception

那么子类实现这个方法可以这样写

1
2

public String something(Map map)
                  throws ExecutionException, NoSuchMethodException

这里，入参是HashMap，出参是Object和Exception。入参扩大，所以子类出现了Map；出参缩小，所以子类出现了String和ExecutionException和NoSuchMethodException。同理，此处getHTML() throws Exception由子类实现的形式可以是getHTML() throws MojoExecutionException。

坏处

1. 不管getHTML()是否需要抛出异常，你都得在实现代码中抛出异常；
2. 由于对外表现的是抛出较宽泛的Exception，所以丧失了对于具体受检 (checked exception)异常进行检查的好处。

这里有个JDK中比较类似的例子，就是关于Runnable和Callable接口的设计问题：

1
2
3
4
5
6
7

public interface Runnable {
    public void run();
}

public interface Callable<V> {
    V call() throws Exception;
}

它们就是两个极端，Runnable必须将受检的异常转换成非受检(unchecked exception)或者发明一种方式来将异常暴露给调用者；Callable就是无论如何都得抛出异常，而且迫使用户去捕获一个较宽泛的异常。

解决方式

这个时候，泛型就派上用场了。

1
2
3
4
5
6

interface Callback<E extends Exception> {
    FileWriter getHTML() throws E;
}

//interface parser
public <E extends Exception> void parse(String srcX, Callback<E> cb) throws E;

通过这种方式，我们可以捕获具体的异常：

1
2
3
4
5
6
7
8
9
10

try {
    parser.parse(srcX, new Callback<MojoExecutionException>() {
        @Override
        public FileWriter getHTML() throws MojoExecutionException {
            return new FileWriter(outputPath(suffix(srcX, "html")));
        }
    });
} catch (MojoExecutionException e) {
    getLog().error("Failed to execute. {}", e);
}

使用lambda表达式可以简化成下面的模样：

1
2
3
4
5

try {
    parser.parse(srcX, (Callback<MojoExecutionException>) () -> new FileWriter(outputPath(suffix(srcX, "html"))));
} catch (MojoExecutionException e) {
    getLog().error("Failed to execute. {}", e);
}

我们解决了迫使用户去捕获一个较宽泛的异常的问题，但是无论如何都得抛出异常这个问题还是没有得到解决。或许我们需要一个像是throws Nothing一样的语法，表示什么也没有抛出来。我们知道RuntimeException是非受检的异常(unchecked exception)，所以throws RuntimeException就表明这个异常跟没有抛出异常一样，不需要捕获。如下：

1
2
3
4
5
6
7
8

parser.parse(srcX, new Callback<Nothing>() {
    @Override
    public FileWriter getHTML() throws Nothing {
        return new FileWriter(outputPath(suffix(srcX, "html")));
    }
});

public abstract class Nothing extends RuntimeException {}

走到这一步，我们算是较为完全地解决了匿名内部类的异常处理问题。

异常透明化

With the throws type parameter on the Block interface, we can now accurately generify over the set of exceptions thrown by the Block; with the generic forEach method, we can mirror the exception behavior of the block in forEach(). This is called exception transparency because now the exception behavior of forEach can match the exception behavior of its block argument. Exception transparency simplifies the construction of library classes that implement idioms like internal iteration of data structures, because it is common that methods that accept function-valued arguments will invoke those functions, meaning that the library method will throw a superset of the exceptions thrown by its function-valued arguments.

1
2
3
4
5
6
7

interface Block<T, throws E> {
    public void invoke(T element) throws E;
}

interface NewCollection<T> {
    public<throws E> forEach(Block<T, throws E> block) throws E;
}

异常透明化，简单来讲，就是调用者的签名中的异常完全由它的函数值(function-valued)的参数决定，所有这些调用者最终的异常都会是该函数值所注异常的超集。

异常透明化就是用来解决我们常用的通过内部类模拟闭包调用时异常处理的手法了。

闭包的定义
一个包含了自由变量的开发表达式，和该自由变量的约束环境组合之后，产生了一种封闭的状态。

参考链接
[1] Exception Transparency
[2] Throwing Checked Exceptions from Anonymous Inner Classes

搭建 Node.js 开发环境

NVM安装

1. Download nvm-noinstall.zip
2. Update the system environment variables:
NVM_HOME, NVM_SYMLINK (C:\Users\Program Files\nodejs This directory should not exist in previously.)
3. Create settings.txt file

root: C:\Users\qinayan\bin\nvm
path: C:\Program Files\nodejs
arch: 64
proxy: none

详情请参考 如何安装nvm-windows
另外别忘了在NVM_HOME目录中运行install命令

node.js安装

1
2
3
4
5
6
7
8
9
10
11
12
13
14

安装特定版本的nodejs
> nvm install 0.12.10
安装最新版本的nodejs
> nvm install latest
查看本地安装了哪些nodejs
> nvm ls
 * 5.7.1 (Currently using 64-bit executable)
   0.12.10
验证安装完成   
> node -v
  v5.7.1
> node
...> console.log("hello world");
  hello world

模块

每个文件就是一个模块，文件的路径名就是模块的名字

require

类似于Java中的import关键字，导入不同的包。

1

var express = require('express');

exports

导出模块的公有方法和属性。可以理解为Java中的public方法和属性。

1
2
3
4
5
6
7
8

// util.js
exports.greeting = function(name) {
   return "hello, " + name;   
}
// index.js
var greeting = require('./util').greeting;
console.log(greeting("lambeta"))
>  hello, lambeta

module

包含当前模块的一些信息，常用的做法是替换当前模块的导出对象。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// util.js
console.log(module)
>>
Module {
  id: '.',
  exports: { greeting: [Function] },
  parent: null,
  filename: 'C:\\Users\\qianyan\\Projects\\lesson2\\util.js',
  loaded: false,
  children: [],
  paths:
   [ 'C:\\Users\\qianyan\\Projects\\lesson2\\node_modules',
     'C:\\Users\\qianyan\\Projects\\node_modules',
     'C:\\Users\\qianyan\\node_modules',
     'C:\\Users\\node_modules',
     'C:\\node_modules' ] }

// replace with obj
module.exports = {greeting: {}};
>>
Module {
  id: '.',
  exports: { greeting: {} },
  parent: null,
  filename: 'C:\\Users\\qianyan\\Projects\\lesson2\\util.js',
  loaded: false,
  children: [],
  paths:
   [ 'C:\\Users\\qianyan\\Projects\\lesson2\\node_modules',
     'C:\\Users\\qianyan\\Projects\\node_modules',
     'C:\\Users\\qianyan\\node_modules',
     'C:\\Users\\node_modules',
     'C:\\node_modules' ] }

module initialize发生的时机

模块中的代码只会在首次被使用的时候才会执行一次，同时初始化该模块的导出对象，之后导出对象会被缓存到内存当中，供任意使用。

小结

• NVM是Node Version Manager，管理node的版本的工具。使用NVM，可以保证同一个操作系统下，多个不同版本的node得以共存。
• node作为javascript的解析器，可以在终端下进入交互式模式(repl read-eval-print-loop)，很方便快速地反馈我们程序的结果。
• nodeJS的模块系统实现了CMD标准，即CommonJS Module Definition标准；而对于运行在浏览器上的javascript的模块化，因为需要异步加载js文件，所以由require.js实现了AMD (Asynchronous Module Definition)标准

1
2
3
4
5
6
7
8
9
10
11
12

CMD
require('express')

AMD
define("alpha", ["require", "exports", "beta"],
function (require, exports, beta) {
       exports.verb = function() {
           return beta.verb();
           //Or:
           return require("beta").verb();
       }
});

问题

• 是否可以使用require('./data.json')将json文件引入到我们的程序当中呢？
• 有两个js文件同时引入了data.json，先执行a.js，后执行b.js。下面的程序会输出什么？

  1 2 3 4 5 6 7 8 9 10

  //data.json {"hello": "world"} //a.js var data = require('./data.json'); data = {}; //b.js var data = require('./data.json'); console.log(data)

代码组织

模块解析路径

node_modules

不想直接require文件路径名，因为这样一旦所依赖的文件路径发生变化，牵扯的文件会很多。所以我们需要一个约定的根目录。这个根目录就是node_modules
以这个文件的路径为例：C:\\Users\\qianyan\\Projects\\lesson2\\util.js，node搜索的路径如下。

1
2
3
4
5
6

paths:
  [ 'C:\\Users\\qianyan\\Projects\\lesson2\\node_modules',
    'C:\\Users\\qianyan\\Projects\\node_modules',
    'C:\\Users\\qianyan\\node_modules',
    'C:\\Users\\node_modules',
    'C:\\node_modules' ]

NODE_PATH

我们知道java中依赖包的搜索路径是通过classpath这个JVM的参数控制的。其实node也有这样的变量提供支持。这个变量就是NODE_PATH
windows下

1
2
3
4

cmd
set NODE_PATH="your_path"
powershell
env:NODE_PATH="your_path"

NODE_PATH中的路径被遍历是发生在从项目的根位置递归搜寻 node_modules 目录，直到文件系统根目录的node_modules，如果还没有查找到指定模块的话，就会去 NODE_PATH中注册的路径中查找。

内置模块

如fs, http等，不做路径解析就直接使用其导出对象require('fs'), require('http')

Package（包）

包就是封装多个子模块，同时提供入口的大模块。这个大模块的功能是内聚的。举个例子：

1
2
3
4
5
6

C:\USERS\QIANYAN\PROJECTS\LESSON2
└───plane
        body.js
        engine.js
        main.js
        wing.js

其中plane目录定义了一个包，其中包含了4个子模块。main.js作为入口模块，如下：

1
2
3
4
5
6
7
8
9
10

var engine = require('./engine');
var wing = require('./wing');
var body = require('./body');

exports.plane = {
    type: "747",
    engine: engine,
    wing: wing,
    body: body
}

其他模块需要使用plane这个包时，得使用require('./plane/main')才行。不过，这里有两种方法可以省去写文件名main。

1. index.js

这里有个约定，如果将main.js重命名成index.js，那么就不需要写出文件名字，直接require('./plane')就可以了。

这样模块显得更内聚，和Clojure中的(use namespace)的用法类似。以下两条语句等价。

1
2

require('./plane/main')
require('./plane')

2. package.json

如果想自定义入口模块的文件名和存放位置，就需要在包目录下包含一个package.json文件，并在其中指定入口模块的路径。上例中的模块可以重构如下。

1
2
3
4
5
6
7
8
9
10
11

C:\USERS\QIANYAN\PROJECTS\LESSON2\PLANE
│   package.json //包描述文件
│
├───doc //文档
├───lib //API文件
│       body.js
│       engine.js
│       main.js
│       wing.js
│
└───tests //测试文件

其中package.json内容如下。

1
2
3
4

{
    "name": "plane",
    "main": "./lib/main.js" //这里入口文件的名字可以按自己的喜好更改
}

如此一来，就同样可以使用require(‘./lib/plane’)的方式加载模块。NodeJS会根据包目录下的package.json找到入口模块所在位置。

命令行程序

node.js的程序是跑在命令行之中的，命令行程序长得类似cmd --name=value这样的形式。

创建目录

在windows下创建一个greeting程序的目录，如下：

1
2
3
4
5
6
7
8
9
10
11
12
13

C:\USERS\QIANYAN\PROJECTS\LESSON2\GREETING
│   package.json
│   README.md
│
├───bin
│       greeting.cmd
│
├───doc
├───lib
│       index.js
│
├───node_modules
└───tests

package.json的内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "name": "greeting",
  "version": "1.0.0",
  "description": "say hi to everyone",
  "main": "lib/index.js",
  "directories": {
    "doc": "doc",
    "test": "tests"
  },
  "bin": {
    "greeting": "bin/greeting.cmd"  
  },
  "scripts": {
    "test": "node test"
  },
  "author": "lambeta",
  "license": "MIT"
}

在windows下，如果我们想要实现cmd –name=value的效果，就必须使用cmd后缀的文件，如下：

1
2

//greeting.cmd
@node "lib/index.js" %*

我们实现一个接受人的名字作为参数的命令行程序lib/index.js，如下：

1

console.log('hello,', process.argv[2]);

到这里，可以直接这样运行./bin/greeting.cmd lambeta，输出hello, lambeta。不过，还是没有预期的样子。

npm link

我们再运行一条npm的命令

1
2
3

> npm link
C:\Program Files\nodejs\greeting -> C:\Program Files\nodejs\node_modules\greeting\bin\greeting.cmd
C:\Program Files\nodejs\node_modules\greeting -> C:\Users\qianyan\Projects\lesson2\greeting

这条命令帮助我们设置两个软链接。第一个链接使得我们可以直接运行greeting lambeta；第二个则在全局范围内，其他的模块得以引入greeting这个包。
此时，我们可以直接使用greeting lambeta来运行程序了

依赖第三方库

为了实现真正的cmd –name=value，我们使用一个第三方库yargs。

1. 安装yargs: npm install yargs –save
2. 修改index.js文件如下

   1 2	var argv = require('yargs').argv; console.log('hello,', argv.name);

3. 运行

   1 2	> greeting --name=lambeta hello, lambeta

最后再来看看一个完整的node.js的整体结构

1
2
3
4
5
6
7
8
9
10
11
12
13

C:\USERS\QIANYAN\PROJECTS\LESSON2\GREETING
│   package.json //包描述文件
│   README.md    //说明文件
│
├───bin
│       greeting.cmd //命令行相关代码
│
├───doc   //文档
├───lib   //API代码
│       index.js
│
├───node_modules //第三方依赖
└───tests //测试

小结

• 按照标准目录结构
• 分模块管理项目
• 使用NPM管理第三方模块和命令行程序
• 使用package.json描述项目信息和依赖

问题

• 下载一个第三方命令行程序到本地npm install es-checker，不要使用-g参数，如何运行起来这个程序？
• 了解一下npm scripts，在上题的基础上，添加包含下面的内容的package.json，运行npm test。思考这样做是否可行？

  1 2 3 4 5 6

  //package.json { "scripts": { "test": "es-checker" } }

文件操作

前置条件：安装Windows上的离线文档工具

文件操作相关的API

buffer对象（数据块）

Javascript语言本身只支持字符串操作，没有提供针对二进制数据流的操作。NodeJS提供了一个与String对等的全局对象Buffer. Buffer和整数的数组很类似，但是它是固定长度，一旦创建就不能修改。

1
2
3
4
5
6
7
8

var bin = new Buffer('hello', 'utf8');// <Buffer 68 65 6c 6c 6f>
bin.toString(); //'hello'
var bin = new Buffer([ 0x68, 0x65, 0x6c, 0x6c, 0x6f ]);
bin.toString(); //'hello'

var bin = new Buffer([ 0x68, 0x65, 0x6c, 0x6c, 0x6f ]);
var dump = new Buffer(bin.length);
bin.copy(dump);

stream模块（数据流）

Stream是一个抽象的接口，所有的stream都是EventEmitter的实例。
当内存中无法一次装下需要处理的数据时，或者一边读取一边处理更加高效时，我们就需要用到数据流。NodeJS中通过各种Stream来提供对数据流的操作。

1
2
3
4
5
6
7
8
9
10

var fs = require('fs');
var readStream = fs.createReadStream('README.md'); //readStream是EventEmitter的实例。

readStream.on('data', function(chunk) {
   console.log(chunk.toString());
});

readStream.on('end', function() {
   console.log('end.');
});

fs模块

NodeJS通过fs内置模块提供对文件的操作。fs模块提供的API基本可以分为以下三类：

• 文件属性读写。
  其中常用的有fs.stat、fs.chmod、fs.chown等等。

• 文件内容读写。
  其中常用的有fs.readFile、fs.readdir、fs.writeFile、fs.mkdir等等。

• 底层文件操作。
  其中常用的有fs.open、fs.read、fs.write、fs.close等等。

我们可以通过require('fs')来引用这个模块，而且该模块下的每个方法都有同步和异步的形式。

1
2
3
4
5
6
7
8
9
10
11
12

// read sync
var file = fs.readFileSync(process.cwd() + '/README.md', 'utf8');
console.log(file);

// read async
fs.readFile(process.cwd() + '/README.md', 'utf8', function (err, data) {
    if(err) {
        console.log(err);
        return;
    }
    console.log(data)
});

一段遍历当前目录的程序

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

var fs = require('fs');
var p = require('path');

function recursiveRead(path) {
    if(fs.statSync(path).isFile()) {
        console.log("File:", path);
    } else {
        fs.readdir(path, function(err, files) {
            if(err) {
                console.log(err);
                return;
            }

            files.forEach(function(file) {
                var absPath = p.join(path, file);
                if(fs.statSync(absPath).isFile()) {
                    console.log("File:", absPath);
                } else {
                    console.log("Directory:", absPath);
                    recursiveRead(absPath);
                }
            });
        });  
    }
}
recursiveRead(__dirname); //全局的对象__dirname，当前脚本执行的目录。

path模块

和java类似，NodeJS提供path来简化对文件路径的操作。

• path.normalize

  1 2	var path = require('path'); path.normalize('foo/bar/..'); // 'foo'

• path.join & path.sep

  1 2	path.join('foo', '/bar/', '/baz', 'par/') // 'foo\\bar\\baz\\par\\' path.sep // '\\'

• path.extname

  1	path.extname('node.js') //'.js'

小结

• Buffer提供了NodeJS操作二进制的机制；
• Stream是一个抽象的接口，每种stream都是EventEmitter的实例。当我们在读取大文件时，可以使用数据流一边读取，一边处理；
• fs提供了文件属性读写，内容读写以及底层文件操作。
• 不要使用字符串拼接，使用path简化操作

问题

• 使用fs的API创建一个copy的函数；
• NodeJS对文本编码的处理；
• 使用第三方包findit重写遍历当前目录的程序。

网络操作

简单的HTTP服务器

使用http实现一个简单的HTTP服务器。

1
2
3
4
5

var http = require('http');
http.createServer(function(req, res) {
    res.writeHead(200, {'Content-type': 'text/plain'});
    res.end('Hello Node.js');
}).listen(12306);

http模块

http模块提供两种使用方式：

• 作为服务端使用时，创建一个HTTP服务器，监听HTTP客户端请求并返回响应；
• 作为客户端使用时，发起一个HTTP客户端请求，获取服务端响应。

先创建一个HTTP服务器

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

//http-server.js
var http = require('http');

http.createServer(function(req, res) {
   var body = [];
   res.writeHead(200, {'Content-type': 'text/plain'});

   req.on('data', function(chunk) {
      res.write(chunk);
      body.push(chunk);
   });

   req.on('end', function() {
      body = Buffer.concat(body);
      console.log(body.toString());
      res.end();
   })
}).listen(12306);

再创建一个HTTP客户端

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

//http-client.js
var http = require('http');
var options = {hostname: 'localhost',
    port: 12306,
    method: 'POST',
    headers: {
        'Content-type': 'text/plain'
    }};
var req = http.request(options, function(res) {
    res.on('data', function(chunk) {
       console.log('res:', chunk.toString());
    });
});

req.write('hello world');
req.end();

url模块

• parse
  使用url解析成URL对象

  1 2 3 4 5 6 7 8 9 10 11 12 13 14

  > url.parse('http://user:pass@host.com:8080/p/a/t/h?query=string#hash Url { protocol: 'http:', slashes: true, auth: 'user:pass', host: 'host.com:8080', port: '8080', hostname: 'host.com', hash: '#hash', search: '?query=string', query: 'query=string', pathname: '/p/a/t/h', path: '/p/a/t/h?query=string', href: 'http://user:pass@host.com:8080/p/a/t/h?query=string#hash' }

• format
  format方法允许将一个URL对象转换为URL字符串

  1 2 3 4 5 6 7

  > url.format({ protocol: 'http:', host: 'www.example.com', pathname: '/p/a/t/h', search: 'query=string' }); //'http://www.example.com/p/a/t/h?query=string'

• resolve
  resolve方法拼接两个URL

  1 2 3 4

  > url.resolve('http://www.baid.com/path', '../www.google.com') 'http://www.baid.com/www.google.com' > url.resolve('http://example.com/one', '/two') 'http://example.com/two'

querystring

1
2

> querystring.parse('foo=bar&baz=qux&baz=quux&corge');
{ foo: 'bar', baz: [ 'qux', 'quux' ], corge: '' }

小结

• http模块支持服务端模式和客户端模式两种使用方式；
• request和response对象除了用于读写头数据外，可以当作数据流来操作；
• url.parse方法加上request.url属性是处理HTTP请求时的固定搭配。

问题

• http模块和https模块的区别？
• 如何创建一个https服务器？

进程操作

API一览

Process

process是一个全局的对象，可以在node环境中随处访问。并且它是EventEmitter的实例。
一个进程对象里头到底包含些什么属性？

1
2
3
4

pid
stdio
argv
env

只在POSIX平台支持的函数

1
2
3
4

getuid
getgid
geteuid
getegid

进程ID、标准输入输出以及错误流、启动进程的参数、运行环境、运行时权限。

应用场景

• 获取命令行参数

  1 2 3 4 5 6 7 8

  // index.js console.log(process.argv); > node index.js hello [ 'C:\\Program Files\\nodejs\\node.exe', //node的执行路径 'C:\\Users\\qianyan\\Projects\\lesson5\\index.js', //文件路径 'hello' ] //参数

  一般获取参数的写法

  1	process.argv.splice(2)

• 退出程序
  类似Java中的System.exit(1)，当我们捕获一个异常，同时觉得程序需要立即停止时，就执行process.exit(1)来表示非正常退出。

• 控制输入和输出
  stdin是只读流，而stdout和stderr都是只写流。console.log等价于

  1 2 3

  console.log = (msg) => { process.stdout.write(`${msg}\n`); };