從官方文件去學習之FreeMarker
一、前言
上一篇 <從現在開始，試著學會用官方文件去學習一個技術框架> 提倡大家多去從官方文件學習技術，沒有講到具體的實踐，本篇就拿一個案例具體的說一說，就是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首頁，找配置相關的字眼，發現
就是它了吧，大概點進去看一下
更多的圖就不貼了，總之我們指導這裡就是介紹配置屬性的地方，詳細內容大家自己看一看，這裡有一個比較重要的點就是模板載入器，大家自己查閱熟悉一下。
3.4 更多API
熟悉完配置，我們需要了解一些API的使用，這裡就不展開了，點到javaApi，自行查閱，這裡就不展開說明了。
3.4 表示式、指令
這裡的沒人在上面的套路圖中沒標，那個圖我表達的是一個通用的套路，這裡算套路圖中[更多基礎API]一種吧。
表示式、指令是對與模板來說的，也就是輸出資料的一些命令。瀏覽文件相關內容找模板、表示式、指令相關的關鍵字，就可以鎖定相關內容主要在
單純的表示式、指令使用都很簡單，這裡不多講了。
3.5 高階用法
所謂高階用法也就是一些提升效能的配置、自定義擴充套件、一些指令、表示式之類的，這需要大家熟悉基本的使用、配置、api和文件的相關介紹。這裡暫不展開，相信有了前面的基礎掌握一些技巧和方法，這裡來說不是難事。
3.6 原理、原始碼
這裡針對有興趣，想深入學習的人，寫到這是為了保證套路的完整性，這裡也不展開，也不是本篇內容的重點。
四、總結
本篇重點是帶大家從官網去學習一個技術框架，至少用到一些配置、api知道怎麼去查，要學習一個新技術的時候大概需要怎麼做，還提了一個基本的學習套路，希望能給需要的人一些幫助。
沒看上一篇的建議看一下。
Over。