HTTP 教程：https://www.w3cschool.cn/http/a96bxfml.html
RESTful 架构详解：https://www.runoob.com/w3cnote/restful-architecture.html
说明
本文以简单的账号管理业务为蓝本，介绍前后端分离的 java web 项目如何进行接口设计和规划。
在前后端分离的web项目中，前端项目负责页面渲染和事件触发，服务端项目负责提供数据操作接口。在功能设计过程中，技术经理会规划好接口规范，前后端开发人员根据各自分工进行页面开发和接口开发工作。为了便于前端开发人员和后端开发人员的接口对接，企业往往会采用API接口管理工具进行接口管理。
一. 业务需求
我们需要开发一个账号管理模块，该模块为管理员使用，需要包含如下功能：
- 账号创建：本系统中账号需要包含 用户名、姓名、密码、邮箱、手机号码 五项基本属性
- 账号展示：要求以分页形式展示账号列表，列表页必须呈现每个账号的 用户名、姓名、邮箱信息
- 账号详情：账号信息查看页面，根据账号ID显示账号的 五项基本属性
- 账号修改：提供姓名、密码、邮箱和手机号码的修改功能
- 账号删除：提供删除账号功能
二. 需求分析
从以上业务需求看，以上五个业务需求点，我们可以分成相对应的五个接口，创建账号接口、账号列表分页接口、账号查看接口、账号修改接口、账号删除接口。
1、账号创建 接口
-
业务描述
该接口由学员端调用，以用户名、姓名、密码、邮箱和手机号码作为参数。
服务端验证用户名是否已经在系统中存在：如存在则返回报错提醒；若不存在则创建账号，并返回创建结果。 -
业务流程图
2、账号展示 接口
-
业务描述
该接口由学员端调用，以页号、每页记录条数、排序规则为参数。
服务端根据参数获取所需页的数据列表及相关分页信息。 -
业务流程图
3、账号详情 接口
-
业务描述
该接口由学员端调用，以学员ID为参数。
服务端该学员ID查询学员详情信息。 -
业务流程图
4、账号修改 接口
-
业务描述
该接口由学员端调用，以修改属性姓名、密码、邮箱、手机号码和学员ID为参数。
服务端根据学员ID修改该学员记录的相关信息。 -
业务流程图
5、账号删除 接口
-
业务描述
该接口由学员端调用，以学员ID为参数。
服务端根据学员ID修改该学员记录的相关信息。 -
业务流程图
三. 接口设计
就RESTful风格的服务端API接口设计，我们需要考虑 接口URI、请求方法、传入参数、返回结果 四方面的入手考虑。
1、接口URI
URI的标准格式如下：
scheme://host[:port#]/path/.../[;url-params][?query-string][#anchor]
- scheme ：包含我们常见的各种协议，如http、https、git、ftp等
- host：用于定位网络主机，通常为域名、IP地址或主机名
- port：端口号，主机资源提供的访问端口
- url-params：路径所携带的参数
- query-string：发送给服务器的查询参数
- anchor：锚点定位符
RESTful 风格的URI 建议采用/api/organization/users 格式定位资源位置，需要注意如下两点：
资源对象本身采用复数形式。
资源路径上/间尽量采用单个名词，若必须采用多名词表述时，采用-短横线进行分割，禁止使用驼峰命名法。
2、请求方法
对于资源的操作，常规用法包含添加资源、删除资源、修改资源、查找资源，其中新增操作为非幂等操作；删除操作、查询操作均为幂等操作；修改操作大多数情况下为幂等操作（UPDATE table SET column = column+1时为非幂等操作）。
根据 HTTP协议 和 RESTful设计风格 以及 HATEOAS 约束 Level 2层次的规范，我们对请求方法的使用，进行以下规定：
采用HTTP协议的POST方法实现新增操作；
采用HTTP协议的DELETE方法实现删除操作；
采用HTTP协议的PUT方法实现修改操作；
采用HTTP协议的GET方法实现查询操作；
3、请求参数
在通过基于HTTP协议的RESTful风格API访问资源时，请求参数可以通过HTTP协议的请求头、请求体、上下文路径段进行传输。
spring 为我们提供了@PathVariable、@RequestHeader、@CookieValue、@RequestParam、@RequestBody等接收请求参数，作者将在下一篇文章中详细整理不同请求方法下参数的接收语法。
4、返回值
API接口调用的返回信息，遵循HTTP响应信息的基本规则，本文仅对常规处理习惯进行整理。
- 新增请求须返回新增数据的id,以便解决
创建并进入编辑的业务场景。 - 删除请求返回执行状态即可。
- 修改请求返回执行状态即可。
- 查询资源详情时，以JSON格式返回资源信息。
- 查询资源列表，无分页需求时，则以JSON格式返回数据集。
- 查询资源列表，有分页需求时，除返回数据集信息外，还需要返回当前页号、每页记录条数、总记录条数等信息。
5、接口规划
按照账号管理模块的业务需求，我们规划的接口如下：
http://www.tysite.org/api/organization/users //POST 请求实现 账号创建接口
http://www.tysite.org/api/organization/users/paging //GET 请求实现 账号展示接口，以分页显示
http://www.tysite.org/api/organization/users/1 //GET 请求实现 账号详情接口，获取标识为1的账号信息
http://www.tysite.org/api/organization/users/1 //PUT 请求实现 账号修改接口，修改标识为1的账号
http://www.tysite.org/api/organization/users/1 //DELETE 请求实现 账号删除接口，删除标识为1账号
注意：查询全部数据列表的接口采用如下写法（get请求）：
http://www.tysite.org/api/organization/users
四. HATEOAS 约束
前面讲述的 REST 架构 并非完整的 REST，其只使用到了 HATEOAS 约束 约束的 Level 2 层，完整的HATEOAS约束还应当包含链接信息，如下图所示：
当前spring全家桶中，为我们提供了 Spring Data REST 和 Spring HATEOAS ，配合 JPA / Spring Security 可以实现标准REST风格的API接口，但由于Angular、Vue这些主流的前端框架并没有对links提供相应的解决方案，使用时需要在前端项目中自行处理，故而尚未普及，有兴趣的朋友们可以自行阅读如下相关文档。
https://www.ibm.com/developerworks/cn/java/j-lo-SpringHATEOAS/
https://spring.io/projects/spring-data-rest
https://spring.io/projects/spring-security
https://spring.io/projects/spring-data-jpa
