5、从业务需求到服务端接口设计

最新推荐文章于 2023-07-26 15:24:17 发布

tysite

最新推荐文章于 2023-07-26 15:24:17 发布

阅读量1.9k

点赞数 1

分类专栏： Java Web 文章标签： restful rest web service

本文链接：https://blog.csdn.net/tysite/article/details/104490081

版权

Java Web 专栏收录该内容

9 篇文章 0 订阅

订阅专栏

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提供相应的解决方案，使用时需要在前端项目中自行处理，故而尚未普及，有兴趣的朋友们可以自行阅读如下相关文档。