此示例演示了Java中的RESTful服務如何使用其ID檢索特定的post。@GetMapping(“/{id}”) 注釋指定此方法應使用URI中的特定post ID來響應GET請求。

使用HTTP方法進行CRUD操作

RESTful API使用標準HTTP方法來執(zhí)行CRUD操作：
● GET，用于檢索資源。
● POST，用于創(chuàng)建新資源。
● PUT或PATCH，用于更新現(xiàn)有資源。
● DELETE，用于刪除資源。
這些操作中的每一個都對應于數(shù)據(jù)庫管理中的傳統(tǒng)CRUD（創(chuàng)建、讀取、更新、刪除）操作。
Java示例

@RestController

@RequestMapping("/api/users")

public class UserController {



    private UserService userService; // Service class for user operations



    @GetMapping("/{id}")

    public ResponseEntity<User> getUserById(@PathVariable Long id) {

        User user = userService.getUserById(id);

        return ResponseEntity.ok(user);

    }



    @PostMapping

    public ResponseEntity<User> createUser(@RequestBody User user) {

        User createdUser = userService.createUser(user);

        return new ResponseEntity<>(createdUser, HttpStatus.CREATED);

    }



    @PutMapping("/{id}")

    public ResponseEntity<User> updateUser(@PathVariable Long id, @RequestBody User updatedUser) {

        User user = userService.updateUser(id, updatedUser);

        return ResponseEntity.ok(user);

    }



    @DeleteMapping("/{id}")

    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {

        userService.deleteUser(id);

        return ResponseEntity.noContent().build();

    }

}

這段代碼演示了在 RESTful API 中使用不同的 HTTP 方法進行 CRUD 操作。每個方法（GET、POST、PUT、DELETE）對應一個特定的 CRUD 操作，可以對用戶資源進行操作。

無狀態(tài)交互

在REST中，客戶端和服務器之間通信是無狀態(tài)的。這意味著每個來自客戶端的請求都必須攜帶服務器處理所需的全部信息，而服務器則不保留關(guān)于客戶端會話的任何狀態(tài)。這種無狀態(tài)特性確保每個HTTP請求都能獨立理解，進而提高了應用程序的可靠性和可擴展性。

資源的表示形式

RESTful API中的資源與其表示形式是分離的。這意味著同一資源可以根據(jù)客戶的請求以不同的格式表示，如JSON、XML、HTML等。服務器以特定格式（如JSON）提供信息，每個響應都包括一個Content-Type頭。

可緩存響應

為了提高API的效率和性能，應將響應定義為可緩存或不可緩存。如果響應是可緩存的，則客戶端緩存有權(quán)為以后的等效請求重用該響應數(shù)據(jù)。

分層系統(tǒng)

RESTful API可以構(gòu)造為分層系統(tǒng)。這意味著客戶端通常無法判斷它是直接連接到最終服務器，還是連接到中間服務器。中間服務器可以通過實現(xiàn)負載平衡和提供共享緩存來提高系統(tǒng)可擴展性。

按需編碼（可選）

這一原則更多的是REST的可選約束。它允許在需要時將可執(zhí)行代碼從服務器發(fā)送到客戶端，從而擴展客戶端功能。

統(tǒng)一接口

為了獲得統(tǒng)一的接口，RESTful API依賴于以下內(nèi)容：
● 基于資源的URI：URI應該基于資源（名詞），而不是動作或動詞。
● HTTP Methods：顯式使用HTTP方法（GET、POST、PUT、DELETE）。
● HATEOAS（超文本作為應用程序狀態(tài)的引擎）：一種應用超媒體（超文本中的鏈接）作為瀏覽應用程序狀態(tài)手段的約束。
Java示例

@RestController

@RequestMapping("/api/books")

public class BookController {



    private BookService bookService; // Service class for book operations



    @GetMapping

    public ResponseEntity<List<Book>> getAllBooks() {

        List<Book> books = bookService.getAllBooks();

        // Logic to add HATEOAS links to each book

        return ResponseEntity.ok(books);

    }

}

這段代碼展示了在RESTful API中實現(xiàn)統(tǒng)一接口的方法。它采用基于資源的URI和HTTP方法，可能還包括HAEOAS鏈接，使得客戶端能夠瀏覽API的狀態(tài)。

