Newbe.Claptrap 框架入門，第二步 —— 創建項目

接上一篇 Newbe.Claptrap 框架入門，第一步 —— 開發環境准備，我們繼續了解如何創建一個 Newbe.Claptrap 項目。

Newbe.Claptrap 是一個用於輕松應對並發問題的分布式開發框架。如果您是首次閱讀本系列文章。建議可以先從本文末尾的入門文章開始了解。

安裝項目模板

打開控制台運行以下命令來安裝最新的項目模板：

dotnet new --install Newbe.Claptrap.Template

安裝完畢后，可以在安裝結果中查看到已經安裝的項目模板。

newbe.claptrap.template安裝完畢

創建項目

選擇一個位置，創建一個文件夾，本示例選擇在 D:\Repo 下創建一個名為 HelloClaptrap 的文件夾。該文件夾將會作為新項目的代碼文件夾。

打開控制台，並且將工作目錄切換到 D:\Repo\HelloClaptrap。然后運行以下命令便可以創建出項目：

dotnet new newbe.claptrap --name HelloClaptrap

通常來說，我們建議將 D:\Repo\HelloClaptrap 創建為 Git 倉庫文件夾。通過版本控制來管理您的源碼。

啟動項目

接下來，我們使用命令行啟動項目。將命令行切換到 C:\Repos\HelloClaptrap\HelloClaptrap，運行以下命令：

tye run

啟動之后可以在 tye dashboard 上查看到項目模板包含的所有項目：

newbe.claptrap service

tye dashboard 的地址通常為 http://localhost:8000，若端口被占用將自動使用其他端口，可以查看命令行上的提示，以得到當前具體的地址。

我們可以在如上圖所示的界面上找到 helloclaptrap-webapi 服務的運行地址。例如，上圖所示，其終結點地址為 http://localhost:14285。

因此，我們使用瀏覽器打開該地址，以查看 swagger 界面。

在 swagger 頁面上，嘗試調用/AuctionItems/{itemId}/statusAPI：

newbe.claptrap AuctionItems

服務返回 200 說明當前服務各個組件已經正常啟動。

體驗項目

使用項目模板創建的項目實際上是一個模擬拍賣競價業務的程序。

拍賣競價是一個典型的可能具有並發請求需要處理的業務場景。使用 Newbe.Claptrap 可以很簡單的解決該問題。后續的文檔中我們將連續使用該業務場景進行演示，因此，此處進行一下簡單的業務場景說明。

業務規則

業務規則大致如下：

每個拍賣品由一個唯一的 itemId
拍賣品只能在一段時間內進行競價拍賣
拍賣品有一個起始拍賣價格
所有的競拍者都擁有一個唯一的 userId
競拍者在拍賣時間段內可以無限次對拍賣品進行出價，只要其出價大於當前最高出價，即可算作有效出價，並成為該拍賣品目前的得標人
需要記錄所有成功出價的詳細情況，包括出價時間，出價額，出價人。

拍賣品的狀態如下：

0 Planned 等待開拍
1 OnSell 正在拍賣
2 Sold 已經拍出
3 UnSold 流拍

API 設計

為了最簡單的演示效果，本樣例設計了以下這些 API ：

GET /AuctionItems/{itemId}/status 獲取指定拍賣品當前的競價狀態
GET /AuctionItems/{itemId} 獲取指定拍賣品的詳細信息
POST /AuctionItems 對指定的拍賣品進行出價

下面我們使用一個簡單的場景來體驗一下這些 API 的效果。

尋找當前在拍的拍賣品

由於拍賣品的狀態受到時間的影響，為了讓開發者可以在任何時候都可以找到各種狀態的拍賣品，項目中使用了一些基於時間的算法，來生成所有狀態的拍賣品。

開發者可以使用 0/1/2/3 四個 itemId 調用 GET /AuctionItems/{itemId}/status 獲取拍賣品當前的狀態。

其中至少存在一個狀態為 1 OnSell 的拍賣品。為了后續方便說明，我們假設其 itemId 為 1。

查看拍賣品的詳細信息

使用 GET /AuctionItems/{itemId} 可以查詢到拍賣品的詳細信息。例如，我們使用 itemId 為 1 進行查詢，可能可以得到如下結果:

{
 "state": {
 "biddingRecords": null,
 "basePrice": 10,
 "startTime": "2021-02-27T12:59:12.673013+08:00",
 "endTime": "2021-02-27T16:59:12.673013+08:00"
 }
}

以上結果說明：

該拍賣品的起拍價格為 basePrice 10
競拍時間段為 startTime - endTime 時間的時段
當前的競拍記錄 biddingRecords 為空

其中時段可能由於啟動項目模板的時間發生變化，視具體項目啟動時間而定。

嘗試出價

接下來，我們調用 POST /AuctionItems 嘗試對當前在拍的拍賣品進行出價，調用並傳入參數如下：

{
 "userId": 1,
 "price": 36524,
 "itemId": 1
}

參數說明如下：

出價人 userId 為 1
出價為 36524
拍賣品為 itemId 1

這將得到結果：

{
 "success": true,
 "userId": 1,
 "auctionItemStatus": 1,
 "nowPrice": 36524
}

返回結果表明：

success 出價成功
出價人 userId 為 1
最新出價為 36524
拍賣品當前狀態為 1 OnSell

然后在使用 GET /AuctionItems/{itemId} 便可以查看到當前最新的拍賣品情況：

{
 "state": {
 "biddingRecords": {
 "36524": {
 "userId": 1,
 "price": 36524,
 "biddingTime": "2021-02-27T07:31:09.8954519+00:00"
 }
 },
 "basePrice": 10,
 "startTime": "2021-02-27T12:59:12.673013+08:00",
 "endTime": "2021-02-27T16:59:12.673013+08:00"
 }
}