基於 RESTlet 框架開發 JSR 311 (JAX-RS) 規範合規的 RESTful Web Service

RESTlet 與 JAX-RS：兩種架構風格的融合

RESTlet 遵循 Roy Fielding 博士論文的 REST 架構風格，核心組件（Component、Application、Resource、Route、Connector）結構化組織資源。JSR 311 (JAX-RS) 採用 POJO + 註解風格，資源非結構化，URI 直接映射在類/方法上。RESTlet 1.1+ 提供 JAX-RS Extension，讓開發者在 RESTlet 運行時上使用標準 JAX-RS 註解開發。

JAX-RS 核心註解速查

RESTlet JAX-RS Extension 核心實現類

• JaxRsApplication：實現 JAX-RS Application 接口，封裝 JaxRsRestlet。
• JaxRsRestlet：核心處理器，啟動時掃描資源類註解構建 URI 路由表，運行時分發請求至匹配資源方法。
• internal.Provider：實現 MessageBodyReader/Writer，支援 InputStream、JAXB、ByteArray 等序列化。
• internal.spi：實現 HTTP 基礎類（CacheControl、Cookie 等），通過 RuntimeDelegate 代理。

兩種部署模式

模式一：獨立 Java 應用（內嵌 HTTP 服務器）

// 依賴：org.restlet.jar, org.restlet.ext.jaxrs_1.0.jar
Component component = new Component();
component.getServers().add(Protocol.HTTP, 8182);
component.getDefaultHost().attach(new JaxRsExtensionApplication(null));
component.start();

模式二：Servlet 容器部署 (WAR)

需求 JAR：org.restlet.jar, org.restlet.ext.jaxrs_1.0.jar, com.noelios.restlet.jar, com.noelios.restlet.ext.servlet_2.5.jar

<web-app>
  <context-param>
    <param-name>org.restlet.application</param-name>
    <param-value>com.example.JaxRsExtensionApplication</param-value>
  </context-param>
  <servlet>
    <servlet-name>RestletServlet</servlet-name>
    <servlet-class>com.noelios.restlet.ext.servlet.ServerServlet</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>RestletServlet</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>
</web-app>

完整示例：用戶管理服務

資源類

@Path("users")
public class JaxRsExtensionResource {
    @GET @Path("usergroup")
    public String getUserGroup() { return "Group classification..."; }

    @GET @Path("user")
    public String getUser() { return "Registered users..."; }

    @GET @Path("user/{id}")
    public String findUser(@PathParam("id") String id) {
        User u = UserManager.get().getDetails(id);
        return (u != null) ? u.toString() : "User " + id + " not found";
    }

    @GET @Path("usergroup/{id}")
    public String findUserGroup(@PathParam("id") String id) {
        UserGroup g = UserGroupManager.get().getDetails(id);
        return (g != null) ? g.toString() : "Group " + id + " not found";
    }
}

應用配置類

public class ExampleApplication extends Application {
    public Set<Class<?>> getClasses() {
        Set<Class<?>> s = new HashSet<>();
        s.add(JaxRsExtensionResource.class);
        return s;
    }
}

public class JaxRsExtensionApplication extends JaxRsApplication {
    public JaxRsExtensionApplication(Context context) {
        super(context);
        this.add(new ExampleApplication());
    }
}

啟動類 (獨立模式)

public class JaxRsExtensionServer {
    public static void main(String[] args) {
        try {
            Component component = new Component();
            component.getServers().add(Protocol.HTTP, 8182);
            component.getDefaultHost().attach(new JaxRsExtensionApplication(null));
            component.start();
        } catch (Exception e) { e.printStackTrace(); }
    }
}

運行驗證

• GET /users/user → 返回用戶概念說明
• GET /users/user/2 → 返回 ID=2 用戶詳情
• GET /users/user/99 → 返回「用戶不存在」提示
• GET /users/usergroup → 返回用戶組說明
• GET /users/usergroup/1 → 返回 ID=1 用戶組詳情

總結

RESTlet JAX-RS Extension 完美橋接兩種風格：RESTlet 開發者可用標準註解降低遷移風險，JAX-RS 習慣者可享受 RESTlet 穩定內核。IBM Systems Director 等產品已採用此技術棧。