在ASP.NET Core Web API中為RESTful服務增加對HAL的支持

本文轉載自查看原文 2017-11-14 22:56 2613 Apworks/ .NET Core

HAL（Hypertext Application Language，超文本應用語言）是一種RESTful API的數據格式風格，為RESTful API的設計提供了接口規范，同時也降低了客戶端與服務端接口的耦合度。很多當今流行的RESTful API開發框架，包括Spring REST，也都默認支持HAL規范，當RESTful API被調用后，服務端就會返回ContentType為application/hal+json的JSON內容，例如：

{
  "_links": {
    "self": {
      "href": "http://example.com/api/book/hal-cookbook"
    }
  },
  "_embedded": {
    "author": {
      "_links": 
        "self": {
          "href": "http://author-example.com"
        }
      }, 
      "id": "shahadat",
      "name": "Shahadat Hossain Khan"
    }
  },
  "id": "hal-cookbook",
  "name": "HAL Cookbook"
}

相對於僅返回一個id和一個name的結果而言，這樣的JSON Response包含了更為豐富的信息，比如：當前請求的API地址、HAL Cookbook這本書的作者信息，以及訪問作者信息的超文本鏈接。那么客戶端在獲取到這個服務端的響應后，就能很方便地將這些信息綁定在界面上，而無需通過多個API的調用來查找關聯信息。另一方面，這種JSON Response中包含的超文本鏈接也可以是動態的，比如分頁導航鏈接，這樣客戶端實現分頁功能將變得非常方便。本文着重介紹在ASP.NET Core Web API中，如何為自己設計的RESTful API增加對HAL的支持。

Apworks框架

在ASP.NET Core Web API中為RESTful服務增加對HAL的支持，是通過Apworks框架以及HAL框架來完成的。這兩個框架都是我自己設計開發的開源框架，前者基於Apache 2.0開源，后者基於MIT開源，因此完全可以用於商業系統開發。HAL項目為超文本應用語言（Hypertext Application Language）提供了基本的數據模型和處理邏輯，它對JSON的支持基於大名鼎鼎的Newtonsoft.Json，因此性能方面是可以保證的。簡便快捷的流暢接口（Fluent Interface API）編程方式，使得構建一個完整合理的HAL對象模型變得非常容易。HAL項目的設計使用了一些對象結構化模式，有興趣的朋友可以到Github項目主頁（https://github.com/daxnet/hal）了解一下。

至於Apworks框架，它的主要功能並不是僅僅為了向ASP.NET Core Web API提供HAL的支持，它更重要的是一套基於.NET Core的微服務快速開發框架，不僅提供了面向領域驅動（DDD）的基本構造元素（聚合、實體、倉儲、工廠等），而且整合了消息隊列、消息派發及訂閱、消息處理、查詢服務、事件存儲等微服務架構功能模塊，並基於MongoDB、Entity Framework、RabbitMQ、PostgreSQL、SQL Server等基礎服務作出了實現。目前整個框架還在開發和完善階段，讀者有興趣也可以上Apworks Examples案例項目查看Apworks框架的案例代碼，案例代碼也在同步更新之中。等所有的案例代碼開發完成后，我會對Apworks框架發布一個相對穩定的版本。

值得一提的是，Apworks框架中的Apworks.Integration.AspNetCore Package提供了對ASP.NET Core Web API的開發擴展，對HAL的支持也是該Package的一個部分。OK，Apworks框架和HAL框架暫時介紹這些，它們不是本文重點。接下來，讓我們看看，如何快速地在ASP.NET Core Web API中實現HAL的支持。

最簡單的案例

事實上，在《在ASP.NET Core中使用Apworks開發數據服務：對HAL的支持》一文中，我已經介紹了如何在Apworks快速搭建數據服務的同時，提供HAL的JSON數據格式。當時的案例是需要滿足數據服務開發模式的，比如需要注入倉儲實例，並且Controller需要默認提供GET、POST、PUT、DELETE的操作。這對於僅需要實現某些特定功能的通用Web API Controller而言，又顯得太重了。所以，我們還是從最簡單的案例開始吧。

打開Visual Studio 2017，新建一個ASP.NET Core Web API，.NET框架建議選擇.NET Core/ASP.NET Core 2.0，項目模板選擇Web API，此時會生成一個默認的ASP.NET Core 2.0 Web API應用程序。可以暫且不啟用Docker支持
直接啟動這個ASP.NET Core Web API應用程序，將默認在瀏覽器中輸出value1和value2兩個值：
根據《在ASP.NET Core中使用Apworks快速開發數據服務》一文中的介紹，將Apworks和Apworks.Integration.AspNetCore兩個Package添加到項目中。注意，版本必須大於等於0.1.138（目前是開發版本）
添加成功后，ASP.NET Core Web API應用程序的NuGet依賴項類似如下：

