diff --git a/Document.md b/Document.md index bc32029b..2baa8b46 100644 --- a/Document.md +++ b/Document.md @@ -3,9 +3,9 @@ * ### [1.示例](#1) * ### [2.对比传统方式](#2) * [2.1 开发流程](#2.1) -* [2.2 客户端请求](#2.2) -* [2.3 服务端操作](#2.3) -* [2.4 客户端解析](#2.4) +* [2.2 前端请求](#2.2) +* [2.3 后端操作](#2.3) +* [2.4 前端解析](#2.4) * [2.5 对应不同需求的请求](#2.5) * [2.6 对应不同请求的结果](#2.6) * ### [3.对应关系总览](#3) @@ -14,9 +14,9 @@ * ### [4.快速上手](#4) * [4.1 下载解压](#4.1) * [4.2 导入数据库表](#4.2) -* [4.3 运行服务端工程](#4.3) -* [4.4 运行客户端工程](#4.4) -* [4.4 操作客户端App](#4.5) +* [4.3 运行后端工程](#4.3) +* [4.4 运行前端工程](#4.4) +* [4.4 操作前端App](#4.5) * ### [5.其它](#5) * [5.1 相关推荐](#5.1) * [5.2 关于作者](#5.2) @@ -270,39 +270,39 @@ ###

2.1 开发流程

开发流程 | 传统方式 | APIJSON -------- | ------------ | ------------ - 接口传输 | 等服务端编辑接口，然后更新文档，客户端再按照文档编辑请求和解析代码 | 客户端按照自己的需求编辑请求和解析代码。
没有接口，更不需要文档！客户端再也不用和服务端沟通接口或文档问题了！ - 兼容旧版 | 服务端增加新接口，用v2表示第2版接口，然后更新文档 | 什么都不用做！ + 接口传输 | 等后端编辑接口，然后更新文档，前端再按照文档编辑请求和解析代码 | 前端按照自己的需求编辑请求和解析代码。
没有接口，更不需要文档！前端再也不用和后端沟通接口或文档问题了！ + 兼容旧版 | 后端增加新接口，用v2表示第2版接口，然后更新文档 | 什么都不用做！
-###

2.2 客户端请求

- 客户端请求 | 传统方式 | APIJSON +###

2.2 前端请求

+ 前端请求 | 传统方式 | APIJSON -------- | ------------ | ------------ - 要求 | 客户端按照文档在对应URL后面拼接键值对 | 客户端按照自己的需求在固定URL后拼接JSON + 要求 | 前端按照文档在对应URL后面拼接键值对 | 前端按照自己的需求在固定URL后拼接JSON 结构 | 同一个URL内table_name只能有一个

base_url/get/table_name?
key0=value0&key1=value1... | 同一个URL后TableName可传任意数量个

base_url/get/
{
   TableName0:{
     key0:value0,
     key1:value1,
     ...
   },
   TableName1:{
     ...
   }
   ...
} URL | 不同的请求对应不同的URL，基本上有多少个不同的请求就得有多少个接口URL | 相同的操作方法(增删改查)都用同一个URL，
大部分请求都用7个通用接口URL的其中一个 键值对 | key=value | key:value
-###

2.3 服务端操作

- 服务端操作 | 传统方式 | APIJSON +###

2.3 后端操作

+ 后端操作 | 传统方式 | APIJSON -------- | ------------ | ------------ - 解析和返回 | 取出键值对，把键值对作为条件用预设的的方式去查询数据库，最后封装JSON并返回给客户端 | 把Parser#parse方法的返回值返回给客户端就行 - 返回JSON结构的设定方式 | 由服务端设定，客户端不能修改 | 由客户端设定，服务端不能修改 + 解析和返回 | 取出键值对，把键值对作为条件用预设的的方式去查询数据库，最后封装JSON并返回给前端 | 把Parser#parse方法的返回值返回给前端就行 + 返回JSON结构的设定方式 | 由后端设定，前端不能修改 | 由前端设定，后端不能修改
-###

2.4 客户端解析

- 客户端解析 | 传统方式 | APIJSON +###

