RESTFul风格接口如何设计

RESTFul风格设计规范

1. HTTP协议请求方式要求

   REST 风格主张在项目设计、开发过程中，具体的操作符合HTTP协议定义的请求方式的语义。

   操作	请求方式
   查询操作	GET
   保存操作	POST
   删除操作	DELETE
   更新操作	PUT

    

需求分析

• 数据结构： User {id 唯一标识,name 用户名，age 用户年龄}

• 功能分析

  • 用户数据分页展示功能（条件：page 页数 默认1，size 每页数量 默认 10）

  • 保存用户功能

  • 根据用户id查询用户详情功能

  • 根据用户id更新用户数据功能

  • 根据用户id删除用户数据功能

  • 多条件模糊查询用户功能（条件：keyword 模糊关键字，page 页数 默认1，size 每页数量 默认 10）

1. 接口设计

   功能	接口和请求方式	请求参数	返回值
   分页查询	GET /user	page=1&size=10	{ 响应数据 }
   用户添加	POST /user	{ user 数据 }	{响应数据}
   用户详情	GET /user/1	路径参数	{响应数据}
   用户更新	PUT /user	{ user 更新数据}	{响应数据}
   用户删除	DELETE /user/1	路径参数	{响应数据}
   条件模糊	GET /user/search	page=1&size=10&keywork=关键字	{响应数据}

2. 问题讨论

   为什么查询用户详情，就使用路径传递参数，多条件模糊查询，就使用请求参数传递？

   误区：restful风格下，不是所有请求参数都是路径传递！可以使用其他方式传递！

   在 RESTful API 的设计中，路径和请求参数和请求体都是用来向服务器传递信息的方式。

   • 对于查询用户详情，使用路径传递参数是因为这是一个单一资源的查询，即查询一条用户记录。使用路径参数可以明确指定所请求的资源，便于服务器定位并返回对应的资源，也符合 RESTful 风格的要求。

   • 而对于多条件模糊查询，使用请求参数传递参数是因为这是一个资源集合的查询，即查询多条用户记录。使用请求参数可以通过组合不同参数来限制查询结果，路径参数的组合和排列可能会很多，不如使用请求参数更加灵活和简洁。 此外，还有一些通用的原则可以遵循：

   • 路径参数应该用于指定资源的唯一标识或者 ID，而请求参数应该用于指定查询条件或者操作参数。

   • 请求参数应该限制在 10 个以内，过多的请求参数可能导致接口难以维护和使用。

   • 对于敏感信息，最好使用 POST 和请求体来传递参数。

3. 总结