restful 参数带斜杠_SpringCloud实战：Restful架构API接口经典设计误区

前言

目前微服务架构盛行，发现很多同学设计业务API接口时，写法五花八门。现总结下目前项目上，设计业务API接口的经典误区写法。

API接口设计经典误区写法

1、查询某个对象接口： GET /app/getImportantApp

@GetMapping(path = "/getImportantApp")public R getImportionApp(@RequestHeader("pid") String pid)

2、查询列表接口： GET /app/list

@RequestMapping("/list")public R list(String deptId) 

3、保存对象接口：POST /app/save

@PostMapping("/save") public R add(CmsAppLicationEntity appLication, String deptId) 

4、删除对象接口：POST /app/delete

 @DeleteMapping("/delete/{applicationId}") public R delete(@PathVariable("applicationId") long applicationId) 

5、更新对象接口：POST /app/batchUpdate

@PostMapping("/batchUpdate")public R batchUpdate(@RequestBody List list) 

是不是感觉很熟悉的代码，难道写的不对？看着挺直观易懂的。如果采用Restful架构风格，写法当然不对，这是对Restful架构风格不了解所致。

1、请求路径URI应该是名词，而不是动词

按照Restful架构，每个业务实体代表一种资源，代表一个名词。比方说，

设计产品列表接口时：

错误写法

/getProductList

推荐写法

/products

“/getProductList”出现动词get。另外URL出现"/addProduct"、/deleteProduct、/updateProduct等等写法也是不对的。

如果某些动作是HTTP动词？表示不了的，你应该把该动作变成一种资源。比方说获取用户下的产品列表，错误接口设计是：

POST /users/1/getProducts或者POST /users/1/getProductList

正确的写法是把动词getProducts改成名词products

POST /users/1/products

2、URI中带版本号

业界对URI中是否带版本号存在两种意见。

支持方认为：

在URI中加入版本避免了向后兼容，另外通过过期提示，重定向，文档等手段也能降低用户迁移到新的接口上的成本。

比方说

POST /products/v1GET /users/v1POST /orders/v1POST /items/v1

反对方认为：

1. 加入版本号会让服务接口变得混乱，经常碰到的情况是：一些低版本的API接口调用一些高版本的API接口，导致数据解析错误。这无疑加大了用户迁移的成本。

2. 版本和资源的概念没有任何关系，因此在URI中加入版本会让用户混淆。

我个人是比较倾向使用版本号的， 因为我认为加版本号是站在程序角度来考虑新老版本的接口移植问题，特别是现在流行微服务架构，业务粒度很细的情况下，接口的升级，原有版本是否保留？

3、URI中路径大小写

URL中路径最好是小写，不要有驼峰式写法。比如下面接口错误写法

POST /orderItems/v1/1001

正确写法

POST /orders/v1/items/1001或者/order-items/v1/1001

HTTP动词

大家熟悉的POST 、GET、PUT、DELETE等

GET动词

查询列表或者单个对象的时候使用

POST动词

一般是提交表单或者是查询参数比较多的时候使用

PUT动词

更新对象的时候使用

DELETE动词

删除对象的时候使用

关于我

大家好，我是Wooola，10年JAVA老兵，擅长微服务，分布式，并发，工作流。请大家多多关注我。