Java API的版本控制策略

在API開發(fā)領域，版本控制是管理變更和維護向后兼容性的關(guān)鍵方面。針對Java API，存在多種版本控制策略，每種策略都有其獨特的優(yōu)點和適用場景。

URI版本控制

URI（統(tǒng)一資源標識符）版本控制是將API的版本號直接嵌入URI中。這種方法透明易理解，因為可以直接從訪問的URL中看出版本信息，尤其當對API進行重大更改并有可能影響現(xiàn)有客戶端時。但有一個缺點，如果必須同時維護API的多個版本，可能會導致URL冗余。盡管如此，這種策略通常因其簡單明了而備受青睞，因為它消除了訪問哪個API版本的不確定性。

Java示例

@RestController

@RequestMapping("/api/v1/users")

public class UserV1Controller {

    private UserService userService; // Service for user operations



    @GetMapping("/{id}")

    public ResponseEntity<User> getUserById(@PathVariable Long id) {

        User user = userService.getUserByIdV1(id);

        return ResponseEntity.ok(user);

    }



    // Additional methods for version 1

}



@RestController

@RequestMapping("/api/v2/users")

public class UserV2Controller {

    private UserService userService; // Service for user operations



    @GetMapping("/{id}")

    public ResponseEntity<User> getUserById(@PathVariable Long id) {

        User user = userService.getUserByIdV2(id);

        return ResponseEntity.ok(user);

    }



    // Additional methods for version 2

}

此示例顯示了兩個控制器類，每個類都為不同版本的API提供服務。API的版本1通過 /api/v1/users 訪問，版本2通過 /api/v2/users 訪問。每個控制器都使用#2中適合其版本的特定方法。

參數(shù)版本控制

與URI版本控制不同，參數(shù)版本控制不修改基本URI。相反，它使用請求參數(shù)來指定API版本。這種方法保持了URI的簡潔性，在API版本之間差異較小且不需要更改基本URI時尤其有用。它允許客戶端只需調(diào)整請求中的參數(shù)即可在不同的API版本之間切換。然而，與URI版本控制相比，它可能不那么直觀，因為版本信息不直接顯現(xiàn)在端點URL中。這種方法適用于頻繁但較小地更改版本的API，能最大程度地減少對整個URL結(jié)構(gòu)的影響。

Java示例

@RestController

@RequestMapping("/api/users")

public class UserParameterVersioningController {

    private UserService userService; // Service for user operations



    @GetMapping

    public ResponseEntity<User> getUserById(@RequestParam("version") String version, @RequestParam("id") Long id) {

        if ("v1".equals(version)) {

            User user = userService.getUserByIdV1(id);

            return ResponseEntity.ok(user);

        } else if ("v2".equals(version)) {

            User user = userService.getUserByIdV2(id);

            return ResponseEntity.ok(user);

        } else {

            return ResponseEntity.badRequest().build();

        }

    }



    // Other methods handling versioning through request parameters

}

此代碼使用一個帶有方法的控制器，該方法基于請求參數(shù)區(qū)分API版本?？蛻舳酥付ò姹荆ɡ?nbsp;v1 或 v2 ）作為請求的一部分，并且該方法相應地處理請求。

Header 版本控制

Header版本控制包括在HTTP頭中指定API版本，保持URI不變。這種方法更靈活，更適合于版本控制需要更加謹慎的API。這種方式還使得在版本間轉(zhuǎn)換更加容易，因為更改是在標頭中進行的，而不是在URI或參數(shù)中。由于URL中沒有版本控制信息，可能導致不夠透明且難以進行測試。通常，這種方法適用于需要穩(wěn)定、不變端點的API用戶，并且版本變更在標頭內(nèi)部進行管理的情況。

Java示例

@RestController

@RequestMapping("/api/users")

public class UserHeaderVersioningController {

    private UserService userService; // Service for user operations



    @GetMapping

