從官方文件去學習之FreeMarker

風象南發表於2019-02-26

一、前言

上一篇 <從現在開始，試著學會用官方文件去學習一個技術框架> 提倡大家多去從官方文件學習技術，沒有講到具體的實踐，本篇就拿一個案例具體的說一說，就是FreeMarker，選擇這個框架沒什麼特別的含義，最近要用，就拿這個做個典型。

二、套路

上篇文章最後說到技術學習沒有套路，無招勝有招，無招即是有招，解讀一下實際上就是說本身還是有些招式套路，但是要靈活運用，不要什麼都往上套，應該忘掉固有的套路，讓其化為你的一種本能，見招拆招。

下面就介紹一種常規學習套路給大家，如下圖：

下面就根據上面的套路結合FreeMarker官網溜一遍，來學習FreeMarker，重點在前4部分，後面兩部分需要一些積累和經驗後才更容易上手，所以本篇不會重點講

三、實踐

3.1 瞭解框架

首先我們應該瞭解FreeMarker是用來幹什麼的，這時候我看開啟官網 https://freemarker.apache.org/

上圖來自官網首頁上方的導航，依次為 Home(主頁)、Manual(手冊)、JavaApi(API介面)、Contribute(貢獻)、 Report a Bug(反饋BUG)、 Download(下載) ，單詞不認識，找工具翻譯一下，沒有別的辦法，上篇也提到了。從字面意思理解可以看出跟我們有關的就是標紅的那4個，好的來看看首頁的介紹（大部分框架首頁都會有簡要介紹，說明框架的用途）：

這是首頁的兩段介紹，自行翻譯一下，這裡就不在翻譯了，解讀一下，我們從這兩段內容中可以得到如下資訊：

（1）這是一個Java模板引擎

（2）用模板語言(FTL)編寫

（3）基本思想：java或其他程式語言準備資料，FreeMarker顯示資料，配合官方給的圖，更直觀

（4）在模板中，您關注的是如何顯示資料，而在模板之外，您關注的是顯示什麼資料，這也是所有模板引擎解決的核心問題 資料與顯示分離

（5）用於MVC模式，有助於分離Java開發人員和web設計人員，設計人員不會在模板中面對複雜的邏輯，並且可以在不需要程式設計師更改或重新編譯程式碼的情況下更改頁面的外觀，這裡就說明了模板的好處，面試問你，為什麼用模板技術啊，結合上面的一點就可以完美回答這個問題了

（6）不依賴Servlet，也就是web環境和非Web環境都可以使用

（7）更多細節內容看 manual (手冊)

通過解讀官方的文件，我們就可以得到以上7個方面的資訊。也就瞭解了Freemarker的作用、基本思想、好處、應用環境，這些東西，相信在很多FreeMarker的教程中，都不會這麼詳細，而且上面的資訊基本上只要你把英文翻譯過來都可以直觀看到，我並沒有做太多總結性歸納。這是基本內容，首頁還標出了一些特性我們再來看一下

解讀一下得到的資訊如下

（1）強大的模板語言，支援條件塊、迭代、賦值、字串和算術操作等

（2）零依賴，任何輸出格式，可以從任何地方載入模板

（3）支援國際化

（4）支援xml資料模型，也就是可以將xml資料填充到模板上

（5）支援java物件暴露在模板，簡單理解模板中可以呼叫物件的方法

結合上面的基本內容和特性部分的內容，相信大家對freemarker有了較為完整的認識，包括能不能滿足自己的一些場景，也會有一些基本的判斷，方便技術選型。

3.2 Helloworld

看完基本內容，有了大致瞭解後，是不是迫不及待想去敲程式碼試一下，小階段的輸出成果更容易促使學習的動力。看文件首頁顯然沒有告訴我們怎麼用，怎麼去開始寫程式碼，但提到了更多內容看manual，那我們就點到manual去看一下

