search

leyafo / leyafo.github.io

4 stars 1 forks source link

一个 API 设计问题带来的思考 #9

Open utterances-bot opened 3 years ago

utterances-bot commented 3 years ago

一个 API 设计问题带来的思考

https://www.liyafu.com/2019-09-03-an-api-problem-myth/

chaleaoch commented 3 years ago

为什么? 我也不知道,但是 我们选择了 自定义. 另外, 宜家的api也是永远200, 在meta中自定义一套异常信息.

leyafo commented 3 years ago

为什么? 我也不知道,但是 我们选择了 自定义. 另外, 宜家的api也是永远200, 在meta中自定义一套异常信息.

  1. 你内部的具体业务逻辑没必要让外面知道。
  2. 用户判断 HTTP status code 比解析body更加简单，另外就是你永远返回200是不是要自己去定义一套返回码？
  3. HTTP 天然适合 CRUD 类的业务，GET PUT DELETE POST，这些已经在 HTTP 协议里面抽象好了，你代码按照这个逻辑去抽象，用户可以无脑使用。
  4. 你的业务按照 GET PUT DELETE POST, 对路由设计，log 统计，业务抽象更加容易。我这篇文章里 CreateUser 这个例子，就需要在 HTTP SERVER 入口的地方解析一遍body，然后再把数据丢给对应的业务逻辑接口去处理。而且还不能让每个接口去单独序列化它自己需要的数据结构。

对于第四个问题我文章里可能没说太清楚，比如你有一个 create_user 的接口 规范的做法是这个接口应用使用 post /user { "name": "foo", } HTTP 实现的接口可以是： create_user(raw_data []byte) return 201 //数据创建成功

丑陋的做法就是： json_parse(body) //然后这里面你该返回什么数据结构？ 假设你设计了个万能的数据结构。然后，你的API服务里有一个类似这样的switch接口 switch(action){ case "create_user": create_user(??) //这里你传啥好？，是解析好的json，还是 http 的 raw body？ case "create_foo": create_user(??) //这里你又该传啥？，如果是解析好的 json，怎么和 create_user 需要的数据结构兼容？ } return 200 //是你收到了数据，还是数据创建成功了？还是数据创建好了，我需要给你一个ticket？