TFS Restful API

1. Restful简介：

       Restful的一个思想就是充分利用http的特性，将资源独立出来，并对资源可以有各种操作。比如http标准的get/put/delete/post/header/option等。

       一般来说，get/put/delete是等幂的操作，也就是说，相同的多次操作，原则上是不应该影响到最终结果的。而post则多用于添加一个新的资源，是一个不等幂的操作，多次重复操作，产生的最终效果会不一致，比如可能会创建了多个资源，这个现象在我们在提交浏览器表单请求的时候可以看到，重复提交，浏览器会有提示的。

Get操作的原则是不会改变数据的本身，它不应该做对数据的修改等操作。

Put则仅仅是对数据做更新操作。

Delete则仅仅是删除数据的操作了。

 所以，可以看出，restful接口对资源和操作有一个很清晰的定义与界限。

2. TFS Restful接口设计思路：

          对TFS来说，他是一个高可扩展、高可用、高性能、面向互联网服务的分布式文件系统，其设计目标是支持海量的非结构化数据。而数据就是一种资源，在对该资源进行适当的分类之后（分为原生TFS文件名和自定义TFS文件名），那对这个资源就可以进行各种不同的操作。 在此将各种不同的操作分为以下2类：

第一类：增删改查操作：

写文件：可以用Post操作来实现，如：POST /v1/appkey HTTP/1.1。 其中v1表示为原生TFS文件名资源，appkey表示所操作的应用（每个不同的应用具有不同的操作权限和优先级别）；操作成功后将返回Status 200 OK及resposne body内包含的文件名；若操作失败，将返回相应错误信息的Status状态码，如400 Bad Request， 500 Internal Server Error等信息，便于使用人员debug问题。

读文件：可以用Get操作来实现，如： GET /v1/appkey/TfsFileName HTTP/1.1。 其中TfsFileName表示所需要读取的文件名；操作成功后将返回Status 200 OK及response body内包含所要获取的文件内容；若操作失败，将返回相应错误信息的Status状态码，如400， 500和404 Not Found等信息。

删文件：可以用Delete操作来实现，如：DELETE /v1/appkey/TfsFileName HTTP/1.1。 操作成功后将返回Status 200 OK 无需返回response body信息；若操作失败，依然返回错误信息的Status状态码。

获取文件元信息： 元信息指数据的一些基本信息，如存放位置、文件大小、当前状态（删除、隐藏等）等信息，依然可以通过Get操作来实现，如： GET /v1/appkey/metadata/TfsFileName HTTP/1.1。 在url中增加metadata字段，以此来区分是否读取文件的元信息。操作成功后将返回Status 200 OK及response body内包含文件的元信息数据；若操作失败则返回错误信息的Status状态码。

第二类：由于TFS本身的特性，因此会有像指定suffix/delete/hide/offset/size等更多操作。可以将这些控制信息放到url的args里面。如: GET /v1/appkey/TfsFileName?suffix=.jpg&offset=6&size=2012 HTTP/1.1。 之后通过Nginx对请求的解析信息来做后续的数据库请求逻辑处理。

3. TFS Restful接口开发过程中容易出现的bug分析

将TFS Restful接口开发过程容易出现的bug分为以下4类：

1. TFS Restful 与 后端数据库TFS 之间的TCP通讯：

a. TFS Restful 在处理读、写请求完成之后不关闭与客户端的连接，导致大量TCP连接处于Close_Wati状态，无法释放连接，最终导致连接数耗尽 ；这是由于TFS Restful在完成处理请求并接收到Client端返回的FIN数据包后，未返回FIN数据包，单方面hold住了TCP连接；

b. TFS Restful 未能正确处理后端TFS响应超时问题；这是由于后端TFS由于网络堵塞等问题，无法在正常时间内返回响应，而TFS Restful所设置的超时处理不生效，导致TFS Restful hold。

2. TFS Restful内部数据存储：

a. TFS Restful 在集群间重试的时候没有修改对应的接收buf；

   b. TFS Restful获取不到 所需删除的物理集群地址；

c.  TFS Restful 分配tfs_module_rcs_zone 内存时出错；

 这是由于TFS是分布式数据库，涉及多集群处理，因此TFS Restful在各个集群之间获取信息时，需要修改相对应的接收buf，否则将导致数据不正确。

 3. TFS Restful控制信息处理不正确：

a. TFS Resultful size测试设置为0是没有返回badrequest, 而是出现访问异常：read timeout；

b. TFS Restful 读文件请求offset等于文件大小时read timeout ；

这是由于TFS Restful对控制信息的处理不正确，导致读取TFS集群失败；

4. TFS Restful对返回错误信息处理不正确：

a. TFS Restful 选择集群失败时返回500而不是404;

b. TFS resultful 读取文件时Response没有返回content-type和accpet-ranges头信息 ；

c. TFS resultful 读取不存在的block信息时，返回的error code不正确 ；

d. TFS Resultful 查询元信息时请求uri没有设置appkey时返回error code不正确 ；

 这是由于TFS Restful response信息设置不正确所导致的。