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

C#

浏览数:161

2019-5-5

AD:资源代下载服务

原文地址: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 SmithVladimir 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);

UserIdOrderId在方法调用时,写反了!!

这个例子看起来似乎有点像人为错误(要求提供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方法 – 编译器会报错。

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

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应用中更容易使用。

作者:LamondLu