HTTP接口设计及日志打印

任何一个稍大的项目中，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 {

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一遍自己的代码，保证没有逻辑上的错误等等。