使用强类型实体Id来避免原始类型困扰（一）

2022-07-19 22:37:19

原文地址：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

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

其实，许多比我厉害的程序员已经讨论过C#中原始类型困扰的问题了。特别是Jimmy Bogard, Mark Seemann, Steve Smith和Vladimir Khorikov编写的一些文章, 以及Martin Fowler的代码重构书籍。最近我正在研究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应用中更容易使用。

码农公寓