从零搭建WebApi接口开发框架-接口规范

因为是接口框架，首先要做的就是制定接口规范，好的接口规范能约束开发人员，能降低前后端人员之间的沟通协调，能避免后期联调带来的一系列问题。

1.接口规范
接口规范包含以下内容：
1、请求类型及参数
2、返回值及返回码
3、权限及版本控制
4、接口示例
2.接口请求说明
Api使用Restful风格，接口地址（测试）：http://host:port
（接口描述中地址需要扩展自此地址，如/api/users/register，扩展后则为 http://host:port/api/users/register）
接口请求类型分为两种，GET和POST，GET通常为请求获取资源；POST通常为提交资源到服务器；
接口请求返回值基本分为两种：
GET的请求若无错误，则返回所需资源的JSON格式内容，若有错误则返回一致的JSON格式内容，如：{“success”:false, “message”: “提交的参数不正确”, data: {}}，其中data为额外的对象，具体值根据接口而定；
POST的请求的Body部分可以将对象格式化为JSON的字符串后提交，也可以使用传统的Form表单形式提交，返回一致的JSON格式内容：如：{“success”:true, “message”: null, data: {id:1}}，其中data的内容也是具体根据接口而定。
返回码说明：

200 请求成功
400 客户端请求时所提交的参数不正确（通常为客户端的问题）
401 未提供accessToken（即未登录）
403 权限不足（已登录，但不具有访问该资源的权限）
404 找不到该资源（通常为请求的地址不正确）
500 服务发生错误（通常为服务端的问题）

实际生产中，请求基本都为POST
3.接口权限说明
接口权限验证使用OAUTH2.0标准，即先请求授权服务获取accessToken，得到accessToken后使用其内容封装到request的头（Headers）中，用以请求被保护的资源；
accessToken封装在Headers中是以Authorization键值对形式组成的，如：accessToken为4cac113f-29b1-4585-99a8-16e39331ccb3，封装的内容为：Authorization: 4cac113f-29b1-4585-99a8-16e39331ccb3这种形式。
4.接口请求版本说明
各个接口在header里面都加Version字段，用于控制接口的版本，服务端程序可以根据版本号来动态返回数据，也可以根据版本号来提示app升级。不加version默认1.0。
5.公共返回码
为了保证接口的规范性，特制定标准返回码：
成功类：

10001 保存成功
10002 删除成功
10003 操作成功
10004 审核成功

失败类

20001 操作失败
20002 代码已存在
30001 无权限
30002 系统错误
30003 参数错误
30004 路径不存在

5.接口示例

接口示例.png

上述是登录接口的文档标识

总结
设计接口规范是一个相当复杂的事情，要综合考虑很多技术及实现细节。后续章节依次讲述这些细节，并不断完善规范文档。

从零搭建WebApi接口开发框架-接口规范相关推荐

java快速搭建webapi,4.从零搭建WebApi接口开发框架-设计Dao、Service
这里面采用jdbcTemplate来作为数据库的访问功能,dao只简单包括用户的登录.news的增删改查. 1.pom依赖 UTF-8 org.springframework.boot spring- ...
服务器和网页接口,WebApi架构详解，WebApi接口搭建与部署WebApi服务器
WebApi架构详解,WebApi接口搭建与部署WebApi服务器本文关键词:WebApi架构, WebApi接口搭建, WebApi部署 1. Api是什么? API(Application ...
[渝粤教育] 宁波城市职业技术学院 Web服务器运维（从零搭建一个企业网站）参考资料
教育 -Web服务器运维(从零搭建一个企业网站)-章节资料考试资料-宁波城市职业技术学院[] 作业:购买阿里云ECS 作业:在万网注册域名作业:ICP备案微测验:准备主机 1.[单选题]ECS是阿 ...
容器云原生DevOps学习笔记——第三期：从零搭建CI/CD系统标准化交付流程
暑期实习期间,所在的技术中台-效能研发团队规划设计并结合公司开源协同实现符合DevOps理念的研发工具平台,实现研发过程自动化.标准化: 实习期间对DevOps的理解一直懵懵懂懂,最近观看了阿里专家带 ...
从零搭建React全家桶框架教程
从零搭建React全家桶框架教程源码地址:https://github.com/brickspert/react-family 欢迎star 提问反馈:blog 原文地址:https://githu ...
青云八核服务器无限申请教程,零云旗下快速开发框架lyadmin映像使用指南（青云服务器版）...
零云旗下快速开发框架lyadmin映像使用指南欢迎使用快速开发框架lyadmin.本指南将帮助您在青云服务器上快速部署并使用我们的产品. 概述: lyadmin是"零云"旗下的一 ...
python学习框架图-从零搭建深度学习框架（二）用Python实现计算图和自动微分
我们在上一篇文章<从零搭建深度学习框架(一)用NumPy实现GAN>中用Python+NumPy实现了一个简单的GAN模型,并大致设想了一下深度学习框架需要实现的主要功能.其中,不确定性最 ...
从零搭建Prometheus监控报警系统
从零开始搭建Prometheus自动监控报警系统从零搭建Prometheus监控报警系统什么是Prometheus? Prometheus是由SoundCloud开发的开源监控报警系统和时序列数据 ...
typeorm mysql_从零搭建项目 (10) --- 后端: 使用 TypeORM 和 MySQL
从零搭建项目 (10) --- 后端: 使用 TypeORM 和 MySQL 我的博客地址正式地址测试地址前端源码后端源码文章目录项目及其技术栈介绍前端: 项目初始化前端: 使用 Sa ...

从零搭建WebApi接口开发框架-接口规范

从零搭建WebApi接口开发框架-接口规范相关推荐

最新文章

热门文章