共计 1970 个字符，预计需要花费 5 分钟才能阅读完成。
当年初生牛犊不怕虎机翻了如何设计 RESTful API?，妄图在实践中用起来，在每一个禁受的我的项目中都想实现，每一次都被打脸，工夫久了就放弃医治了。接下来埋怨一些过程中遇到的坑吧。
HTTP 实现 RESTFul API 一共就 3 件事件，怎么就这么难呢？
- 看 url 就晓得操作什么
- 看 http method 就晓得干什么
- 看 http status code 就晓得后果
难以定义 URL
资源的定义就很难，教程里的案例都是很简略的状况，现实情况简单得多。
例如，当初有一个需要，一个客户端 A 须要一个用户分页接口，查问条件有姓名、电话、注册工夫等。还有一个客户端 B 也须要用户分页接口，然而查问条件有姓名、罕用收货地址等。尽管都是分页查问用户，然而实现的逻辑齐全不同，个别都是离开定义 API
客户端 A 须要的接口：
GET /v1/users HTTP/1.1
Host: www.demo.com
name=tom&phone=123321&sign_time=2011-01-01客户端 B 须要的接口：
GET /v1/users/with-common-address HTTP/1.1
Host: www.demo.com
name=tom&phone=123321&common_address=abc%20efg越是根底数据，越容易遇到多端须要的参数不同，要求返回的数据也不同。特地是遇到实现办法天壤之别的时候，通常都是通过加后缀或者前缀的形式辨别。
然而这个例子是能够用一个接口实现的，程序上是能够通过是否蕴含 commons_address 参数辨别不同的解决逻辑。然而这里有个很事实的问题，如果第一个接口曾经存在并且工作良好的话，作为承受第二个接口开发的你，有勇气去批改第一个接口的实现吗？特地是在逻辑很简单，第一个接口的代码可读性不高的时候。
除了以上的问题，当相似的需要过多时，这个接口的参数将越来越多，返回的音讯构造蕴含的字段也越来越多。参数该怎么传，什么状况下哪些参数不能传。返回音讯体每个字段什么时候会有值，什么时候没有值。这些都须要在逻辑里实现，并且测试，最初还得同步到 API 文档中。这样的代码难以保护，接口文档难以浏览。
临时没有找到比加后缀老本更低的形式，或者能够思考加一个中间层，毕竟 计算机领域的任何问题都能够通过减少一个间接的中间层来解决
被弃用的状态码
应用服务器通常只返回 200、401、500 错误码，其中 401 通常还是由权限框架实现的。更常见的是自定义 code 示意谬误起因，如果没有国际化需要的话，大概率这个 code 只有两个值，一个示意胜利，一个示意业务逻辑谬误。就像上面的例子：
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"code": 123321,
"message": "手机号曾经被占用"
}实质的起因还是大部分业务逻辑上的谬误，不须要非凡解决只须要提醒就行。所以只须要辨别：
- 胜利 http 200, code 0
- 业务逻辑谬误 http 200, code 不等于 0
- 代码谬误 http 500
而且不同 HTTP 状态码，须要编码实现如何解决，然而实现的成果都是把应用服务器返回的音讯提醒一下而已。这里的坑在于提示信息是硬编码在应用服务器的代码中，如果想改一下提示信息就得公布代码。
POST 一把梭
- GET 查问
- POST 新增
- PUT 批改
- DELETE 删除
很清晰是不是？然而 登录 应该用哪个？登记 又应该用哪个？获取受权 呢？获取签名 呢？
参数太简单客户端说用 POST 他们代码好写一点，我的项目要延期了改不改？
既然这么多问题搞不清楚还不如 POST 一把梭
永远的 V1 版本
代码的版本永远都是 1.0.0-SNAPSHOT，就更别说 URL 的版本了。
如果客户端只有 web，那还降级啥接口的版本哦，间接改就是了。然而客户端中有 APP 呢？间接让旧版本的用户降级就行了，不降级就不然用，这样岂不是很简略。那 URL 还要版本干啥呢？不如去掉算了。
如果 API 有其余第三方服务在调用呢？那版本号就有用了，然而大多数小厂可没有这种场景，那就只能永远的 V1 了。
去他喵的接口设计
去他喵的接口设计，工夫紧、工作重、变动大，没工夫设计，设计好了也得半路改掉，不如间接开撸，写好了导出一个接口文档就行，什么不懂来问啊。
半个月之后，客户端共事问：“这个字段是啥意思啊？”，后端开发：“你稍等啊，我查一查”，心田 OS：“我他喵为啥要这个字段呀？？？如同没啥用，然而又不敢删！哎~~”
最初吐槽
没有良好零碎设计，不要推 RESTFul API，没用的，反正最初也会腐烂成一坨屎。抛开 工夫紧、工作重、变动大，按 BUG 算绩效 这些不谈，开发就一点责任也没有吗？
当初公司 钱不够、演员未定、剧本暂无，等你们几个开发搞好了就发奖金
释怀，肯定会发的，公司上市了还有期权。最近辛苦一下，毕竟你也不想毕业吧？你说是吧~~~