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

標籤：其他

上一篇：Protobuf生成檔案報錯

下一篇：RabbitMQ原理和架構圖解(附6大作業模式)