API设计

1. 是否Restful。

   首先需要清楚，Restful是一种风格而不是规范，不存在必须遵守的问题。

   Restful本质上是对HTTP API进行有效的分类。

   分类是应该的，可以让API组织变得有序、层次清晰

2. 一定要以Restful的风格分类吗？

   Restful风格的特点

   • url表示的只是资源，没有动作，所以只会出现名词，不会出现动词

     这样的url不对 /accounts/1/transfer/499

     应该是这样 /accounts/1/transactions/499

     想想传统的login、reset password在restful下要怎么办？

   • 动作用http method来表示

     针对CRUD，对应的语义分别是POST、GET、PATCH（PUT）、DELETE

     • GET、PUT、DELETE是幂等的，其余不是
     • PATCH表示部分更新
     • PUT的确切语义是CREATE OR REPLACE
   • 使用http状态码来表示基础的响应状态
     • 200 操作成功
     • 400 请求有问题；如：参数验证失败、签名验证失败等
     • 401 认证失败。
     • 403 无访问权限。
     • 409 请求处理完成但因为业务规则限制或其他原因并未真正成功的响应
     • 500 服务器错误
     • 503 服务器维护中
3. 应有的支持
   • 版本化

     客户端必须明确知道自己调用的API版本。

     兼容性被破坏时+1 https://api.expample.com/v1/endpoint

     为了避免同时支持多版本API时，服务端消耗过多不必要的资源，应该以微服务的方式裁剪API，不同服务独立部署、迭代。

   • 业务编号

     https://api.expample.com/v1/biz/0

   • 资源包升级

     客户端不放资源包升级的逻辑，只发出升级请求，是否升级完全由服务端决定。

   • 强制升级

     特殊情况下要求客户端连主程序包括资源包都必须升级。

   • https

     可以使用自签名证书

4. 数据查询DSL(?)
   

   允许客户端直接提交DSL文本，自行决定要查询一种或多种资源，查询多种资源时，支持JOIN，并且支持结果集过滤、排序。

   • DSL只读，结果集仅以二维表体现
   • url表示的资源只支持单个资源的读写
   • 批量资源的写操作使用业务编号
   • 需要特殊结构的数据使用数据集编号

应用设计

1. 微服务

   从传统的monolithic风格到microservice，就好比原来是所有人一起搭一辆大巴前往目的地，现在改成三五成群，各自自驾前往。

   • 优势在于小规模独立部署及迭代，不必牵一发动全身，灵活
   • 未必会更方便、未必会降低成本，需要具体问题具体分析以及依赖具体实践
   • 开发工程微服务化及部署微服务化是两回事
2. 使用spring mvc搭载应用

   把应用的依赖抽象成诸多service，可能包括且不限于：

   • session
   • cache
   • storage
   • relational db/orm
   • log
   • auth
   • httpclient
   • qrcode
   • image processing
   • config
   • queue
   • mail
   • sms
   • event
   • schedule
3. 后台管理
   • cli

     面向运维及开发。

   • web

     面向业务及运营。