OData WebAPI实践-兼容OData集合响应

WebAPI,OData · 浏览次数 : 268

小编点评

**OData 标准请求与返回形式** OData 是一种开放标准，其标准请求与返回形式可以在 oasis 组织标准化中查询到。对于实体对象和实体对象的集合，OData 提供了不同的返回格式，以确保兼容性。 **实体对象** 当返回单个实体对象时，OData 会返回一个 JSON 对象，其中包含以下内容： * `@odata.context`：指向 OData 路由的上下文链接。 * `timestamp`：当前时间戳。 * `max`、`min`、`avg`：实体对象的最大值、最小值和平均值。 **实体对象的集合** 当返回实体对象的集合时，OData 会返回一个 JSON 对象，其中包含以下内容： * `@odata.context`：指向 OData 路由的上下文链接。 * `timestamp`：当前时间戳。 * `items`：包含实体对象的数组。 **封装** 为了让前端访问非 OData 路由 API 的资源，可以考虑在返回对象时进行封装。例如，可以使用 `value` 作为 key 对齐进行封装，将原始数组对象转换为 JSON 对象。 **示例** ```csharp // 实体对象 [Serializable] public class DeviceDataDto { public string timestamp { get; set; } public double max { get; set; } public double min { get; set; } public double avg { get; set; } } // 实体对象集合 public class DeviceDataDtoCollection { public DeviceDataDto[] items { get; set; } } // 获取实体对象 [HttpGet("/api/v1/Current")] [ProducesResponseType(typeof(DeviceDataDto), Status200OK)] public IActionResult Current(string key) { // 封装实体对象 var deviceDataDto = _context.DeviceData.Find(key); return Ok(_mapper.Map(deviceDataDto)); } ``` **注意** * OData 标准提供了多种返回格式，根据特定需求可以选择合适的格式。 * 在返回非 OData 路由 API 的资源时，需要进行封装，例如使用 `value` 对齐进行封装。

正文

本文属于 OData 系列文章

引言

OData 是一个开放标准，已经在 oasis 组织标准化，因此我们可以在标准的官网查询到 OData 的标准请求与返回形式：OData JSON Format Version 4.01 (oasis-open.org)

针对不同的数据类型，输出返回的格式也不尽相同，涉及的内容非常多。日常使用 OData 的过程中，我们经常处理的是实体对象以及实体对象的集合。如果直接返回 IQueryable 用于 OData 查询，那么返回的数据大多是集合（数组/列表）。

{
    "@odata.context": "http://localhost:9000/api/v2/$metadata#Collection(Datum_AggDto)",
    "@odata.count": 2,
    "value": [
        {
            "timestamp": 1682294400000,
            "max": 180.0,
            "min": 152.0,
            "avg": 161.7605633802817
        },
        {
            "timestamp": 1682985600000,
            "max": 281.0,
            "min": 180.0,
            "avg": 228.39583333333334
        }]
}

这个数组对象也不是很纯粹，它被 value 封装，并且提供了 @odata.context 元数据链接。如果我们的 API 没有被 OData 路由解析，那么默认 WEBAPI 会返回一个纯粹的数组对象：

[
{
	"timestamp": 1682294400000,
	"max": 180.0,
	"min": 152.0,
	"avg": 161.7605633802817
},
{
	"timestamp": 1682985600000,
	"max": 281.0,
	"min": 180.0,
	"avg": 228.39583333333334
}]

假设我们的对外的数据接口不完全被 OData 路由，会导致前端访问的行为不一致：一些 API 可以直接解析，另外一些 API 则需要使用 value 封装后处理。

封装非 OData Route Mapping

由于 OData 有了标准，为了对外保持一致性，我们可以尝试在返回非 OData 路由 API 时，将原始数组对象进行封装。

单实体对象

        [HttpGet("/api/v1/Current")]
        [ProducesResponseType(typeof(DeviceDataDto), Status200OK)]
        public IActionResult Current(string key)
        {
            key = key.Trim('\'');
            var data = _context.DeviceData.Where(w => w.DeviceId == key).OrderByDescending(w => w.Timestamp).FirstOrDefault();

            return Ok(_mapper.Map<DeviceDataDto>(datas));
        }

对于以上的代码，只返回单个实体对象，返回的形式与 OData 标准中返回单个实体对象的标准一致，因此不需要额外的转换操作。

{
	//OData 返回会多一个context，普通API不会有。
	"@odata.context": "http://localhost:9000/api/v2/$metadata#Datum_AggDto",
	"timestamp": 1682985600000,
	"max": 281.0,
	"min": 180.0,
	"avg": 228.39583333333334
}

实体对象集合

        [HttpGet("/api/v1")]
        [ProducesResponseType(typeof(IEnumerable<DeviceDataDto>), Status200OK)]
        public async Task<IActionResult> Get(string key)
        {
            key = key.Trim('\'');
            return Ok(await _context.DeviceData.Where(w => w.DeviceId == key).ToListAsync());
        }

以上代码返回的类型是一个集合，并且被 OData 路由映射。我们使用 value 这个 key 对齐进行封装：

        [HttpGet("/api/v1")]
        [ProducesResponseType(typeof(IEnumerable<DeviceDataDto>), Status200OK)]
        public async Task<IActionResult> Get(string key)
        {
            key = key.Trim('\'');
            var datas = await _context.DeviceData.Where(w => w.DeviceId == key).ToListAsync();

            var result = new { Value = datas };
            return Ok(result);
        }

注意这个 Value 我使用的是大写，由于我启用了 camelCase，所以会自动转换为小写。这样前端访问 API 时，不论是否为 OData API 都可以访问 value 的值获取数组对象。