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 的流程圖：

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

1. 在項目的 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>

2. 在項目的 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