2.4 前端解析

+ 前端解析 | 传统方式 | APIJSON -------- | ------------ | ------------ 查看方式 | 查文档或问后端，或等请求成功后看日志 | 看请求就行，所求即所得，不用查、不用问、不用等。也可以等请求成功后看日志 解析方法 | 用JSON解析器来解析JSONObject | 可以用JSONResponse解析JSONObject，或使用传统方式
-###

2.5 客户端对应不同需求的请求

- 客户端的请求 | 传统方式 | APIJSON +###

2.5 前端对应不同需求的请求

+ 前端的请求 | 传统方式 | APIJSON -------- | ------------ | ------------ User | base_url/get/user?id=38710 | [base_url/get/
{
   "User":{
     "id":38710
   }
}](http://39.108.143.172:8080/get/{"User":{"id":38710}}) Moment和对应的User | 分两次请求
Moment:
base_url/get/moment?userId=38710

User:
base_url/get/user?id=38710 | [base_url/get/
{
   "Moment":{
     "userId":38710
   },
   "User":{
     "id":38710
   }
}](http://39.108.143.172:8080/get/{"Moment":{"userId":38710},"User":{"id":38710}}) @@ -312,14 +312,14 @@
-###

2.6 服务端对应不同请求的返回结果

- 服务端的返回结果 | 传统方式 | APIJSON +###

2.6 后端对应不同请求的返回结果

+ 后端的返回结果 | 传统方式 | APIJSON -------- | ------------ | ------------ User | {
   "data":{
     "id":38710,
     "name":"xxx",
     ...
   },
   "code":200,
   "msg":"success"
} | {
   "User":{
     "id":38710,
     "name":"xxx",
     ...
   },
   "code":200,
   "msg":"success"
} Moment和对应的User | 分别返回两次请求的结果，获取到Moment后取出userId作为User的id条件去查询User

Moment:
{
   "data":{
     "id":235,
     "content":"xxx",
     ...
   },
   "code":200,
   "msg":"success"
}

User:
{
   "data":{
     "id":38710,
     "name":"xxx",
     ...
   },
   "code":200,
   "msg":"success"
} | 一次性返回，没有传统方式导致的 长时间等待结果、两次结果间关联、线程多次切换 等问题

{
   "Moment":{
     "id":235,
     "content":"xxx",
     ...
   },
   "User":{
     "id":38710,
     "name":"xxx",
     ...
   },
   "code":200,
   "msg":"success"
} User列表 | {
   "data":[
     {
       "id":38710,
       "name":"xxx",
       ...
     },
     {
       "id":82001,
       ...
     },
     ...
   ],
   "code":200,
   "msg":"success"
} | {
   "User[]":[
     {
       "id":38710,
       "name":"xxx",
       ...
     },
     {
       "id":82001,
       ...
     },
     ...
   ],
   "code":200,
   "msg":"success"
} Moment列表，每个Moment包括发布者User和前3条Comment | Moment里必须有
1.User对象
2.Comment数组

{
   "data":[
     {
       "id":235,
       "content":"xxx",
       ...,
       "User":{
         ...
       },
       "Comment":[
         ...
       ]
     },
     {
       "id":301,
       "content":"xxx",
       ...,
       "User":{
         ...
       },
       ...
     },
     ...
   ],
   "code":200,
   "msg":"success"
} | 1.高灵活，可任意组合
2.低耦合，逻辑很清晰

{
   "[]":[
     {
       "Moment":{
         "id":235,
         "content":"xxx",
         ...
       },
       "User":{
         ...
       },
       "Comment[]":[
         ...
       ]
     },
     {
       "Moment":{
         "id":301,
         "content":"xxx",
         ...
       },
       "User":{
         ...
       },
       ...
     },
     ...
   ],
   "code":200,
   "msg":"success"
} - User发布的Moment列表，每个Moment包括发布者User和前3条Comment | 1.大量重复User，浪费流量和服务器性能
2.优化很繁琐，需要后端扩展接口、写好文档，前端/客户端再配合优化

{
   "data":[
     {
       "id":235,
       "content":"xxx",
       ...,
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment":[
         ...
       ]
       ...
     },
     {
       "id":470,
       "content":"xxx",
       ...,
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment":[
         ...
       ]
       ...
     },
     {
       "id":511,
       "content":"xxx",
       ...,
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment":[
         ...
       ]
       ...
     },
     {
       "id":595,
       "content":"xxx",
       ...,
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment":[
         ...
       ]
       ...
     },
     ...
   ],
   "code":200,
   "msg":"success"
} | 以上不同请求方式的结果:

① 常规请求
{
   "[]":[
     {
       "Moment":{
         "id":235,
         "content":"xxx",
         ...
       },
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment[]":[
         ...
       ]
     },
     ...
   ],
   "code":200,
   "msg":"success"
}

② 省去重复的User
{
   "User":{
     "id":38710,
     "name":"Tommy",
     ...
   },
   "[]":[
     {
       "Moment":{
         "id":235,
         "content":"xxx",
         ...
       },
       "Comment[]":[
         ...
       ]
     },
     ...
   ],
   "code":200,
   "msg":"success"
}

③ 不查询已获取到的User
{
   "[]":[
     {
       "Moment":{
         "id":235,
         "content":"xxx",
         ...
       },
       "Comment[]":[
         ...
       ]
     },
     ...
   ],
   "code":200,
   "msg":"success"
} + User发布的Moment列表，每个Moment包括发布者User和前3条Comment | 1.大量重复User，浪费流量和服务器性能
2.优化很繁琐，需要后端扩展接口、写好文档，前端/前端再配合优化

{
   "data":[
     {
       "id":235,
       "content":"xxx",
       ...,
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment":[
         ...
       ]
       ...
     },
     {
       "id":470,
       "content":"xxx",
       ...,
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment":[
         ...
       ]
       ...
     },
     {
       "id":511,
       "content":"xxx",
       ...,
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment":[
         ...
       ]
       ...
     },
     {
       "id":595,
       "content":"xxx",
       ...,
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment":[
         ...
       ]
       ...
     },
     ...
   ],
   "code":200,
   "msg":"success"
} | 以上不同请求方式的结果:

① 常规请求
{
   "[]":[
     {
       "Moment":{
         "id":235,
         "content":"xxx",
         ...
       },
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment[]":[
         ...
       ]
     },
     ...
   ],
   "code":200,
   "msg":"success"
}

② 省去重复的User
{
   "User":{
     "id":38710,
     "name":"Tommy",
     ...
   },
   "[]":[
     {
       "Moment":{
         "id":235,
         "content":"xxx",
         ...
       },
       "Comment[]":[
         ...
       ]
     },
     ...
   ],
   "code":200,
   "msg":"success"
}

③ 不查询已获取到的User
{
   "[]":[
     {
       "Moment":{
         "id":235,
         "content":"xxx",
         ...
       },
       "Comment[]":[
         ...
       ]
     },
     ...
   ],
   "code":200,
   "msg":"success"
} 1.base_url指基地址，一般是顶级域名，其它分支url都是在base_url后扩展。如base_url:http://www.google.com/ ，对应的GET分支url:http://www.google.com/get/ 。下同。
@@ -343,14 +343,14 @@ GET:
普通获取数据，
明文，
可用浏览器调试 | bas HEAD:
普通获取数量，
明文，
可用浏览器调试 | base_url/head/ | {
   TableName:{
     …
   }
}
{…}内为限制条件

例如获取一个id为38710的User所发布的Moment总数：
{
   "Moment":{
     "userId":38710
   }
} | {
   TableName:{
     "code":200,
     "msg":"success",
     "count":10
   },
   "code":200,
   "msg":"success"
}
例如
{
   "Moment":{
     "code":200,
     "msg":"success",
     "count":10
   },
   "code":200,
   "msg":"success"
} GETS:
安全/私密获取数据，
非明文，
用于获取钱包等
对安全性要求高的数据 | base_url/gets/ | 最外层加一个"tag":tag，其它同GET | 同GET HEADS:
安全/私密获取数量，
非明文，
用于获取银行卡数量等
对安全性要求高的数据总数 | base_url/heads/ | 最外层加一个"tag":tag，其它同HEAD | 同HEAD -POST:
新增数据，
非明文 | base_url/post/ | {
   TableName:{
     …
   },
   "tag":tag
}
{…}中id由服务端生成，不能传