雙擊打開Startup.cs文件，在ConfigureServices方法中，加入以下代碼：

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();

    var halBuildConfiguration = new HalBuildConfiguration(new HalBuildConfigurationItem[]
    {
        new HalBuildConfigurationItem("Values.Get", context =>
            new ResourceBuilder().WithState(null)
                .AddSelfLink()
                .WithLinkItem(context.HttpContext.Request.GetDisplayUrl())
                .AddEmbedded("values")
                .Resource(new ResourceBuilder().WithState(context.State)))
    });

    services.AddApworks()
        .WithHalSupport(halBuildConfiguration)
        .Configure();
}

雙擊打開ValuesController.cs文件，在Get()方法上，加上SupportsHal特性：

[HttpGet]
[SupportsHal]
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

再次運行，可以看到，返回結果已經是HAL的JSON格式，Content-Type為application/hal+json：

上面是最簡單的案例，我們就只用了幾行代碼，花了10分鍾不到，就把ASP.NET Core Web API的默認項目打造成了支持HAL JSON格式的RESTful API項目。大概介紹幾個要點：

首先需要創建一個HalBuildConfiguration對象，這個對象可以容納一個或者多個HalBuildConfigurationItem對象，每個HalBuildConfigurationItem對象包含了“需要對哪個Controller的哪個Action的返回值進行HAL格式處理”以及“如何處理API的返回結果並包裝成HAL JSON數據格式”這兩方面的信息
構造HalBuildConfigurationItem的第一個參數，用以指定API Controller下的Action的方法簽名，以便能夠確定HAL處理的API。大致規則如下，但事實上要更加靈活：

*.Get：表示匹配所有Controller下，參數個數為0的Get方法
Values.Get：表示匹配Values Controller下，參數個數為0的Get方法
Values.Get(int,string)：表示匹配Values Controller下，參數個數為2，類型分別為int和string的Get方法

構造HalBuildConfigurationItem的第二個參數，用以指定HAL JSON的產生方式。關於HAL ResourceBuilder的相關詳細文檔，請參考https://github.com/daxnet/hal
在相應的Controller Action上使用SupportsHal特性，標注當前方法需要產生HAL JSON的輸出。SupportsHalAttribute還可以直接使用在Controller級別，用以標注當前Controller下，所有的Action都能夠支持HAL JSON的輸出

過程非常簡單，而且非常靈活，開發人員可以完全自定義所產生的HAL JSON的格式（比如在這個例子中，我們向RESTful API的結果輸出了請求的URL路徑（也就是上圖中_links.self節點））。接下來，讓我們看一個稍微復雜一點的應用場景，看看如何通過HAL JSON的RESTful API快速實現服務端分頁。

服務端分頁案例介紹

分頁，是Web Service開發中不可避免的常見問題。來自服務端的數據量往往很大，即使可以通過查詢條件來過濾掉很大一部分數據，用戶數據庫中的數據量仍然是無法估計的。采用服務端分頁，不僅可以減少網絡上的數據傳輸，提高服務響應度，而且還可以降低客戶端數據處理的壓力，為用戶提供較好的使用體驗。Apworks.Integration.AspNetCore程序包通過向ASP.NET Core Web API提供HAL的支持，開發人員可以非常方便地實現專業化的服務端分頁功能。接下來，就讓我們一起看一個簡單的案例：將26個英文字母進行分頁並根據用戶的輸入條件返回相應頁的數據。

我們仍舊使用上面的Web API項目：

將ValuesController中的Get()方法改成如下代碼：

[HttpGet]
[SupportsHal]
public IActionResult Get(int page = 1, int size = 5)
{
    var values = new[] { "a", "b", "c", "d", "e",
        "f", "g", "h", "i", "j",
        "k", "l", "m", "n", "o",
        "p","q", "r","s","t",
        "u","v","w","x","y",
        "z" };
    var skip = (page - 1) * size;
    var take = size;
    var records = values.Length;
    var pages = (records + size - 1) / size;
    return Ok(new PagedResult(values.Skip(skip).Take(take), page, size, records, pages));
}

修改Startup.cs文件，將ConfigureServices方法改為如下代碼，注意HalBuildConfigurationItem的第一個參數，已經變成Values.Get(int, int)，表示匹配ValuesController中含有兩個int類型參數的Get方法：
```
public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();

    services.AddApworks()
        .WithHalSupport(new PagedResultHalBuildConfiguration("Values.Get(int, int)"))
        .Configure();
}
```
Ctrl+F5直接運行Web API應用程序，在瀏覽器中輸出如下：

可以看到，英文字母已經通過分頁形式輸出，在_links節點下包含了self、first、last、next的鏈接，與此同時，服務端還返回了當前頁碼、每頁數、總記錄條數以及總頁數的信息。
在瀏覽器中，輸入http://localhost:52566/api/values?page=2，產生的結果如下：

此時已經顯示了第二頁的信息，並且分頁的鏈接已經相應地更新了。如果你的瀏覽器安裝了JSON格式數據查看插件，那么很有可能JSON中的超文本鏈接已經可以直接點擊了，於是，你就可以在瀏覽器中直接點擊這些鏈接來實現各頁面的跳轉，非常方便。

