Java RESTful API 開發入門指南 從 Annotation 到權限管理與 Maven 配置，打造高效 Java Web Service

如何使用 Jersey 開發高品質的 Java RESTful API？

Java RESTful API 開發 的核心在於選擇合適的框架與設計模式。Jersey Framework 作為 JAX-RS 的參考實作，是打造 Java Web Service 的首選。其實作關鍵包含六大面向：1. Annotation 應用：利用 @Path 與 @GET 等標註簡化路由與邏輯；2. Filters & Interceptors：在數據流中進行 Request 攔截與回應處理；3. API 權限管理：透過 @RolesAllowed 實作精細的安全性控管；4. Maven 配置：利用 pom.xml 自動化依賴管理與專案打包；5. Response & Error 處理：統一 JAX-RS 回傳狀態碼與錯誤訊息；6. Log4J 日誌管理：強化系統可觀察性。掌握這些技術，能顯著提升 Java API 開發 的效率與穩定性。

開發高效穩定的 Java RESTful API 並提供給前端使用，是現代 Java Web Service 開發的關鍵一環。在複雜的企業級應用中，Java API 開發的品質直接影響到系統的效能、安全與擴展性。主要流程如下:

1. 建立 Java Web Application 並提供 RESTful Web Service
2. 透過 War 檔發佈至容器: 將程式發佈至伺服器供前端存取
3. 讓撰寫的 RESTful Web Service 存取實體資料庫

在前一篇文章整理了網路上教學範例實作心得 透過 Java 開發 Web API (RESTful API)，本文將深入探討如何利用 Jersey Framework 實作 RESTful API，並整理其在使用上需要了解的六個核心關鍵面向，特別是關於 API 權限管理的實踐，以助您精通高效的 Java API 開發。

1. 常用的 Annotation
2. Filters & Interceptors
3. API 權限管理
4. NameBinding 和 Dynamic Binding
5. JAX-RS Response & Error Message
6. Maven 設定

什麼是 Jersey?

Jersey Framework 是實作 Java RESTful API 的一個領先框架，基於 JAX-RS (Java API for RESTful Web Services) 規範來實現高效的 RESTful Web Service。

• 使用大量的 Annotation 來簡化撰寫，提升開發效率。
• 支援 XML (jaxb) 及 JSON (jackson) 等主流資料交換格式。

作為 JAX-RS（Java API for RESTful Web Services）的參考實作，Jersey Framework 提供了一套強大且靈活的工具，讓開發者能夠高效地構建和部署 Java RESTful API。

其高度整合的特性，加上對多種資料交換格式的支援，使得 Jersey 成為進行 Java API 開發時的熱門選擇。

透過 Jersey，開發者可以專注於業務邏輯的實現，而無需過多關注底層的 HTTP 協定細節，從而加速 Java Web Service 的開發進程。

使用 Jersey 開發 RESTful API 完成後，將應用程式放到任何一種像是 jettyt、Tomcat、JBoss 就能完成 http server 的架設，輕鬆部署您的 Java Web Service。

Jersey RESTful API 簡單範例

假設今天想要開的 API 路徑是 http://localhost:{PORT}/{專案名稱}/rest/test

• @ApplicationPath: 設定應用程式層級的路徑，這個例子中為 rest，透過 Annotation 來幫你分配底層的 Servelt
• @Path(“/test”): 定義功能路徑 test
• @GET: 定義 HTTP Method 方法為 Get

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

@ApplicationPath("/rest")
public class TomcatApplication extends ResourceConfig{
    public TomcatApplication(){
      property(ServerProperties.WADL_FEATURE_DISABLE, "true");
      property(ServerProperties.PROVIDER_PACKAGES, "com.web.tomcat.jersey,com.web.tomcat.filter,com.web.tomcat.interceptor");
    }
}

// test 則是用 @Path 來設置：
@Path("/test")
public class TestRestPractice {
    @GET
    public String hello() {
      return "hello >////<";
    }
}

Jersey 常用的 Annotation

底下是常用的 Annotation：

