我的编码习惯 —— API 接口定义
工作中,少不了要定义各种接口,系统集成要定义接口,前后台掉调用也要定义接口。接口定义一定程度上能反应程序员的编程功底。列举一下工作中我发现大家容易出现的问题:
1. 返回格式不统一
同一个接口,有时候返回数组,有时候返回单个;成功的时候返回对象,失败的时候返回错误信息字符串。工作中有个系统集成就是这样定义的接口,真是辣眼睛。这个对应代码上,返回的类型是map,json,object,都是不应该的。实际工作中,我们会定义一个统一的格式,就是ResultBean,分页的有另外一个PageResultBean
错误范例:
//返回map可读性不好,尽量不要@PostMapping("/delete")public Map<String, Object> delete(long id, String lang) {}// 成功返回boolean,失败返回string,大忌@PostMapping("/delete")public Object delete(long id, String lang) {try {boolean result = configService.delete(id, local);return result;} catch (Exception e) {log.error(e);return e.toString();}}
2. 没有考虑失败情况
一开始只考虑成功场景,等后面测试发现有错误情况,怎么办,改接口呗,前后台都改,劳民伤财无用功。
错误范例:
//不返回任何数据,没有考虑失败场景,容易返工@PostMapping("/update")public void update(long id, xxx) {}
3. 出现和业务无关的输入参数
如lang语言,当前用户信息 都不应该出现参数里面,应该从当前会话里面获取。后面讲ThreadLocal会说到怎么样去掉。除了代码可读性不好问题外,尤其是参数出现当前用户信息的,这是个严重问题。
错误范例:
// (当前用户删除数据)参数出现lang和userid,尤其是userid,大忌@PostMapping("/delete")public Map<String, Object> delete(long id, String lang, String userId) {}
4. 出现复杂的输入参数
一般情况下,不允许出现例如json字符串这样的参数,这种参数可读性极差。应该定义对应的bean。
错误范例:
// 参数出现json格式,可读性不好,代码也难看@PostMapping("/update")public Map<String, Object> update(long id, String jsonStr) {}
5. 没有返回应该返回的数据
例如,新增接口一般情况下应该返回新对象的id标识,这需要编程经验。新手定义的时候因为前台没有用就不返回数据或者只返回true,这都是不恰当的。别人要不要是别人的事情,你该返回的还是应该返回。
错误范例:
// 约定俗成,新建应该返回新对象的信息,只返回boolean容易导致返工@PostMapping("/add")public boolean add(xxx) {//xxxreturn configService.add();}
很多人看了我的这篇文章 程序员你为什么这么累?,都觉得里面的技术也很简单,没有什么特别的地方,但是,实现这个代码框架之前,就是要你的接口的统一的格式ResultBean,aop才好做。有些人误解了,我那篇文章说的都不是技术,重点说的是编码习惯工作方式,如果你重点还是放在什么技术上,那我也帮不了你了。同样,如果我后面的关于习惯和规范的帖子,你重点还是放在技术上的话,那是丢了西瓜捡芝麻,有很多贴还是没有任何技术点呢。
附上ResultBean,没有任何技术含量:
@Data
public class ResultBean<T> implements Serializable {private static final long serialVersionUID = 1L;public static final int SUCCESS = 0;public static final int FAIL = 1;public static final int NO_PERMISSION = 2;private String msg = "success";private int code = SUCCESS;private T data;public ResultBean() {super();}public ResultBean(T data) {super();this.data = data;}public ResultBean(Throwable e) {super();this.msg = e.toString();this.code = FAIL ;}
}
统一的接口规范,能帮忙规避很多无用的返工修改和可能出现的问题。能使代码可读性更加好,利于进行aop和自动化测试这些额外工作。大家一定要重视。
我的编码习惯 —— API 接口定义相关推荐
- 记一次API 接口定义 添加 @ApiOperation 注解触发中间件 bug 问题分析
API 接口定义 添加 @ApiOperation 注解触发中间件 bug 问题分析 背景 我有一个服务 A ,写了一个接口定义如下: @RequestMapping({"/config/c ...
- 上传图片-服务端-Api接口定义
API接口 模型类 系统的文件信息(图片.文档等小文件的信息)在mongodb中存储,下边是文件信息的模型类. 1) 模型如下: package com.learn.framework.domain. ...
- 程序员你为什么这么累【续】:编码习惯之日志建议
转自:https://mp.weixin.qq.com/s?__biz=MzAxODcyNjEzNQ==&mid=2247484164&idx=1&sn=8351e9fb42e ...
- 各种快递查询Api接口(快递鸟)
文章目录 #应用场景 #申请Key #快递查询Api接口 #前提 项目开发中,有些需求难免会用到关于快递的一些Api接口:本篇主要介绍的是快递的查询Api及与其他各家的不同之处: 常用的提供快递Api ...
- 快递鸟查询Api接口使用(PHP版)
前提 项目开发中,有些需求难免会用到关于快递的一些Api接口:本篇主要介绍的是快递的查询Api及与其他各家的不同之处: 常用的提供快递Api接口的有: 快递鸟 快递100 爱查快递 等等 如大家使用 ...
- 快递查询Api接口(快递鸟)
前提 应用场景 可实现需求 申请Key 快递查询Api接口 接口文档及各开发语言Demo 查询Api接口定义 系统级输入参数 应用级输入参数 返回结果参数 请求JSON参数 响应JSON参数 查询Ap ...
- ASP.NET Web API 入门 (API接口、寄宿方式、HttpClient调用)
一.ASP.NET Web API接口定义 ASP.NET Web API默认实现了Action方法和HTTP方法的映射,Action方法方法名体现了其能处理的请求必须采用的HTTP方法 二.寄宿方式 ...
- api接口怎么分批传递数据_新手上路:浅谈什么是API接口 API定义是什么
API应用已经越来越广泛,那你们你了解API吗?API接口是什么呢?本人就来聊聊什么是API接口.首先我们来看看API的定义: API:应用程序接口(API:Application Program I ...
- 地理坐标逆编码 API 接口
地理坐标逆编码 API 接口 获取地理坐标周围的地址信息. 1. 产品功能 提供精准.高效的地理坐标逆编码接口: 返回的地址包含详细的位置信息: 一次可返回坐标周边的 10 个地址信息: 全接口支持 ...
最新文章
- GNU make manual 翻译( 一百一十三)
- 什么是ERP (转载自百度知道)
- boost::mp11::mp_min_element_q相关用法的测试程序
- 论文浅尝 | 将文本建模为关系图,用于联合实体和关系提取
- 21 张让你代码能力突飞猛进的速查表(神经网络、线性代数、可视化等)
- 4.namespace
- mysql三高讲解(三)3.2:如何确定用哪条索引
- ubuntu安装atom
- word文档怎么一分为二_微信文章怎么转成word文档,这个强大工具可以帮你搞定...
- java编译及运行过程_简述JAVA程序的编辑编译和运行过程
- 我去,还有这种网站!
- 方便自己的一些学习科研的记录 【小神器】
- 各大快递公司面单号准确性验证的正则表达式
- Win10系统打开共享文件提示没有权限使用网络资源怎么处理?
- 智能衣橱控制系统的设计
- 傻白入门芯片设计,Substrate/RDL/Interposer/EMIB/TSV(三)
- docker常用操作(二) docker安装mysql5.7
- 咬住爱的甜蜜 像夹心巧克力 连懒懒的猫咪 也偷偷看你 难以抗拒你的美丽 裙摆摇不停 只为了与你相遇
- c语言 __at定位编译报错,david
- z-index的使用及注意事项
热门文章
- Java B2B2C多用户商城 springcloud架构- common-service 项目构建过程(七)
- 让DB2数据库更牢靠
- linux下安装jira详细步骤
- 【编程之美】3.5 最短摘要的生成
- Java对MySQL数据库进行连接、查询和修改【转载】
- 一个完美网站的101项指标(转)
- Matlab自定义函数的几种方法
- linux下安装glibc-2.14,解决“`GLIBC_2.14‘ not found”问题
- C/C++协程库libco:微信怎样漂亮地完成异步化改造
- Android:图片加载库Glide VS Picasso