标签：变更 1.2 eval 功能 复用 require ted rest 构建流程
今天的互联网世界，API 已经无处不在，越来越多的服务依赖 API 交换信息，彼此协作，彼此连接，API 开发协作的体验也越来越重要。
有协作，就有沟通，显而易见的方法就是写文档，用文档描述 API 的用途，使用方法。但如何保持文档与代码的同步确是业界的千古难题，能做得到位的寥寥无几。
难道就真的没有方法了吗？
这就是本文的主题，构建自描述 RESTFul API 体系，如何通过自描述的 API 设计，抹除代码与文档的界限，一切皆代码。
所谓的自描述，就是让 API 在提供具体的功能的同时，能够提供一些用于描述该 API 的元数据，包括但不限于以下几个方面：
API 的用途，主题以及简介
API 的参数及每个参数的含义
API 的返回结果及每个字段的含义
相关的 API 或者子 API 的引用
利用这些元数据，再通过合适的工具，对这些元数据予以聚合、展示，便形成了我们能够直观看到的 API 文档~
相比静态的 API 文档，自描述元数据能够提供更加动态的内容，能够依据参数，用户的身份而返回不同的内容，从而更好的适应 API 使用者的需求。
要完美优雅的实现自描述的 RESTFul API 体系需要从三个层次入手：框架层，协议层和表现层：
框架层
框架层是与具体语言相关的，通过框架的支持，让业务 API 及对应的元数据能更方便的通过 RESTFul 接口对外暴露。
协议层
协议层是框架层和展现层的桥梁和通信规范，框架层和表现层都可以有多个实现，但协议层的规范只有一个。
在 HTTP 的层面，我们可以使用 OPTIONS 请求来获取元数据，这也是符合 HTTP 规范的定义：
This method allows the client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval.
表现层
表现层通过可视化的手段，让 API 的元数据更方便被人们所认知和查看。比如通过元数据生成的 API 文档就属于展现层的工具。
业内已经有很多的 RESTFul API 文档工具，比如 Swagger API 和 API Blueprint，它们都是很很优秀的生产力工具，不过它们并没有提供自描述的方案支持。
当然，这并不妨碍我们站在巨人的肩膀上，充分复用它们在协议层和表现层的成果，更方便快捷的构建自己的自描述 RESTFul API 体系。
做一件事情的方式千千万万，为什么选择这样做，背后是有一套理念的，理念是指导做事方法的原则。
这个理念就是「一切皆代码」，文档亦如是。
这个理念并不是什么新东西，业内有很多先进的生产力工具都是这样做的，比如：
Docker 的 Dockerfile 将构建流程变为代码，让运行环境更具可复制性
知名持续集成工具 Travis CI 通过 .travis-ci.yml 描述项目构建过程
在应用「一切皆代码」理念的前期下，再通过版本控制软件，将一切的变更记录在案，所有的修改也在同一个地方进行，都在一个地方修改了，想不同步都难。
除了上文提到的 API 文档的场景，自描述的 RESTFul API 显然有更多的潜力可被挖掘，下面是简单的介绍。
自动化测试
通过元数据，可对所有的 API 自动的做一些基本的单元测试或者功能测试，从而减轻测试编写所花费的时间。更重要的是，所有的数据都只需要维护一份，比如 API 模型的定义。
服务集成
通过自描述的 RESTFul API ，可以方便的让彼此依赖的服务通过元数据进行信息交换。
比如我们可以实现一个独立的数据导出服务，它能够自动的根据 API 返回的数据及对应的元数据导出成 Excel 文件，从而实现让导出与数据解藕，API 专心提供数据即可。
自动 SDK 生成
通过元数据信息，可以自动生成各个语言的 SDK 库，对于动态语言，甚至可以在运行时进行动态生成。
标签：变更 1.2 eval 功能 复用 require ted rest 构建流程
原文地址：http://www.cnblogs.com/gongxiaojiu/p/7236718.html