• @ApplicationPath: 應用程式層級路徑
• @PATH: 定義路徑
• @GET, @POST, @PUT, @DELETE: http 方法
• @Consumes, @Produces: 定義 MIME
• @PathParam: http://localhost:你開的洞 /專案名稱/rest/test/我是 PathParam
• @FormParam: 可以用 REST client 製造一個 Form 的 POST
• @QueryParam: http://localhost:你開的洞 /專案名稱/rest/test?我是 QueryParam = 我的值
• @DefaultValue: 也可以修飾 POJO 裡的變數
• @CookieParam
• @HeaderParam

進階款：

• @Provider
• @Priority: 利用 @Priority 來標註優先權
• @PreMatching
• @NameBinding
• @RolesAllowed

用在其他 Annotation 上的 Annotation

• @Retention 確定標註的生命周期, 用一個 Enum 的 RetentionPolicy 參數設定
• @Documented 文檔化
• @Target 表示標註適用的範圍，也用 Enum 的 EnumType 的參數設定
• @SessionScope
• @Inject 針對資料的標註，@JsonProperty 改變 JSON 名稱

Jersey 資料傳輸格式 (@Consumes、@Produces)

Jersey 支援直接將 POJO 轉成 XML (jaxb) 及 JSON (jackson) 的功能，只需要使用兩種 @ 設定即可。

• @Consumes: @Consumes("text/plain")
• @Produces: @Produces({"application/xml", "application/json"})

1
2
3
4
5
6
7
8
9
10
11

@POST
@Consumes("text/plain")
public void postClichedMessage(String message) {
}

@GET
@Produces({"application/xml", "application/json"})
public String doGetAsXmlOrJson() {
}

Jersey API 權限管理

在 Java RESTful API 開發中，尤其是在使用 Jersey Framework 時，API 權限管理是確保應用程式安全的重要環節。Jersey 提供透過 Annotation 針對 API 做精細的權限管理，常見的 Annotation 包含：

• @PermitAll
• @RolesAllowed

底下範例針對同個路徑讓一般使用者、管理員取得不同的資料

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

@Path("/")
@PermitAll
public class Resource {
    @RolesAllowed("user")
    @GET
    public String get() { return "GET"; }

    @RolesAllowed("admin")
    @POST
    public String post(String content) { return content; }

    @Path("sub")
    public SubResource getSubResource() {
        return new SubResource();
    }
}

Jersey Filters & Interceptors

Filters & Interceptors 用途是在 API 的資料流中進行把關和處理

• Filter 可以針對傳入的 request 或即將送出的 response 的參數操作，像是 header 判斷、HTTP Method 修改等等，自訂 Server Filters 需要 override 以下兩個方法：
  • ContainerRequestFilter
  • ContainerResponseFilter
• Interceptors 攔截器可以針對 input/output 串流做處理，常見的像是壓縮
  • WriterInterceptor
  • ReaderInterceptor

當一個 Client 發出請求後，執行的粗略順序如下:

1. ClientRequestFilters
2. ReaderInterceptor
3. WriterInterceptor
4. ClientResponseFilters

@Pre-matching 範例

提前攔截並更改方法，如未加標註則預設都為 Post-matching 僅做判斷後篩選

1
2
3
4
5
6
7
8
9
10
11

@PreMatching
public class PreMatchingFilter implements ContainerRequestFilter {
    @Override
    public void filter(ContainerRequestContext requestContext)
                        throws IOException {
        // change all PUT methods to POST
        if (requestContext.getMethod().equals("PUT")) {
            requestContext.setMethod("POST");
        }
    }
}

NameBinding 和 Dynamic Binding

加上 @Provider 則為預設啟動，若需建立 filter 及 interceptors 與特定 RESTful Services 之間的關連，會利用 @NameBinding 再加上自定標註，或是使用 Dynamic Binding。

NameBinding 範例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

@NameBinding
@Retention(value =RetentionPolicy.RUNTIME)
public @interface Test {

}
--------------------------------------------------------
@Provider
@Test
public class TestFilter2 implements ContainerRequestFilter,
 ContainerResponseFilter {
 //
}
--------------------------------------------------------
@Test
@GET
public String hello() {
    return "hello >////<";
}

Dynamic Binding 範例

1. 包在 my.package.admin 裡的

1
2
3
4
5
6
7
8
9
10
11
12

