Jmix 中 REST API 的兩種實現

你知道嗎，在 Jmix 中，REST API 有兩種實現方式！

很多應用是採取前後端分離的方式進行開發。這種模式下，對前端的選擇相對靈活，可以根據團隊的擅長技能選擇流行的 Angular/React/Vue 之一，或者前端為App/小程式等手機應用。Jmix 的一種典型應用場景就是作為這種型別應用程式的高階別管理 UI 和後端。為此，Jmix 提供了強大的通用 REST API 功能，支援包括開箱即用的實體、檔案、後設資料、使用者對談的 API 以及經過簡單設定就能支援的業務邏輯（服務）REST API。

由於 Jmix 是基於 Spring Boot 框架，因此也支援 Spring 的 RestController。那麼對於 Spring 的 REST API 機制和 Jmix 提供機制，究竟有什麼不同，而我們在開發時又該如何選擇呢？本文將通過具體的程式碼範例，介紹這兩種 API 的區別，相信看完之後，該如何選擇您心裡應該有數了。

資料模型和服務

我們假設一個簡單的場景，為了給使用者提供湊單功能，我們在後端寫一個服務用於查詢低於某個價格的產品（Product），並將滿足條件的產品列表返回給使用者端。

資料模型

首先我們構建一個簡單的 JPA 實體：Product 類，包含名稱和價格兩個屬性：

@JmixEntity
@Table(name = "SLS_PRODUCT")
@Entity(name = "sls_Product")
public class Product {
    @JmixGeneratedValue
    @Column(name = "ID", nullable = false)
    @Id
    private UUID id;

    @InstanceName
    @Column(name = "NAME")
    private String name;

    @Column(name = "PRICE")
    private Double price;

    ... // 其他屬性
}

實體通過 Jmix Studio 建立可以選擇其他實體特性，比如版本、實體審計、軟刪除屬性等。

服務

可以像普通 Spring Boot 應用那樣，自己手動建立一個 @Service 類。也可以通過 Jmix Studio 提供的建立 bean 的功能建立 Service。這裡我們用 Jmix Studio 建立一個 Bean，該功能預設建立帶 @Component 註解的類，我們手動將類註解修改為 @Service：

@Service("sls_ProductService")
public class ProductService {

    @Autowired
    private DataManager dataManager; // 插入程式碼段時，預設注入帶有許可權檢查的 DataManager

    public List<Product> getProductsCheaperThan(Double price){

        // 注意，這裡我們並沒有對輸入引數 price 做檢查

        List<Product> productList = dataManager.load(Product.class)
                .query("select p from sls_Product p " +
                        "where p.price < :priceInput")
                .parameter("priceInput", price)
                .list();

        return productList;
    }
}

這裡的載入實體列表程式碼，我們通過 Studio 的程式碼段功能自動新增。

服務中，我們使用了 Jmix 的 DataManager 和 JPQL 查詢語句載入實體，並使用方法的輸入引數作為 JPQL 的引數。Jmix 的持久層也支援 Spring Data Repository 或者 MyBatis。而使用 DataManager 的一個好處是可以利用 Jmix 的安全機制，控制 API 呼叫方對實體的存取許可權。

Jmix 服務 API

Jmix 服務（Service） API 可以將任意 Spring bean 作為 HTTP 介面開放。Jmix 負責 HTTP 互動，例如，提供 HTTP 響應編碼、進行錯誤處理等。下圖是 Jmix 服務 API 的流程圖：

可以看到，作為應用程式開發者，僅需要編寫服務程式碼。另外，還需做一些設定：

在專案的 resources 目錄新增 rest-services.xml，用於設定可作為 REST API 使用的服務及其方法，內容如下：

<?xml version="1.0" encoding="UTF-8"?>
  <services xmlns="http://jmix.io/schema/rest/services">
      <service name="sls_ProductService"> <!-- 指定服務名稱 -->
          <method name="getProductsCheaperThan"> <!-- 指定方法名稱 -->
              <param name="price" type="java.lang.Double"/> <!-- 指定方法引數和型別 -->
          </method>
          <!-- 可以新增服務中其他方法 -->
      </service>
      <!-- 可以新增其他服務 -->
  </services>

在專案的 application.properties 檔案中，設定 jmix.rest.services-config 引數，指定上面設定的 xml 檔案：

jmix.rest.services-config = com/abmcode/sales/rest-services.xml

完成這些設定之後，就可以通過 REST 使用者端呼叫了，URL 為 /rest/services/<service_name>/<method_name>。例如，通過 Postman 呼叫：

服務 API 會預設使用 Jmix 的安全機制：API 埠需要使用認證 token 進行存取，而且使用者需要有存取 REST API 和所查詢實體的許可權。另外，Jmix 的服務 API 也支援匿名存取。

Spring 控制器 API

然後我們再看看 Spring 的 RestController 方式。首先，我們定義一個控制器：

@RestController("sls_ProductController")
@RequestMapping("/products")
public class ProductController {
    @Autowired
    private ProductService productService;

    @GetMapping("priceunder")
    public List<Product> getPriceUnder(@RequestParam Double price) throws Throwable {

        if (price < 0) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "價格引數必須大於 0"); // 自定義控制器層的引數檢查，丟擲請求異常。
        }

        return productService.getProductsCheaperThan(price);
    }
}

Jmix 中的控制器介面預設都是匿名的，但是為匿名使用者設定能存取實體資訊又不夠安全，Jmix 提供了一個應用程式屬性，支援使用 Jmix 安全機制對自定義控制器進行保護：

# 支援逗號分隔的多個 pattern
jmix.rest.authenticatedUrlPatterns=/products/**

然後，重啟服務就可以通過 Postman 進行呼叫。注意，這裡的 URL 與服務 URL 不同，直接使用了控制器中定義的路徑：

結論

通過上面的程式碼，我們可以看到，在 Jmix 中使用兩種型別的 REST API 其實都不復雜，但是，也是各有優勢：

Jmix 服務 API：

不用編寫控制器程式碼，僅通過 XML 設定即可使用
預設使用 Jmix 的安全機制
可以使用 Fetch plan 定義返回實體的欄位

Spring 控制器：

更加靈活，可以使用 Spring 控制器自定義 HTTP 狀態碼、響應型別或者異常錯誤
除了使用服務層的實體控制外，還可以在控制器層使用自定義的 DTO 對返回實體的資訊做進一步控制

因此，在大多數情況下，我們僅使用 Jmix 的服務 API 就能夠滿足使用要求。針對部分複雜場景可以使用 Spring 控制器 API。

文中使用的 Jmix 版本：1.3.1