HTTP接口设计及日志打印
2014-09-15 13:50
337 查看
任何一个稍大的项目中,web接口的使用是少不了的,不管C2S还是S2S都会依赖于http的接口。下面对这一两年来写过各种Http接口做一个总结。
大致可以分为以下五点:
1、使用requestId来记录追踪请求
2、只在body中接收json字符串的请求,避免产生编码问题
3、返回适当的数据结构
4、打印有用的日志
5、提供可阅读的文档
第一点,使用requestId来记录追踪请求。如果你这么做了,当你查找定位问题的时候就会知道这是一个多么有用的规则。这里可以强制请求中用UUID作为requestId,服务器返回时带上同样的UUID。或者业务上没有此需求,则可以通过对每个请求生成一个唯一的id来标识,这个方法在第四点,日志中会介绍。
第二点,除了请求的数据非常简单或者特殊情形一定需要使用GET方法以外,所有的请求都应尽量使用POST方法,并且规定请求参数为JSON字符串,放在RequstBody中,尽量不要将额外的参数信息放在form-encoded里面,这样不仅可以有效避免编码问题,同时也可以与接口返回的JSON BODY对应。
第三点,设计每个API的时候,要定义好返回状态码,错误信息,以及有效信息。大部分情况下,HTTP API应使用JSON作为ResponseBody,这要可以与请求相对应,同时可以方便接口的扩展。下面是我常用的返回数据结构:public class ResponseEntry {
code的存在可以让请求的客户端更准确的确定返回的信息,判断此次请求的结果。ResponseCode的设计也应遵循一定的规则,如200通常表示成功,404通常表示not found等。如果你使用springmvc作为框架开发,那么我们可以在接口中直接返回ResponseEntry对象,并通过配置servlet-context使其自动转为json字符串并返回。如下所示:
这里用的是fastjson作为转换,也可以使用默认的jackson或其他json处理方法。
第四点,打印有用的日志。在接口中打印出必要的信息,可以有效的帮助查找定位问题。通常需要打印出Request和Response的内容。并用requestId来表示每个Response和对应的Request。在Http接口设计中,我们可以加入一个Filter用来打印log,这样就不必再每一个API都去做一遍打印输入输出的动作。可以使代码更加简洁。这里代码比较多,就不贴了,参看源码github。
第五点,当完成接口,并测试通过以后,应该给出一份可阅读的接口文档,这不仅仅是帮助其他人使用你的API,同时在写文档的过程中,可以review一遍自己的代码,保证没有逻辑上的错误等等。
大致可以分为以下五点:
1、使用requestId来记录追踪请求
2、只在body中接收json字符串的请求,避免产生编码问题
3、返回适当的数据结构
4、打印有用的日志
5、提供可阅读的文档
第一点,使用requestId来记录追踪请求。如果你这么做了,当你查找定位问题的时候就会知道这是一个多么有用的规则。这里可以强制请求中用UUID作为requestId,服务器返回时带上同样的UUID。或者业务上没有此需求,则可以通过对每个请求生成一个唯一的id来标识,这个方法在第四点,日志中会介绍。
第二点,除了请求的数据非常简单或者特殊情形一定需要使用GET方法以外,所有的请求都应尽量使用POST方法,并且规定请求参数为JSON字符串,放在RequstBody中,尽量不要将额外的参数信息放在form-encoded里面,这样不仅可以有效避免编码问题,同时也可以与接口返回的JSON BODY对应。
第三点,设计每个API的时候,要定义好返回状态码,错误信息,以及有效信息。大部分情况下,HTTP API应使用JSON作为ResponseBody,这要可以与请求相对应,同时可以方便接口的扩展。下面是我常用的返回数据结构:public class ResponseEntry {
private int code; // 状态码 private String result; // 描述信息 private Object data; // 有效信息 public ResponseEntry(int code) { this.code = code; } public ResponseEntry(int code, String result) { this.code = code; this.result = result; } // 省略Getter and Setter @Override public String toString() { return "ResponseEntry{" + "code=" + code + ", result='" + result + '\'' + ", data=" + data + '}'; } public String toJSONString() { return JSON.toJSONString(this); } }
code的存在可以让请求的客户端更准确的确定返回的信息,判断此次请求的结果。ResponseCode的设计也应遵循一定的规则,如200通常表示成功,404通常表示not found等。如果你使用springmvc作为框架开发,那么我们可以在接口中直接返回ResponseEntry对象,并通过配置servlet-context使其自动转为json字符串并返回。如下所示:
@ResponseBody @RequestMapping(value = "/communicate", method = RequestMethod.POST) private ResponseEntry communicate(@RequestBody String jsonBody) { /* code */ }
<mvc:annotation-driven> <mvc:message-converters register-defaults="true"> <!-- fastjosn spring support --> <bean id="jsonConverter" class="com.alibaba.fastjson.support.spring.FastJsonHttpMessageConverter"> <property name="supportedMediaTypes"> <list> <!--<value>application/json;charset=UTF-8</value>--> <value>text/html;charset=UTF-8</value> </list> </property> </bean> </mvc:message-converters> </mvc:annotation-driven>
这里用的是fastjson作为转换,也可以使用默认的jackson或其他json处理方法。
第四点,打印有用的日志。在接口中打印出必要的信息,可以有效的帮助查找定位问题。通常需要打印出Request和Response的内容。并用requestId来表示每个Response和对应的Request。在Http接口设计中,我们可以加入一个Filter用来打印log,这样就不必再每一个API都去做一遍打印输入输出的动作。可以使代码更加简洁。这里代码比较多,就不贴了,参看源码github。
第五点,当完成接口,并测试通过以后,应该给出一份可阅读的接口文档,这不仅仅是帮助其他人使用你的API,同时在写文档的过程中,可以review一遍自己的代码,保证没有逻辑上的错误等等。
相关文章推荐
- HTTP接口设计及日志打印
- 一个简单的用于嵌入式Linux开发的C调试日志打印接口
- 关于http接口防止非法调用的设计方案
- HTTP API接口安全设计
- android,retrofit,okhttp,日志拦截器,使用拦截器Interceptor统一打印请求与响应的json
- 极简 HTTP 接口设计状态码指南
- 实现IHttpModule接口获取Session来实现页面访问日志功能。
- HTTP 接口设计指北
- 使用 Nlog 将日志打印到 Logstash 的监控接口
- 架构设计 - 日志管理接口设计
- 优雅设计封装基于Okhttp3的网络框架(六):HttpHeader接口设计实现 及 Response、Request封装实现
- 业务类接口在TCP,HTTP,BLL模式下的实例 设计模式混搭 附源码一份
- LR做接口压力测试时,后台打印日志的异常信息
- 黑马程序员——学习日志5面向对象(static关键字,单例设计模式,抽象类,接口)
- Restful是一种非常优美的http接口设计风格及设计规范
- spring aop实现拦截接口请求打印日志
- C++简单的打印日志接口
- Selenium Webdriver自动化测试设计(webdriver自动化架构设计、定义接口、日志处理、Java Robot类应用)
- 接口测试:打印日志的小开关
- python 接口测试1 --如何创建和打印日志文件