原文地址:
https://andrewlock.net/using-strongly-typed-entity-ids-to-avoid-primitive-obsession-part-1/

<https://andrewlock.net/using-strongly-typed-entity-ids-to-avoid-primitive-obsession-part-1/>
作者:Andrew Lock
译者:Lamond Lu
译文地址:https://www.cnblogs.com/lwqlun/p/10693763.html
<https://www.cnblogs.com/lwqlun/p/10693763.html>



回想一下,在你以往编程的过程中,是否经常遇到以下场景:当你从一个服务(Web Api/Database/通用服务)中请求一个实体时,服务响应404,
但是你确信这个实体是存在的。这种问题我已经见过很多次了,有时候它的原因是请求实体时使用了错误的ID。 在本篇博文中,我将描述一种避免此类错误(
原始类型困扰)的方法,并使用C#的类型系统来帮助我们捕获错误。

其实,许多比我厉害的程序员已经讨论过C#中原始类型困扰的问题了。特别是Jimmy Bogard
<https://lostechies.com/jimmybogard/2007/12/03/dealing-with-primitive-obsession/>
,Mark Seemann <http://blog.ploeh.dk/2011/05/25/DesignSmellPrimitiveObsession/>,
Steve Smith <http://www.weeklydevtips.com/012>和Vladimir Khorikov
<https://enterprisecraftsmanship.com/2015/03/07/functional-c-primitive-obsession/>
编写的一些文章, 以及Martin Fowler的代码重构书籍
<https://martinfowler.com/articles/refactoring-2nd-ed.html>。最近我正在研究F#,
据我所知,这被认为是一个已解决的问题!

原始类型困扰的一个例子

为了给出一个问题说明,我将使用一个非常基本的例子。假设你有一个电子商务的网站,在这个网站中用户可以下订单。

其中订单拥有以下的简单属性。
public class Order { public Guid Id { get; set; } public Guid UserId { get;
set; } public decimal Total { get; set; } }
你可以通过OrderService来创建和读取订单。
public class OrderService { private readonly List<Order> _orders = new
List<Order>(); public void AddOrder(Order order) { _orders.Add(order); } public
Order GetOrderForUser(Guid orderId, Guid userId) { return
_orders.FirstOrDefault( order => order.Id == orderId && order.UserId ==
userId); } }
为了简化代码,这里我们将订单对象保存在内存中,并且只提供了两个方法。

* AddOrder(): 在订单集合中添加订单
* GetOrderForUser(): 根据订单Id和用户Id获取订单信息
最后,我们创建一个API控制器,调用这个控制器我们可以创建新订单或者获取一个订单信息。
[Route("api/[controller]")] [ApiController, Authorize] public class
OrderController : ControllerBase { private readonly OrderService _service;
public OrderController(OrderService service) { _service = service; } [HttpPost]
public ActionResult<Order> Post() { var userId =
Guid.Parse(User.FindFirstValue(ClaimTypes.NameIdentifier)); var order = new
Order { Id = Guid.NewGuid(), UserId = userId }; _service.AddOrder(order);
return Ok(order); } [HttpGet("{orderId}")] public ActionResult<Order> Get(Guid
orderId) { var userId =
Guid.Parse(User.FindFirstValue(ClaimTypes.NameIdentifier)); var order =
_service.GetOrderForUser(userId, orderId); if (order == null) { return
NotFound(); } return order; } }
这个API控制器被一个[Authorize]特性所保护,用户只有登录之后才能调用它。

这里控制器提供了2个action方法:

* Post(): 用来创建新订单。新的订单信息会放在响应体内返回。
* Get(): 根据一个指定的ID获取订单信息。如果订单存在,就将该订单信息放在响应体内返回。
这两个方法都需要知道当前登录用户的UserId, 所以这里需要从用户Claims里面获取ClaimTypes.NameIdentifier,并将其转换成
Guid类型。

不幸的是,以上API控制器的代码是有Bug的。

你能找到它么?

如果找不到也没有关系,但是我觉着我能找到。

Bug - 所有的GUID参数都是可以互换的。

代码编译之后,你可以成功的添加一个新订单,但是调用GET()方法时却总是返回404。

这里问题出在OrderController.Get()方法中,使用OrderService获取订单的部分。
var order = _service.GetOrderForUser(userId, orderId);
这个方法的方法签名如下
public Order GetOrderForUser(Guid orderId, Guid userId);
UserId和OrderId在方法调用时,写反了!!

这个例子看起来似乎有点像人为错误(要求提供UserId感觉有点多余),但是这种模式可能是你在实践中经常看到的。这里的问题是,我们使用了原始类型
System.GUID
来表示了两个不同的概念:用户的唯一标识符和订单的唯一标识符。使用原始类型值来表示领域概念的问题,我们称之为原始类型困扰(Primitive
Obsession)。

原始类型困扰

在这里,原始类型指的是C#中的内置类型,bool, int, Guid, string
等。原始类型困扰是指过度使用这些内置类型来表示领域概念,其实这并不适合。这里一个常见的例子是使用string类型表示邮编或者电话号码(使用int类型更糟糕)。

乍看之下,使用string类型可能是有意义的,毕竟你可以使用一串字符表示邮编,但是这里会有几个问题。

首先,如果使用内置类型 string,
所有和邮编相关的逻辑都只能存储在类型之外的其他地方。例如,不是所有的字符串都是合法的邮编,所以你需要在你的应用中针对邮编添加验证。如果你有一个ZipCode
类型,你可以将验证逻辑封装在里面。相反的,如果使用string
类型,你将不得不把这些逻辑放在程序的其他地方。这意味着数据(邮政编码的值)和针对数据的操作方法被分离了,这打破了封装。