@Provider
public class MyDynamicFeature implements DynamicFeature {
    @Override
    public void configure(ResourceInfo resourceInfo, FeatureContext context) {
    String resourcePackage = resourceInfo.getResourceClass().getPackage().getName();
    Method resourceMethod = resourceInfo.getResourceMethod();
        if ("my.package.admin".equals(resourcePackage)
        && resourceMethod.getAnnotation(GET.class) != null) {
        context.register(LoggingFilter.class);
        }
    }
}

2. HelloWorldResource.class 裡的

1
2
3
4
5
6
7
8
9
10

public class CompressionDynamicBinding implements DynamicFeature {
    @Override
    public void configure(ResourceInfo resourceInfo, FeatureContext context) {
        if (HelloWorldResource.class.equals(resourceInfo.getResourceClass())
                && resourceInfo.getResourceMethod()
                    .getName().contains("VeryLongString")) {
            context.register(GZIPWriterInterceptor.class);
        }
    }
}

JAX-RS Response & Error Message

Return Response 可以設定 status

1. .status(Response.Status.OK) //200
2. .status(Response.Status.CREATED) // 201
3. .status(Response.Status.NO_CONTENT)// 204
   • the resource method’s return type is void
   • the value of the returned entity is null
4. .seeOther() //303
5. .notModified()//304
6. .temporaryRedirect()//307
7. .status(Response.Status.FORBIDDEN)//403
8. .status(Response.Status.CONFLICT)//409
   • 取到後可以判斷 Response response = request.get();
   • Assert.assertTrue(response.getStatus() == 200);

Maven 設定

Maven 透過 Project Object Model 的設置，也就是 pom.xml 會定義以下這些東西：

在 Java API 開發中，尤其是在使用 Jersey Framework 構建 Java RESTful API 時，Maven 扮演著核心的專案管理與建置工具角色。

Maven 透過其 Project Object Model (POM) — 也就是 pom.xml 配置檔 — 簡化了專案的建置、依賴管理和發佈流程。

正確配置 pom.xml 不僅能確保所有必要的 JavaScript 模組和函式庫被正確引入，也能自動處理編譯、測試和打包等任務，是高效 Java Web Service 開發不可或缺的一部分。

理解 Maven 的運作機制，對於任何 Java API 開發者來說都至關重要。

1. 版本相關資訊

1
2
3
4

<modelVersion>4.0.0</modelVersion>
<groupId>test</groupId>
<artifactId>test</artifactId>
<version>0.0.1-SNAPSHOT</version>

2. 定義 Project 的 layout

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<sourceDirectory>src</sourceDirectory>
<resources>
    <resource>
        <directory>src</directory>
        <excludes>
            <exclude>**/*.java</exclude>
        </excludes>
    </resource>
    <resource>
        <directory>properties</directory>
        <excludes>
            <exclude>**/*.java</exclude>
        </excludes>
    </resource>
</resources>

3. 定義相關 dependencies

1
2
3
4
5
6
7

<dependencies>
    <dependency>
        <groupId>org.glassfish.jersey.containers</groupId>
        <artifactId>jersey-container-servlet</artifactId>
        <version>2.16</version>
    </dependency>
</dependencies>

加入 dependencies 後會自動產生 jar, war 相關的檔案，少去自己加參考的過程，但需要了解 dependencies 是針對什麼而加，像是 POJO to JSON 需要 MOXy 或是 Jackson：

1
2
3
4
5
6
7
8
9

<dependency>
     <groupId>org.glassfish.jersey.media</groupId>
     <artifactId>jersey-media-moxy</artifactId>
 </dependency>

<dependency>
     <groupId>org.glassfish.jersey.media</groupId>
     <artifactId>jersey-media-json-jackson</artifactId>
 </dependency>

除了 pom.xml 外，在 JAX-RS Application 有個 class 叫 ResourceConfig 提供了註冊資源的方式。

1
2
3
4
5
6
7
8
9
10
11
12
13

ApplicationPath("/rest")
public class TomcatApplication extends ResourceConfig{
    public TomcatApplication() {
        property(ServerProperties.WADL_FEATURE_DISABLE, "true");
        property(ServerProperties.PROVIDER_PACKAGES,
        "com.web.tomcat.jersey,com.web.tomcat.filter,com.web.tomcat.interceptor");
        register(XXX.class);
    }
}

final Application application = new ResourceConfig()
.packages("org.glassfish.jersey.examples.linking")
.register(DeclarativeLinkingFeature.class);