由此可見，基於Apworks在ASP.NET Core Web API中為RESTful服務增加對HAL的支持還是非常方便的。在上面分頁的案例中，分頁查詢是通過在URL中增加名為page的Query String來實現了，page這個Query String就對應Get方法中的第一個page參數。那么，如果我希望使用其它的Query String來作為分頁的頁碼參數，又該如何做呢？

自定義分頁參數

自定義分頁參數方法非常簡單，只需要在參數定義前加上PageNumberAttribute就行了。比如下面的Get方法：

[HttpGet]
[SupportsHal]
public IActionResult Get([PageNumber] int p = 1, int size = 5)
{
    var values = new[] { "a", "b", "c", "d", "e",
        "f", "g", "h", "i", "j",
        "k", "l", "m", "n", "o",
        "p","q", "r","s","t",
        "u","v","w","x","y",
        "z" };
    var skip = (p - 1) * size;
    var take = size;
    var records = values.Length;
    var pages = (records + size - 1) / size;
    return Ok(new PagedResult(values.Skip(skip).Take(take), p, size, records, pages));
}

我們通過PageNumberAttribute來指定參數p為分頁參數，那么，在訪問特定頁的數據時，就可以使用http://localhost:52566/api/values?p=2這樣的方式：

客戶端范例

既然我們已經有了一個服務端分頁的RESTful API，我們不妨快速搭建一個客戶端App，來試用一下這個支持HAL JSON格式的服務端分頁API是否好用。為此，我建立了一個客戶端項目，開發采用Angular 4和TypeScript，主要代碼如下：

// LettersResponse.ts
export class LettersResponse {
    public first: string;
    public prev: string;
    public next: string;
    public last: string;
    public values: string[];
}

// my-letters-service.service.ts
@Injectable()
export class MyLettersServiceService {

  constructor(private http: Http) { }

  getLetters(url: string): Promise<LettersResponse> {
    return this.http.get(url)
      .toPromise()
      .then(response => {
        const json = response.json();
        return {
          first: json._links.first ? json._links.first.href : null,
          last: json._links.last ? json._links.last.href : null,
          prev: json._links.prev ? json._links.prev.href : null,
          next: json._links.next ? json._links.next.href : null,
          values: json._embedded.values
        };
      });
  }
}

// app.component.ts
@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
  providers: [MyLettersServiceService]
})
export class AppComponent implements OnInit {

  response: LettersResponse;

  constructor(private service: MyLettersServiceService) {
  }

  ngOnInit(): void {
    this.service.getLetters(environment.serviceUrl)
      .then(res => this.response = res);
  }

  onLinkClicked(url: string): void {
    console.log(url);
    this.service.getLetters(url)
    .then(res => this.response = res);
  }
}

// app.component.html
<div *ngIf="response">
  <ul>
    <li *ngFor="let c of response.values">
      <h2>{{c}}</h2>
    </li>
  </ul>
  <button (click)="onLinkClicked(response.first)" [disabled]="!response.first">First Page</button>
  <button (click)="onLinkClicked(response.prev)" [disabled]="!response.prev">Previous Page</button>
  <button (click)="onLinkClicked(response.next)" [disabled]="!response.next">Next Page</button>
  <button (click)="onLinkClicked(response.last)" [disabled]="!response.last">Last Page</button>
</div>

在命令行使用NgCLI啟動客戶端程序，然后訪問http://localhost:4200，得到的效果如下：

總結

本文介紹了如何使用Apworks對於ASP.NET Core的擴展，來實現為RESTful API提供HAL支持的功能。文章使用了兩個案例，展示了ASP.NET Core Web API對HAL的支持是非常簡單方便的，而且自定義功能很強大，第二個服務端分頁案例更是引入了Angular和TypeScript，通過實現一個簡單的客戶端頁面來更詳細地展示具有HAL特性的RESTful API的便捷之處。正如上文所說，對HAL的支持僅僅是Apworks框架中對ASP.NET Core進行擴展的一個部分，Apworks框架更多地專注於為微服務的快速開發提供解決方案。在今后的文章中，我會更多地介紹Apworks對微服務支持的相關內容。

免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。

猜您在找 ASP.NET Core Web API 開發-RESTful API實現支持多個版本的ASP.NET Core Web API 使用靜態基類方案讓 ASP.NET Core 實現遵循 HATEOAS Restful Web API ASP.NET Core Web API中Startup的使用技巧 ASP.Net Core Web API中的IActionFilter總結 Asp.Net Core中的Web服務器通過擴展讓ASP.NET Web API支持JSONP 【無私分享：ASP.NET CORE 項目實戰（第十二章）】添加對SqlServer、MySql、Oracle的支持使用 ASP.NET Core MVC 創建 Web API（四） ASP.NET Core Web API 集成測試