5、从业务需求到服务端接口设计 |
您所在的位置：网站首页 › 日系民宿设计说明书模板图 › 5、从业务需求到服务端接口设计 |
5、从业务需求到服务端接口设计
|
HTTP 教程：https://www.w3cschool.cn/http/a96bxfml.html RESTful 架构详解：https://www.runoob.com/w3cnote/restful-architecture.html 说明本文以简单的账号管理业务为蓝本，介绍前后端分离的 java web 项目如何进行接口设计和规划。 在前后端分离的web项目中，前端项目负责页面渲染和事件触发，服务端项目负责提供数据操作接口。在功能设计过程中，技术经理会规划好接口规范，前后端开发人员根据各自分工进行页面开发和接口开发工作。为了便于前端开发人员和后端开发人员的接口对接，企业往往会采用API接口管理工具进行接口管理。 一. 业务需求我们需要开发一个账号管理模块，该模块为管理员使用，需要包含如下功能： 账号创建：本系统中账号需要包含 用户名、姓名、密码、邮箱、手机号码 五项基本属性账号展示：要求以分页形式展示账号列表，列表页必须呈现每个账号的 用户名、姓名、邮箱信息账号详情：账号信息查看页面，根据账号ID显示账号的 五项基本属性账号修改：提供姓名、密码、邮箱和手机号码的修改功能账号删除：提供删除账号功能 二. 需求分析从以上业务需求看，以上五个业务需求点，我们可以分成相对应的五个接口，创建账号接口、账号列表分页接口、账号查看接口、账号修改接口、账号删除接口。 1、账号创建 接口业务描述 该接口由学员端调用，以 用户名、姓名、密码、邮箱 和 手机号码作为参数。 服务端验证用户名是否已经在系统中存在：如存在则返回报错提醒；若不存在则创建账号，并返回创建结果。 业务流程图 业务描述 该接口由学员端调用，以页号、每页记录条数、排序规则为参数。 服务端根据参数获取所需页的数据列表及相关分页信息。 业务流程图 业务描述 该接口由学员端调用，以学员ID为参数。 服务端该学员ID查询学员详情信息。 业务流程图 业务描述 该接口由学员端调用，以修改属性姓名、密码、邮箱、手机号码 和 学员ID为参数。 服务端根据学员ID修改该学员记录的相关信息。 业务流程图 业务描述 该接口由学员端调用，以学员ID为参数。 服务端根据学员ID修改该学员记录的相关信息。 业务流程图 就RESTful风格的服务端API接口设计，我们需要考虑 接口URI、请求方法、传入参数、返回结果 四方面的入手考虑。 1、接口URIURI的标准格式如下： 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约束还应当包含链接信息，如下图所示： 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 |
当前spring全家桶中，为我们提供了 Spring Data REST 和 Spring HATEOAS ，配合 JPA / Spring Security 可以实现标准REST风格的API接口，但由于Angular、Vue这些主流的前端框架并没有对links提供相应的解决方案，使用时需要在前端项目中自行处理，故而尚未普及，有兴趣的朋友们可以自行阅读如下相关文档。【本文地址】
今日新闻 |
推荐新闻 |