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 模型，主要是有几个方面：

实体框架中的实体类可能包含与 OData 服务定义不同的属性。例如，实体框架中的实体类可能包含用于持久化和跟踪状态的属性，而这些属性可能并不需要在 OData 服务中公开。
实体框架中的实体类可能使用与 OData 服务定义不同的命名约定。例如，实体框架中的实体类可能使用 PascalCase（首字母大写）命名约定，而在 OData 服务中的 EDM 可以使用 camelCase（首字母小写）命名约定。
实体框架中的实体类可能包含与 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 文件，并将其解析为客户端代码。