    public ResponseEntity<User> getUserById(@RequestHeader("API-Version") String apiVersion, @RequestParam("id") Long id) {

        if ("v1".equals(apiVersion)) {

            User user = userService.getUserByIdV1(id);

            return ResponseEntity.ok(user);

        } else if ("v2".equals(apiVersion)) {

            User user = userService.getUserByIdV2(id);

            return ResponseEntity.ok(user);

        } else {

            return ResponseEntity.badRequest().build();

        }

    }



    // Other methods handling versioning through custom headers

}

在此示例中，API版本由自定義標頭（ API-Version ）確定。該方法檢查標頭中指定的版本，并為版本1或版本2調(diào)用適當?shù)姆辗椒ā?/p>

Java API文檔實踐

有效的文檔是使API可用和可訪問的關(guān)鍵。有據(jù)可查的API不僅便于開發(fā)人員更容易地集成和使用，而且還提高了軟件的整體質(zhì)量和可維護性。在Java中，可以使用幾種最佳實踐和工具為API創(chuàng)建高質(zhì)量的文檔。

文檔的重要性

API文檔是開發(fā)人員理解API并與之交互的路線圖。它應該清楚地概述如何有效地使用API，解釋其功能，并詳細說明可以預期的請求和響應。優(yōu)秀的文檔可以顯著減少新用戶的學習曲線，并可以為經(jīng)驗豐富的用戶作為參考。理想情況下，它應該易于導航、是最新版本且全面，涵蓋API的所有方面。

API文檔的關(guān)鍵組成部分

1.概述和簡介：首先概述API，包括其用途、范圍和高級功能。該部分為文檔的其余部分設置了上下文。
2.身份驗證和授權(quán)：詳細說明現(xiàn)有的任何身份驗證或授權(quán)機制。例如，如果API使用OAuth 2.0，提供有關(guān)用戶如何進行身份驗證的分步說明。
3.Endpoint描述：每個Endpoint都應該有完整的文檔。這包括URI、HTTP方法（GET、POST等）、必需和可選參數(shù)、請求和響應格式以及狀態(tài)代碼。
4.示例：提供請求和響應的實際示例。示例在說明API的工作方式方面起著至關(guān)重要的作用，通常是開發(fā)人員首先要了解的使用模式
5.錯誤處理：記錄常見錯誤、它們的含義以及如何解決它們。這有助于調(diào)試并確保在客戶端應用程序中正確處理錯誤。
6.版本控制信息：如果API有多個版本，記錄差異以及用戶如何訪問特定版本。
7.費率限制和配額：如適用，包括有關(guān)費率限制和限額的信息，以防止濫用并確保公平使用。

API文檔工具

創(chuàng)建和維護API文檔的最有效方法之一是，使用可以通過代碼自動生成文檔的工具。在Java中，Swagger（現(xiàn)在是OpenAPI規(guī)范的一部分）等工具被廣泛使用。

Swagger示例：Swagger或OpenAPI提供了一組工具，用于使用OpenAPI規(guī)范設計API。它提供了從API設計到文檔生成的一系列功能。例如，SwaggerUI創(chuàng)建交互式文檔，允許用戶直接從瀏覽器嘗試API調(diào)用。

@Configuration

@EnableSwagger2

public class SwaggerConfig {

    public Docket api() {

        return new Docket(DocumentationType.SWAGGER_2)  

                .select()                                  

                .apis(RequestHandlerSelectors.any())              

                .paths(PathSelectors.any())                          

                .build();                                           

    }

}

上面的代碼片段在Java應用程序中配置Swagger 2。它設置了一個 Docket bean，這是Swagger spring集成的主要接口，并將其配置為選擇任何控制器和路徑。此設置自動為API生成文檔，可以在用戶友好的界面中查看這些文檔。

結(jié)論

在本篇文章中，我們深入探討了在Java中設計出高效且用戶友好的API的關(guān)鍵策略。從遵循RESTful原則和采用合適的版本控制策略，到詳盡文檔的重要性，這些實踐構(gòu)筑了強大API開發(fā)的基石。這些原則突顯了清晰性、靈活性以及以用戶為核心的設計理念，引導開發(fā)者打造不僅在技術(shù)上合理，而且易于使用和整合的API。

原文鏈接：Effective?API?Design?in?Java:?A?Guide?to?Creating?Robust?and?User-Friendly?APIs