RESTful API 是基于 REST（Representational State Transfer） 架構風格設計的 API，其核心目標是提高系統的可伸縮性、簡潔性和可維護性。以下是 RESTful API 的設計原則及在 Java 中的實現方法：

---

一、RESTful API 的核心設計原則

1. 客戶端-服務器分離

   • 客戶端負責用戶界面和交互，服務器負責數據存儲和業務邏輯。兩者通過標準協議（HTTP）解耦。
   • Java 實現：使用 Spring Boot 或 Jakarta EE（原 Java EE）的 @RestController 定義服務端 API，客戶端可以是瀏覽器、移動端或其他服務。

2. 無狀態（Stateless）

   • 每個請求必須包含處理所需的所有信息，服務器不保存客戶端狀態（如會話）。
   • Java 實現：避免使用 HttpSession，依賴請求頭（如 Authorization）或令牌（JWT）傳遞狀態。

3. 統一接口（Uniform Interface）

   • 資源標識（URI）：每個資源通過唯一的 URI 標識（如 /users/123）。
   • 通過表述操作資源：客戶端通過 HTTP 方法（GET、POST、PUT、DELETE）操作資源，使用 JSON/XML 等格式傳輸數據。
   • 自描述消息：明確使用 HTTP 方法、狀態碼（如 200 OK、404 Not Found）和媒體類型（如 application/json）。
   • HATEOAS（Hypermedia as the Engine of Application State）：響應中包含相關資源的鏈接（如分頁導航）。
   • Java 實現：
     • 使用 @GetMapping、@PostMapping 等注解映射 HTTP 方法。
     • 通過 ResponseEntity 設置狀態碼和響應體。
     • 使用 Spring HATEOAS 或 Jersey 實現 HATEOAS。

4. 資源導向（Resource-Oriented）

   • 將業務實體抽象為資源（如用戶、訂單），通過 URI 操作資源。
   • Java 實現：

     @RestController
     @RequestMapping("/users")
     public class UserController {@GetMapping("/{id}")public User getUser(@PathVariable Long id) { /* ... */ }
     }
     

5. 可緩存（Cacheable）

   • 響應應明確是否可緩存（如 Cache-Control 頭）。
   • Java 實現：

     @GetMapping("/{id}")
     public ResponseEntity<User> getUser(...) {return ResponseEntity.ok().cacheControl(CacheControl.maxAge(30, TimeUnit.MINUTES)).body(user);
     }
     

6. 分層系統（Layered System）

   • 允許通過代理、網關或負載均衡器分層部署，客戶端無需感知底層結構。
   • Java 實現：使用 API 網關（如 Spring Cloud Gateway）或反向代理（如 Nginx）。

---

二、Java 中實現 RESTful API 的步驟

1. 選擇框架

• Spring Boot（推薦）：集成 Spring MVC、Spring HATEOAS 和 Spring Security。
• Jersey：JAX-RS 標準的實現，輕量級。
• Micronaut/Quarkus：適用于云原生場景。

2. 定義資源和 URI

@RestController
@RequestMapping("/api/v1/books")
public class BookController {// 資源操作
}

3. 映射 HTTP 方法

@GetMapping("/{id}")
public ResponseEntity<Book> getBook(@PathVariable Long id) {Book book = service.findById(id);return ResponseEntity.ok(book);
}@PostMapping
public ResponseEntity<Book> createBook(@RequestBody Book book) {Book saved = service.save(book);return ResponseEntity.created(URI.create("/books/" + saved.getId())).body(saved);
}@DeleteMapping("/{id}")
public ResponseEntity<Void> deleteBook(@PathVariable Long id) {service.delete(id);return ResponseEntity.noContent().build();
}

4. 處理狀態碼和異常

@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {ErrorResponse error = new ErrorResponse("NOT_FOUND", ex.getMessage());return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
}

5. 實現 HATEOAS

@GetMapping("/{id}")
public EntityModel<Book> getBook(@PathVariable Long id) {Book book = service.findById(id);EntityModel<Book> model = EntityModel.of(book);model.add(linkTo(methodOn(BookController.class).getBook(id)).withSelfRel());model.add(linkTo(methodOn(BookController.class).getAllBooks()).withRel("books"));return model;
}

6. 內容協商（JSON/XML）

• 添加依賴（如 Jackson XML）并配置 produces 和 consumes：

@GetMapping(value = "/{id}", produces = {MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE})
public Book getBook(...) { /* ... */ }

---

三、工具和庫

1. Spring Boot：快速搭建 REST API。
2. Spring HATEOAS：支持超媒體。
3. Swagger/OpenAPI：生成 API 文檔（集成 springdoc-openapi）。
4. Postman：測試 API 端點。
5. JUnit/Mockito：編寫單元測試。

---

四、總結

RESTful API 的設計核心是 資源抽象 和 HTTP 語義化，Java 通過 Spring Boot 等框架可高效實現這些原則。關鍵點包括：

• 使用 URI 標識資源，通過 HTTP 方法操作。
• 嚴格遵循狀態碼規范。
• 無狀態設計，支持緩存和分層擴展。
• 結合 HATEOAS 提升 API 可發現性。