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 可以很简单的解决该问题。后续的文档中我们将连续使用该业务场景进行演示，因此，此处进行一下简单的业务场景说明。

业务规则

业务规则大致如下：

  1. 每个拍卖品由一个唯一的 itemId
  2. 拍卖品只能在一段时间内进行竞价拍卖
  3. 拍卖品有一个起始拍卖价格
  4. 所有的竞拍者都拥有一个唯一的 userId
  5. 竞拍者在拍卖时间段内可以无限次对拍卖品进行出价，只要其出价大于当前最高出价，即可算作有效出价，并成为该拍卖品目前的得标人
  6. 需要记录所有成功出价的详细情况，包括出价时间，出价额，出价人。

拍卖品的状态如下：

  • 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"
  }
}

以上结果说明：

  • 出价记录已更新，添加了最新的一条竞拍详情。

这样便完成了最简单的出价演示。

开发者可以自行尝试更多不同的状态和参数体验以上 API 的基础用法。例如，出价小于当前最高出价，对非再拍商品进行出价等等操作。

停止项目

若想要停止当前正在运行的模板项目。只要在刚才运行 tye run 的控制台上使用键盘按下 Ctrl+C 即可停止正在运行的程序。

小结

本篇我们了解了安装项目模板和使用项目模板的基本步骤。

下一步，我们将介绍项目模板中包含的主要内容。

最后但是最重要！

如果读者对该内容感兴趣，欢迎转发、评论、收藏文章以及项目。

最近作者正在构建以 Actor 模式 和 事件溯源 为理论基础的一套服务端开发框架。希望为开发者提供能够便于开发出 “分布式”、“可水平扩展”、“可测试性高” 的应用系统 ——Newbe.Claptrap

本篇文章是该框架的一篇技术选文，属于技术构成的一部分。

项目文档库：claptrap.newbe.pro

联系方式： QQ 群 610394020

您还可以查阅本系列的其他选文：

理论入门篇

  1. Newbe.Claptrap - 一套以 “事件溯源” 和 “Actor 模式” 作为基本理论的服务端开发框架

术语介绍篇

  1. Actor 模式
  2. 事件溯源（Event Sourcing）
  3. Claptrap
  4. Minion
  5. 事件 （Event）
  6. 状态 （State）
  7. 状态快照 （State Snapshot）
  8. Claptrap 设计图 （Claptrap Design）
  9. Claptrap 工厂 （Claptrap Factory）
  10. Claptrap Identity
  11. Claptrap Box
  12. Claptrap 生命周期（Claptrap Lifetime Scope）
  13. 序列化（Serialization）
  14. 最小竞争资源 (Minimal Competing Resources)

样例实践篇

  1. 设计一个火车票销售系统

开发入门篇

  1. Newbe.Claptrap 框架入门，第一步 —— 开发环境准备
  2. Newbe.Claptrap 框架入门，第二步 —— 创建项目

开发工具篇

  1. 使用 Tye 辅助开发 k8s 应用竟如此简单（一）
  2. 使用 Tye 辅助开发 k8s 应用竟如此简单（二）
  3. 使用 Tye 辅助开发 k8s 应用竟如此简单（三）
  4. 使用 Tye 辅助开发 k8s 应用竟如此简单（四）
  5. 使用 Tye 辅助开发 k8s 应用竟如此简单（五）
  6. 使用 Tye 辅助开发 k8s 应用竟如此简单（六）

其他番外篇

  1. 谈反应式编程在服务端中的应用，数据库操作优化，从 20 秒到 0.5 秒
  2. 谈反应式编程在服务端中的应用，数据库操作优化，提速 Upsert
  3. 十万同时在线用户，需要多少内存？——Newbe.Claptrap 框架水平扩展实验
  4. docker-mcr 助您全速下载 dotnet 镜像
  5. 十多位全球技术专家，为你献上近十个小时的.Net 微服务介绍
  6. 年轻的樵夫哟，你掉的是这个免费 8 核 4G 公网服务器，还是这个随时可用的 Docker 实验平台？
  7. 如何使用 dotTrace 来诊断 netcore 应用的性能问题
  8. 只要十步，你就可以应用表达式树来优化动态调用

GitHub 项目地址：https://github.com/newbe36524/Newbe.Claptrap

Gitee 项目地址：https://gitee.com/yks/Newbe.Claptrap

您当前查看的是先行发布于 www.newbe.pro 上的博客文章，实际开发文档随版本而迭代。若要查看最新的开发文档，需要移步 claptrap.newbe.pro。

Newbe.Claptrap

------ 本文结束 ------
posted @ 2021-02-28 13:19  Newbe36524  阅读(293)  评论(1)  编辑  收藏  举报