例如一个id为38710的User发布一个新Moment：
{
   "Moment":{
     "userId":38710,
     "content":"APIJSON,let interfaces and documents go to hell !"
   },
   "tag":"Moment"
} | {
   TableName:{
     "code":200,
     "msg":"success",
     "id":38710
   },
   "code":200,
   "msg":"success"
}
例如
{
   "Moment":{
     "code":200,
     "msg":"success",
     "id":120
   },
   "code":200,
   "msg":"success"
} +POST:
新增数据，
非明文 | base_url/post/ | {
   TableName:{
     …
   },
   "tag":tag
}
{…}中id由后端生成，不能传

例如一个id为38710的User发布一个新Moment：
{
   "Moment":{
     "userId":38710,
     "content":"APIJSON,let interfaces and documents go to hell !"
   },
   "tag":"Moment"
} | {
   TableName:{
     "code":200,
     "msg":"success",
     "id":38710
   },
   "code":200,
   "msg":"success"
}
例如
{
   "Moment":{
     "code":200,
     "msg":"success",
     "id":120
   },
   "code":200,
   "msg":"success"
} PUT:
修改数据，
非明文，
只修改所传的字段 | base_url/put/ | {
   TableName:{
     "id":id,
     …
   },
   "tag":tag
}
{…}中id必传

例如修改id为235的Moment的content：
{
   "Moment":{
     "id":235,
     "content":"APIJSON,let interfaces and documents go to hell !"
   },
   "tag":"Moment"
} | 同POST DELETE:
删除数据，
非明文 | base_url/delete/ | {
   TableName:{
     "id":id
   },
   "tag":tag
}
{…}中id必传，一般只传id

