OData 4.0 核心规范（中文版）

1. 概述

OData（Open Data Protocol）是一个开放的RESTful数据访问协议，OData 4.0是其最新的核心版本，旨在简化数据服务的创建和消费。它允许客户端通过标准化的HTTP方法（GET/POST/PUT/PATCH/DELETE）访问和操作数据源，支持JSON和XML两种数据格式。

2. 核心概念

2.1 资源模型

实体（Entity）：表示数据的基本单元，如用户、产品等，每个实体有唯一标识符
实体集（Entity Set）：同类型实体的集合，如Users、Products，是实体的容器
属性（Property）：实体的特征，如ID、Name、Price，分为基本类型和复杂类型
导航属性（Navigation Property）：实体间的关联关系，如用户的订单、产品的分类

2.2 服务文档与元数据

OData服务必须提供元数据文档（$metadata），描述数据模型的结构，客户端可通过以下请求获取：

GET /odata/$metadata HTTP/1.1
Host: example.com
Accept: application/xml

3. URL语法

3.1 基础URL结构

http://example.com/odata/[实体集]/[实体ID]?[查询选项]

3.2 常用查询选项

查询选项	用途	示例
$select	选择返回的属性，减少数据传输量	$select=Id,Name,Price
$filter	按条件过滤数据，支持多种运算符	$filter=Price gt 100 and Category eq '电子'
$orderby	对结果排序，支持升序（asc）和降序（desc）	$orderby=Price desc, Name asc
$top/$skip	分页查询，$top取前N条，$skip跳过前N条	$top=10&$skip=20（获取第21-30条）
$expand	展开关联实体，减少多次请求	$expand=Orders($select=OrderId,Amount)

4. 请求方法

HTTP方法	用途	示例
GET	查询单个/多个实体	GET /odata/Products(1) （查询ID=1的产品）
POST	创建新实体	POST /odata/Products + JSON数据
PUT	全量更新实体（必须传所有属性）	PUT /odata/Products(1) + JSON数据
PATCH	部分更新实体（只需传修改的属性）	PATCH /odata/Products(1) + JSON数据
DELETE	删除实体	DELETE /odata/Products(1)

5. 响应格式（JSON）

{
  "@odata.context": "http://example.com/odata/$metadata#Products/$entity",
  "Id": 1,
  "Name": "智能手机",
  "Price": 2999.00,
  "Category": "电子设备",
  "CreateTime": "2025-01-01T12:00:00Z"
}

6. 错误处理

OData 4.0定义了标准化的错误响应格式，便于客户端统一处理：

{
  "error": {
    "code": "404",
    "message": "请求的实体不存在",
    "target": "ProductId",
    "details": [
      {
        "code": "EntityNotFound",
        "message": "ID为10的产品不存在",
        "target": "Id"
      }
    ],
    "innererror": {
      "trace": "内部调试信息",
      "context": "请求上下文"
    }
  }
}