感受-App接口开发课程讲解和总结

1.背景

      今天有幸给学弟学妹们上了一节课，课程内容—— app接口开发。算起来在学校玩程序和软件已经有一年的时间了，这一年里学习到了很多东西，从接触编程语言到会做 安卓软件 ，再到 会写网站，付出了很多。自己呢，没有在公司实习过，所以就不知道公司什么怎么开发软件和网站的。就此经验，在安卓接口开发上给学弟学妹分享一下，作为借鉴。

      在我自己开发的时候，我们没有考虑过写个接口文档什么的，而是直接给队友说了声或发了个链接，说这个地址 是干什么干什么的。现在想起来就很汗颜，因为没有一套固定的规范，来约束一个开发流程！

      就此，我就开始摸索了一套规范化编程，包括写接口文档，封装多种格式数据，规范化数据格式等。于是就有了这篇文章。

2.基本的课程讲解流程

       （1） 复习了app 通信的知识，基本的app如何通信的！

       （2） 讲解了数据的来源和数据封装格式 json和xml

       （3） Json 数据 重点 知识 讲解

       （4） Xml 数据 重点 知识 讲解

       （5） 通信数据标准格式 

       （6） 封装Josn数据

       （7） 封装Xml数据

       （8） 封装ajax 回调函数 类型数据

       （9） 规范化接口开发文档

       （10）一个例子—— 实现 安卓登陆的例子和登陆接口的开发

3.app通信知识

        一句话概括：app客户端发送http请求，服务器端响应处理，返回json数据或xml数据！（cs）

4.数据格式和数据来源

      数据传输格式：json和xml 。

             数据来源：直接查询数据库所得 和 读取缓存所得（静态缓存，mamchace，redis）

5. Json数据重点知识 

     （1）一种轻量级的数据交换格式

     （2）易于阅读和理解，同时方便生成和解析

     （3）语法：key-value格式 ，中间使用 逗号 隔开 ，大括号 是Json对象 ，中括号为 Json数据

     （4）示例：

<span style="font-size:18px;">{
    "data":{
        "competitorNum":30,
        "enrollDeadLine":"2015.8.1",
        "gameLocation":"郑州体育中心",
        "gamename":"百事创新网球大赛",
        "gametime":"2015.8.26",
        "id":2,
        "personNum":2
    },
    "code":1,
    "msg":"success"
}</span>

6. Xml数据 重点知识

      （1）可扩展标记语言

      （2）注意事项：有起始标签就有结束标签 ， 标签可以自定义 ，标签不能为纯数字

      （3）示例

<span style="font-size:18px;"><root>
<data>
<competitorNum>30</competitorNum>
<enrollDeadLine>2015.8.1</enrollDeadLine>
<gameLocation>郑州体育中心</gameLocation>
<gamename>百事创新网球大赛</gamename>
<gametime>2015.8.26</gametime>
<id>2</id>
<personNum>2</personNum>
</data>
<code>1</code>
<msg>success</msg>
</root></span>

7.Json和Xml 的比较

     （1）可读性：Json语法简单，Xml语法规范 ，两者不相上下

     （2）编写生成难度：Json 更简单 ，Xml 稍微有点麻烦

     （3）网络传输速率上：Json 更快 ，数据长度短

     （4）总的来说，Json 更占优势，但使用上 还是要看 习惯！

8.通信数据标准格式

     （1）背景

            因为在慕课网上学习 php相关知识，所以就 学习php版的app接口开发知识，感觉在定义一些通信数据标准格     式，这方面的知识，十分给力，所有就借鉴 过来了！感谢慕课网提供的好教程，给我这些没有开发流程的学生提供     了一个好的引导！

     （2）数据必须含有的内容

             响应码：code  , 响应信息 ：msg , 返回逻辑数据：data

          这三个字段是必须有的，因为提示的信息越全面，开发速度就越快！在过很长一段时间，再去看这个工程，也       是可以得，很容易上手的！

      （3）示例

<span style="font-size:18px;">{"data":{"competitorNum":50,"enrollDeadLine":"2015.7.1","gameLocation":"焦作市体育馆","gamename":"金秋杯网球比赛","gametime":"2015.7.12","id":1,"personNum":3},"code":1,"msg":"success"}</span>

9.封装Json 和 Xml 数据  操作类

    （1）Json 封装方法

           第一个是： 字符串 拼接的方式 ，生成Json字符串，不过 不推荐使用，有点麻烦！

           第二个是：采用第三方 jar包 来封装（点我下载）

    （2）Xml 封装方法

           第一个是：字符串 拼接的方式，比较简单 ，推荐使用，比较简单！

           第二个是：采用 dom , don4j , xpath 等 编程编写，我自己感觉 不习惯！

    （3）Json封装方法 示例：

           第一，刚才的Json_jar包，后 使用JsonObject 和 JsonArray 对象 来实现封装！

           第二，考虑到 刚才的 数据标准格式，进行数据进行二次封装为map。

          

<span style="font-size:18px;"> /**
	  * 用来封装数据
	  * @param code 状态码
	  * @param msg  信息
	  * @param obj 数据
	  * @return
	  */
	private static Map<String, Object> toKeyVal(int code,String msg,Object obj){
		 
		Map<String,Object> map=new HashMap<String, Object>();
		map.put("code", code);
		map.put("msg", msg);
		map.put("data", obj);
		
		return map;
	 }</span>

           第三，封装为 Json对象 （ps：大括号的格式 { }）