例如删除id为120的Moment：
{
   "Moment":{
     "id":120
   },
   "tag":"Moment"
} | 同POST 1.TableName指要查询的数据库表Table的名称字符串。第一个字符为大写字母，剩下的字符要符合英语字母、数字、下划线中的任何一种。对应的值的类型为JSONObject，结构是 {...}，里面放的是Table的字段(列名)。下同。
-2."tag":tag 后面的tag是非GET、HEAD请求中匹配请求的JSON结构的key，一般是要查询的table的名称，由服务端Request表中指定。下同。
-3.GET、HEAD请求是开放请求，可任意组合任意嵌套。其它请求为受限制的安全/私密请求，对应的 方法、tag、结构 都必须和 服务端Request表中所指定的 一一对应，否则请求将不被通过。下同。
+2."tag":tag 后面的tag是非GET、HEAD请求中匹配请求的JSON结构的key，一般是要查询的table的名称，由后端Request表中指定。下同。
+3.GET、HEAD请求是开放请求，可任意组合任意嵌套。其它请求为受限制的安全/私密请求，对应的 方法、tag、结构 都必须和 后端Request表中所指定的 一一对应，否则请求将不被通过。下同。
4.GETS与GET、HEADS与HEAD分别为同一类型的操作方法，请求稍有不同但返回结果相同。下同。
5.在HTTP通信中，GET、HEAD方法一般用HTTP GET请求，其它一般用HTTP POST请求。下同。
6.所有JSONObject都视为容器(或者文件夹)，结构为 {...} ，里面可以放普通对象或子容器。下同。
@@ -386,16 +386,16 @@ DELETE:
删除数据，
非明文 | base_url/delete/ | {
 & Clone or download > Download ZIP > 解压到一个路径并记住这个路径。 -#### 你可以跳过步骤4.2和步骤4.3，用我的服务器IP地址 39.108.143.172:8080 来测试服务端对客户端请求的返回结果。 +#### 你可以跳过步骤4.2和步骤4.3，用我的服务器IP地址 39.108.143.172:8080 来测试后端对前端请求的返回结果。 ###

4.2 导入表文件到数据库

-服务端需要MySQL Server和MySQLWorkbench，没有安装的都先下载安装一个。
+后端需要MySQL Server和MySQLWorkbench，没有安装的都先下载安装一个。
我的配置是Windows 7 + MySQL Community Server 5.7.16 + MySQLWorkbench 6.3.7 和 OSX EI Capitan + MySQL Community Server 5.7.16 + MySQLWorkbench 6.3.8，其中系统和软件都是64位的。 启动MySQLWorkbench > 进入一个Connection > 点击Server菜单 > Data Import > 选择刚才解压路径下的APIJSON-Master/table > Start Import > 刷新SCHEMAS, 左下方sys/tables会出现添加的table。 -###

4.3 用Eclipse for JavaEE或IntellIJ IDEA Ultimate运行服务端工程

+###

4.3 用Eclipse for JavaEE或IntellIJ IDEA Ultimate运行后端工程

如果以上编辑器一个都没安装，运行前先下载安装一个。
我的配置是Windows 7 + JDK 1.7.0_71 + Eclipse 4.6.1 + IntellIJ 2016.3 和 OSX EI Capitan + JDK 1.8.0_91 + Eclipse 4.6.1 + IntellIJ 2016.2.5 @@ -422,9 +422,9 @@ Open > 选择刚才解压路径下的APIJSON-Master/APIJSON(Server)/APIJSON(Idea 3.运行
Run > Run APIJSONApplication -###

4.4 用ADT Bundle或Android Studio运行客户端工程

+###

4.4 用ADT Bundle或Android Studio运行前端工程

-可以跳过这个步骤，直接使用 [APIJSON在线工具](http://39.108.143.172/) 或 下载下方提供的客户端App。 +可以跳过这个步骤，直接使用 [APIJSON在线工具](http://39.108.143.172/) 或 下载下方提供的前端App。 如果以上编辑器一个都没安装，运行前先下载安装一个。
我的配置是Windows 7 + JDK 1.7.0_71 + ADT Bundle 20140702 + Android Studio 2.2 和 OSX EI Capitan +（JDK 1.7.0_71 + ADT Bundle 20140702）+（JDK 1.8.0_91 + Android Studio 2.1.2），其中系统和软件都是64位的。 @@ -445,10 +445,10 @@ Open an existing Android Studio project > 选择刚才解压路径下的APIJSON- 2.运行
Run > Run app -###

4.5 操作客户端App

+###

4.5 操作前端App

选择发送APIJSON请求并等待显示结果。
-如果默认url不可用，修改为一个可用的，比如正在运行APIJSON服务端工程的电脑的IPV4地址，然后点击查询按钮重新请求。 +如果默认url不可用，修改为一个可用的，比如正在运行APIJSON后端工程的电脑的IPV4地址，然后点击查询按钮重新请求。

@@ -464,7 +464,7 @@ Run > Run app [后端自动化版本管理，再也不用改URL了！](https://my.oschina.net/tommylemon/blog/1576587) -[3步创建APIJSON服务端新表及配置](https://my.oschina.net/tommylemon/blog/889074) +[3步创建APIJSON后端新表及配置](https://my.oschina.net/tommylemon/blog/889074) ###

5.2 关于作者

TommyLemon：[https://github.com/TommyLemon](https://github.com/TommyLemon)
@@ -473,7 +473,7 @@ QQ群：607020115 如果有什么问题或建议可以[提ISSUE](https://github.com/TommyLemon/APIJSON/issues)、加群或者[发我邮件](https://github.com/TommyLemon)，交流技术，分享经验。
如果你解决了某些bug，或者新增了一些通用性强的功能，欢迎[贡献代码](https://github.com/TommyLemon/APIJSON/pulls)，感激不尽^_^ -###

5.3 下载试用客户端App

+###

5.3 下载试用前端App

仿微信朋友圈动态实战项目
[APIJSONApp.apk](http://files.cnblogs.com/files/tommylemon/APIJSONApp.apk)