從這裡我看看到了Getting Started（開始），大部分的官網都會有Getting Started，點進去看一下，這裡要多做一件事，寫程式碼肯定要使用freemarler的jar，我們就從download去拿一下，進到download

可以看到，我們可以直接下freemarker.jar、原始碼，或者通過maven引入，這裡大家隨意，匯入工程，然後回到剛才的地方，看quick start

三塊內容

（1）模板 + 資料模型 = 輸出

（2）一睹資料模型

（3）一睹模板

分別點進去看一下，可以瞭解到

(1) 模板有表示式和指令

(2) 資料模型是樹形結果

但是我們沒有看到程式碼，只看到一段模板程式碼和最終的結果輸出，這裡沒有怎麼辦？我們再掃一眼目錄，發現這裡還有個Getting Started（一些框架官網沒有直接給demo，我們可以去框架託管程式碼(github、gitee)的地方去找一下，基本上都會有demo）

然後看一下它的分類是 Programmer's Guide(程式設計師指南)，那就應該是這裡了，點進去看一下，可以看到，除過最後最後的 Putting all together, 其他部分是使用模板的每一個步驟，分為：建立配置例項 -> 建立資料模型 -> 獲取模板 -> 合併資料模型到模板，這也是使用freemaker的基本步驟，分步驟的就不看了，我們直接看最後的Putting all together（所有合到一起的內容）

測試類

import freemarker.template.*;
import java.util.*;
import java.io.*;

public class Test {

    public static void main(String[] args) throws Exception {

        /* ------------------------------------------------------------------------ */
        /* You should do this ONLY ONCE in the whole application life-cycle:        */

        /* Create and adjust the configuration singleton */
        Configuration cfg = new Configuration(Configuration.VERSION_2_3_27);
        cfg.setDirectoryForTemplateLoading(new File("/where/you/store/templates"));
        cfg.setDefaultEncoding("UTF-8");
        cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
        cfg.setLogTemplateExceptions(false);
        cfg.setWrapUncheckedExceptions(true);

        /* ------------------------------------------------------------------------ */
        /* You usually do these for MULTIPLE TIMES in the application life-cycle:   */

        /* Create a data-model */
        Map root = new HashMap();
        root.put("user", "Big Joe");
        Product latest = new Product();
        latest.setUrl("products/greenmouse.html");
        latest.setName("green mouse");
        root.put("latestProduct", latest);

        /* Get the template (uses cache internally) */
        Template temp = cfg.getTemplate("test.ftlh");

        /* Merge data-model with template */
        Writer out = new OutputStreamWriter(System.out);
        temp.process(root, out);
        // Note: Depending on what `out` is, you may need to call `out.close()`.
        // This is usually the case for file output, but not for servlet output.
    }
}複製程式碼

資料模型

/**
 * Product bean; note that it must be a public class!
 */
public class Product {

    private String url;
    private String name;

    // As per the JavaBeans spec., this defines the "url" bean property
    // It must be public!
    public String getUrl() {
        return url;
    }

    public void setUrl(String url) {
        this.url = url;
    }

    // As per the JavaBean spec., this defines the "name" bean property
    // It must be public!
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

}複製程式碼

模板 test.ftlh

<html>
<head>
  <title>Welcome!</title>
</head>
<body>
  <h1>Welcome ${user}!</h1>
  <p>Our latest product:
  <a href="${latestProduct.url}">${latestProduct.name}</a>!
</body>
</html>複製程式碼

相信不出意外，複製貼上到自己的工程裡，就可以正常執行了，至此一個helloworld就算OK了，對於程式碼的含義，可以直接查javaApi，可以看分步驟的內容有解釋。

至此我們對freemarker應該有了更直觀的認識和理解，也基本知道了使用的套路

3.3 熟悉配置

為什麼要熟悉配置，很多框架的功能支援、效能調優實際上做的就是配置引數的調整，所以說比較重要，我們來看一下，回到manual首頁，找配置相關的字眼，發現