OData WebAPI实践-OData与EDM

本文属于 OData 系列

引言

在 OData 中，EDM（Entity Data Model） 代表“实体数据模型”，它是一种用于表示 Web API 中的结构化数据的格式。EDM 定义了可以由 OData 服务公开的数据类型、实体和关系。 EDM 也提供了一些规则来描述数据模型中的实体之间的关系，例如继承、关联和复合类型。EDM 是 OData 协议的核心组成部分之一，它允许客户端和服务器之间以一致的方式交换和操作数据。

EDM 与实体对象模型

我刚接触 EDM 时恰好是与 EF Core 一起使用，就非常不理解这个现象：明明已经在 EF Core 中已经定义了模型，为啥还需要单独配置一个 EDM？

其实，EDM 和实体框架（EF）Core 中的实体对象虽然都用于数据建模，但却是不同的概念：在 EF Core 中，实体对象表示数据库中的表或视图，而 EDM 定义了 OData 服务中的数据结构，包括实体、属性、导航属性等。可以理解实体对象是为数据库服务，而 EDM 是用于数据开放服务的。

虽然 EDM 和 EF Core 中的实体对象都具有一些相似之处，例如它们都有属性和关系，甚至你也可以直接返回实体模型用提供给 OData 让其动态自动生成 EDM 模型（Non-ODM 模式），但是依然建议使用 EDM 模型，主要是有几个方面：

1. 实体框架中的实体类可能包含与 OData 服务定义不同的属性。例如，实体框架中的实体类可能包含用于持久化和跟踪状态的属性，而这些属性可能并不需要在 OData 服务中公开。
2. 实体框架中的实体类可能使用与 OData 服务定义不同的命名约定。例如，实体框架中的实体类可能使用 PascalCase（首字母大写）命名约定，而在 OData 服务中的 EDM 可以使用 camelCase（首字母小写）命名约定。
3. 实体框架中的实体类可能包含与 OData 服务定义不同的数据结构。例如，联合主键的实现用于 OData 查询较为麻烦，可以配置 EDM 使得 OData 对外服务不使用联合主键。

EDM 配置

在配置 OData 时，我们需要在代码中提供 EDM 对象。

.AddRouteComponents(AuthorizeHelper.PREFIX, EdmHelper.GetEdmModels());

GetEdmModels 函数返回一个 IEdmModel 对象。

      public static IEdmModel GetEdmModels()
        {
            ODataConventionModelBuilder builder = new ODataConventionModelBuilder();

            var device = builder.EntitySet<DeviceInfo>("DeviceInfos").EntityType.HasKey(p => p.DeviceId);
			device.Action("Upload");
            builder.EnableLowerCamelCase();
            return builder.GetEdmModel();
        }

以上代码中对 DeviceInfo 类型定义了一个实体对象，其具有 DeviceId 作为主键，拥有一个名为 Upload 的 Action。并且对所有的 EDM 对象启用了 LowerCamelCase 支持。上面的感觉是挺简单的是吧，注意我们使用到了 ODataConventionModelBuilder 对象，这个对象帮助我们自动实现了很多配置内容。如果我们使用其他的方式就不那么简单了。实际上配置 EDM 总共有三种方式。

我一般只使用 Convention 的配置方法，因此这里引用官方网站的例子，详情请见 Introduction to the model builders - OData | Microsoft Learn

Explicit

如果模型通过 new EdmModel() 构建，那么构建的是无类型模型，相当于你不依赖现有的 CLR 类型凭空构建了一个模型。

public IEdmModel GetEdmModel()
{
    EdmModel model = new EdmModel();
    
	EdmEntityType customer = new EdmEntityType("WebApiDocNS", "Customer");
	customer.AddKeys(customer.AddStructuralProperty("CustomerId", EdmPrimitiveTypeKind.Int32));
	customer.AddStructuralProperty("Location", new EdmComplexTypeReference(address, isNullable: true));
	model.AddElement(customer);
	
	EdmEntityType order = new EdmEntityType("WebApiDocNS", "Order");
	order.AddKeys(order.AddStructuralProperty("OrderId", EdmPrimitiveTypeKind.Int32));
	order.AddStructuralProperty("Token", EdmPrimitiveTypeKind.Guid);
	model.AddElement(order);

    return model;
}

Non-convention

如果模型是依赖 new ODataModelBuilder() 构建，那么构建模型时可以依据现有的 CLR 对象进行构建，不过依然需要配置每一个属性、操作等。

public static IEdmModel GetEdmModel()
{
    var builder = new ODataModelBuilder();
    var customer = builder.EntityType<Customer>();
customer.HasKey(c => c.CustomerId);
customer.ComplexProperty(c => c.Location);
customer.HasMany(c => c.Orders);

	var order = builder.EntityType<Order>();
order.HasKey(o => o.OrderId);
order.Property(o => o.Token);
    return builder.GetEdmModel();
}

相当于前一种方法已经有了很大改进，我们可以依赖现有的结构，而不再需要手动去命名了。

Convention

更进一步，我们可以使用惯例 （ Convention ）方式，模型依赖 new ODataConventionModelBuilder () 构建，这个是代码最少的，整个模型的配置按照 OData RESTful 惯例实现。

      public static IEdmModel GetEdmModels()
        {
            ODataConventionModelBuilder builder = new ODataConventionModelBuilder();

            var device = builder.EntitySet<DeviceInfo>("DeviceInfos").EntityType;
            return builder.GetEdmModel();
        }

Convention 涉及的内容很多，有机会以后会详细解释惯例生成 EDM 这种模式。

常用 EDM 配置

EDM 配置项目繁多，我们常用的有：

• 配置实体（主键）

var device = builder.EntitySet<DeviceInfo>("DeviceInfos").EntityType;

• 配置（集合） Action

//对于实体上的Action
device.Action("Upload");
//对于集合上的Action
device.Collection.Action("Upload");

• 配置（集合） Function

//对于实体上的Function
device.Function("Data").Returns<string>();
//对于集合上的Function
device.Collection.Function("Data").Returns<string>();

对 Function 以及 Action 的详细介绍，请期待后续文章。

访问 EDM 模型

OData 服务提供了 $metadata 终结点，可以从服务的根 URL 后添加 $metadata 来访问。例如以下是一个可以直接访问的 EDM 模型，以 XML 形式提供：

http://services.odata.org/TripPinRESTierService/$metadata

此外，也可以使用某些工具（如 Microsoft 的 OData Connected Service）来自动生成客户端代码，并从服务中获取元数据。这些工具通常会从服务的根 URL 下载 $metadata 文件，并将其解析为客户端代码。