OData（Open Data Protocol，开放数据协议）是ISO/IEC 20802和OASIS双认证的 RESTful API 国际标准，旨在为结构化数据的创建、查询、更新和删除提供统一的、可互操作的接口规范。它由微软于 2007 年首次提出，目前最新稳定版本为OData V4.01，已成为 SAP、微软、Salesforce 等企业构建数据中台和跨系统集成的核心协议。
一、OData 核心认知
1.1 什么是 OData
OData 本质上是对 REST 架构的深度标准化，它定义了一套通用的 URI 约定、查询语法和数据格式，使客户端能够以统一的方式访问和操作不同系统中的数据，无需为每个系统编写专用的 API 客户端。
- 核心设计理念：元数据驱动（Metadata-Driven），通过机器可读的元数据文档描述数据模型和服务能力
- 传输协议：基于 HTTP/HTTPS
- 数据格式：默认 JSON，兼容 XML
- 操作语义：直接映射 HTTP 标准方法（GET/POST/PUT/PATCH/DELETE）
1.2 OData 解决的核心问题
传统 REST API 存在以下痛点：
- 接口碎片化：每个系统都有自己的 API 设计规范，客户端需要适配不同的接口
- 过度获取 / 获取不足：要么返回过多无用数据，要么需要多次请求才能获取完整数据
- 查询能力弱：复杂查询需要服务端专门开发接口，灵活性差
- 集成成本高：跨系统数据交换需要大量定制化开发
OData 通过标准化的查询语法和元数据驱动架构，完美解决了这些问题，实现了 "一次定义，到处消费"。
1.3 OData 发展历史
版本 | 发布时间 | 关键里程碑 |
V1.0 | 2007 年 | 微软首次发布，基于 AtomPub 协议 |
V2.0 | 2009 年 | 增加 JSON 支持，完善查询语法 |
V3.0 | 2011 年 | 引入复杂类型、枚举、操作等概念 |
V4.0 | 2014 年 | 通过 OASIS 标准化，成为 ISO/IEC 国际标准 |
V4.01 | 2017 年 | 简化语法，增强查询能力，提高兼容性 |
注意：目前OData V4是主流版本，V3 及更早版本已逐渐被淘汰，新项目应优先使用 V4.01。
二、OData 核心概念
2.1 实体数据模型（EDM）
EDM（Entity Data Model）是 OData 的核心，它定义了 OData 服务暴露的数据结构和关系，使用CSDL（Conceptual Schema Definition Language） 格式描述，通常以 XML 形式呈现。
EDM 的核心组成部分：
- 实体（Entity）：数据的基本单元，对应数据库中的表行或业务对象，具有唯一标识符（Key）
- 实体集（Entity Set）：相同类型实体的集合，对应数据库中的表
- 属性（Property）：实体的特征，对应数据库中的列，分为简单类型（字符串、数字、日期等）和复杂类型
- 导航属性（Navigation Property）：表示实体之间的关系（一对一、一对多、多对多），允许客户端通过关联查询获取相关实体
- 复杂类型（Complex Type）：没有唯一标识符的结构化类型，用于表示实体的复合属性（如地址）
- 枚举类型（Enum Type）：表示固定取值集合的类型
- 函数（Function）：无副作用的数据查询操作，可带参数
- 操作（Action）：有副作用的数据修改操作
2.2 服务文档与元数据文档
OData 服务提供两个核心的发现文档：
- 服务文档（Service Document）
- 访问路径：服务根 URL（如https://api.example.com/odata）
- 作用：列出服务中所有可用的实体集和单例，帮助客户端了解服务的基本结构
- 元数据文档（Metadata Document）
- 访问路径：服务根 URL +/$metadata（如https://api.example.com/odata/$metadata）
- 作用：完整描述服务的 EDM 模型，包括所有实体、属性、关系、函数和操作
- 价值：客户端可以基于元数据自动生成代码、构建查询和验证请求，实现零代码集成
2.3 资源寻址
OData 使用 URI 来唯一标识资源，遵循以下基本约定：
- 服务根：https://api.example.com/odata
- 实体集：https://api.example.com/odata/Books
- 单个实体：https://api.example.com/odata/Books(1)（通过主键标识）
- 实体属性：https://api.example.com/odata/Books(1)/Title
- 导航属性：https://api.example.com/odata/Books(1)/Author
- 属性原始值：https://api.example.com/odata/Books(1)/Title/$value
三、OData 基本操作（CRUD）
OData 直接映射 HTTP 标准方法来实现 CRUD 操作：
3.1 查询（GET）
用于获取数据，支持各种查询选项来精确控制返回结果。
http |