第二点,使用原始类型表示领域概念,你将失去一些从类型系统中获取的好处。

例如,C#的编译器不会允许你做以下的事情。
int total = 1000; string name = "Jim"; name = total; // compiler error
但是当你将一个电话号码值赋给一个邮政编码变量就没有问题,即使从逻辑上看,这就是个Bug。
string phoneNumber = "+1-555-229-1234"; string zipCode = "1000 AP" zipCode =
phoneNumber; // no problem!
你可能会觉着这种“错误分配”类型的错误很少见,但是它经常出现在将多个原始类型对象作为参数的方法。这就是之前我们在GetOrderForUser()
方法中出现问题的原因。

那么,我们该如何避免原始类型困扰呢?

答案是使用封装。我们可以针对每一个领域概念创建一个自定义类型,而不是用使用原始类型来表示它们。例如,我们可以创建一个ZipCode类来封装概念,放弃使用
string类型来表示邮编,并在整个领域模型和整个应用中使用ZipCode类型来表示邮编的概念。

使用强类型ID

所以现在回到我们之前的问题,我们该如何避免GetOrderForUser方法调用错误的ID呢?
var order = _service.GetOrderForUser(userId, orderId);
我们可以使用封装!我们可以为订单ID和用户ID创建对应的强类型ID。

原始的方法签名:
public Order GetOrderForUser(Guid orderId, Guid userId);
使用强类型ID的方法签名:
public Order GetOrderForUser(OrderId orderId, UserId userId);
一个OrderId是不能指派给一个UserId的,反之亦然。所以这里没有办法使用错误的参数顺序来调用GetOrderForUser方法 - 编译器会报错。

那么, OrderId和UserId类型的代码应该怎么写呢?这取决与你自己,但是在下一部分中,我将展示一个实现的示例。

OrderId类型的实现。

以下是OrderId类型的实现代码。
public readonly struct OrderId : IComparable<OrderId>, IEquatable<OrderId> {
public Guid Value { get; } public OrderId(Guid value) { Value = value; } public
static OrderId New() => new OrderId(Guid.NewGuid()); public bool Equals(OrderId
other) => this.Value.Equals(other.Value); public int CompareTo(OrderId other)
=> Value.CompareTo(other.Value); public override bool Equals(object obj) { if
(ReferenceEquals(null, obj)) return false; return obj is OrderId other &&
Equals(other); } public override int GetHashCode() => Value.GetHashCode();
public override string ToString() => Value.ToString(); public static bool
operator ==(OrderId a, OrderId b) => a.CompareTo(b) == 0; public static bool
operator !=(OrderId a, OrderId b) => !(a == b); }
这里我将OrderId定义成了一个struct - 它只是一个封装了一个Guid类型数据的简单类型,所以使用class
可能有点小题大做了。但是,也就是说,如果你使用了像EF 6这种ORM, 使用struct可能会出现问题,所以使用class
可能更容易。这也为提供了创建基于强类型ID类的选项,以避免一些问题。

使用struct还会有一些其他的潜在问题,例如C#中struct是没有无参构造函数的。

该类型中唯一的数据保存在属性Value中,它包含了我们之前传递的原始Guid值。 这里我们定义了一个构造函数,要求你传入Guid值。

OrderId 中大部分功能都是来自复写标准object类型对象的方法,以及IEquatable<T>和IComparable<T>
的接口定义方法。这里我们也复写了相等判断操作符。

接下来,我将展示一下我针对这个强类型ID编写的一些测试。

测试强类型ID的行为

以下的xUnit测试演示了强类型ID - OrderId的一些特性。 这里我们还使用了(类似定义的)UserId来证明它们是不同的类型。
public class StronglyTypedIdTests { [Fact] public void SameValuesAreEqual() {
var id = Guid.NewGuid(); var order1 = new OrderId(id); var order2 = new
OrderId(id); Assert.Equal(order1, order2); } [Fact] public void
DifferentValuesAreUnequal() { var order1 = OrderId.New(); var order2 =
OrderId.New(); Assert.NotEqual(order1, order2); } [Fact] public void
DifferentTypesAreUnequal() { var userId = UserId.New(); var orderId =
OrderId.New(); //Assert.NotEqual(userId, orderId); // 编译不通过
Assert.NotEqual((object) bar, (object) foo); } [Fact] public void
OperatorsWorkCorrectly() { var id = Guid.NewGuid(); var same1 = new
OrderId(id); var same2 = new OrderId(id); var different = OrderId.New();
Assert.True(same1 == same2); Assert.True(same1 != different);
Assert.False(same1 == different); Assert.False(same1 != same2); } }
通过使用像这样的强类型ID,我们可以充分利用C#的类型系统,以确保不会意外地传错ID。
在领域业务核心中使用这些类型将有助于防止一些简单的错误,例如不正确的参数顺序问题。这很容易做到,并且很难发现!

但是高兴地太早,这里还有待解决问题。 确实,你可以很容易地在领域业务核心中使用这些类型,但不可避免地,你最终还是要与外部进行交互。
目前,最常用的是在MVC和ASP.NET Core中通过一些JSON API来传递数据。
在下一篇文章中,我将展示如何创建一些简单的转换器,以便更加简单地处理强类型ID。

总结


C#拥有一个很棒的类型系统,所以我们应该尽量利用它。原始类型困扰是一个非常常见的场景,但是你需要尽量去客服它。在本篇博文中,我展示了使用强类型ID来避免传递错误ID的问题。在下一篇我将扩展这些类型,以便让他们在ASP.NET
Core应用中更容易使用。