C# 服务端篇之实现RestFul Service开发(简单实用)

一、RestFul简介

　　REST（Representational State Transfer 通常被翻译为“表述性状态传输”或者“表述性状态转移”）是RoyFielding提出的一个描述互联系统架构风格的名词。为什么称为REST？Web本质上由各种各样的资源组成，资源由URI 唯一标识。浏览器（或者任何其它类似于浏览器的应用程序）将展示出该资源的一种表现方式，或者一种表现状态。如果用户在该页面中定向到指向其它资源的链接，则将访问该资源，并表现出它的状态。这意味着客户端应用程序随着每个资源表现状态的不同而发生状态转移，也即所谓REST。

　　简单地来说REST它是一种使用URL来定位资源，使用HTTP请求描述操作的Web服务规范。REST主要包括以下几方面：

　　（1） REST是一组架构约束条件和原则，而满足这些约束条件和原则的应用程序就是RESTful。
　　（2）REST的目标是构建可扩展的Web Service，它是一种更简单的SOAP(Simple Object Access Protocol)协议以及以WSDL为基础的WebService的替代。
　　（3）REST采用的是HTTP协议并通过HTTP中的GET、POST、PUT、DELETE等动词收发数据。
　　（4） REST希望通过HTTP来完成对数据的元操作，即传统的CRUD(Create、Read、Update、Delete)分别对应GET、POST、PUT、DELETE，这样就统一了数据操作的接口，实现在不同平台上提供一套相同的服务。
　　（5） REST是一种面向服务的、分布式的API设计风格。

　　RESTful API的开发和使用，无非是客户端向服务器发请求（request），以及服务器对客户端请求的响应（response）。所以RESTful架构风格具有统一接口的特点，即：使用不同的http方法表达不同的行为：

• GET（SELECT）：从服务器取出资源（一项或多项）
• POST（CREATE）：在服务器新建一个资源
• PUT（UPDATE）：在服务器更新资源（客户端提供完整资源数据）
• PATCH（UPDATE）：在服务器更新资源（客户端提供需要修改的资源数据）
• DELETE（DELETE）：从服务器删除资源

二、REST的约束条件和原则

　　REST本质上是Web服务的一种规范，一种思想。它主要包括以下特性：

1、资源(Resources)

　　在REST中资源是整个架构或者说整个网络处理的核心，那么什么又是资源呢？在我们传统的观念中，资源是指服务器上的一个文件，而在REST里资源则是指一个URL。URL即统一资源定位，而我们都知道通过URL可以访问互联网上的资源，所以在REST里这种对资源的指向性更加强烈，并且在这里资源的范畴会被无限放大而并非局限在文件本身，例如以下实例：

1 http://api.cnblogs.com/info/source 表示获取某人的成绩
2 http://api.cnblogs.com/info/friends 表示获取某人的好友列表
3 http://api.cnblogs.com/info/profile 表示获取某人的详细信息

　　由此我们注意到REST在形式上更加趋向API设计，而我们获取的资源则通过一定的形式进行统一而规范化的表达，因此REST实现了让不同的平台共享一套API这样的愿望，这是一件非常美好的事情，这个世界上的技术阵营举不胜数，而它们为了各自的利益建立一套封闭、臃肿的体系框架，很多时候当我们不需要这样的“全家桶”并且希望“跨平台”的时候，REST将会是一个不错的选择。

2、表现形式(Representational)

　　在REST中表现形式作为我们对资源请求的一个结果的呈现，通过对HTTP协议的学习我们已经知道，服务器会给客户端返回什么形式的信息，这一点取决于服务器响应报文中相关头部字段，而对REST来讲，它通常会采用XML或者JSON来告诉请求者请求的结果，因为JSON相比XML所含的冗余信息较少，所以目前更加倾向于或者说流行使用JSON作为请求结果的表现形式。

3、状态变化(State Transfer)

　　虽然我们一再强调HTTP协议是无状态，这主要体现在HTTP请求与请求、HTTP响应与响应的上下文无关性上。在REST中，我们所说状态变化更多是指HTTP中的GET、POST、PUT、DELETE等动词实现。具体来讲，看下面的简单示例：

