Struts 2 JSON 插件實現 Ajax 互動完整指南

核心價值

JSON 插件提供 json Result Type，Action 回傳 JSON 資料無需 JSP/Velocity 等視圖模板，直接支援前端 Ajax 異步呼叫。

安裝步驟

1. 下載 jsonplugin-x.x.jar (Struts 2.3/2.5 對應版本) 至 WEB-INF/lib。
2. 或 Maven：
   <dependency><groupId>com.googlecode.json-plugin</groupId><artifactId>jsonplugin</artifactId><version>0.41</version></dependency>

Action 實作

@Namespace("/api")
@Action(value = "user", results = {
    @Result(type = "json", params = {"includeProperties", "id,name,email,roles.*"})
})
public class UserAction extends ActionSupport {
    private String id;
    private String name;
    private String email;
    private List<Role> roles = new ArrayList<>();
    private Map<String, Object> metadata = new HashMap<>();

    // Getter/Setter 略

    @JSON(name = "userName") // 重新命名序列化欄位
    public String getName() { return name; }

    @JSON(serialize = false) // 不序列化敏感欄位
    public String getPassword() { return password; }

    @JSON(format = "yyyy-MM-dd") // 日期格式化
    public Date getCreateTime() { return createTime; }

    public String execute() {
        // 模擬查詢
        this.id = "1001";
        this.name = "Alice";
        this.email = "alice@example.com";
        this.roles.add(new Role("ADMIN"));
        this.roles.add(new Role("USER"));
        metadata.put("lastLogin", System.currentTimeMillis());
        return SUCCESS;
    }
}

JSON 註解完整屬性

struts.xml 配置 (非註解方式)

<package name="api" namespace="/api" extends="json-default">
    <action name="user" class="com.example.UserAction">
        <result type="json">
            <param name="includeProperties">id,name,email,roles.*</param>
            <param name="excludeProperties">password</param>
            <param name="enableGZIP">true</param>
            <param name="noCache">true</param>
        </result>
    </action>
</package>

關鍵點：
- extends="json-default" 繼承 JSON 插件預設攔截器堆疊。
- includeProperties/excludeProperties 以 OGNL 運算式控制序列化範圍。
- enableGZIP 壓縮回應；noCache 防快取。

前端 Ajax 呼叫範例 (jQuery)

$.ajax({
    url: "${pageContext.request.contextPath}/api/user.action",
    type: "GET",
    dataType: "json",
    success: function(data) {
        console.log("User:", data.name); // "Alice"
        console.log("Roles:", data.roles); // [{name:"ADMIN"},{name:"USER"}]
        $("#userName").text(data.userName); // 對應 @JSON(name="userName")
    }
});

進階：JSONP 跨域支援

<result type="json">
    <param name="callbackParameter">callback</param> <!-- 支援 ?callback=xxx -->
</result>

前端：dataType: "jsonp"。

常見問題

結語

Struts 2 JSON 插件讓 Action 直接輸出 JSON，極大簡化 Ajax 開發。善用註解與 includeProperties 精確控制序列化範圍，配合 GZIP 與快取控制，即可構建高效能 RESTful 端點。