<span style="font-size:18px;">	 /**
	  * 转 json 对象 
	  * @param code 状态码
	  * @param msg  提示信息
	  * @param obj  数据
	  * @return json对象 字符串
	  */
	 private static String toJsonString(int code,String msg,Object obj){
		 
		 if(obj==null) {
				obj="";
			}
		 
		 Map<String, Object> map=toKeyVal(code, msg, obj);
		 
		 JSONObject jsonObject=JSONObject.fromObject(map);
		 return jsonObject.toString();
	 }
	 </span>

            第四，封装为 JsonArray 格式 （ps: 中括号格式 [ ]）

<span style="font-size:18px;">     /**
      * 对象转 json 数组 
      * @param code 状态码
      * @param msg  状态信息
      * @param obj  数据
      * @return json数组 字符串
      */
	 @SuppressWarnings("unused")
	private static String toJsonArray(int code,String msg,Object obj){
		 
		 Map<String, Object> map=toKeyVal(code, msg, obj);
		 
		 JSONArray jsonArray=JSONArray.fromObject(map);
		 return jsonArray.toString();
	 }
	 </span>

        （4）Xml 封装方法示例：

            思路：因为传的参数格式不确定，比较对象，数据，集合 等等，是不固定的 操作起来有点复杂，所以

                 就想到了先转Json （json 只有两个对象 JsonObject和JsonArray）在去封装 xml。

          

<span style="font-size:18px;"> /**
	  *  转xml 格式 ：字符串拼装的格式 
	  * @param code 状态码
	  * @param msg  提示信息
	  * @param obj  数据
	  * @return xml数据
	  */
	 private static String toXml(int code,String msg,Object obj){
		 
		if(obj==null) {
			obj="";
		}
		 
    	Map<String,Object> map=toKeyVal(code, msg, obj);
	    JSONObject object=JSONObject.fromObject(map);
		 
		 StringBuilder builder=new StringBuilder("<?xml version='1.0' encoding='UTF-8'?>");
		 builder.append("<root>");
		 builder.append(mapToxml(object));
		 builder.append("</root>");
		 
		return builder.toString();
	 }</span>

 

             下面的是 mapToxml 的格式去封装和生成主要数据 ，使用了递归调用！

<span style="font-size:18px;">/**
	 * 生成 xml
	 * @param object
	 * @return
	 */
	private static String mapToxml(JSONObject object){

		
		StringBuilder builder=new StringBuilder();
		
		@SuppressWarnings("unchecked")
		Iterator<String> iterator=object.keys();
		
	    while(iterator.hasNext()){
	    	
	    	String key=iterator.next();

	    	builder.append("<"+key+">");
	    	
	    	if(object.get(key) instanceof JSONObject){
	    		//如果是 JSONObject的话
	    		//递归 调用
	    		builder.append(mapToxml((JSONObject) object.get(key)));
	    	}else if(object.get(key) instanceof JSONArray){
	    		//如果是 JSONArray的话 
	    		StringBuilder builder2=new StringBuilder();
	    		JSONArray array=(JSONArray) object.get(key);
	    		
	    		if(array.isArray()){
	    			int i=0;
	    		   for(Object obj : array) {
	    			   JSONObject objitem=(JSONObject) obj;
	    			   String attr="num='"+i+"'";
	    			   
	    			   //如果有 id 的话 ，可以使用这个
//	    			   if(objitem.containsKey("id")){
//	    				   attr="id='"+objitem.getString("id")+"'";
//	    			   }
	    			   
	    			   builder2.append("<item "+attr+">");
					   builder2.append(mapToxml(objitem));
					   builder2.append("</item>");
					   i++;
				    }
	    		}
	    		builder.append(builder2.toString());
	    		
	    		
	    	}else{
	        	builder.append(object.get(key));
	    	}
	    	
	    	builder.append("</"+key+">");
	    }
		
		return builder.toString();
	}</span>

 10.封装ajax 回调函数 数据

      思路：直接调用 生成的json数据 ，在 添加 回调函数名称 即可！

<span style="font-size:18px;">/**
	 * ajax 发送异步请求的时候回调使用
	 * @return
	 */
	private static String toajax(String str){
		
		
		return "callback("+str+")";
		
	}
	</span>

  11.规范化 接口开发文档

      在这里写接口开发文档 是很重要的，可以选择多种 方式来写，比如 html , MarkDown 编辑器，Execl 等

      我使用的时候，选择了比较简单的一种方式 ：Execl 。简单，方便，快捷！

      基本格式如下：（复制Execl 里的，自己可以照着在Execl 里 写一个）

接口名称：	用户登录接口
接口地址：	http://192.168.1.114:8080/TennisGameSys/app_userlogin?name=hpujava&pasd=111
接口说明：	通过get / post 方式请求均可
参数：	参数类型	参数说明	参数说明
name	String	用户名
pasd	String	用户密码
返回类型：	JSON数据
返回值参数说明：	字段类型	字段说明	说明补充
code	int	1:成功，0：失败
msg	String	提示信息
data	object	用户信息
返回值示例：	{"data":{"address":"中国广州","borth":"1983.2.13","id":1,"matchage":3,"password":"111","realname":"李娜","sex":"女","username":"hpujava"},"code":1,"msg":"success"}

  12.总结

       这节课，本来安排是讲2个半小时，包括用户登录的例子（从服务端开发到客户端开发）一并讲完，最后，因为网络原因，差json解析没演示，有点遗憾。但是总的来说，自我感觉还不错。

  13. 生成Json 和xml 工具类下载

     http://download.csdn.net/detail/lablenet/9002325

     谢谢阅读