使用 Struts 2 REST Plugin 開發 RESTful 服務完整教學

REST 架構核心原則

• 一切皆資源，統一用 URI 識別（如 /books/1）。
• 標準 HTTP 方法操作資源：GET(查)、POST(增)、PUT(改)、DELETE(刪)。
• 同一資源多重表現：HTML、XML、JSON 由 Accept 或副檔名決定。
• 無狀態：每請求含完整上下文，伺服端不保存會話狀態。
• 可快取：回應標記快取元數據，減少網路傳輸。

Struts 2 REST Plugin 架構

核心 RestActionMapper 將 Rails 風格 URL 映射至 Action 七大標準方法：

HTML 表單不支援 PUT/DELETE，約定加隱藏欄位 _method=put 或 _method=delete 模擬。

環境建置

1. 複製 JAR 至 WEB-INF/lib：
   • struts2-convention-plugin-2.1.6.jar
   • struts2-rest-plugin-2.1.6.jar
   • xstream-1.2.2.jar、json-lib-2.1.jar、ezmorph-1.0.3.jar、commons-lang/collections/beanutils/logging
2. struts.xml 設定預設父包為 rest-default：

<constant name="struts.convention.default.parent.package" value="rest-default"/>
<constant name="struts.convention.action.suffix" value="Controller"/>
<constant name="struts.convention.action.mapAllMatches" value="true"/>

領域模型與服務層

public class Book {
    private Integer id; private String name; private double price;
    // getter/setter 略
}

public class BookService {
    private static Map<Integer, Book> books = new HashMap<>();
    private static int nextId = 5;
    static { /* 初始 4 筆資料 */ }
    public Book get(int id) { return books.get(id); }
    public List<Book> getAll() { return new ArrayList<>(books.values()); }
    public void saveOrUpdate(Book b) { if (b.getId()==null) b.setId(nextId++); books.put(b.getId(), b); }
    public void remove(int id) { books.remove(id); }
}

REST Controller 實現

@Results(@Result(name="success", type="redirectAction", params={"actionName", "book"}))
public class BookController extends ActionSupport implements ModelDriven<Object> {
    private int id;
    private Book model = new Book();
    private List<Book> list;
    private BookService bookService = new BookService();

    public void setId(int id) {
        this.id = id;
        if (id > 0) this.model = bookService.get(id); // 自動載入模型
    }
    public int getId() { return id; }

    // 1. GET /books
    public HttpHeaders index() {
        list = bookService.getAll();
        return new DefaultHttpHeaders("index").disableCaching();
    }

    // 2. GET /books/new
    public String editNew() {
        model = new Book();
        return "editNew";
    }

    // 3. POST /books
    public HttpHeaders create() {
        bookService.saveOrUpdate(model);
        addActionMessage("新增成功");
        return new DefaultHttpHeaders("success").setLocationId(model.getId());
    }

    // 4. GET /books/1
    public HttpHeaders show() {
        return new DefaultHttpHeaders("show");
    }

    // 5. GET /books/1/edit
    public String edit() { return "edit"; }

    // 6. PUT /books/1
    public String update() {
        bookService.saveOrUpdate(model);
        addActionMessage("更新成功");
        return "success";
    }

    // 7. GET /books/1/deleteConfirm (額外動作)
    public String deleteConfirm() { return "deleteConfirm"; }

    // 8. DELETE /books/1
    public String destroy() {
        bookService.remove(id);
        addActionMessage("刪除 ID " + id);
        return "success";
    }

    @Override public Object getModel() { return list != null ? list : model; }
}

• HttpHeaders 允許設定快取控制、Location 標頭等 REST 元數據。
• ModelDriven 讓結果類型直接序列化模型物件（XML/JSON）。

視圖層

Convention 預設視圖路徑：WEB-INF/content/{actionName}-{methodName}.jsp。

book-index.jsp (列表)

<s:iterator value="model">
  <tr>
    <td><s:property value="id"/></td>
    <td>${name}</td><td>${price}</td>
    <td>
      <a href="book/${id}">查看</a> |
      <a href="book/${id}/edit">編輯</a> |
      <a href="book/${id}/deleteConfirm">刪除</a>
    </td>
  </tr>
</s:iterator>
<a href="book/new">新增書籍</a>

book-edit.jsp (編輯表單)

<s:form method="post" action="%{#request.contextPath}/book/%{id}">
  <s:hidden name="_method" value="put" /> <!-- 模擬 PUT -->
  <s:textfield name="name" label="書名"/>
  <s:textfield name="price" label="價格"/>
  <s:submit value="修改"/>
</s:form>

book-deleteConfirm.jsp

<s:form method="post" action="%{#request.contextPath}/book/%{id}">
  <s:hidden name="_method" value="delete" />
  確定刪除《${name}》嗎？ <s:submit value="刪除"/>
</s:form>

多重表現驗證

• /books → HTML 列表
• /books.xml → XML 序列化（XStream）
• /books.json → JSON 序列化（json-lib）

總結

Struts 2 REST Plugin 以 Convention over Configuration 方式，將傳統 Action 轉為 RESTful Controller。關鍵在於：rest-default 父包、七大標準方法映射、HttpHeaders 控制回應元數據、_method 參數模擬 PUT/DELETE、ModelDriven 統一序列化入口。掌握此模式，可快速建構符合 REST 原則、支援多重表現的企業級 API 服務。