舉例來說要利用 Jersey 上下傳檔案，可能就需要額外註冊以下的資訊：

1
2
3
4

<dependency>
     <groupId>org.glassfish.jersey.media</groupId>
     <artifactId>jersey-media-multipart</artifactId>
 </dependency>

要記得到 ResourceConfig 註冊

1
2

packages("com.rest.resource");
register(MultiPartFeature.class);

Log4J

了解了 Jersey 的相關設定後，使用 Log4J 可以大大幫助我們在開發上的除錯。

在 Java API 開發與 Java Web Service 運行中，有效的日誌記錄對於應用程式的除錯、監控與維護至關重要。

Log4J 作為一個功能強大且高度可配置的日誌框架，能夠幫助開發者輕鬆地管理應用程式的日誌輸出。

透過在 Maven 的 pom.xml 中配置相關依賴，並在程式碼中簡單調用，Log4J 即可實現多層級、多輸出的日誌記錄，極大地提升了 Java RESTful API 的可觀察性與問題診斷效率。

對於構建穩定可靠的 Java API 開發而言，熟練運用 Log4J 是不可或缺的一環。

1. POM 檔設定相關相依性

1
2
3
4
5
6
7
8
9
10

<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-api</artifactId>
    <version>2.4</version>
</dependency>
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-core</artifactId>
    <version>2.4</version>
</dependency>

2. import 相關 Library

1
2
3
4
5
6
7
8
9

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

public class HelloWorld {
private static final Logger logger = LogManager.getLogger("HelloWorld");
    public static void main(String[] args) {
        logger.info("Hello, World!");
    }
}

3. XML 設定

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
<Appenders>
    <!-- Console 為 console 顯示 log 格式的設定-->
    <Console name="Console" target="SYSTEM_OUT">
        <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n" />
    </Console>
    <!-- DailyFile 為以日為單位儲存的 log 檔設定 -->
    <RollingFile name="DailyFile" fileName="logs/jarvis-log.log"
    filePattern="logs/jarvis-log-%d{yyyy-MM-dd}~%i.log">
        <PatternLayout>
            <Pattern>[%-5level] %d{yyyy-MM-dd HH:mm:ss} [%t] %c{1} - %msg%n</Pattern>
        </PatternLayout>
        <Policies>
            <TimeBasedTriggeringPolicy interval="1" modulate="true" />
            <SizeBasedTriggeringPolicy size="100 MB" />
        </Policies>
    </RollingFile>
</Appenders>
<Loggers>
    <Logger name="org.apache.log4j.xml" level="info" />
    <Root level="debug">
        <AppenderRef ref="Console" />
        <AppenderRef ref="DailyFile" />
    </Root>
</Loggers>
</Configuration>

FAQ：Java Jersey API 開發常見問題

Q1：在現代開發中，為什麼還要選擇 Jersey 而非 Spring Boot？

A：雖然 Spring Boot 目前非常流行，但 Jersey Framework 教學 強調其作為 JAX-RS 標準實作的純粹性。如果您追求輕量級、遵循 Java EE 標準，且不需要 Spring 龐大的生態系，Jersey 是一個更專注於 Java RESTful API 開發 的選擇。它能無縫運行在簡單的 Servlet 容器（如 Tomcat）中，維持較低的資源消耗。

Q2：Jersey 中的 Filters 與 Interceptors 有什麼本質區別？

A：Filters 專注於處理「HTTP 數據」（Headers, Method, URL），適合執行驗證、授權或修改傳輸協定。而 Interceptors 則專注於處理「實體內容流 (Entity Stream)」，如對資料進行 GZIP 壓縮或解壓縮、加解密 JSON 內容。在 JAX-RS 實作 中，了解兩者的執行順序對於構建高品質的數據管道至關重要。

Q3：如何解決 Maven 設定中常見的相依性衝突？

A：在 Maven 配置 Java 專案時，建議利用 mvn dependency:tree 指令查看依賴樹。針對版本衝突，可以使用 <exclusion> 標籤排除掉衝突的舊版本，並在 <dependencyManagement> 中統一管控關鍵套件（如 Jackson 或 Jersey Core）的版本號，確保 Java Web Service 運行的穩定性。

• ← 上一篇
• 下一篇 →