1 GET http://url/info    表示获取全部的info
2 POST http://url/info    表示创建一个新的info
3 GET http://url/info/{id}    表示获取一个指定id的info
4 PUT http://url/info/{id}    表示更新一个指定id的info
5 DELETE http://url/info/{id}    表示删除一个指定id的info

　　除此之外，我们注意到REST基于HTTP协议，所以HTTP协议中的状态码对它来讲同样适用，例如最常用的200表示成功、500表示服务器内部错误、404表示无法找到请求资源、400表示请求错误等等。

三、如何构建RestFul风格的API

　　如何构建REST风格的API？我们可以通过以下实例说明

• URLRoot采用下面这样的结构：

1 http://example.com/api/v1/
2 http://api.example.com/v1/

• API版本可以放在URL或者HTTP的Header里
• URL使用名词而非动词：

1 http://example.com/api/v1/getProducts 这是一个糟糕的设计
2 GET http://example.com/api/v1/products 这是一个优雅的设计

• 保证方法时安全的不会对资源状态有所改变。例如：

GET http://example.com/api/v1/deleteProduct?id=1 这是一个危险的信号

• 资源的地址推荐使用嵌套结构

GET http://example.com/api/v1/friends/123456789/profile

• 使用正确的HTTP状态码表示访问状态
• 返回含义明确的结果(一般推荐JSON)

四、Restful 服务端

　　下面主要讲解如何用C#实现一个Rest 风格的web服务供外部调用，主要包括以下4点：

• 定义service的契约
• 定义URL Routing
• 实现service
• 为服务编写宿主程序

　　1、定义service的契约和URL Routing

　　先定义服务契约，这里我介绍最常见的两种方式，分别采用GET和POST方式访问，使用VS2015创建一个新的控制台工程,命名为RestFulService。如图所示：

　　并为该工程添加引用System.ServiceModel 和System.ServiceModel.Web

　　创建一个接口类文件，命名为IPersonInfoQuery。为了让.Net FrameWork识别这是一个service接口，我们需要给接口添加上ServiceContract特性，并且给接口定义的方法添加OperationContract特性。这里我介绍最常见的两种方式，分别采用GET和POST方式访问。我们可以看到，与普通WCF服务契约不同的是，需要额外用WebGet或者WebInvoke指定REST访问的方式。另外还要指定消息包装样式和消息格式，默认的消息请求和响应格式为XML，若选择JSON需要显式声明。 UriTemplate用来将方法映射到具体的Uri上，但如果不指定映射，将映射到默认的Uri。比如采用Get访问的GetUser方法，默认映射是:/GetSource?Name={Name}

　　我们定义两种方法，1、GetScore方法：通过GET请求传入name，返回对应的成绩；2、GetInfo方法：通过POST请求，传入Info对象，查找对应的User并返回给客户端，代码如下　　

 1 using System;
 2 using System.Collections.Generic;
 3 using System.Linq;
 4 using System.ServiceModel;
 5 using System.ServiceModel.Web;
 6 using System.Text;
 7 using System.Threading.Tasks;
 8 
 9 namespace RestFulService
10 {
11     /// <summary>
12     /// 简单定义两种方法，1、GetScore方法：通过GET请求传入name，返回对应的成绩；2、GetInfo方法：通过POST请求，传入Info对象，查找对应的User并返回给客户端
13     /// </summary>
14     [ServiceContract(Name = "PersonInfoQueryServices")]
15     public interface IPersonInfoQuery
16     {
17         /// <summary>
18         /// 说明：GET请求
19         /// WebGet默认请求是GET方式
20         /// UriTemplate(URL Routing)的参数名name必须要方法的参数名必须一致（不区分大小写）
21         /// RequestFormat规定客户端必须是什么数据格式请求的（JSon或者XML），不设置默认为XML
22         /// ResponseFormat规定服务端返回给客户端是以是什么数据格返回的（JSon或者XML）
23         /// </summary>
24         /// <param name="name"></param>
25