我的java接口开发总结（个人总结，仅供参考）有代码和文档

项目需要开发几个接口让客户调用，用来获取平台上的设备数据（基础数据、应急数据、检查设备数据）。根据数据类型不同简单划分了三个接口来获取三类不同的数据。

第一步确定请求方式、验证方式。

1、个人比较喜欢post请求方式，请求参数和响应参数为json类型，这样提取某个需要的参数会比较简单。

2、验证方式一开始考虑的是直接写死几个固定String字符串来进行验证，效果是达到了，但是感觉上会比较low，而且验证不具备时效性。之后参考了下网上资料，决定采取获取token的方式来进行验证，token失效设定为30分钟有效。对方第一次通过接口获取token值，第二次请求带上token值和其他请求参数来获取参数。token放在redis中，设定保存30分钟。

第二步根据项目层级设计接口请求地址，详细请求参数、响应参数。

1、确定接口请求地址（根据自己项目实际来设计）。

2、设计请求参数，第一次获取token，设计请求参数userName、type、data三个来验证，正确返回token值，错误给出错误提示，如：参数不正确、缺少参数等。第二次获取数据，设计请求参数token、type、time，其中time为非必须参数，不填，则获取全部数据；填，则获取当日新建或者更新数据，用来获取增量数据。

3、设计相应参数，其中公共相应参数有status（响应状态，成功/失败），error（错误信息），其他参数有token（验证信息）、totalNumber（响应总消息条数）、info（消息集合）等。

第三步测试已经写好的接口。

1、根据自己的设计利用postman来进行测试，首先是测试正常正确状态下，是否可以访问，并获取想要的参数。如果可以，那么大部分的工作是完成了；如果不行，则查看代码、路径、参数、项目配置等，排查原因。

2、已经可以正常访问，现在就是主动模拟可能出现错误的情况，来编写error错误提示信息，如：参数不多、参数不全、日期不对等情况，在代码里面给出响应的提示。

第四步根据第三部的测试来完善代码

1、根据第三步的参数结果，可能出现的错误情况，来完善错误提示部分的代码。

2、建议在finally中，写一个“系统错误”的提示，应对网络或者其他一些突发情况。还有一些流的关闭，链接的断开等都放在里面。

3、从头到尾走不一遍自己的代码逻辑，看看有没有不合理、不规范的地方，及时调整（可参考一些代码规范）。

第五步编写接口文档

根据已经开发好接口来编写接口文档，交付客户。需要明确请求地址、请求方式、请求参数类型、响应参数类型、具体的请求参数及取值（规则）、请求参数实例、响应参数数据层级和参数名（便于获取其中的参数值）、响应参数实例、可能出现的错误情况及应对措施、开发人员的联系方式（便于后期客户调试交流，这一步根据自身实际取舍）等。

第六步提交测试

部署项目，提交接口文档给公司测试人员进行系统测试。通过则提交产品经理；不通过则进行修改，直至通过。

 

以上是我的java接口开发总结，纯属个人偏好，不喜勿喷，共同学习进步。

下面是一段java实例和文档实例，仅供参考。

/**
     * 获取token
     * 请求方式POST
     * 数据类型JSON
     * 请求参数：userName=userName,type=type,dataSource=dataSource
     * 响应参数：
     * hhj
     */
    @RequestMapping(value = "/gettoken.do",method = RequestMethod.POST,consumes = { "application/json" }, produces = "application/json;charset=utf-8")
    @ResponseBody
    public JSONObject getToken(@RequestBody JSONObject json) {
        
        JSONObject response=new JSONObject();
        Jedis jedis = pool.getResource();
        try {
            //判断对方身份
            if(json.has("userName")&&
               json.has("type")&&
               json.has("dataSource")&&
               "userName".equals(json.getString("userName"))&&
               "type".equals(json.getString("type"))&&
               "dataSource".equals(json.getString("dataSource"))){
                
                if(jedis.exists("yichun@token")) {//存在token直接读取
                    token=jedis.get("yichun@token");
                    status="success";
                    response.put("status", status);
                    response.put("token", token);
                }else {
                    Token tokenInfo = TokenUtil.createToken("yichun");//不存在则重新生成并存进redis中
                    token=tokenInfo.getToken();
                    jedis.set("yichun@token", token, "NX", "EX", 1800);;//将token存进redis内30分钟失效
                    status="success";
                    response.put("status", status);
                    response.put("token", token);
                }
            }else {
                status="failure";
                error="验证信息错误";
                response.put("status", status);
                response.put("error", error);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }finally {
            if(status==null) {
                status="failure";
                error="未知错误，请稍后重试或联系系统管理员";
                response.put("status", status);
                response.put("error", error);
            }
            jedis.close();
        }
        return response;
    }

1、获取token

接口名称:获取token

接口地址:项目网址+/gettoken.do

请求方法:post 

请求数据类型:application/json 

响应类型:application/json 

 

请求参数 

参数名称	是否必须	数据类型	描述
userName	是	string	用户名（userName）
type	是	string	接口类型(type)
dataSource	是	string	数据来源（dataSource）

 

实例：

{

"userName":"userName",

"type":"type",

"dataSource":"dataSource"

}

响应参数

     

参数名称	是否必须	数据类型	描述
status	是	string	响应状态 （success-成功、failure-失败）
token	否	string	验证标识 （30分钟失效）
error	否	string	错误信息

 

实例：

{

    "status": "success",

    "token": "6C0A9C862F188FE278C8B3EA81D3FD44"

}